find-up

Variables

• findUpStop

Functions

• findDown()
• findDownSync()
• findUp()
• findUpMultiple()
• findUpMultipleSync()
• findUpSync()

Type Aliases

• FindDownOptions
• Match
• Options

variable findUpStop

const findUpStop: Symbol;

• Return this in a matcher function to stop the search and force findUp to immediately return undefined.

function findDown

findDown: (
    name: string | readonly string[],
    options?: FindDownOptions
) => Promise<string | undefined>;

• Find a file or directory by walking down descendant directories from cwd.

  Parameter name

  The name of the file or directory to find. Can be an array of names to search for multiple files.

  Returns

  The path or undefined if it could not be found.

  Example 1

  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'

function findDownSync

findDownSync: (
    name: string | readonly string[],
    options?: FindDownOptions
) => string | undefined;

• Synchronously find a file or directory by walking down descendant directories from cwd.

  Parameter name

  The name of the file or directory to find. Can be an array of names to search for multiple files.

  Returns

  The path or undefined if it could not be found.

  Example 1

  import {findUpSync, findDownSync} from 'find-up';
  
  // Find the nearest parent directory that contains a specific file
  // in its direct children (useful for monorepo roots)
  console.log(findUpSync(async directory => {
  	return findDownSync('example.js', {cwd: directory, depth: 1});
  }));
  //=> '/Users/sindresorhus/foo'

function findUp

findUp: {
    (name: string | readonly string[], options?: Options): Promise<
        string | undefined
    >;
    (
        matcher: (directory: string) => Match | Promise<Match>,
        options?: Options
    ): Promise<string>;
};

• Find a file or directory by walking up parent directories.

  Parameter name

  The name of the file or directory to find. Can be an array of names to search for multiple files.

  Returns

  The first path found (by respecting the order of names) or undefined if none could be found.

  Example 1

  // /
  // └── Users
  //     └── sindresorhus
  //         ├── unicorn.png
  //         └── foo
  //             └── bar
  //                 ├── baz
  //                 └── example.js
  
  // example.js
  import {findUp} 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'

• Find a file or directory by walking up parent directories.

  Parameter matcher

  Called for each directory in the search. Return a path or findUpStop to stop the search.

  Returns

  The path or undefined if it could not be found.

  Example 1

  import path from 'node:path';
  import {pathExists} from 'path-exists';
  import {findUp} from 'find-up';
  
  console.log(await findUp(async directory => {
  	const hasUnicorn = await pathExists(path.join(directory, 'unicorn.png'));
  	return hasUnicorn && directory;
  }, {type: 'directory'}));
  //=> '/Users/sindresorhus'

function findUpMultiple

findUpMultiple: {
    (name: string | readonly string[], options?: Options): Promise<string[]>;
    (
        matcher: (directory: string) => Match | Promise<Match>,
        options?: Options
    ): Promise<string[]>;
};

• Find files or directories by walking up parent directories.

  Parameter name

  The name of the file or directory to find. Can be an array of names to search for multiple files.

  Returns

  An array of all paths found (by respecting the order of names) or an empty array if none could be found.

  Example 1

  // /
  // └── Users
  //     └── sindresorhus
  //         ├── unicorn.png
  //         └── foo
  //             ├── unicorn.png
  //             └── bar
  //                 ├── baz
  //                 └── example.js
  
  // example.js
  import {findUpMultiple} from 'find-up';
  
  console.log(await findUpMultiple('unicorn.png'));
  //=> ['/Users/sindresorhus/foo/unicorn.png', '/Users/sindresorhus/unicorn.png']
  
  console.log(await findUpMultiple(['rainbow.png', 'unicorn.png']));
  //=> ['/Users/sindresorhus/foo/unicorn.png', '/Users/sindresorhus/unicorn.png']

• Find files or directories by walking up parent directories.

  Parameter matcher

  Called for each directory in the search. Return a path or findUpStop to stop the search.

  Returns

  An array of all paths found or an empty array if none could be found.

  Example 1

  import path from 'node:path';
  import {pathExists} from 'path-exists';
  import {findUpMultiple} from 'find-up';
  
  console.log(await findUpMultiple(async directory => {
  	const hasUnicorn = await pathExists(path.join(directory, 'unicorn.png'));
  	return hasUnicorn && directory;
  }, {type: 'directory'}));
  //=> ['/Users/sindresorhus/foo', '/Users/sindresorhus']

function findUpMultipleSync

