Nonprofit Pizza Maker

    @dozerg/find-up
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    Find Up

    npm Downloads Build Status

    Find a file or directory by walking up parent directories.

    Table of contents

    Install

    npm i @dozerg/find-up
    

    APIs

    findUp

    Find file(s) asynchrously and return a promise.

    • findUp(name: string, options?: Options) => Promise<string[]>
    import findUp from '@dozerg/find-up';
    
    findUp('package.json').then((results: string[]) => {
      if(results.length === 0) {
        // No files found.
      } else {
        // Found 'package.json' files in results.
        // The results are in the order they were found,
        // i.e. from the deepest to the root.
      }
    })
    
    // Find the first 'package.json' starting from specific directory.
    const [package] = await findUp('package.json', { stopAtLimit: 1, cwd: 'path/to/start' });
    • findUp(names: string[], options?: Options) => Promise<string[]>
    // Find the first supported eslintrc file.
    const [eslintrc] = await findUp(['.eslintrc.yaml', '.eslintrc.json'], { stopAtLimit: 1 })
    // If both '.eslintrc.yaml' and '.eslintrc.json' are found in a directory,
    // '.eslintrc.yaml' will be returned because it's in front of the other in the array.
    • findUp(matcher: Function, options?: Options) => Promise<string[]>

    matcher is of type (directory: string) => string | undefined. It'll be called with every directory in the search, and return a string or undefined. If a string is returned, a file path will be checked. If the string is relative, the file path will be the join of directory and returned string. If the string is absolute, the file path will be the string.

    When in async mode, matcher could be an async or promise-returning function.

    const matcher = (directory: string) => {
      if(condition_1) {
        return undefined;
        // Nothing to check
      } else if (condition_2) {
        return '/absolute/path/to/file';
        // Will check '/absolute/path/to/file'
      } else
        return 'relative/path/to/file';
        // Will check '${directory}/relative/path/to/file'
    }
    
    const results = await findUp(matcher);

    findUp.gen

    Find file(s) asynchrously and return an async generator.

    • findUp.gen(name: string, options?: Options) => AsyncGenerator<string>
    for await (const file of findUp.gen('my.config')) {
      // Found 'my.config' file.
    }
    • findUp.gen(names: string[], options?: Options) => AsyncGenerator<string>
    for await (const file of findUp.gen(['my.json', 'my.yaml'])) {
      // Found either 'my.json' or 'my.yaml' file.
      // If both are found in a directory, 'my.json' will be returned
      // because it's in front of the other in the array.
    }
    • findUp.gen(matcher: Function, options?: Options) => AsyncGenerator<string>
    const matcher = (dir: string) => 'my.config';
    
    for await (const file of findUp.gen(matcher)) {
      // Found 'my.config' file.
    }

    findUp.sync

    Find file(s) synchrously.

    • findUp.sync(name: string, options?: Options) => string[]
    // Find all 'package.json' files.
    const packages = findUp.sync('package.json');
    
    // Find the first 'package.json' starting from specific directory.
    const [package] = findUp.sync('package.json', { stopAtLimit: 1, cwd: 'path/to/start' });
    • findUp.sync(names: string[], options?: Options) => string[]
    // Find the first supported eslintrc file.
    const [eslintrc] = findUp.sync(['.eslintrc.yaml', '.eslintrc.json'], { stopAtLimit: 1 })
    // If both '.eslintrc.yaml' and '.eslintrc.json' are found in a directory,
    // '.eslintrc.yaml' will be returned because it's in front of the other in the array.
    • findUp.sync(matcher: Function, options?: Options) => string[]
    const matcher = (dir: string) => 'my.config';
    
    // Find all 'my.config' files.
    const configs = findUp.sync(matcher);

    Options

    Name Type Default Description
    cwd string | URL process.cwd() The directory to start searching from.
    type "file" | "directory" "file" The type of paths that can match.
    stopAtLimit number Number.POSITIVE_INFINITY Stop the search once a number of results have been found.
    stopAtPath string | URL path.parse(cwd).root The path to the directory to stop the search before reaching root.
    allowSymlinks boolean true Allow symlinks to match if they point to the chosen path type.

    License

    MIT © Zhao DAI daidodo@gmail.com

    Install

    npm i @dozerg/find-up

    DownloadsWeekly Downloads

    354

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    21.8 kB

    Total Files

    5

    Last publish

    Collaborators

    • wqqafnd