1107 lines
No EOL
39 KiB
TypeScript
Executable file
1107 lines
No EOL
39 KiB
TypeScript
Executable file
/// <reference types="node" />
|
|
/// <reference types="node" />
|
|
/// <reference types="node" />
|
|
import { LRUCache } from 'lru-cache';
|
|
import { posix, win32 } from 'path';
|
|
import type { Dirent, Stats } from 'fs';
|
|
import { Minipass } from 'minipass';
|
|
/**
|
|
* An object that will be used to override the default `fs`
|
|
* methods. Any methods that are not overridden will use Node's
|
|
* built-in implementations.
|
|
*
|
|
* - lstatSync
|
|
* - readdir (callback `withFileTypes` Dirent variant, used for
|
|
* readdirCB and most walks)
|
|
* - readdirSync
|
|
* - readlinkSync
|
|
* - realpathSync
|
|
* - promises: Object containing the following async methods:
|
|
* - lstat
|
|
* - readdir (Dirent variant only)
|
|
* - readlink
|
|
* - realpath
|
|
*/
|
|
export interface FSOption {
|
|
lstatSync?: (path: string) => Stats;
|
|
readdir?: (path: string, options: {
|
|
withFileTypes: true;
|
|
}, cb: (er: NodeJS.ErrnoException | null, entries?: Dirent[]) => any) => void;
|
|
readdirSync?: (path: string, options: {
|
|
withFileTypes: true;
|
|
}) => Dirent[];
|
|
readlinkSync?: (path: string) => string;
|
|
realpathSync?: (path: string) => string;
|
|
promises?: {
|
|
lstat?: (path: string) => Promise<Stats>;
|
|
readdir?: (path: string, options: {
|
|
withFileTypes: true;
|
|
}) => Promise<Dirent[]>;
|
|
readlink?: (path: string) => Promise<string>;
|
|
realpath?: (path: string) => Promise<string>;
|
|
[k: string]: any;
|
|
};
|
|
[k: string]: any;
|
|
}
|
|
interface FSValue {
|
|
lstatSync: (path: string) => Stats;
|
|
readdir: (path: string, options: {
|
|
withFileTypes: true;
|
|
}, cb: (er: NodeJS.ErrnoException | null, entries?: Dirent[]) => any) => void;
|
|
readdirSync: (path: string, options: {
|
|
withFileTypes: true;
|
|
}) => Dirent[];
|
|
readlinkSync: (path: string) => string;
|
|
realpathSync: (path: string) => string;
|
|
promises: {
|
|
lstat: (path: string) => Promise<Stats>;
|
|
readdir: (path: string, options: {
|
|
withFileTypes: true;
|
|
}) => Promise<Dirent[]>;
|
|
readlink: (path: string) => Promise<string>;
|
|
realpath: (path: string) => Promise<string>;
|
|
[k: string]: any;
|
|
};
|
|
[k: string]: any;
|
|
}
|
|
export type Type = 'Unknown' | 'FIFO' | 'CharacterDevice' | 'Directory' | 'BlockDevice' | 'File' | 'SymbolicLink' | 'Socket';
|
|
/**
|
|
* Options that may be provided to the Path constructor
|
|
*/
|
|
export interface PathOpts {
|
|
fullpath?: string;
|
|
relative?: string;
|
|
relativePosix?: string;
|
|
parent?: PathBase;
|
|
/**
|
|
* See {@link FSOption}
|
|
*/
|
|
fs?: FSOption;
|
|
}
|
|
/**
|
|
* An LRUCache for storing resolved path strings or Path objects.
|
|
* @internal
|
|
*/
|
|
export declare class ResolveCache extends LRUCache<string, string> {
|
|
constructor();
|
|
}
|
|
/**
|
|
* an LRUCache for storing child entries.
|
|
* @internal
|
|
*/
|
|
export declare class ChildrenCache extends LRUCache<PathBase, Children> {
|
|
constructor(maxSize?: number);
|
|
}
|
|
/**
|
|
* Array of Path objects, plus a marker indicating the first provisional entry
|
|
*
|
|
* @internal
|
|
*/
|
|
export type Children = PathBase[] & {
|
|
provisional: number;
|
|
};
|
|
declare const setAsCwd: unique symbol;
|
|
/**
|
|
* Path objects are sort of like a super-powered
|
|
* {@link https://nodejs.org/docs/latest/api/fs.html#class-fsdirent fs.Dirent}
|
|
*
|
|
* Each one represents a single filesystem entry on disk, which may or may not
|
|
* exist. It includes methods for reading various types of information via
|
|
* lstat, readlink, and readdir, and caches all information to the greatest
|
|
* degree possible.
|
|
*
|
|
* Note that fs operations that would normally throw will instead return an
|
|
* "empty" value. This is in order to prevent excessive overhead from error
|
|
* stack traces.
|
|
*/
|
|
export declare abstract class PathBase implements Dirent {
|
|
#private;
|
|
/**
|
|
* the basename of this path
|
|
*
|
|
* **Important**: *always* test the path name against any test string
|
|
* usingthe {@link isNamed} method, and not by directly comparing this
|
|
* string. Otherwise, unicode path strings that the system sees as identical
|
|
* will not be properly treated as the same path, leading to incorrect
|
|
* behavior and possible security issues.
|
|
*/
|
|
name: string;
|
|
/**
|
|
* the Path entry corresponding to the path root.
|
|
*
|
|
* @internal
|
|
*/
|
|
root: PathBase;
|
|
/**
|
|
* All roots found within the current PathScurry family
|
|
*
|
|
* @internal
|
|
*/
|
|
roots: {
|
|
[k: string]: PathBase;
|
|
};
|
|
/**
|
|
* a reference to the parent path, or undefined in the case of root entries
|
|
*
|
|
* @internal
|
|
*/
|
|
parent?: PathBase;
|
|
/**
|
|
* boolean indicating whether paths are compared case-insensitively
|
|
* @internal
|
|
*/
|
|
nocase: boolean;
|
|
/**
|
|
* the string or regexp used to split paths. On posix, it is `'/'`, and on
|
|
* windows it is a RegExp matching either `'/'` or `'\\'`
|
|
*/
|
|
abstract splitSep: string | RegExp;
|
|
/**
|
|
* The path separator string to use when joining paths
|
|
*/
|
|
abstract sep: string;
|
|
get dev(): number | undefined;
|
|
get mode(): number | undefined;
|
|
get nlink(): number | undefined;
|
|
get uid(): number | undefined;
|
|
get gid(): number | undefined;
|
|
get rdev(): number | undefined;
|
|
get blksize(): number | undefined;
|
|
get ino(): number | undefined;
|
|
get size(): number | undefined;
|
|
get blocks(): number | undefined;
|
|
get atimeMs(): number | undefined;
|
|
get mtimeMs(): number | undefined;
|
|
get ctimeMs(): number | undefined;
|
|
get birthtimeMs(): number | undefined;
|
|
get atime(): Date | undefined;
|
|
get mtime(): Date | undefined;
|
|
get ctime(): Date | undefined;
|
|
get birthtime(): Date | undefined;
|
|
/**
|
|
* This property is for compatibility with the Dirent class as of
|
|
* Node v20, where Dirent['path'] refers to the path of the directory
|
|
* that was passed to readdir. So, somewhat counterintuitively, this
|
|
* property refers to the *parent* path, not the path object itself.
|
|
* For root entries, it's the path to the entry itself.
|
|
*/
|
|
get path(): string;
|
|
/**
|
|
* Do not create new Path objects directly. They should always be accessed
|
|
* via the PathScurry class or other methods on the Path class.
|
|
*
|
|
* @internal
|
|
*/
|
|
constructor(name: string, type: number | undefined, root: PathBase | undefined, roots: {
|
|
[k: string]: PathBase;
|
|
}, nocase: boolean, children: ChildrenCache, opts: PathOpts);
|
|
/**
|
|
* Returns the depth of the Path object from its root.
|
|
*
|
|
* For example, a path at `/foo/bar` would have a depth of 2.
|
|
*/
|
|
depth(): number;
|
|
/**
|
|
* @internal
|
|
*/
|
|
abstract getRootString(path: string): string;
|
|
/**
|
|
* @internal
|
|
*/
|
|
abstract getRoot(rootPath: string): PathBase;
|
|
/**
|
|
* @internal
|
|
*/
|
|
abstract newChild(name: string, type?: number, opts?: PathOpts): PathBase;
|
|
/**
|
|
* @internal
|
|
*/
|
|
childrenCache(): ChildrenCache;
|
|
/**
|
|
* Get the Path object referenced by the string path, resolved from this Path
|
|
*/
|
|
resolve(path?: string): PathBase;
|
|
/**
|
|
* Returns the cached children Path objects, if still available. If they
|
|
* have fallen out of the cache, then returns an empty array, and resets the
|
|
* READDIR_CALLED bit, so that future calls to readdir() will require an fs
|
|
* lookup.
|
|
*
|
|
* @internal
|
|
*/
|
|
children(): Children;
|
|
/**
|
|
* Resolves a path portion and returns or creates the child Path.
|
|
*
|
|
* Returns `this` if pathPart is `''` or `'.'`, or `parent` if pathPart is
|
|
* `'..'`.
|
|
*
|
|
* This should not be called directly. If `pathPart` contains any path
|
|
* separators, it will lead to unsafe undefined behavior.
|
|
*
|
|
* Use `Path.resolve()` instead.
|
|
*
|
|
* @internal
|
|
*/
|
|
child(pathPart: string, opts?: PathOpts): PathBase;
|
|
/**
|
|
* The relative path from the cwd. If it does not share an ancestor with
|
|
* the cwd, then this ends up being equivalent to the fullpath()
|
|
*/
|
|
relative(): string;
|
|
/**
|
|
* The relative path from the cwd, using / as the path separator.
|
|
* If it does not share an ancestor with
|
|
* the cwd, then this ends up being equivalent to the fullpathPosix()
|
|
* On posix systems, this is identical to relative().
|
|
*/
|
|
relativePosix(): string;
|
|
/**
|
|
* The fully resolved path string for this Path entry
|
|
*/
|
|
fullpath(): string;
|
|
/**
|
|
* On platforms other than windows, this is identical to fullpath.
|
|
*
|
|
* On windows, this is overridden to return the forward-slash form of the
|
|
* full UNC path.
|
|
*/
|
|
fullpathPosix(): string;
|
|
/**
|
|
* Is the Path of an unknown type?
|
|
*
|
|
* Note that we might know *something* about it if there has been a previous
|
|
* filesystem operation, for example that it does not exist, or is not a
|
|
* link, or whether it has child entries.
|
|
*/
|
|
isUnknown(): boolean;
|
|
isType(type: Type): boolean;
|
|
getType(): Type;
|
|
/**
|
|
* Is the Path a regular file?
|
|
*/
|
|
isFile(): boolean;
|
|
/**
|
|
* Is the Path a directory?
|
|
*/
|
|
isDirectory(): boolean;
|
|
/**
|
|
* Is the path a character device?
|
|
*/
|
|
isCharacterDevice(): boolean;
|
|
/**
|
|
* Is the path a block device?
|
|
*/
|
|
isBlockDevice(): boolean;
|
|
/**
|
|
* Is the path a FIFO pipe?
|
|
*/
|
|
isFIFO(): boolean;
|
|
/**
|
|
* Is the path a socket?
|
|
*/
|
|
isSocket(): boolean;
|
|
/**
|
|
* Is the path a symbolic link?
|
|
*/
|
|
isSymbolicLink(): boolean;
|
|
/**
|
|
* Return the entry if it has been subject of a successful lstat, or
|
|
* undefined otherwise.
|
|
*
|
|
* Does not read the filesystem, so an undefined result *could* simply
|
|
* mean that we haven't called lstat on it.
|
|
*/
|
|
lstatCached(): PathBase | undefined;
|
|
/**
|
|
* Return the cached link target if the entry has been the subject of a
|
|
* successful readlink, or undefined otherwise.
|
|
*
|
|
* Does not read the filesystem, so an undefined result *could* just mean we
|
|
* don't have any cached data. Only use it if you are very sure that a
|
|
* readlink() has been called at some point.
|
|
*/
|
|
readlinkCached(): PathBase | undefined;
|
|
/**
|
|
* Returns the cached realpath target if the entry has been the subject
|
|
* of a successful realpath, or undefined otherwise.
|
|
*
|
|
* Does not read the filesystem, so an undefined result *could* just mean we
|
|
* don't have any cached data. Only use it if you are very sure that a
|
|
* realpath() has been called at some point.
|
|
*/
|
|
realpathCached(): PathBase | undefined;
|
|
/**
|
|
* Returns the cached child Path entries array if the entry has been the
|
|
* subject of a successful readdir(), or [] otherwise.
|
|
*
|
|
* Does not read the filesystem, so an empty array *could* just mean we
|
|
* don't have any cached data. Only use it if you are very sure that a
|
|
* readdir() has been called recently enough to still be valid.
|
|
*/
|
|
readdirCached(): PathBase[];
|
|
/**
|
|
* Return true if it's worth trying to readlink. Ie, we don't (yet) have
|
|
* any indication that readlink will definitely fail.
|
|
*
|
|
* Returns false if the path is known to not be a symlink, if a previous
|
|
* readlink failed, or if the entry does not exist.
|
|
*/
|
|
canReadlink(): boolean;
|
|
/**
|
|
* Return true if readdir has previously been successfully called on this
|
|
* path, indicating that cachedReaddir() is likely valid.
|
|
*/
|
|
calledReaddir(): boolean;
|
|
/**
|
|
* Returns true if the path is known to not exist. That is, a previous lstat
|
|
* or readdir failed to verify its existence when that would have been
|
|
* expected, or a parent entry was marked either enoent or enotdir.
|
|
*/
|
|
isENOENT(): boolean;
|
|
/**
|
|
* Return true if the path is a match for the given path name. This handles
|
|
* case sensitivity and unicode normalization.
|
|
*
|
|
* Note: even on case-sensitive systems, it is **not** safe to test the
|
|
* equality of the `.name` property to determine whether a given pathname
|
|
* matches, due to unicode normalization mismatches.
|
|
*
|
|
* Always use this method instead of testing the `path.name` property
|
|
* directly.
|
|
*/
|
|
isNamed(n: string): boolean;
|
|
/**
|
|
* Return the Path object corresponding to the target of a symbolic link.
|
|
*
|
|
* If the Path is not a symbolic link, or if the readlink call fails for any
|
|
* reason, `undefined` is returned.
|
|
*
|
|
* Result is cached, and thus may be outdated if the filesystem is mutated.
|
|
*/
|
|
readlink(): Promise<PathBase | undefined>;
|
|
/**
|
|
* Synchronous {@link PathBase.readlink}
|
|
*/
|
|
readlinkSync(): PathBase | undefined;
|
|
/**
|
|
* Call lstat() on this Path, and update all known information that can be
|
|
* determined.
|
|
*
|
|
* Note that unlike `fs.lstat()`, the returned value does not contain some
|
|
* information, such as `mode`, `dev`, `nlink`, and `ino`. If that
|
|
* information is required, you will need to call `fs.lstat` yourself.
|
|
*
|
|
* If the Path refers to a nonexistent file, or if the lstat call fails for
|
|
* any reason, `undefined` is returned. Otherwise the updated Path object is
|
|
* returned.
|
|
*
|
|
* Results are cached, and thus may be out of date if the filesystem is
|
|
* mutated.
|
|
*/
|
|
lstat(): Promise<PathBase | undefined>;
|
|
/**
|
|
* synchronous {@link PathBase.lstat}
|
|
*/
|
|
lstatSync(): PathBase | undefined;
|
|
/**
|
|
* Standard node-style callback interface to get list of directory entries.
|
|
*
|
|
* If the Path cannot or does not contain any children, then an empty array
|
|
* is returned.
|
|
*
|
|
* Results are cached, and thus may be out of date if the filesystem is
|
|
* mutated.
|
|
*
|
|
* @param cb The callback called with (er, entries). Note that the `er`
|
|
* param is somewhat extraneous, as all readdir() errors are handled and
|
|
* simply result in an empty set of entries being returned.
|
|
* @param allowZalgo Boolean indicating that immediately known results should
|
|
* *not* be deferred with `queueMicrotask`. Defaults to `false`. Release
|
|
* zalgo at your peril, the dark pony lord is devious and unforgiving.
|
|
*/
|
|
readdirCB(cb: (er: NodeJS.ErrnoException | null, entries: PathBase[]) => any, allowZalgo?: boolean): void;
|
|
/**
|
|
* Return an array of known child entries.
|
|
*
|
|
* If the Path cannot or does not contain any children, then an empty array
|
|
* is returned.
|
|
*
|
|
* Results are cached, and thus may be out of date if the filesystem is
|
|
* mutated.
|
|
*/
|
|
readdir(): Promise<PathBase[]>;
|
|
/**
|
|
* synchronous {@link PathBase.readdir}
|
|
*/
|
|
readdirSync(): PathBase[];
|
|
canReaddir(): boolean;
|
|
shouldWalk(dirs: Set<PathBase | undefined>, walkFilter?: (e: PathBase) => boolean): boolean;
|
|
/**
|
|
* Return the Path object corresponding to path as resolved
|
|
* by realpath(3).
|
|
*
|
|
* If the realpath call fails for any reason, `undefined` is returned.
|
|
*
|
|
* Result is cached, and thus may be outdated if the filesystem is mutated.
|
|
* On success, returns a Path object.
|
|
*/
|
|
realpath(): Promise<PathBase | undefined>;
|
|
/**
|
|
* Synchronous {@link realpath}
|
|
*/
|
|
realpathSync(): PathBase | undefined;
|
|
/**
|
|
* Internal method to mark this Path object as the scurry cwd,
|
|
* called by {@link PathScurry#chdir}
|
|
*
|
|
* @internal
|
|
*/
|
|
[setAsCwd](oldCwd: PathBase): void;
|
|
}
|
|
/**
|
|
* Path class used on win32 systems
|
|
*
|
|
* Uses `'\\'` as the path separator for returned paths, either `'\\'` or `'/'`
|
|
* as the path separator for parsing paths.
|
|
*/
|
|
export declare class PathWin32 extends PathBase {
|
|
/**
|
|
* Separator for generating path strings.
|
|
*/
|
|
sep: '\\';
|
|
/**
|
|
* Separator for parsing path strings.
|
|
*/
|
|
splitSep: RegExp;
|
|
/**
|
|
* Do not create new Path objects directly. They should always be accessed
|
|
* via the PathScurry class or other methods on the Path class.
|
|
*
|
|
* @internal
|
|
*/
|
|
constructor(name: string, type: number | undefined, root: PathBase | undefined, roots: {
|
|
[k: string]: PathBase;
|
|
}, nocase: boolean, children: ChildrenCache, opts: PathOpts);
|
|
/**
|
|
* @internal
|
|
*/
|
|
newChild(name: string, type?: number, opts?: PathOpts): PathWin32;
|
|
/**
|
|
* @internal
|
|
*/
|
|
getRootString(path: string): string;
|
|
/**
|
|
* @internal
|
|
*/
|
|
getRoot(rootPath: string): PathBase;
|
|
/**
|
|
* @internal
|
|
*/
|
|
sameRoot(rootPath: string, compare?: string): boolean;
|
|
}
|
|
/**
|
|
* Path class used on all posix systems.
|
|
*
|
|
* Uses `'/'` as the path separator.
|
|
*/
|
|
export declare class PathPosix extends PathBase {
|
|
/**
|
|
* separator for parsing path strings
|
|
*/
|
|
splitSep: '/';
|
|
/**
|
|
* separator for generating path strings
|
|
*/
|
|
sep: '/';
|
|
/**
|
|
* Do not create new Path objects directly. They should always be accessed
|
|
* via the PathScurry class or other methods on the Path class.
|
|
*
|
|
* @internal
|
|
*/
|
|
constructor(name: string, type: number | undefined, root: PathBase | undefined, roots: {
|
|
[k: string]: PathBase;
|
|
}, nocase: boolean, children: ChildrenCache, opts: PathOpts);
|
|
/**
|
|
* @internal
|
|
*/
|
|
getRootString(path: string): string;
|
|
/**
|
|
* @internal
|
|
*/
|
|
getRoot(_rootPath: string): PathBase;
|
|
/**
|
|
* @internal
|
|
*/
|
|
newChild(name: string, type?: number, opts?: PathOpts): PathPosix;
|
|
}
|
|
/**
|
|
* Options that may be provided to the PathScurry constructor
|
|
*/
|
|
export interface PathScurryOpts {
|
|
/**
|
|
* perform case-insensitive path matching. Default based on platform
|
|
* subclass.
|
|
*/
|
|
nocase?: boolean;
|
|
/**
|
|
* Number of Path entries to keep in the cache of Path child references.
|
|
*
|
|
* Setting this higher than 65536 will dramatically increase the data
|
|
* consumption and construction time overhead of each PathScurry.
|
|
*
|
|
* Setting this value to 256 or lower will significantly reduce the data
|
|
* consumption and construction time overhead, but may also reduce resolve()
|
|
* and readdir() performance on large filesystems.
|
|
*
|
|
* Default `16384`.
|
|
*/
|
|
childrenCacheSize?: number;
|
|
/**
|
|
* An object that overrides the built-in functions from the fs and
|
|
* fs/promises modules.
|
|
*
|
|
* See {@link FSOption}
|
|
*/
|
|
fs?: FSOption;
|
|
}
|
|
/**
|
|
* The base class for all PathScurry classes, providing the interface for path
|
|
* resolution and filesystem operations.
|
|
*
|
|
* Typically, you should *not* instantiate this class directly, but rather one
|
|
* of the platform-specific classes, or the exported {@link PathScurry} which
|
|
* defaults to the current platform.
|
|
*/
|
|
export declare abstract class PathScurryBase {
|
|
#private;
|
|
/**
|
|
* The root Path entry for the current working directory of this Scurry
|
|
*/
|
|
root: PathBase;
|
|
/**
|
|
* The string path for the root of this Scurry's current working directory
|
|
*/
|
|
rootPath: string;
|
|
/**
|
|
* A collection of all roots encountered, referenced by rootPath
|
|
*/
|
|
roots: {
|
|
[k: string]: PathBase;
|
|
};
|
|
/**
|
|
* The Path entry corresponding to this PathScurry's current working directory.
|
|
*/
|
|
cwd: PathBase;
|
|
/**
|
|
* Perform path comparisons case-insensitively.
|
|
*
|
|
* Defaults true on Darwin and Windows systems, false elsewhere.
|
|
*/
|
|
nocase: boolean;
|
|
/**
|
|
* The path separator used for parsing paths
|
|
*
|
|
* `'/'` on Posix systems, either `'/'` or `'\\'` on Windows
|
|
*/
|
|
abstract sep: string | RegExp;
|
|
/**
|
|
* This class should not be instantiated directly.
|
|
*
|
|
* Use PathScurryWin32, PathScurryDarwin, PathScurryPosix, or PathScurry
|
|
*
|
|
* @internal
|
|
*/
|
|
constructor(cwd: string | URL | undefined, pathImpl: typeof win32 | typeof posix, sep: string | RegExp, { nocase, childrenCacheSize, fs, }?: PathScurryOpts);
|
|
/**
|
|
* Get the depth of a provided path, string, or the cwd
|
|
*/
|
|
depth(path?: Path | string): number;
|
|
/**
|
|
* Parse the root portion of a path string
|
|
*
|
|
* @internal
|
|
*/
|
|
abstract parseRootPath(dir: string): string;
|
|
/**
|
|
* create a new Path to use as root during construction.
|
|
*
|
|
* @internal
|
|
*/
|
|
abstract newRoot(fs: FSValue): PathBase;
|
|
/**
|
|
* Determine whether a given path string is absolute
|
|
*/
|
|
abstract isAbsolute(p: string): boolean;
|
|
/**
|
|
* Return the cache of child entries. Exposed so subclasses can create
|
|
* child Path objects in a platform-specific way.
|
|
*
|
|
* @internal
|
|
*/
|
|
childrenCache(): ChildrenCache;
|
|
/**
|
|
* Resolve one or more path strings to a resolved string
|
|
*
|
|
* Same interface as require('path').resolve.
|
|
*
|
|
* Much faster than path.resolve() when called multiple times for the same
|
|
* path, because the resolved Path objects are cached. Much slower
|
|
* otherwise.
|
|
*/
|
|
resolve(...paths: string[]): string;
|
|
/**
|
|
* Resolve one or more path strings to a resolved string, returning
|
|
* the posix path. Identical to .resolve() on posix systems, but on
|
|
* windows will return a forward-slash separated UNC path.
|
|
*
|
|
* Same interface as require('path').resolve.
|
|
*
|
|
* Much faster than path.resolve() when called multiple times for the same
|
|
* path, because the resolved Path objects are cached. Much slower
|
|
* otherwise.
|
|
*/
|
|
resolvePosix(...paths: string[]): string;
|
|
/**
|
|
* find the relative path from the cwd to the supplied path string or entry
|
|
*/
|
|
relative(entry?: PathBase | string): string;
|
|
/**
|
|
* find the relative path from the cwd to the supplied path string or
|
|
* entry, using / as the path delimiter, even on Windows.
|
|
*/
|
|
relativePosix(entry?: PathBase | string): string;
|
|
/**
|
|
* Return the basename for the provided string or Path object
|
|
*/
|
|
basename(entry?: PathBase | string): string;
|
|
/**
|
|
* Return the dirname for the provided string or Path object
|
|
*/
|
|
dirname(entry?: PathBase | string): string;
|
|
/**
|
|
* Return an array of known child entries.
|
|
*
|
|
* First argument may be either a string, or a Path object.
|
|
*
|
|
* If the Path cannot or does not contain any children, then an empty array
|
|
* is returned.
|
|
*
|
|
* Results are cached, and thus may be out of date if the filesystem is
|
|
* mutated.
|
|
*
|
|
* Unlike `fs.readdir()`, the `withFileTypes` option defaults to `true`. Set
|
|
* `{ withFileTypes: false }` to return strings.
|
|
*/
|
|
readdir(): Promise<PathBase[]>;
|
|
readdir(opts: {
|
|
withFileTypes: true;
|
|
}): Promise<PathBase[]>;
|
|
readdir(opts: {
|
|
withFileTypes: false;
|
|
}): Promise<string[]>;
|
|
readdir(opts: {
|
|
withFileTypes: boolean;
|
|
}): Promise<PathBase[] | string[]>;
|
|
readdir(entry: PathBase | string): Promise<PathBase[]>;
|
|
readdir(entry: PathBase | string, opts: {
|
|
withFileTypes: true;
|
|
}): Promise<PathBase[]>;
|
|
readdir(entry: PathBase | string, opts: {
|
|
withFileTypes: false;
|
|
}): Promise<string[]>;
|
|
readdir(entry: PathBase | string, opts: {
|
|
withFileTypes: boolean;
|
|
}): Promise<PathBase[] | string[]>;
|
|
/**
|
|
* synchronous {@link PathScurryBase.readdir}
|
|
*/
|
|
readdirSync(): PathBase[];
|
|
readdirSync(opts: {
|
|
withFileTypes: true;
|
|
}): PathBase[];
|
|
readdirSync(opts: {
|
|
withFileTypes: false;
|
|
}): string[];
|
|
readdirSync(opts: {
|
|
withFileTypes: boolean;
|
|
}): PathBase[] | string[];
|
|
readdirSync(entry: PathBase | string): PathBase[];
|
|
readdirSync(entry: PathBase | string, opts: {
|
|
withFileTypes: true;
|
|
}): PathBase[];
|
|
readdirSync(entry: PathBase | string, opts: {
|
|
withFileTypes: false;
|
|
}): string[];
|
|
readdirSync(entry: PathBase | string, opts: {
|
|
withFileTypes: boolean;
|
|
}): PathBase[] | string[];
|
|
/**
|
|
* Call lstat() on the string or Path object, and update all known
|
|
* information that can be determined.
|
|
*
|
|
* Note that unlike `fs.lstat()`, the returned value does not contain some
|
|
* information, such as `mode`, `dev`, `nlink`, and `ino`. If that
|
|
* information is required, you will need to call `fs.lstat` yourself.
|
|
*
|
|
* If the Path refers to a nonexistent file, or if the lstat call fails for
|
|
* any reason, `undefined` is returned. Otherwise the updated Path object is
|
|
* returned.
|
|
*
|
|
* Results are cached, and thus may be out of date if the filesystem is
|
|
* mutated.
|
|
*/
|
|
lstat(entry?: string | PathBase): Promise<PathBase | undefined>;
|
|
/**
|
|
* synchronous {@link PathScurryBase.lstat}
|
|
*/
|
|
lstatSync(entry?: string | PathBase): PathBase | undefined;
|
|
/**
|
|
* Return the Path object or string path corresponding to the target of a
|
|
* symbolic link.
|
|
*
|
|
* If the path is not a symbolic link, or if the readlink call fails for any
|
|
* reason, `undefined` is returned.
|
|
*
|
|
* Result is cached, and thus may be outdated if the filesystem is mutated.
|
|
*
|
|
* `{withFileTypes}` option defaults to `false`.
|
|
*
|
|
* On success, returns a Path object if `withFileTypes` option is true,
|
|
* otherwise a string.
|
|
*/
|
|
readlink(): Promise<string | undefined>;
|
|
readlink(opt: {
|
|
withFileTypes: false;
|
|
}): Promise<string | undefined>;
|
|
readlink(opt: {
|
|
withFileTypes: true;
|
|
}): Promise<PathBase | undefined>;
|
|
readlink(opt: {
|
|
withFileTypes: boolean;
|
|
}): Promise<PathBase | string | undefined>;
|
|
readlink(entry: string | PathBase, opt?: {
|
|
withFileTypes: false;
|
|
}): Promise<string | undefined>;
|
|
readlink(entry: string | PathBase, opt: {
|
|
withFileTypes: true;
|
|
}): Promise<PathBase | undefined>;
|
|
readlink(entry: string | PathBase, opt: {
|
|
withFileTypes: boolean;
|
|
}): Promise<string | PathBase | undefined>;
|
|
/**
|
|
* synchronous {@link PathScurryBase.readlink}
|
|
*/
|
|
readlinkSync(): string | undefined;
|
|
readlinkSync(opt: {
|
|
withFileTypes: false;
|
|
}): string | undefined;
|
|
readlinkSync(opt: {
|
|
withFileTypes: true;
|
|
}): PathBase | undefined;
|
|
readlinkSync(opt: {
|
|
withFileTypes: boolean;
|
|
}): PathBase | string | undefined;
|
|
readlinkSync(entry: string | PathBase, opt?: {
|
|
withFileTypes: false;
|
|
}): string | undefined;
|
|
readlinkSync(entry: string | PathBase, opt: {
|
|
withFileTypes: true;
|
|
}): PathBase | undefined;
|
|
readlinkSync(entry: string | PathBase, opt: {
|
|
withFileTypes: boolean;
|
|
}): string | PathBase | undefined;
|
|
/**
|
|
* Return the Path object or string path corresponding to path as resolved
|
|
* by realpath(3).
|
|
*
|
|
* If the realpath call fails for any reason, `undefined` is returned.
|
|
*
|
|
* Result is cached, and thus may be outdated if the filesystem is mutated.
|
|
*
|
|
* `{withFileTypes}` option defaults to `false`.
|
|
*
|
|
* On success, returns a Path object if `withFileTypes` option is true,
|
|
* otherwise a string.
|
|
*/
|
|
realpath(): Promise<string | undefined>;
|
|
realpath(opt: {
|
|
withFileTypes: false;
|
|
}): Promise<string | undefined>;
|
|
realpath(opt: {
|
|
withFileTypes: true;
|
|
}): Promise<PathBase | undefined>;
|
|
realpath(opt: {
|
|
withFileTypes: boolean;
|
|
}): Promise<PathBase | string | undefined>;
|
|
realpath(entry: string | PathBase, opt?: {
|
|
withFileTypes: false;
|
|
}): Promise<string | undefined>;
|
|
realpath(entry: string | PathBase, opt: {
|
|
withFileTypes: true;
|
|
}): Promise<PathBase | undefined>;
|
|
realpath(entry: string | PathBase, opt: {
|
|
withFileTypes: boolean;
|
|
}): Promise<string | PathBase | undefined>;
|
|
realpathSync(): string | undefined;
|
|
realpathSync(opt: {
|
|
withFileTypes: false;
|
|
}): string | undefined;
|
|
realpathSync(opt: {
|
|
withFileTypes: true;
|
|
}): PathBase | undefined;
|
|
realpathSync(opt: {
|
|
withFileTypes: boolean;
|
|
}): PathBase | string | undefined;
|
|
realpathSync(entry: string | PathBase, opt?: {
|
|
withFileTypes: false;
|
|
}): string | undefined;
|
|
realpathSync(entry: string | PathBase, opt: {
|
|
withFileTypes: true;
|
|
}): PathBase | undefined;
|
|
realpathSync(entry: string | PathBase, opt: {
|
|
withFileTypes: boolean;
|
|
}): string | PathBase | undefined;
|
|
/**
|
|
* Asynchronously walk the directory tree, returning an array of
|
|
* all path strings or Path objects found.
|
|
*
|
|
* Note that this will be extremely memory-hungry on large filesystems.
|
|
* In such cases, it may be better to use the stream or async iterator
|
|
* walk implementation.
|
|
*/
|
|
walk(): Promise<PathBase[]>;
|
|
walk(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Promise<PathBase[]>;
|
|
walk(opts: WalkOptionsWithFileTypesFalse): Promise<string[]>;
|
|
walk(opts: WalkOptions): Promise<string[] | PathBase[]>;
|
|
walk(entry: string | PathBase): Promise<PathBase[]>;
|
|
walk(entry: string | PathBase, opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Promise<PathBase[]>;
|
|
walk(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): Promise<string[]>;
|
|
walk(entry: string | PathBase, opts: WalkOptions): Promise<PathBase[] | string[]>;
|
|
/**
|
|
* Synchronously walk the directory tree, returning an array of
|
|
* all path strings or Path objects found.
|
|
*
|
|
* Note that this will be extremely memory-hungry on large filesystems.
|
|
* In such cases, it may be better to use the stream or async iterator
|
|
* walk implementation.
|
|
*/
|
|
walkSync(): PathBase[];
|
|
walkSync(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): PathBase[];
|
|
walkSync(opts: WalkOptionsWithFileTypesFalse): string[];
|
|
walkSync(opts: WalkOptions): string[] | PathBase[];
|
|
walkSync(entry: string | PathBase): PathBase[];
|
|
walkSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesUnset | WalkOptionsWithFileTypesTrue): PathBase[];
|
|
walkSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): string[];
|
|
walkSync(entry: string | PathBase, opts: WalkOptions): PathBase[] | string[];
|
|
/**
|
|
* Support for `for await`
|
|
*
|
|
* Alias for {@link PathScurryBase.iterate}
|
|
*
|
|
* Note: As of Node 19, this is very slow, compared to other methods of
|
|
* walking. Consider using {@link PathScurryBase.stream} if memory overhead
|
|
* and backpressure are concerns, or {@link PathScurryBase.walk} if not.
|
|
*/
|
|
[Symbol.asyncIterator](): AsyncGenerator<PathBase, void, void>;
|
|
/**
|
|
* Async generator form of {@link PathScurryBase.walk}
|
|
*
|
|
* Note: As of Node 19, this is very slow, compared to other methods of
|
|
* walking, especially if most/all of the directory tree has been previously
|
|
* walked. Consider using {@link PathScurryBase.stream} if memory overhead
|
|
* and backpressure are concerns, or {@link PathScurryBase.walk} if not.
|
|
*/
|
|
iterate(): AsyncGenerator<PathBase, void, void>;
|
|
iterate(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): AsyncGenerator<PathBase, void, void>;
|
|
iterate(opts: WalkOptionsWithFileTypesFalse): AsyncGenerator<string, void, void>;
|
|
iterate(opts: WalkOptions): AsyncGenerator<string | PathBase, void, void>;
|
|
iterate(entry: string | PathBase): AsyncGenerator<PathBase, void, void>;
|
|
iterate(entry: string | PathBase, opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): AsyncGenerator<PathBase, void, void>;
|
|
iterate(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): AsyncGenerator<string, void, void>;
|
|
iterate(entry: string | PathBase, opts: WalkOptions): AsyncGenerator<PathBase | string, void, void>;
|
|
/**
|
|
* Iterating over a PathScurry performs a synchronous walk.
|
|
*
|
|
* Alias for {@link PathScurryBase.iterateSync}
|
|
*/
|
|
[Symbol.iterator](): Generator<PathBase, void, void>;
|
|
iterateSync(): Generator<PathBase, void, void>;
|
|
iterateSync(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Generator<PathBase, void, void>;
|
|
iterateSync(opts: WalkOptionsWithFileTypesFalse): Generator<string, void, void>;
|
|
iterateSync(opts: WalkOptions): Generator<string | PathBase, void, void>;
|
|
iterateSync(entry: string | PathBase): Generator<PathBase, void, void>;
|
|
iterateSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Generator<PathBase, void, void>;
|
|
iterateSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): Generator<string, void, void>;
|
|
iterateSync(entry: string | PathBase, opts: WalkOptions): Generator<PathBase | string, void, void>;
|
|
/**
|
|
* Stream form of {@link PathScurryBase.walk}
|
|
*
|
|
* Returns a Minipass stream that emits {@link PathBase} objects by default,
|
|
* or strings if `{ withFileTypes: false }` is set in the options.
|
|
*/
|
|
stream(): Minipass<PathBase>;
|
|
stream(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Minipass<PathBase>;
|
|
stream(opts: WalkOptionsWithFileTypesFalse): Minipass<string>;
|
|
stream(opts: WalkOptions): Minipass<string | PathBase>;
|
|
stream(entry: string | PathBase): Minipass<PathBase>;
|
|
stream(entry: string | PathBase, opts: WalkOptionsWithFileTypesUnset | WalkOptionsWithFileTypesTrue): Minipass<PathBase>;
|
|
stream(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): Minipass<string>;
|
|
stream(entry: string | PathBase, opts: WalkOptions): Minipass<string> | Minipass<PathBase>;
|
|
/**
|
|
* Synchronous form of {@link PathScurryBase.stream}
|
|
*
|
|
* Returns a Minipass stream that emits {@link PathBase} objects by default,
|
|
* or strings if `{ withFileTypes: false }` is set in the options.
|
|
*
|
|
* Will complete the walk in a single tick if the stream is consumed fully.
|
|
* Otherwise, will pause as needed for stream backpressure.
|
|
*/
|
|
streamSync(): Minipass<PathBase>;
|
|
streamSync(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Minipass<PathBase>;
|
|
streamSync(opts: WalkOptionsWithFileTypesFalse): Minipass<string>;
|
|
streamSync(opts: WalkOptions): Minipass<string | PathBase>;
|
|
streamSync(entry: string | PathBase): Minipass<PathBase>;
|
|
streamSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesUnset | WalkOptionsWithFileTypesTrue): Minipass<PathBase>;
|
|
streamSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): Minipass<string>;
|
|
streamSync(entry: string | PathBase, opts: WalkOptions): Minipass<string> | Minipass<PathBase>;
|
|
chdir(path?: string | Path): void;
|
|
}
|
|
/**
|
|
* Options provided to all walk methods.
|
|
*/
|
|
export interface WalkOptions {
|
|
/**
|
|
* Return results as {@link PathBase} objects rather than strings.
|
|
* When set to false, results are fully resolved paths, as returned by
|
|
* {@link PathBase.fullpath}.
|
|
* @default true
|
|
*/
|
|
withFileTypes?: boolean;
|
|
/**
|
|
* Attempt to read directory entries from symbolic links. Otherwise, only
|
|
* actual directories are traversed. Regardless of this setting, a given
|
|
* target path will only ever be walked once, meaning that a symbolic link
|
|
* to a previously traversed directory will never be followed.
|
|
*
|
|
* Setting this imposes a slight performance penalty, because `readlink`
|
|
* must be called on all symbolic links encountered, in order to avoid
|
|
* infinite cycles.
|
|
* @default false
|
|
*/
|
|
follow?: boolean;
|
|
/**
|
|
* Only return entries where the provided function returns true.
|
|
*
|
|
* This will not prevent directories from being traversed, even if they do
|
|
* not pass the filter, though it will prevent directories themselves from
|
|
* being included in the result set. See {@link walkFilter}
|
|
*
|
|
* Asynchronous functions are not supported here.
|
|
*
|
|
* By default, if no filter is provided, all entries and traversed
|
|
* directories are included.
|
|
*/
|
|
filter?: (entry: PathBase) => boolean;
|
|
/**
|
|
* Only traverse directories (and in the case of {@link follow} being set to
|
|
* true, symbolic links to directories) if the provided function returns
|
|
* true.
|
|
*
|
|
* This will not prevent directories from being included in the result set,
|
|
* even if they do not pass the supplied filter function. See {@link filter}
|
|
* to do that.
|
|
*
|
|
* Asynchronous functions are not supported here.
|
|
*/
|
|
walkFilter?: (entry: PathBase) => boolean;
|
|
}
|
|
export type WalkOptionsWithFileTypesUnset = WalkOptions & {
|
|
withFileTypes?: undefined;
|
|
};
|
|
export type WalkOptionsWithFileTypesTrue = WalkOptions & {
|
|
withFileTypes: true;
|
|
};
|
|
export type WalkOptionsWithFileTypesFalse = WalkOptions & {
|
|
withFileTypes: false;
|
|
};
|
|
/**
|
|
* Windows implementation of {@link PathScurryBase}
|
|
*
|
|
* Defaults to case insensitve, uses `'\\'` to generate path strings. Uses
|
|
* {@link PathWin32} for Path objects.
|
|
*/
|
|
export declare class PathScurryWin32 extends PathScurryBase {
|
|
/**
|
|
* separator for generating path strings
|
|
*/
|
|
sep: '\\';
|
|
constructor(cwd?: URL | string, opts?: PathScurryOpts);
|
|
/**
|
|
* @internal
|
|
*/
|
|
parseRootPath(dir: string): string;
|
|
/**
|
|
* @internal
|
|
*/
|
|
newRoot(fs: FSValue): PathWin32;
|
|
/**
|
|
* Return true if the provided path string is an absolute path
|
|
*/
|
|
isAbsolute(p: string): boolean;
|
|
}
|
|
/**
|
|
* {@link PathScurryBase} implementation for all posix systems other than Darwin.
|
|
*
|
|
* Defaults to case-sensitive matching, uses `'/'` to generate path strings.
|
|
*
|
|
* Uses {@link PathPosix} for Path objects.
|
|
*/
|
|
export declare class PathScurryPosix extends PathScurryBase {
|
|
/**
|
|
* separator for generating path strings
|
|
*/
|
|
sep: '/';
|
|
constructor(cwd?: URL | string, opts?: PathScurryOpts);
|
|
/**
|
|
* @internal
|
|
*/
|
|
parseRootPath(_dir: string): string;
|
|
/**
|
|
* @internal
|
|
*/
|
|
newRoot(fs: FSValue): PathPosix;
|
|
/**
|
|
* Return true if the provided path string is an absolute path
|
|
*/
|
|
isAbsolute(p: string): boolean;
|
|
}
|
|
/**
|
|
* {@link PathScurryBase} implementation for Darwin (macOS) systems.
|
|
*
|
|
* Defaults to case-insensitive matching, uses `'/'` for generating path
|
|
* strings.
|
|
*
|
|
* Uses {@link PathPosix} for Path objects.
|
|
*/
|
|
export declare class PathScurryDarwin extends PathScurryPosix {
|
|
constructor(cwd?: URL | string, opts?: PathScurryOpts);
|
|
}
|
|
/**
|
|
* Default {@link PathBase} implementation for the current platform.
|
|
*
|
|
* {@link PathWin32} on Windows systems, {@link PathPosix} on all others.
|
|
*/
|
|
export declare const Path: typeof PathWin32 | typeof PathPosix;
|
|
export type Path = PathBase | InstanceType<typeof Path>;
|
|
/**
|
|
* Default {@link PathScurryBase} implementation for the current platform.
|
|
*
|
|
* {@link PathScurryWin32} on Windows systems, {@link PathScurryDarwin} on
|
|
* Darwin (macOS) systems, {@link PathScurryPosix} on all others.
|
|
*/
|
|
export declare const PathScurry: typeof PathScurryWin32 | typeof PathScurryDarwin | typeof PathScurryPosix;
|
|
export type PathScurry = PathScurryBase | InstanceType<typeof PathScurry>;
|
|
export {};
|
|
//# sourceMappingURL=index.d.ts.map
|