@dozerg/find-up NPM

Find Up

Downloads

Find a file or directory by walking up parent directories.

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.