@lifaon/path
Version:
Useful tool to manage paths like the URL object
165 lines (164 loc) • 6.13 kB
TypeScript
import type { IPathPlatformConfig } from '../types/platform-config/path-platform-config.type.js';
import type { IWindowsPathPlatformConfig } from '../types/platform-config/windows-path-platform-config.type.js';
import type { ISpecialSegmentsAllowedForBasename } from '../types/segments/special-segments-allowed-for-basename.type.js';
import type { IPathInput } from '../types/path-input.type.js';
import type { IPathSegments } from '../types/segments/path-segments.type.js';
import type { IStemAndExtTuple } from '../types/stem-and-ext-tuple.type.js';
/**
* A class to manipulate Paths.
*/
export declare class Path {
static get posix(): IPathPlatformConfig;
static get windows(): IWindowsPathPlatformConfig;
static get generic(): IPathPlatformConfig;
static get currentPlatform(): IPathPlatformConfig | never;
/**
* Returns the current process working directory as a `Path`.
*/
static process(config?: IPathPlatformConfig): Path | never;
/**
* If `path` is a `Path`, returns `path`,
* else creates a `Path` from `path`.
* => useful if you want to accept many types as the `path` input of a function without sacrificing performances
*/
static of(path: IPathInput, config?: IPathPlatformConfig): Path;
readonly segments: IPathSegments;
readonly config: IPathPlatformConfig;
constructor(path: IPathInput, config?: IPathPlatformConfig);
/**
* Returns `true` if this Path is absolute.
*/
isAbsolute(): boolean;
/**
* Returns `true` if this Path is a pure root (ex: `c:` or `/`).
*/
isRoot(): boolean;
/**
* Returns true if this Path is a sub-path of `path` (after normalization).
*
* @example:
* `new Path('a/b/').isSubPathOf('a/')` => `true`
*/
isSubPathOf(parentPath: IPathInput): boolean;
/**
* Returns `true` if this Path is equal to `path` (after normalization).
*
* @example:
* `new Path('a/b/').equals('a/c/../b')` => `true`
*/
equals(path: IPathInput): boolean;
/**
* Returns the parent directory's Path of this Path.
* If this operation cannot be performed (ex: this Path is a "root"), the function throws.
*
* @example:
* `new Path('a/b').dirname()` => `./a`
* `new Path('c:/').dirname()` => throws
*/
dirname(): Path | never;
/**
* Like `.dirname()`, but returns `null` instead of throwing.
*
* @see dirname
*/
dirnameOptional(): Path | null;
/**
* Returns the basename of this Path:
* - if `ext` is provided, `ext` is removed from the basename
* - the function throws if the basename is special (ex: relative or root) and `allowedSpecialSegments` doesn't include it
*
* @param ext - default: `''`
* @param allowedSpecialSegments - default: `new Set()`
*
* @example:
* `new Path('/a/b').basename()` => 'b'
* `new Path('/').basename()` => throws
*/
basename(ext?: string, allowedSpecialSegments?: Iterable<ISpecialSegmentsAllowedForBasename>): string | never;
/**
* Like `.basename(...)`, but returns `null` instead of throwing.
*
* @see basename
*/
basenameOptional(ext?: string, allowedSpecialSegments?: Iterable<ISpecialSegmentsAllowedForBasename>): string | null;
/**
* Returns a tuple composed of the stem and the extension of the basename of this Path.
* If this operation cannot be performed (ex: this Path is a "root"), the function throws.
*/
stemAndExt(): IStemAndExtTuple | never;
/**
* Like `.stemAndExt(...)`, but returns `null` instead of throwing.
*
* @see stemAndExt
*/
stemAndExtOptional(): IStemAndExtTuple | null;
/**
* Returns the common base between this Path, and each `paths`:
* - if no common base are found, the function throws.
*
* @example:
* `new Path('a/b/').commonBase('a/c')` => `./a`
* `new Path('/a/b/').commonBase('d/e')` => throws
*/
commonBase(...paths: IPathInput[]): Path | never;
/**
* Like `.commonBase(...)`, but returns `null` instead of throwing.
* @see commonBase
*/
commonBaseOptional(...paths: IPathInput[]): Path | null;
/**
* Returns the relative Path from this Path to `path` (after normalization)
* - the function throw if it's not possible to reach `path` from this Path.
*
* @example:
* `new Path('a/b/').relative('a/d')` => `../d`
* `new Path('a/b/').relative('/a/d')` => throws
*/
relative(path: IPathInput): Path | never;
/**
* Like `.relative(...)`, but returns `null` instead of throwing.
* @see relative
*/
relativeOptional(path: IPathInput): Path | null;
/**
* Returns a new Path composed of this Path followed by 'paths'
* - equivalent of path.join() of NodeJS
*
* @example:
* - `new Path('./a').concat('b')` => `./a/b`
*/
concat(...paths: IPathInput[]): Path;
/**
* Returns a new absolute Path from this Path:
* - if this Path is absolute, this function returns a cloned path,
* - else it appends `root` before this Path
*
* @param root - default: `process.cwd()`
*/
resolve(root?: IPathInput): Path;
/**
* Clones the path. Kind of new Path(this, config) but faster.
*/
clone(config?: IPathPlatformConfig): Path;
/**
* Forces this Path to be converted to an absolute Path IF it is not already absolute.
*
* @param root - default: `process.cwd()`
*/
makeAbsolute(root?: IPathInput): Path;
/**
* Forces this Path to be converted to a relative path IF it is not already relative.
* => it replaces Path's first segment (the root) with '.'
*/
makeRelative(): Path;
/**
* Returns the concatenated string of the different segments of this Path, separated by `separa
* tor`.
* @param separator - default: `config.separator`
*/
toString(separator?: string): string;
/**
* Returns a 'file://' url having this Path as pathname
*/
toURL(): URL;
}