shelving/util/path.d.ts

Toolkit for using data in JavaScript.

import type { AnyCaller } from "./function.js";
import { type Optional } from "./optional.js";
/** Absolute path string starts with `/` slash. */
export type AbsolutePath = `/` | `/${string}`;
/** Relative path string starts with `./` or `../` */
export type RelativePath = `.` | `./${string}` | `..` | `../${string}`;
/** Either an absolute path string or a relative path string. */
export type Path = AbsolutePath | RelativePath;
/** Is a string path an absolute path? */
export declare function isAbsolutePath(path: string): path is AbsolutePath;
/** Is a string path an absolute path? */
export declare function isRelativePath(path: string): path is RelativePath;
/**
 * Resolve a relative or absolute path and return the absolute path, or `undefined` if not a valid path.
 * - Uses `new URL` to do path processing, so URL strings can also be resolved.
 * - Returned paths are cleaned with `cleanPath()` so runs of slashes and trailing slashes are removed.
 *
 * @param value 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 getPath(value: Optional<string | URL>, base?: AbsolutePath | undefined): AbsolutePath | undefined;
/**
 * 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 value 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(value: string, base?: AbsolutePath, caller?: AnyCaller): AbsolutePath;
/** 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;