find-up
Version:
Find a file or directory by walking up parent directories
241 lines (152 loc) • 6.17 kB
Markdown
> Find a file or directory by walking up parent directories or down descendant directories
```sh
npm install find-up
```
```
/
└── Users
└── sindresorhus
├── unicorn.png
└── foo
└── bar
├── baz
└── example.js
```
`example.js`
```js
import path from 'node:path';
import {pathExists} from 'path-exists';
import {findUp, findDown} from 'find-up';
console.log(await findUp('unicorn.png'));
//=> '/Users/sindresorhus/unicorn.png'
console.log(await findUp(['rainbow.png', 'unicorn.png']));
//=> '/Users/sindresorhus/unicorn.png'
console.log(await findUp(async directory => {
const hasUnicorn = await pathExists(path.join(directory, 'unicorn.png'));
return hasUnicorn && directory;
}, {type: 'directory'}));
//=> '/Users/sindresorhus'
// Find .git (could be a file or directory, common in submodules)
console.log(await findUp('.git', {type: 'both'}));
//=> '/Users/sindresorhus/.git'
```
Returns a `Promise` for either the path or `undefined` if it could not be found.
Returns a `Promise` for either the first path found (by respecting the order of names) or `undefined` if none could be found.
### findUpMultiple(name, options?)
### findUpMultiple(matcher, options?)
Returns a `Promise` for either an array of all paths found or an empty array if none could be found.
**Note:** You can limit the number of matches by setting the `limit` option.
### findUpMultiple([...name], options?)
Returns a `Promise` for either an array of all paths found (by respecting the order of names) or an empty array if none could be found.
**Note:** You can limit the number of matches by setting the `limit` option.
### findUpSync(name, options?)
### findUpSync(matcher, options?)
Returns a path or `undefined` if it could not be found.
### findUpSync([...name], options?)
Returns the first path found (by respecting the order of names) or `undefined` if none could be found.
### findUpMultipleSync(name, options?)
### findUpMultipleSync(matcher, options?)
Returns an array of all paths found or an empty array if none could be found.
### findUpMultipleSync([...name], options?)
Returns an array of all paths found (by respecting the order of names) or an empty array if none could be found.
**Note:** You can limit the number of matches by setting the `limit` option.
### findDown(name, options?)
### findDown([...name], options?)
Find a file or directory by walking down descendant directories from `cwd`.
Returns a `Promise` for either the path or `undefined` if it could not be found.
```js
import {findUp, findDown} from 'find-up';
// Find the nearest parent directory that contains a specific file
// in its direct children (useful for monorepo roots)
console.log(await findUp(async directory => {
return findDown('example.js', {cwd: directory, depth: 1});
}));
//=> '/Users/sindresorhus/foo'
```
Synchronous version of `findDown`.
Returns the path or `undefined` if it could not be found.
Type: `string`
The name of the file or directory to find. Can be an array of names to search for multiple files.
Type: `Function`
Called for each directory in the search. Return a path or `findUpStop` to stop the search. Useful if you want to match files with certain patterns, set of permissions, or other advanced use-cases.
Type: `object`
Type: `URL | string`\
Default: `process.cwd()`
The directory to start from.
Type: `string`\
Default: `'file'`\
Values: `'file' | 'directory' | 'both'`
The type of path to match.
Type: `boolean`\
Default: `true`
Allow symbolic links to match if they point to the chosen path type.
*Only for `findUp` functions*
Type: `URL | string`\
Default: Root directory
A directory path where the search halts if no matches are found before reaching this point.
*Only for `findUpMultiple` and `findUpMultipleSync`*
Type: `number`\
Default: `Infinity`
The maximum number of matches to return. Useful for limiting results when searching for multiple files.
A [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) that can be returned by a `matcher` function to stop the search and cause `findUp` to immediately return `undefined`. Useful as a performance optimization in case the current working directory is deeply nested in the filesystem.
```js
import path from 'node:path';
import {findUp, findUpStop} from 'find-up';
await findUp(directory => {
// Stop searching if we've reached a 'work' directory
if (path.basename(directory) === 'work') {
return findUpStop;
}
// Look for package.json in this directory
return 'package.json';
});
```
Type: `object`
Type: `URL | string`\
Default: `process.cwd()`
The directory to start from.
Type: `number`\
Default: `1`
Maximum number of directory levels to traverse below `cwd`.
Type: `string`\
Default: `'file'`\
Values: `'file' | 'directory' | 'both'`
The type of path to match.
Type: `boolean`\
Default: `true`
Allow symbolic links to match if they point to the chosen path type.
Type: `string`\
Default: `'breadth'`\
Values: `'breadth' | 'depth'`
Search strategy to use:
- `'breadth'`: Breadth-first search, finds shallower matches first.
- `'depth'`: Depth-first search, fully explores each branch before moving to the next.
- [find-up-cli](https://github.com/sindresorhus/find-up-cli) - CLI for this module
- [package-up](https://github.com/sindresorhus/package-up) - Find the closest package.json file
- [package-directory](https://github.com/sindresorhus/package-directory) - Find the root directory of an npm package
- [resolve-from](https://github.com/sindresorhus/resolve-from) - Resolve the path of a module like `require.resolve()` but from a given path