find-up

To use find-up in your project, install it using npm:

npm install find-up

Instead of a string or array of strings, you can provide a matcher function to findUp or findDown methods. The matcher function is called with the current directory (cwd) as an argument.

If the matcher function returns a string, that string is treated as a relative path to be located within the current directory. If it returns a path that doesn't exist, the search continues.

To stop the search manually, the matcher function can return the findUpStop symbol.

import {findUp, findUpStop} from 'find-up';

const path = await findUp(async (cwd) => {
	if (cwd.includes('special-dir')) {
		return findUpStop;
	}
	return 'target.txt';
});

Use findUpMultiple() to find all occurrences of a file or directory by walking up parent directories.

• Returns a Promise that resolves to an Array of all paths found, or an empty array if none are found.
• You can limit the number of results by setting the limit option.

Returns a Promise that resolves to an Array<string>.

// Returns an array of all matches found walking up
const paths = await findUpMultiple('config.json', { limit: 5 });

Use findDown() to search for a file or directory by walking down from the current directory into descendant directories.

• Returns a Promise that resolves to the path or undefined if not found.
• You can control the search depth using the depth option.
• You can choose between 'breadth' (breadth-first) or 'depth' (depth-first) search strategies.

import {findDown} from 'find-up';

// Find a file in descendant directories
console.log(await findDown('example.js'));

If you need to perform searches synchronously, use the following functions:

• findUpSync(name, options?): Returns the path or undefined.
• findUpMultipleSync(name, options?): Returns an array of all paths found or an empty array.

Use findUpMultipleSync() to find all occurrences of a file or directory as you traverse up the directory tree synchronously.

Parameters:

• name: A string, an array of strings, or a matcher function.
• options: An optional object:
  • cwd: The directory to start searching from.
  • stopAt: A directory to stop searching at.
  • limit: The maximum number of matches to return.

Returns a string[].

import {findUpMultipleSync} from 'find-up';

const paths = findUpMultipleSync('package.json');
// returns an array of absolute paths for all package.json files found upwards

Use findUp() to search for a file or directory by name, starting from a specified directory and moving up the directory tree towards the root. It returns the first match found or undefined if no match is found.

Parameters:

• name: A string, an array of strings, or a matcher function.
• options: An optional object:
  • cwd: The directory to start searching from (defaults to current working directory).
  • stopAt: A directory to stop searching at (defaults to the filesystem root).
  • limit: The maximum number of matches to return (used internally by findUpMultiple).

Returns a Promise<string | undefined>.

import {findUp} from 'find-up';

const path = await findUp('package.json');
// returns the absolute path to the first package.json found upwards

Use findUpMultiple() to find all occurrences of a file or directory as you traverse up the directory tree. This is useful when you want to find all instances of a configuration file in a project hierarchy.

Parameters:

• name: A string, an array of strings, or a matcher function.
• options: An optional object:
  • cwd: The directory to start searching from.
  • stopAt: A directory to stop searching at.
  • limit: The maximum number of matches to return.

Returns a Promise<string[]>.

import {findUpMultiple} from 'find-up';

const paths = await findUpMultiple('package.json');
// returns an array of absolute paths for all package.json files found upwards

Use findDown() to search for a file or directory by name, starting from a specified directory and searching through its subdirectories.

Parameters:

• name: A string, an array of strings, or a matcher function.
• options: An optional object:
  • cwd: The directory to start searching from.
  • depth: The maximum depth to search (defaults to 1).
  • type: The type of entry to look for ('file' or 'directory').
  • allowSymlinks: Whether to follow symbolic links (defaults to true).
  • strategy: The search strategy: 'breadth' (default) or 'depth'.

Returns a Promise<string | undefined>.

import {findDown} from 'find-up';

const path = await findDown('config.json', { depth: 2, strategy: 'depth' });
// searches downwards from current directory up to 2 levels deep using depth-first search

Use findDownSync() to search for a file or directory by name, starting from a specified directory and searching through its subdirectories synchronously.

Parameters:

• name: A string, an array of strings, or a matcher function.
• options: An optional object:
  • cwd: The directory to start searching from.
  • depth: The maximum depth to search.
  • type: The type of entry to look for ('file' or 'directory').
  • allowSymlinks: Whether to follow symbolic links.
  • strategy: The search strategy: 'breadth' (default) or 'depth'.

Returns a string | undefined.

import {findDownSync} from 'find-up';

const path = findDownSync('config.json', { depth: 2 });