basant307/AI_Governance_Project
048
1import { LRUCache } from 'lru-cache';2import { posix, win32 } from 'node:path';3import { Minipass } from 'minipass';4import type { Dirent, Stats } from 'node:fs';5/**6 * An object that will be used to override the default `fs`7 * methods. Any methods that are not overridden will use Node's8 * built-in implementations.9 *10 * - lstatSync11 * - readdir (callback `withFileTypes` Dirent variant, used for12 * readdirCB and most walks)13 * - readdirSync14 * - readlinkSync15 * - realpathSync16 * - promises: Object containing the following async methods:17 * - lstat18 * - readdir (Dirent variant only)19 * - readlink20 * - realpath21 */22export interface FSOption {23 lstatSync?: (path: string) => Stats;24 readdir?: (path: string, options: {25 withFileTypes: true;26 }, cb: (er: NodeJS.ErrnoException | null, entries?: Dirent[]) => any) => void;27 readdirSync?: (path: string, options: {28 withFileTypes: true;29 }) => Dirent[];30 readlinkSync?: (path: string) => string;31 realpathSync?: (path: string) => string;32 promises?: {33 lstat?: (path: string) => Promise<Stats>;34 readdir?: (path: string, options: {35 withFileTypes: true;36 }) => Promise<Dirent[]>;37 readlink?: (path: string) => Promise<string>;38 realpath?: (path: string) => Promise<string>;39 [k: string]: any;40 };41 [k: string]: any;42}43interface FSValue {44 lstatSync: (path: string) => Stats;45 readdir: (path: string, options: {46 withFileTypes: true;47 }, cb: (er: NodeJS.ErrnoException | null, entries?: Dirent[]) => any) => void;48 readdirSync: (path: string, options: {49 withFileTypes: true;50 }) => Dirent[];51 readlinkSync: (path: string) => string;52 realpathSync: (path: string) => string;53 promises: {54 lstat: (path: string) => Promise<Stats>;55 readdir: (path: string, options: {56 withFileTypes: true;57 }) => Promise<Dirent[]>;58 readlink: (path: string) => Promise<string>;59 realpath: (path: string) => Promise<string>;60 [k: string]: any;61 };62 [k: string]: any;63}64export type Type = 'Unknown' | 'FIFO' | 'CharacterDevice' | 'Directory' | 'BlockDevice' | 'File' | 'SymbolicLink' | 'Socket';65/**66 * Options that may be provided to the Path constructor67 */68export interface PathOpts {69 fullpath?: string;70 relative?: string;71 relativePosix?: string;72 parent?: PathBase;73 /**74 * See {@link FSOption}75 */76 fs?: FSOption;77}78/**79 * An LRUCache for storing resolved path strings or Path objects.80 * @internal81 */82export declare class ResolveCache extends LRUCache<string, string> {83 constructor();84}85/**86 * an LRUCache for storing child entries.87 * @internal88 */89export declare class ChildrenCache extends LRUCache<PathBase, Children> {90 constructor(maxSize?: number);91}92/**93 * Array of Path objects, plus a marker indicating the first provisional entry94 *95 * @internal96 */97export type Children = PathBase[] & {98 provisional: number;99};100declare const setAsCwd: unique symbol;101/**102 * Path objects are sort of like a super-powered103 * {@link https://nodejs.org/docs/latest/api/fs.html#class-fsdirent fs.Dirent}104 *105 * Each one represents a single filesystem entry on disk, which may or may not106 * exist. It includes methods for reading various types of information via107 * lstat, readlink, and readdir, and caches all information to the greatest108 * degree possible.109 *110 * Note that fs operations that would normally throw will instead return an111 * "empty" value. This is in order to prevent excessive overhead from error112 * stack traces.113 */114export declare abstract class PathBase implements Dirent {115 #private;116 /**117 * the basename of this path118 *119 * **Important**: *always* test the path name against any test string120 * usingthe {@link isNamed} method, and not by directly comparing this121 * string. Otherwise, unicode path strings that the system sees as identical122 * will not be properly treated as the same path, leading to incorrect123 * behavior and possible security issues.124 */125 name: string;126 /**127 * the Path entry corresponding to the path root.128 *129 * @internal130 */131 root: PathBase;132 /**133 * All roots found within the current PathScurry family134 *135 * @internal136 */137 roots: {138 [k: string]: PathBase;139 };140 /**141 * a reference to the parent path, or undefined in the case of root entries142 *143 * @internal144 */145 parent?: PathBase;146 /**147 * boolean indicating whether paths are compared case-insensitively148 * @internal149 */150 nocase: boolean;151 /**152 * boolean indicating that this path is the current working directory153 * of the PathScurry collection that contains it.154 */155 isCWD: boolean;156 /**157 * the string or regexp used to split paths. On posix, it is `'/'`, and on158 * windows it is a RegExp matching either `'/'` or `'\\'`159 */160 abstract splitSep: string | RegExp;161 /**162 * The path separator string to use when joining paths163 */164 abstract sep: string;165 get dev(): number | undefined;166 get mode(): number | undefined;167 get nlink(): number | undefined;168 get uid(): number | undefined;169 get gid(): number | undefined;170 get rdev(): number | undefined;171 get blksize(): number | undefined;172 get ino(): number | undefined;173 get size(): number | undefined;174 get blocks(): number | undefined;175 get atimeMs(): number | undefined;176 get mtimeMs(): number | undefined;177 get ctimeMs(): number | undefined;178 get birthtimeMs(): number | undefined;179 get atime(): Date | undefined;180 get mtime(): Date | undefined;181 get ctime(): Date | undefined;182 get birthtime(): Date | undefined;183 /**184 * This property is for compatibility with the Dirent class as of185 * Node v20, where Dirent['parentPath'] refers to the path of the186 * directory that was passed to readdir. For root entries, it's the path187 * to the entry itself.188 */189 get parentPath(): string;190 /**191 * Deprecated alias for Dirent['parentPath'] Somewhat counterintuitively,192 * this property refers to the *parent* path, not the path object itself.193 *194 * @deprecated195 */196 get path(): string;197 /**198 * Do not create new Path objects directly. They should always be accessed199 * via the PathScurry class or other methods on the Path class.200 *201 * @internal202 */203 constructor(name: string, type: number | undefined, root: PathBase | undefined, roots: {204 [k: string]: PathBase;205 }, nocase: boolean, children: ChildrenCache, opts: PathOpts);206 /**207 * Returns the depth of the Path object from its root.208 *209 * For example, a path at `/foo/bar` would have a depth of 2.210 */211 depth(): number;212 /**213 * @internal214 */215 abstract getRootString(path: string): string;216 /**217 * @internal218 */219 abstract getRoot(rootPath: string): PathBase;220 /**221 * @internal222 */223 abstract newChild(name: string, type?: number, opts?: PathOpts): PathBase;224 /**225 * @internal226 */227 childrenCache(): ChildrenCache;228 /**229 * Get the Path object referenced by the string path, resolved from this Path230 */231 resolve(path?: string): PathBase;232 /**233 * Returns the cached children Path objects, if still available. If they234 * have fallen out of the cache, then returns an empty array, and resets the235 * READDIR_CALLED bit, so that future calls to readdir() will require an fs236 * lookup.237 *238 * @internal239 */240 children(): Children;241 /**242 * Resolves a path portion and returns or creates the child Path.243 *244 * Returns `this` if pathPart is `''` or `'.'`, or `parent` if pathPart is245 * `'..'`.246 *247 * This should not be called directly. If `pathPart` contains any path248 * separators, it will lead to unsafe undefined behavior.249 *250 * Use `Path.resolve()` instead.251 *252 * @internal253 */254 child(pathPart: string, opts?: PathOpts): PathBase;255 /**256 * The relative path from the cwd. If it does not share an ancestor with257 * the cwd, then this ends up being equivalent to the fullpath()258 */259 relative(): string;260 /**261 * The relative path from the cwd, using / as the path separator.262 * If it does not share an ancestor with263 * the cwd, then this ends up being equivalent to the fullpathPosix()264 * On posix systems, this is identical to relative().265 */266 relativePosix(): string;267 /**268 * The fully resolved path string for this Path entry269 */270 fullpath(): string;271 /**272 * On platforms other than windows, this is identical to fullpath.273 *274 * On windows, this is overridden to return the forward-slash form of the275 * full UNC path.276 */277 fullpathPosix(): string;278 /**279 * Is the Path of an unknown type?280 *281 * Note that we might know *something* about it if there has been a previous282 * filesystem operation, for example that it does not exist, or is not a283 * link, or whether it has child entries.284 */285 isUnknown(): boolean;286 isType(type: Type): boolean;287 getType(): Type;288 /**289 * Is the Path a regular file?290 */291 isFile(): boolean;292 /**293 * Is the Path a directory?294 */295 isDirectory(): boolean;296 /**297 * Is the path a character device?298 */299 isCharacterDevice(): boolean;300 /**301 * Is the path a block device?302 */303 isBlockDevice(): boolean;304 /**305 * Is the path a FIFO pipe?306 */307 isFIFO(): boolean;308 /**309 * Is the path a socket?310 */311 isSocket(): boolean;312 /**313 * Is the path a symbolic link?314 */315 isSymbolicLink(): boolean;316 /**317 * Return the entry if it has been subject of a successful lstat, or318 * undefined otherwise.319 *320 * Does not read the filesystem, so an undefined result *could* simply321 * mean that we haven't called lstat on it.322 */323 lstatCached(): PathBase | undefined;324 /**325 * Return the cached link target if the entry has been the subject of a326 * successful readlink, or undefined otherwise.327 *328 * Does not read the filesystem, so an undefined result *could* just mean we329 * don't have any cached data. Only use it if you are very sure that a330 * readlink() has been called at some point.331 */332 readlinkCached(): PathBase | undefined;333 /**334 * Returns the cached realpath target if the entry has been the subject335 * of a successful realpath, or undefined otherwise.336 *337 * Does not read the filesystem, so an undefined result *could* just mean we338 * don't have any cached data. Only use it if you are very sure that a339 * realpath() has been called at some point.340 */341 realpathCached(): PathBase | undefined;342 /**343 * Returns the cached child Path entries array if the entry has been the344 * subject of a successful readdir(), or [] otherwise.345 *346 * Does not read the filesystem, so an empty array *could* just mean we347 * don't have any cached data. Only use it if you are very sure that a348 * readdir() has been called recently enough to still be valid.349 */350 readdirCached(): PathBase[];351 /**352 * Return true if it's worth trying to readlink. Ie, we don't (yet) have353 * any indication that readlink will definitely fail.354 *355 * Returns false if the path is known to not be a symlink, if a previous356 * readlink failed, or if the entry does not exist.357 */358 canReadlink(): boolean;359 /**360 * Return true if readdir has previously been successfully called on this361 * path, indicating that cachedReaddir() is likely valid.362 */363 calledReaddir(): boolean;364 /**365 * Returns true if the path is known to not exist. That is, a previous lstat366 * or readdir failed to verify its existence when that would have been367 * expected, or a parent entry was marked either enoent or enotdir.368 */369 isENOENT(): boolean;370 /**371 * Return true if the path is a match for the given path name. This handles372 * case sensitivity and unicode normalization.373 *374 * Note: even on case-sensitive systems, it is **not** safe to test the375 * equality of the `.name` property to determine whether a given pathname376 * matches, due to unicode normalization mismatches.377 *378 * Always use this method instead of testing the `path.name` property379 * directly.380 */381 isNamed(n: string): boolean;382 /**383 * Return the Path object corresponding to the target of a symbolic link.384 *385 * If the Path is not a symbolic link, or if the readlink call fails for any386 * reason, `undefined` is returned.387 *388 * Result is cached, and thus may be outdated if the filesystem is mutated.389 */390 readlink(): Promise<PathBase | undefined>;391 /**392 * Synchronous {@link PathBase.readlink}393 */394 readlinkSync(): PathBase | undefined;395 /**396 * Call lstat() on this Path, and update all known information that can be397 * determined.398 *399 * Note that unlike `fs.lstat()`, the returned value does not contain some400 * information, such as `mode`, `dev`, `nlink`, and `ino`. If that401 * information is required, you will need to call `fs.lstat` yourself.402 *403 * If the Path refers to a nonexistent file, or if the lstat call fails for404 * any reason, `undefined` is returned. Otherwise the updated Path object is405 * returned.406 *407 * Results are cached, and thus may be out of date if the filesystem is408 * mutated.409 */410 lstat(): Promise<PathBase | undefined>;411 /**412 * synchronous {@link PathBase.lstat}413 */414 lstatSync(): PathBase | undefined;415 /**416 * Standard node-style callback interface to get list of directory entries.417 *418 * If the Path cannot or does not contain any children, then an empty array419 * is returned.420 *421 * Results are cached, and thus may be out of date if the filesystem is422 * mutated.423 *424 * @param cb The callback called with (er, entries). Note that the `er`425 * param is somewhat extraneous, as all readdir() errors are handled and426 * simply result in an empty set of entries being returned.427 * @param allowZalgo Boolean indicating that immediately known results should428 * *not* be deferred with `queueMicrotask`. Defaults to `false`. Release429 * zalgo at your peril, the dark pony lord is devious and unforgiving.430 */431 readdirCB(cb: (er: NodeJS.ErrnoException | null, entries: PathBase[]) => any, allowZalgo?: boolean): void;432 /**433 * Return an array of known child entries.434 *435 * If the Path cannot or does not contain any children, then an empty array436 * is returned.437 *438 * Results are cached, and thus may be out of date if the filesystem is439 * mutated.440 */441 readdir(): Promise<PathBase[]>;442 /**443 * synchronous {@link PathBase.readdir}444 */445 readdirSync(): PathBase[];446 canReaddir(): boolean;447 shouldWalk(dirs: Set<PathBase | undefined>, walkFilter?: (e: PathBase) => boolean): boolean;448 /**449 * Return the Path object corresponding to path as resolved450 * by realpath(3).451 *452 * If the realpath call fails for any reason, `undefined` is returned.453 *454 * Result is cached, and thus may be outdated if the filesystem is mutated.455 * On success, returns a Path object.456 */457 realpath(): Promise<PathBase | undefined>;458 /**459 * Synchronous {@link realpath}460 */461 realpathSync(): PathBase | undefined;462 /**463 * Internal method to mark this Path object as the scurry cwd,464 * called by {@link PathScurry#chdir}465 *466 * @internal467 */468 [setAsCwd](oldCwd: PathBase): void;469}470/**471 * Path class used on win32 systems472 *473 * Uses `'\\'` as the path separator for returned paths, either `'\\'` or `'/'`474 * as the path separator for parsing paths.475 */476export declare class PathWin32 extends PathBase {477 /**478 * Separator for generating path strings.479 */480 sep: '\\';481 /**482 * Separator for parsing path strings.483 */484 splitSep: RegExp;485 /**486 * Do not create new Path objects directly. They should always be accessed487 * via the PathScurry class or other methods on the Path class.488 *489 * @internal490 */491 constructor(name: string, type: number | undefined, root: PathBase | undefined, roots: {492 [k: string]: PathBase;493 }, nocase: boolean, children: ChildrenCache, opts: PathOpts);494 /**495 * @internal496 */497 newChild(name: string, type?: number, opts?: PathOpts): PathWin32;498 /**499 * @internal500 */501 getRootString(path: string): string;502 /**503 * @internal504 */505 getRoot(rootPath: string): PathBase;506 /**507 * @internal508 */509 sameRoot(rootPath: string, compare?: string): boolean;510}511/**512 * Path class used on all posix systems.513 *514 * Uses `'/'` as the path separator.515 */516export declare class PathPosix extends PathBase {517 /**518 * separator for parsing path strings519 */520 splitSep: '/';521 /**522 * separator for generating path strings523 */524 sep: '/';525 /**526 * Do not create new Path objects directly. They should always be accessed527 * via the PathScurry class or other methods on the Path class.528 *529 * @internal530 */531 constructor(name: string, type: number | undefined, root: PathBase | undefined, roots: {532 [k: string]: PathBase;533 }, nocase: boolean, children: ChildrenCache, opts: PathOpts);534 /**535 * @internal536 */537 getRootString(path: string): string;538 /**539 * @internal540 */541 getRoot(_rootPath: string): PathBase;542 /**543 * @internal544 */545 newChild(name: string, type?: number, opts?: PathOpts): PathPosix;546}547/**548 * Options that may be provided to the PathScurry constructor549 */550export interface PathScurryOpts {551 /**552 * perform case-insensitive path matching. Default based on platform553 * subclass.554 */555 nocase?: boolean;556 /**557 * Number of Path entries to keep in the cache of Path child references.558 *559 * Setting this higher than 65536 will dramatically increase the data560 * consumption and construction time overhead of each PathScurry.561 *562 * Setting this value to 256 or lower will significantly reduce the data563 * consumption and construction time overhead, but may also reduce resolve()564 * and readdir() performance on large filesystems.565 *566 * Default `16384`.567 */568 childrenCacheSize?: number;569 /**570 * An object that overrides the built-in functions from the fs and571 * fs/promises modules.572 *573 * See {@link FSOption}574 */575 fs?: FSOption;576}577/**578 * The base class for all PathScurry classes, providing the interface for path579 * resolution and filesystem operations.580 *581 * Typically, you should *not* instantiate this class directly, but rather one582 * of the platform-specific classes, or the exported {@link PathScurry} which583 * defaults to the current platform.584 */585export declare abstract class PathScurryBase {586 #private;587 /**588 * The root Path entry for the current working directory of this Scurry589 */590 root: PathBase;591 /**592 * The string path for the root of this Scurry's current working directory593 */594 rootPath: string;595 /**596 * A collection of all roots encountered, referenced by rootPath597 */598 roots: {599 [k: string]: PathBase;600 };601 /**602 * The Path entry corresponding to this PathScurry's current working directory.603 */604 cwd: PathBase;605 /**606 * Perform path comparisons case-insensitively.607 *608 * Defaults true on Darwin and Windows systems, false elsewhere.609 */610 nocase: boolean;611 /**612 * The path separator used for parsing paths613 *614 * `'/'` on Posix systems, either `'/'` or `'\\'` on Windows615 */616 abstract sep: string | RegExp;617 /**618 * This class should not be instantiated directly.619 *620 * Use PathScurryWin32, PathScurryDarwin, PathScurryPosix, or PathScurry621 *622 * @internal623 */624 constructor(cwd: (URL | string) | undefined, pathImpl: typeof win32 | typeof posix, sep: string | RegExp, { nocase, childrenCacheSize, fs, }?: PathScurryOpts);625 /**626 * Get the depth of a provided path, string, or the cwd627 */628 depth(path?: Path | string): number;629 /**630 * Parse the root portion of a path string631 *632 * @internal633 */634 abstract parseRootPath(dir: string): string;635 /**636 * create a new Path to use as root during construction.637 *638 * @internal639 */640 abstract newRoot(fs: FSValue): PathBase;641 /**642 * Determine whether a given path string is absolute643 */644 abstract isAbsolute(p: string): boolean;645 /**646 * Return the cache of child entries. Exposed so subclasses can create647 * child Path objects in a platform-specific way.648 *649 * @internal650 */651 childrenCache(): ChildrenCache;652 /**653 * Resolve one or more path strings to a resolved string654 *655 * Same interface as require('path').resolve.656 *657 * Much faster than path.resolve() when called multiple times for the same658 * path, because the resolved Path objects are cached. Much slower659 * otherwise.660 */661 resolve(...paths: string[]): string;662 /**663 * Resolve one or more path strings to a resolved string, returning664 * the posix path. Identical to .resolve() on posix systems, but on665 * windows will return a forward-slash separated UNC path.666 *667 * Same interface as require('path').resolve.668 *669 * Much faster than path.resolve() when called multiple times for the same670 * path, because the resolved Path objects are cached. Much slower671 * otherwise.672 */673 resolvePosix(...paths: string[]): string;674 /**675 * find the relative path from the cwd to the supplied path string or entry676 */677 relative(entry?: PathBase | string): string;678 /**679 * find the relative path from the cwd to the supplied path string or680 * entry, using / as the path delimiter, even on Windows.681 */682 relativePosix(entry?: PathBase | string): string;683 /**684 * Return the basename for the provided string or Path object685 */686 basename(entry?: PathBase | string): string;687 /**688 * Return the dirname for the provided string or Path object689 */690 dirname(entry?: PathBase | string): string;691 /**692 * Return an array of known child entries.693 *694 * First argument may be either a string, or a Path object.695 *696 * If the Path cannot or does not contain any children, then an empty array697 * is returned.698 *699 * Results are cached, and thus may be out of date if the filesystem is700 * mutated.701 *702 * Unlike `fs.readdir()`, the `withFileTypes` option defaults to `true`. Set703 * `{ withFileTypes: false }` to return strings.704 */705 readdir(): Promise<PathBase[]>;706 readdir(opts: {707 withFileTypes: true;708 }): Promise<PathBase[]>;709 readdir(opts: {710 withFileTypes: false;711 }): Promise<string[]>;712 readdir(opts: {713 withFileTypes: boolean;714 }): Promise<PathBase[] | string[]>;715 readdir(entry: PathBase | string): Promise<PathBase[]>;716 readdir(entry: PathBase | string, opts: {717 withFileTypes: true;718 }): Promise<PathBase[]>;719 readdir(entry: PathBase | string, opts: {720 withFileTypes: false;721 }): Promise<string[]>;722 readdir(entry: PathBase | string, opts: {723 withFileTypes: boolean;724 }): Promise<PathBase[] | string[]>;725 /**726 * synchronous {@link PathScurryBase.readdir}727 */728 readdirSync(): PathBase[];729 readdirSync(opts: {730 withFileTypes: true;731 }): PathBase[];732 readdirSync(opts: {733 withFileTypes: false;734 }): string[];735 readdirSync(opts: {736 withFileTypes: boolean;737 }): PathBase[] | string[];738 readdirSync(entry: PathBase | string): PathBase[];739 readdirSync(entry: PathBase | string, opts: {740 withFileTypes: true;741 }): PathBase[];742 readdirSync(entry: PathBase | string, opts: {743 withFileTypes: false;744 }): string[];745 readdirSync(entry: PathBase | string, opts: {746 withFileTypes: boolean;747 }): PathBase[] | string[];748 /**749 * Call lstat() on the string or Path object, and update all known750 * information that can be determined.751 *752 * Note that unlike `fs.lstat()`, the returned value does not contain some753 * information, such as `mode`, `dev`, `nlink`, and `ino`. If that754 * information is required, you will need to call `fs.lstat` yourself.755 *756 * If the Path refers to a nonexistent file, or if the lstat call fails for757 * any reason, `undefined` is returned. Otherwise the updated Path object is758 * returned.759 *760 * Results are cached, and thus may be out of date if the filesystem is761 * mutated.762 */763 lstat(entry?: string | PathBase): Promise<PathBase | undefined>;764 /**765 * synchronous {@link PathScurryBase.lstat}766 */767 lstatSync(entry?: string | PathBase): PathBase | undefined;768 /**769 * Return the Path object or string path corresponding to the target of a770 * symbolic link.771 *772 * If the path is not a symbolic link, or if the readlink call fails for any773 * reason, `undefined` is returned.774 *775 * Result is cached, and thus may be outdated if the filesystem is mutated.776 *777 * `{withFileTypes}` option defaults to `false`.778 *779 * On success, returns a Path object if `withFileTypes` option is true,780 * otherwise a string.781 */782 readlink(): Promise<string | undefined>;783 readlink(opt: {784 withFileTypes: false;785 }): Promise<string | undefined>;786 readlink(opt: {787 withFileTypes: true;788 }): Promise<PathBase | undefined>;789 readlink(opt: {790 withFileTypes: boolean;791 }): Promise<PathBase | string | undefined>;792 readlink(entry: string | PathBase, opt?: {793 withFileTypes: false;794 }): Promise<string | undefined>;795 readlink(entry: string | PathBase, opt: {796 withFileTypes: true;797 }): Promise<PathBase | undefined>;798 readlink(entry: string | PathBase, opt: {799 withFileTypes: boolean;800 }): Promise<string | PathBase | undefined>;801 /**802 * synchronous {@link PathScurryBase.readlink}803 */804 readlinkSync(): string | undefined;805 readlinkSync(opt: {806 withFileTypes: false;807 }): string | undefined;808 readlinkSync(opt: {809 withFileTypes: true;810 }): PathBase | undefined;811 readlinkSync(opt: {812 withFileTypes: boolean;813 }): PathBase | string | undefined;814 readlinkSync(entry: string | PathBase, opt?: {815 withFileTypes: false;816 }): string | undefined;817 readlinkSync(entry: string | PathBase, opt: {818 withFileTypes: true;819 }): PathBase | undefined;820 readlinkSync(entry: string | PathBase, opt: {821 withFileTypes: boolean;822 }): string | PathBase | undefined;823 /**824 * Return the Path object or string path corresponding to path as resolved825 * by realpath(3).826 *827 * If the realpath call fails for any reason, `undefined` is returned.828 *829 * Result is cached, and thus may be outdated if the filesystem is mutated.830 *831 * `{withFileTypes}` option defaults to `false`.832 *833 * On success, returns a Path object if `withFileTypes` option is true,834 * otherwise a string.835 */836 realpath(): Promise<string | undefined>;837 realpath(opt: {838 withFileTypes: false;839 }): Promise<string | undefined>;840 realpath(opt: {841 withFileTypes: true;842 }): Promise<PathBase | undefined>;843 realpath(opt: {844 withFileTypes: boolean;845 }): Promise<PathBase | string | undefined>;846 realpath(entry: string | PathBase, opt?: {847 withFileTypes: false;848 }): Promise<string | undefined>;849 realpath(entry: string | PathBase, opt: {850 withFileTypes: true;851 }): Promise<PathBase | undefined>;852 realpath(entry: string | PathBase, opt: {853 withFileTypes: boolean;854 }): Promise<string | PathBase | undefined>;855 realpathSync(): string | undefined;856 realpathSync(opt: {857 withFileTypes: false;858 }): string | undefined;859 realpathSync(opt: {860 withFileTypes: true;861 }): PathBase | undefined;862 realpathSync(opt: {863 withFileTypes: boolean;864 }): PathBase | string | undefined;865 realpathSync(entry: string | PathBase, opt?: {866 withFileTypes: false;867 }): string | undefined;868 realpathSync(entry: string | PathBase, opt: {869 withFileTypes: true;870 }): PathBase | undefined;871 realpathSync(entry: string | PathBase, opt: {872 withFileTypes: boolean;873 }): string | PathBase | undefined;874 /**875 * Asynchronously walk the directory tree, returning an array of876 * all path strings or Path objects found.877 *878 * Note that this will be extremely memory-hungry on large filesystems.879 * In such cases, it may be better to use the stream or async iterator880 * walk implementation.881 */882 walk(): Promise<PathBase[]>;883 walk(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Promise<PathBase[]>;884 walk(opts: WalkOptionsWithFileTypesFalse): Promise<string[]>;885 walk(opts: WalkOptions): Promise<string[] | PathBase[]>;886 walk(entry: string | PathBase): Promise<PathBase[]>;887 walk(entry: string | PathBase, opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Promise<PathBase[]>;888 walk(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): Promise<string[]>;889 walk(entry: string | PathBase, opts: WalkOptions): Promise<PathBase[] | string[]>;890 /**891 * Synchronously walk the directory tree, returning an array of892 * all path strings or Path objects found.893 *894 * Note that this will be extremely memory-hungry on large filesystems.895 * In such cases, it may be better to use the stream or async iterator896 * walk implementation.897 */898 walkSync(): PathBase[];899 walkSync(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): PathBase[];900 walkSync(opts: WalkOptionsWithFileTypesFalse): string[];901 walkSync(opts: WalkOptions): string[] | PathBase[];902 walkSync(entry: string | PathBase): PathBase[];903 walkSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesUnset | WalkOptionsWithFileTypesTrue): PathBase[];904 walkSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): string[];905 walkSync(entry: string | PathBase, opts: WalkOptions): PathBase[] | string[];906 /**907 * Support for `for await`908 *909 * Alias for {@link PathScurryBase.iterate}910 *911 * Note: As of Node 19, this is very slow, compared to other methods of912 * walking. Consider using {@link PathScurryBase.stream} if memory overhead913 * and backpressure are concerns, or {@link PathScurryBase.walk} if not.914 */915 [Symbol.asyncIterator](): AsyncGenerator<PathBase, void, void>;916 /**917 * Async generator form of {@link PathScurryBase.walk}918 *919 * Note: As of Node 19, this is very slow, compared to other methods of920 * walking, especially if most/all of the directory tree has been previously921 * walked. Consider using {@link PathScurryBase.stream} if memory overhead922 * and backpressure are concerns, or {@link PathScurryBase.walk} if not.923 */924 iterate(): AsyncGenerator<PathBase, void, void>;925 iterate(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): AsyncGenerator<PathBase, void, void>;926 iterate(opts: WalkOptionsWithFileTypesFalse): AsyncGenerator<string, void, void>;927 iterate(opts: WalkOptions): AsyncGenerator<string | PathBase, void, void>;928 iterate(entry: string | PathBase): AsyncGenerator<PathBase, void, void>;929 iterate(entry: string | PathBase, opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): AsyncGenerator<PathBase, void, void>;930 iterate(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): AsyncGenerator<string, void, void>;931 iterate(entry: string | PathBase, opts: WalkOptions): AsyncGenerator<PathBase | string, void, void>;932 /**933 * Iterating over a PathScurry performs a synchronous walk.934 *935 * Alias for {@link PathScurryBase.iterateSync}936 */937 [Symbol.iterator](): Generator<PathBase, void, void>;938 iterateSync(): Generator<PathBase, void, void>;939 iterateSync(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Generator<PathBase, void, void>;940 iterateSync(opts: WalkOptionsWithFileTypesFalse): Generator<string, void, void>;941 iterateSync(opts: WalkOptions): Generator<string | PathBase, void, void>;942 iterateSync(entry: string | PathBase): Generator<PathBase, void, void>;943 iterateSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Generator<PathBase, void, void>;944 iterateSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): Generator<string, void, void>;945 iterateSync(entry: string | PathBase, opts: WalkOptions): Generator<PathBase | string, void, void>;946 /**947 * Stream form of {@link PathScurryBase.walk}948 *949 * Returns a Minipass stream that emits {@link PathBase} objects by default,950 * or strings if `{ withFileTypes: false }` is set in the options.951 */952 stream(): Minipass<PathBase>;953 stream(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Minipass<PathBase>;954 stream(opts: WalkOptionsWithFileTypesFalse): Minipass<string>;955 stream(opts: WalkOptions): Minipass<string | PathBase>;956 stream(entry: string | PathBase): Minipass<PathBase>;957 stream(entry: string | PathBase, opts: WalkOptionsWithFileTypesUnset | WalkOptionsWithFileTypesTrue): Minipass<PathBase>;958 stream(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): Minipass<string>;959 stream(entry: string | PathBase, opts: WalkOptions): Minipass<string> | Minipass<PathBase>;960 /**961 * Synchronous form of {@link PathScurryBase.stream}962 *963 * Returns a Minipass stream that emits {@link PathBase} objects by default,964 * or strings if `{ withFileTypes: false }` is set in the options.965 *966 * Will complete the walk in a single tick if the stream is consumed fully.967 * Otherwise, will pause as needed for stream backpressure.968 */969 streamSync(): Minipass<PathBase>;970 streamSync(opts: WalkOptionsWithFileTypesTrue | WalkOptionsWithFileTypesUnset): Minipass<PathBase>;971 streamSync(opts: WalkOptionsWithFileTypesFalse): Minipass<string>;972 streamSync(opts: WalkOptions): Minipass<string | PathBase>;973 streamSync(entry: string | PathBase): Minipass<PathBase>;974 streamSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesUnset | WalkOptionsWithFileTypesTrue): Minipass<PathBase>;975 streamSync(entry: string | PathBase, opts: WalkOptionsWithFileTypesFalse): Minipass<string>;976 streamSync(entry: string | PathBase, opts: WalkOptions): Minipass<string> | Minipass<PathBase>;977 chdir(path?: string | Path): void;978}979/**980 * Options provided to all walk methods.981 */982export interface WalkOptions {983 /**984 * Return results as {@link PathBase} objects rather than strings.985 * When set to false, results are fully resolved paths, as returned by986 * {@link PathBase.fullpath}.987 * @default true988 */989 withFileTypes?: boolean;990 /**991 * Attempt to read directory entries from symbolic links. Otherwise, only992 * actual directories are traversed. Regardless of this setting, a given993 * target path will only ever be walked once, meaning that a symbolic link994 * to a previously traversed directory will never be followed.995 *996 * Setting this imposes a slight performance penalty, because `readlink`997 * must be called on all symbolic links encountered, in order to avoid998 * infinite cycles.999 * @default false1000 */1001 follow?: boolean;1002 /**1003 * Only return entries where the provided function returns true.1004 *1005 * This will not prevent directories from being traversed, even if they do1006 * not pass the filter, though it will prevent directories themselves from1007 * being included in the result set. See {@link walkFilter}1008 *1009 * Asynchronous functions are not supported here.1010 *1011 * By default, if no filter is provided, all entries and traversed1012 * directories are included.1013 */1014 filter?: (entry: PathBase) => boolean;1015 /**1016 * Only traverse directories (and in the case of {@link follow} being set to1017 * true, symbolic links to directories) if the provided function returns1018 * true.1019 *1020 * This will not prevent directories from being included in the result set,1021 * even if they do not pass the supplied filter function. See {@link filter}1022 * to do that.1023 *1024 * Asynchronous functions are not supported here.1025 */1026 walkFilter?: (entry: PathBase) => boolean;1027}1028export type WalkOptionsWithFileTypesUnset = WalkOptions & {1029 withFileTypes?: undefined;1030};1031export type WalkOptionsWithFileTypesTrue = WalkOptions & {1032 withFileTypes: true;1033};1034export type WalkOptionsWithFileTypesFalse = WalkOptions & {1035 withFileTypes: false;1036};1037/**1038 * Windows implementation of {@link PathScurryBase}1039 *1040 * Defaults to case insensitve, uses `'\\'` to generate path strings. Uses1041 * {@link PathWin32} for Path objects.1042 */1043export declare class PathScurryWin32 extends PathScurryBase {1044 /**1045 * separator for generating path strings1046 */1047 sep: '\\';1048 constructor(cwd?: URL | string, opts?: PathScurryOpts);1049 /**1050 * @internal1051 */1052 parseRootPath(dir: string): string;1053 /**1054 * @internal1055 */1056 newRoot(fs: FSValue): PathWin32;1057 /**1058 * Return true if the provided path string is an absolute path1059 */1060 isAbsolute(p: string): boolean;1061}1062/**1063 * {@link PathScurryBase} implementation for all posix systems other than Darwin.1064 *1065 * Defaults to case-sensitive matching, uses `'/'` to generate path strings.1066 *1067 * Uses {@link PathPosix} for Path objects.1068 */1069export declare class PathScurryPosix extends PathScurryBase {1070 /**1071 * separator for generating path strings1072 */1073 sep: '/';1074 constructor(cwd?: URL | string, opts?: PathScurryOpts);1075 /**1076 * @internal1077 */1078 parseRootPath(_dir: string): string;1079 /**1080 * @internal1081 */1082 newRoot(fs: FSValue): PathPosix;1083 /**1084 * Return true if the provided path string is an absolute path1085 */1086 isAbsolute(p: string): boolean;1087}1088/**1089 * {@link PathScurryBase} implementation for Darwin (macOS) systems.1090 *1091 * Defaults to case-insensitive matching, uses `'/'` for generating path1092 * strings.1093 *1094 * Uses {@link PathPosix} for Path objects.1095 */1096export declare class PathScurryDarwin extends PathScurryPosix {1097 constructor(cwd?: URL | string, opts?: PathScurryOpts);1098}1099/**1100 * Default {@link PathBase} implementation for the current platform.1101 *1102 * {@link PathWin32} on Windows systems, {@link PathPosix} on all others.1103 */1104export declare const Path: typeof PathWin32 | typeof PathPosix;1105export type Path = PathBase | InstanceType<typeof Path>;1106/**1107 * Default {@link PathScurryBase} implementation for the current platform.1108 *1109 * {@link PathScurryWin32} on Windows systems, {@link PathScurryDarwin} on1110 * Darwin (macOS) systems, {@link PathScurryPosix} on all others.1111 */1112export declare const PathScurry: typeof PathScurryWin32 | typeof PathScurryDarwin | typeof PathScurryPosix;1113export type PathScurry = PathScurryBase | InstanceType<typeof PathScurry>;1114export {};1115//# sourceMappingURL=index.d.ts.map