find-up

Variables

• findUpStop

Functions

• findUp()
• findUpMultiple()
• findUpMultipleSync()
• findUpSync()
• pathExists()
• pathExistsSync()

Type Aliases

• 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 findUp

findUp: {
    (name: string | readonly string[], options?: Options): Promise<
        string | undefined
    >;
    (
        matcher: (directory: string) => Match | Promise<Match>,
        options?: any
    ): 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 multiple.

  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 first path found or undefined if none could be found.

  Example 1

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

function findUpMultiple

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

• Find files or directories by walking up parent directories.

  Parameter name

  The name of the file or directory to find. Can be multiple.

  Returns

  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

  All paths found or an empty array if none could be found.

  Example 1

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

function findUpMultipleSync

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

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

  Parameter name

  The name of the file or directory to find. Can be multiple.

  Returns

  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

  All paths found or an empty array if none could be found.

  Example 1

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

function findUpSync

findUpSync: {
    (name: string | readonly string[], options?: Options): string | undefined;
    (matcher: (directory: string) => Match, options?: any): 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 multiple.

  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 first path found or undefined if none could be found.

  Example 1

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

function pathExists

pathExists: (path: string) => Promise<boolean>;

• Check if a path exists.

  Parameter path

  The path to a file or directory.

  Returns

  Whether the path exists.

  Example 1

  import {pathExists} from 'find-up';
  
  console.log(await pathExists('/Users/sindresorhus/unicorn.png'));
  //=> true

function pathExistsSync

pathExistsSync: (path: string) => boolean;

• Synchronously check if a path exists.

  Parameter path

  Path to the file or directory.

  Returns

  Whether the path exists.

  Example 1

  import {pathExistsSync} from 'find-up';
  
  console.log(pathExistsSync('/Users/sindresorhus/unicorn.png'));
  //=> true

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;
} & LocatePathOptions;