findUpMultipleSync: {
    (name: string | readonly string[], options?: Options): string[];
    (matcher: (directory: string) => Match, options?: Options): string[];
};

• Synchronously find files or directories by walking up parent directories.

  Parameter name

  The name of the file or directory to find. Can be an array of names to search for multiple files.

  Returns

  An array of all paths found (by respecting the order of names) or an empty array if none could be found.

  Example 1

  // /
  // └── Users
  //     └── sindresorhus
  //         ├── unicorn.png
  //         └── foo
  //             ├── unicorn.png
  //             └── bar
  //                 ├── baz
  //                 └── example.js
  
  // example.js
  import {findUpMultipleSync} from 'find-up';
  
  console.log(findUpMultipleSync('unicorn.png'));
  //=> ['/Users/sindresorhus/foo/unicorn.png', '/Users/sindresorhus/unicorn.png']
  
  console.log(findUpMultipleSync(['rainbow.png', 'unicorn.png']));
  //=> ['/Users/sindresorhus/foo/unicorn.png', '/Users/sindresorhus/unicorn.png']

• Synchronously find files or directories by walking up parent directories.

  Parameter matcher

  Called for each directory in the search. Return a path or findUpStop to stop the search.

  Returns

  An array of all paths found or an empty array if none could be found.

  Example 1

  import path from 'node:path';
  import {pathExistsSync} from 'path-exists';
  import {findUpMultipleSync} from 'find-up';
  
  console.log(findUpMultipleSync(directory => {
  	const hasUnicorn = pathExistsSync(path.join(directory, 'unicorn.png'));
  	return hasUnicorn && directory;
  }, {type: 'directory'}));
  //=> ['/Users/sindresorhus/foo', '/Users/sindresorhus']

function findUpSync

findUpSync: {
    (name: string | readonly string[], options?: Options): string | undefined;
    (matcher: (directory: string) => Match, options?: Options): string;
};

• Synchronously find a file or directory by walking up parent directories.

  Parameter name

  The name of the file or directory to find. Can be an array of names to search for multiple files.

  Returns

  The first path found (by respecting the order of names) or undefined if none could be found.

  Example 1

  // /
  // └── Users
  //     └── sindresorhus
  //         ├── unicorn.png
  //         └── foo
  //             └── bar
  //                 ├── baz
  //                 └── example.js
  
  // example.js
  import {findUpSync} from 'find-up';
  
  console.log(findUpSync('unicorn.png'));
  //=> '/Users/sindresorhus/unicorn.png'
  
  console.log(findUpSync(['rainbow.png', 'unicorn.png']));
  //=> '/Users/sindresorhus/unicorn.png'

• Synchronously find a file or directory by walking up parent directories.

  Parameter matcher

  Called for each directory in the search. Return a path or findUpStop to stop the search.

  Returns

  The path or undefined if it could not be found.

  Example 1

  import path from 'node:path';
  import {pathExistsSync} from 'path-exists';
  import {findUpSync} from 'find-up';
  
  console.log(findUpSync(directory => {
  	const hasUnicorn = pathExistsSync(path.join(directory, 'unicorn.png'));
  	return hasUnicorn && directory;
  }, {type: 'directory'}));
  //=> '/Users/sindresorhus'

type FindDownOptions

type FindDownOptions = {
    /**
	The directory to start from.

	@default process.cwd()
	*/
    readonly cwd?: URL | string;

    /**
	Maximum number of directory levels to traverse below `cwd`.

	@default 1
	*/
    readonly depth?: number;

    /**
	The type of path to match.

	@default 'file'
	*/
    readonly type?: 'file' | 'directory' | 'both';

    /**
	Allow symbolic links to match if they point to the chosen path type.

	@default true
	*/
    readonly allowSymlinks?: boolean;

    /**
	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.

	@default 'breadth'
	*/
    readonly strategy?: 'breadth' | 'depth';
};

• Options for findDown and findDownSync.

type Match

type Match = string | typeof findUpStop | undefined;

type Options

type Options = {
    /**
	A directory path where the search halts if no matches are found before reaching this point.

	Default: Root directory
	*/
    readonly stopAt?: string;

    /**
	The type of path to match.

	@default 'file'
	*/
    readonly type?: 'file' | 'directory' | 'both';

    /**
	The number of matches to limit the search to.

	@default Infinity

	Only available for `findUpMultiple` and `findUpMultipleSync`.
	*/
    readonly limit?: number;
} & Omit<LocatePathOptions, 'type'>;