JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 7400
  • Score
    100M100P100Q137441F
  • License MIT

Find files or directories by walking up parent directories.

Package Exports

  • @dozerg/find-up
  • @dozerg/find-up/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@dozerg/find-up) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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.

Inspiration

Many thanks to find-up from which this project is inspired.

License

MIT © Zhao DAI daidodo@gmail.com