find-up

  • Version 7.0.0
  • Published
  • 16.5 kB
  • 3 dependencies
  • MIT license

Install

npm i find-up
yarn add find-up
pnpm add find-up

Overview

Find a file or directory by walking up parent directories

Index

Variables

variable findUpStop

const findUpStop: Symbol;
  • Return this in a matcher function to stop the search and force findUp to immediately return undefined.

Functions

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 Aliases

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;

      Package Files (1)

      Dependencies (3)

      Dev Dependencies (5)

      Peer Dependencies (0)

      No peer dependencies.

      Badge

      To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

      You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/find-up.

      • Markdown
        [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/find-up)
      • HTML
        <a href="https://www.jsdocs.io/package/find-up"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>