File Explorer

1import { Minimatch } from 'minimatch';2import { Minipass } from 'minipass';3import { FSOption, Path, PathScurry } from 'path-scurry';4import { IgnoreLike } from './ignore.js';5import { Pattern } from './pattern.js';6export type MatchSet = Minimatch['set'];7export type GlobParts = Exclude<Minimatch['globParts'], undefined>;8/**9 * A `GlobOptions` object may be provided to any of the exported methods, and10 * must be provided to the `Glob` constructor.11 *12 * All options are optional, boolean, and false by default, unless otherwise13 * noted.14 *15 * All resolved options are added to the Glob object as properties.16 *17 * If you are running many `glob` operations, you can pass a Glob object as the18 * `options` argument to a subsequent operation to share the previously loaded19 * cache.20 */21export interface GlobOptions {22    /**23     * Set to `true` to always receive absolute paths for24     * matched files. Set to `false` to always return relative paths.25     *26     * When this option is not set, absolute paths are returned for patterns27     * that are absolute, and otherwise paths are returned that are relative28     * to the `cwd` setting.29     *30     * This does _not_ make an extra system call to get31     * the realpath, it only does string path resolution.32     *33     * Conflicts with {@link withFileTypes}34     */35    absolute?: boolean;36    /**37     * Set to false to enable {@link windowsPathsNoEscape}38     *39     * @deprecated40     */41    allowWindowsEscape?: boolean;42    /**43     * The current working directory in which to search. Defaults to44     * `process.cwd()`.45     *46     * May be eiher a string path or a `file://` URL object or string.47     */48    cwd?: string | URL;49    /**50     * Include `.dot` files in normal matches and `globstar`51     * matches. Note that an explicit dot in a portion of the pattern52     * will always match dot files.53     */54    dot?: boolean;55    /**56     * Prepend all relative path strings with `./` (or `.\` on Windows).57     *58     * Without this option, returned relative paths are "bare", so instead of59     * returning `'./foo/bar'`, they are returned as `'foo/bar'`.60     *61     * Relative patterns starting with `'../'` are not prepended with `./`, even62     * if this option is set.63     */64    dotRelative?: boolean;65    /**66     * Follow symlinked directories when expanding `**`67     * patterns. This can result in a lot of duplicate references in68     * the presence of cyclic links, and make performance quite bad.69     *70     * By default, a `**` in a pattern will follow 1 symbolic link if71     * it is not the first item in the pattern, or none if it is the72     * first item in the pattern, following the same behavior as Bash.73     */74    follow?: boolean;75    /**76     * string or string[], or an object with `ignore` and `ignoreChildren`77     * methods.78     *79     * If a string or string[] is provided, then this is treated as a glob80     * pattern or array of glob patterns to exclude from matches. To ignore all81     * children within a directory, as well as the entry itself, append `'/**'`82     * to the ignore pattern.83     *84     * **Note** `ignore` patterns are _always_ in `dot:true` mode, regardless of85     * any other settings.86     *87     * If an object is provided that has `ignored(path)` and/or88     * `childrenIgnored(path)` methods, then these methods will be called to89     * determine whether any Path is a match or if its children should be90     * traversed, respectively.91     */92    ignore?: string | string[] | IgnoreLike;93    /**94     * Treat brace expansion like `{a,b}` as a "magic" pattern. Has no95     * effect if {@link nobrace} is set.96     *97     * Only has effect on the {@link hasMagic} function.98     */99    magicalBraces?: boolean;100    /**101     * Add a `/` character to directory matches. Note that this requires102     * additional stat calls in some cases.103     */104    mark?: boolean;105    /**106     * Perform a basename-only match if the pattern does not contain any slash107     * characters. That is, `*.js` would be treated as equivalent to108     * `**\/*.js`, matching all js files in all directories.109     */110    matchBase?: boolean;111    /**112     * Limit the directory traversal to a given depth below the cwd.113     * Note that this does NOT prevent traversal to sibling folders,114     * root patterns, and so on. It only limits the maximum folder depth115     * that the walk will descend, relative to the cwd.116     */117    maxDepth?: number;118    /**119     * Do not expand `{a,b}` and `{1..3}` brace sets.120     */121    nobrace?: boolean;122    /**123     * Perform a case-insensitive match. This defaults to `true` on macOS and124     * Windows systems, and `false` on all others.125     *126     * **Note** `nocase` should only be explicitly set when it is127     * known that the filesystem's case sensitivity differs from the128     * platform default. If set `true` on case-sensitive file129     * systems, or `false` on case-insensitive file systems, then the130     * walk may return more or less results than expected.131     */132    nocase?: boolean;133    /**134     * Do not match directories, only files. (Note: to match135     * _only_ directories, put a `/` at the end of the pattern.)136     */137    nodir?: boolean;138    /**139     * Do not match "extglob" patterns such as `+(a|b)`.140     */141    noext?: boolean;142    /**143     * Do not match `**` against multiple filenames. (Ie, treat it as a normal144     * `*` instead.)145     *146     * Conflicts with {@link matchBase}147     */148    noglobstar?: boolean;149    /**150     * Defaults to value of `process.platform` if available, or `'linux'` if151     * not. Setting `platform:'win32'` on non-Windows systems may cause strange152     * behavior.153     */154    platform?: NodeJS.Platform;155    /**156     * Set to true to call `fs.realpath` on all of the157     * results. In the case of an entry that cannot be resolved, the158     * entry is omitted. This incurs a slight performance penalty, of159     * course, because of the added system calls.160     */161    realpath?: boolean;162    /**163     *164     * A string path resolved against the `cwd` option, which165     * is used as the starting point for absolute patterns that start166     * with `/`, (but not drive letters or UNC paths on Windows).167     *168     * Note that this _doesn't_ necessarily limit the walk to the169     * `root` directory, and doesn't affect the cwd starting point for170     * non-absolute patterns. A pattern containing `..` will still be171     * able to traverse out of the root directory, if it is not an172     * actual root directory on the filesystem, and any non-absolute173     * patterns will be matched in the `cwd`. For example, the174     * pattern `/../*` with `{root:'/some/path'}` will return all175     * files in `/some`, not all files in `/some/path`. The pattern176     * `*` with `{root:'/some/path'}` will return all the entries in177     * the cwd, not the entries in `/some/path`.178     *179     * To start absolute and non-absolute patterns in the same180     * path, you can use `{root:''}`. However, be aware that on181     * Windows systems, a pattern like `x:/*` or `//host/share/*` will182     * _always_ start in the `x:/` or `//host/share` directory,183     * regardless of the `root` setting.184     */185    root?: string;186    /**187     * A [PathScurry](http://npm.im/path-scurry) object used188     * to traverse the file system. If the `nocase` option is set189     * explicitly, then any provided `scurry` object must match this190     * setting.191     */192    scurry?: PathScurry;193    /**194     * Call `lstat()` on all entries, whether required or not to determine195     * if it's a valid match. When used with {@link withFileTypes}, this means196     * that matches will include data such as modified time, permissions, and197     * so on.  Note that this will incur a performance cost due to the added198     * system calls.199     */200    stat?: boolean;201    /**202     * An AbortSignal which will cancel the Glob walk when203     * triggered.204     */205    signal?: AbortSignal;206    /**207     * Use `\\` as a path separator _only_, and208     *  _never_ as an escape character. If set, all `\\` characters are209     *  replaced with `/` in the pattern.210     *211     *  Note that this makes it **impossible** to match against paths212     *  containing literal glob pattern characters, but allows matching213     *  with patterns constructed using `path.join()` and214     *  `path.resolve()` on Windows platforms, mimicking the (buggy!)215     *  behavior of Glob v7 and before on Windows. Please use with216     *  caution, and be mindful of [the caveat below about Windows217     *  paths](#windows). (For legacy reasons, this is also set if218     *  `allowWindowsEscape` is set to the exact value `false`.)219     */220    windowsPathsNoEscape?: boolean;221    /**222     * Return [PathScurry](http://npm.im/path-scurry)223     * `Path` objects instead of strings. These are similar to a224     * NodeJS `Dirent` object, but with additional methods and225     * properties.226     *227     * Conflicts with {@link absolute}228     */229    withFileTypes?: boolean;230    /**231     * An fs implementation to override some or all of the defaults.  See232     * http://npm.im/path-scurry for details about what can be overridden.233     */234    fs?: FSOption;235    /**236     * Just passed along to Minimatch.  Note that this makes all pattern237     * matching operations slower and *extremely* noisy.238     */239    debug?: boolean;240    /**241     * Return `/` delimited paths, even on Windows.242     *243     * On posix systems, this has no effect.  But, on Windows, it means that244     * paths will be `/` delimited, and absolute paths will be their full245     * resolved UNC forms, eg instead of `'C:\\foo\\bar'`, it would return246     * `'//?/C:/foo/bar'`247     */248    posix?: boolean;249    /**250     * Do not match any children of any matches. For example, the pattern251     * `**\/foo` would match `a/foo`, but not `a/foo/b/foo` in this mode.252     *253     * This is especially useful for cases like "find all `node_modules`254     * folders, but not the ones in `node_modules`".255     *256     * In order to support this, the `Ignore` implementation must support an257     * `add(pattern: string)` method. If using the default `Ignore` class, then258     * this is fine, but if this is set to `false`, and a custom `Ignore` is259     * provided that does not have an `add()` method, then it will throw an260     * error.261     *262     * **Caveat** It *only* ignores matches that would be a descendant of a263     * previous match, and only if that descendant is matched *after* the264     * ancestor is encountered. Since the file system walk happens in265     * indeterminate order, it's possible that a match will already be added266     * before its ancestor, if multiple or braced patterns are used.267     *268     * For example:269     *270     * ```ts271     * const results = await glob([272     *   // likely to match first, since it's just a stat273     *   'a/b/c/d/e/f',274     *275     *   // this pattern is more complicated! It must to various readdir()276     *   // calls and test the results against a regular expression, and that277     *   // is certainly going to take a little bit longer.278     *   //279     *   // So, later on, it encounters a match at 'a/b/c/d/e', but it's too280     *   // late to ignore a/b/c/d/e/f, because it's already been emitted.281     *   'a/[bdf]/?/[a-z]/*',282     * ], { includeChildMatches: false })283     * ```284     *285     * It's best to only set this to `false` if you can be reasonably sure that286     * no components of the pattern will potentially match one another's file287     * system descendants, or if the occasional included child entry will not288     * cause problems.289     *290     * @default true291     */292    includeChildMatches?: boolean;293}294export type GlobOptionsWithFileTypesTrue = GlobOptions & {295    withFileTypes: true;296    absolute?: undefined;297    mark?: undefined;298    posix?: undefined;299};300export type GlobOptionsWithFileTypesFalse = GlobOptions & {301    withFileTypes?: false;302};303export type GlobOptionsWithFileTypesUnset = GlobOptions & {304    withFileTypes?: undefined;305};306export type Result<Opts> = Opts extends GlobOptionsWithFileTypesTrue ? Path : Opts extends GlobOptionsWithFileTypesFalse ? string : Opts extends GlobOptionsWithFileTypesUnset ? string : string | Path;307export type Results<Opts> = Result<Opts>[];308export type FileTypes<Opts> = Opts extends GlobOptionsWithFileTypesTrue ? true : Opts extends GlobOptionsWithFileTypesFalse ? false : Opts extends GlobOptionsWithFileTypesUnset ? false : boolean;309/**310 * An object that can perform glob pattern traversals.311 */312export declare class Glob<Opts extends GlobOptions> implements GlobOptions {313    absolute?: boolean;314    cwd: string;315    root?: string;316    dot: boolean;317    dotRelative: boolean;318    follow: boolean;319    ignore?: string | string[] | IgnoreLike;320    magicalBraces: boolean;321    mark?: boolean;322    matchBase: boolean;323    maxDepth: number;324    nobrace: boolean;325    nocase: boolean;326    nodir: boolean;327    noext: boolean;328    noglobstar: boolean;329    pattern: string[];330    platform: NodeJS.Platform;331    realpath: boolean;332    scurry: PathScurry;333    stat: boolean;334    signal?: AbortSignal;335    windowsPathsNoEscape: boolean;336    withFileTypes: FileTypes<Opts>;337    includeChildMatches: boolean;338    /**339     * The options provided to the constructor.340     */341    opts: Opts;342    /**343     * An array of parsed immutable {@link Pattern} objects.344     */345    patterns: Pattern[];346    /**347     * All options are stored as properties on the `Glob` object.348     *349     * See {@link GlobOptions} for full options descriptions.350     *351     * Note that a previous `Glob` object can be passed as the352     * `GlobOptions` to another `Glob` instantiation to re-use settings353     * and caches with a new pattern.354     *355     * Traversal functions can be called multiple times to run the walk356     * again.357     */358    constructor(pattern: string | string[], opts: Opts);359    /**360     * Returns a Promise that resolves to the results array.361     */362    walk(): Promise<Results<Opts>>;363    /**364     * synchronous {@link Glob.walk}365     */366    walkSync(): Results<Opts>;367    /**368     * Stream results asynchronously.369     */370    stream(): Minipass<Result<Opts>, Result<Opts>>;371    /**372     * Stream results synchronously.373     */374    streamSync(): Minipass<Result<Opts>, Result<Opts>>;375    /**376     * Default sync iteration function. Returns a Generator that377     * iterates over the results.378     */379    iterateSync(): Generator<Result<Opts>, void, void>;380    [Symbol.iterator](): Generator<Result<Opts>, void, void>;381    /**382     * Default async iteration function. Returns an AsyncGenerator that383     * iterates over the results.384     */385    iterate(): AsyncGenerator<Result<Opts>, void, void>;386    [Symbol.asyncIterator](): AsyncGenerator<Result<Opts>, void, void>;387}388//# sourceMappingURL=glob.d.ts.map