shelving/util/path.d.ts

Toolkit for using data in JavaScript.

/**
 * Reuseable utilities for dealing with filesystem paths.
 */
import type { AnyCaller } from "./function.js";
import type { Nullish } from "./null.js";
/** Absolute path string starts with `/` slash. */
export type AbsolutePath = `/` | `/${string}`;
/** Relative path string is `.` dot, or starts with `./` dot slash. */
export type RelativePath = `.` | `./` | `./${string}`;
/** Either an absolute or relative path. */
export type Path = AbsolutePath | RelativePath;
/** Things that can be converted to a path. */
export type PossiblePath = string | readonly string[];
/** Is a string path an absolute path? */
export declare function isAbsolutePath(path: PossiblePath): path is AbsolutePath;
/** Is a string path an relative path? */
export declare function isRelativePath(path: PossiblePath): path is RelativePath;
/**
 * Resolve a relative or absolute path and return the absolute path, or `undefined` if not a valid path.
 * - Normalises runs of `//` more than one slash.
 * - Normalises `\` windows paths.
 * - Strips trailing slashes.
 *
 * @param path Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
 * @param base Absolute path used for resolving relative paths in `possible`
 * @return Absolute path with a leading slash but no trailing slash, e.g. `/a/c/b`
 */
export declare function getPath(inputPath: Nullish<PossiblePath>, inputBase?: AbsolutePath): AbsolutePath | undefined;
/**
 * Normalise a path:
 * - Runs of `/` and `\` collapsed to a single `/`.
 * - `.` "current-directory" segments dropped (so `./a/b` → `a/b`, `a/./b` → `a/b`, `.` → `""`).
 * - Trailing slashes stripped.
 * - The root `"/"` is preserved as-is.
 */
export declare function cleanPath(path: AbsolutePath): AbsolutePath;
export declare function cleanPath(path: string): string;
/**
 * Resolve a relative or absolute path and return the path, or throw `RequiredError` if not a valid path.
 * - Internally uses `new URL` to do path processing but shouldn't ever reveal that fact.
 * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
 *
 * @param path Absolute path e.g. `/a/b/c`, relative path e.g. `./a` or `b` or `../c`, URL string e.g. `http://shax.com/a/b/c`, or `URL` instance.
 * @param base Absolute path used for resolving relative paths in `possible`
 * @return Absolute path with a leading trailing slash, e.g. `/a/c/b`
 */
export declare function requirePath(path: PossiblePath, base?: AbsolutePath, caller?: AnyCaller): AbsolutePath;
/**
 * Match and strip a base path prefix from a path using segment-aware pathname rules.
 * - Both inputs must be absolute paths that begin with `/`.
 * - Returns `/` when the paths are an exact match.
 */
export declare function matchPathPrefix(target: PossiblePath, base: PossiblePath, caller?: AnyCaller): AbsolutePath | undefined;
/** Is a target path active? */
export declare function isPathActive(target: AbsolutePath, current: AbsolutePath): boolean;
/** Is a target path proud (i.e. is the current path, or is a child of the current path)? */
export declare function isPathProud(target: AbsolutePath, current: AbsolutePath): boolean;
/**
 * Get the "segments" in an absolute path.
 * - `splitPath("/")` returns `[]` — the root has no segments.
 */
export declare function splitPath(path: PossiblePath): readonly string[];
/** A single argument accepted by `joinPath()` — either a string (full path or single segment) or an array of segments. */
export type PathPart = string | readonly string[];
/**
 * Join one or more path parts into a single path string.
 * - Each part can be a string (e.g. `"/foo/bar"`, `"foo"`) or an array of segments (e.g. `["foo", "bar"]`). String parts may themselves contain `/` separators — they're flattened and normalised.
 * - Runs of `//` are collapsed and trailing slashes stripped (via `cleanPath()`); `\` Windows slashes are converted too.
 * - If the first argument is an `AbsolutePath` string (starts with `/`), the result is also an `AbsolutePath`; otherwise the return type is `string`.
 *
 * @example joinPath("/foo", "bar") // → "/foo/bar"
 * @example joinPath("/foo", ["bar", "baz"]) // → "/foo/bar/baz"
 * @example joinPath(["foo", "bar"], "baz") // → "foo/bar/baz" (relative — no leading slash)
 * @example joinPath("/a/", "/b/") // → "/a/b" (slashes normalised)
 * @example joinPath("/") // → "/"
 */
export declare function joinPath(first: AbsolutePath, ...rest: PathPart[]): AbsolutePath;
export declare function joinPath(...parts: PathPart[]): string;