### Install find-up using npm

Source: https://github.com/sindresorhus/find-up/blob/main/readme.md

This command installs the 'find-up' package and its dependencies using npm, making it available for use in your Node.js project.

```sh
npm install find-up
```

--------------------------------

### Basic findUp usage examples

Source: https://github.com/sindresorhus/find-up/blob/main/readme.md

Demonstrates how to use the `findUp` function to locate files by name or by a custom matcher function. It shows searching for a single file, an array of files, and a directory using specific options.

```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'
```

--------------------------------

### findDown usage example

Source: https://github.com/sindresorhus/find-up/blob/main/readme.md

Shows how to use the `findDown` function in conjunction with `findUp` to locate a file within a specified depth of descendant directories. This is useful for scenarios like finding monorepo roots.

```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'
```

--------------------------------

### Monorepo Workspace Detection with findUp and findDown

Source: https://context7.com/sindresorhus/find-up/llms.txt

Combines upward and downward search to detect monorepo structures or locate specific files within workspace hierarchies. This example demonstrates finding the monorepo root and nearest workspace package.

```javascript
import {findUp, findDown} from 'find-up';

// Find monorepo root by looking for packages directory containing workspaces
const monorepoRoot = await findUp(async directory => {
  // Check if this directory has a packages folder with package.json files
  const workspacePackage = await findDown('package.json', {
    cwd: directory,
    depth: 1
  });

  if (workspacePackage) {
    return directory;
  }

  return undefined;
}, {type: 'directory'});
console.log(monorepoRoot);
// => '/Users/sindresorhus/monorepo'

// Find nearest workspace package by looking up for packages directory
const nearestPackage = await findUp(async directory => {
  const packageJsonPath = await findDown('package.json', {
    cwd: directory,
    depth: 1
  });
  return packageJsonPath;
});
console.log(nearestPackage);
// => '/Users/sindresorhus/monorepo/packages/utils/package.json'

// Locate TypeScript config in workspace
const tsconfigPath = await findUp(async directory => {
  const config = await findDown('tsconfig.json', {
    cwd: directory,
    depth: 1
  });
  return config;
});
console.log(tsconfigPath);
// => '/Users/sindresorhus/project/tsconfig.json'
```

--------------------------------

### findDown - Search descendant directories (JavaScript)

Source: https://context7.com/sindresorhus/find-up/llms.txt

Searches for files or directories by walking down into subdirectories from a starting point using breadth-first search by default. Supports specifying the search depth, strategy ('depth' or 'breadth'), and can search for multiple file names or specific directory types. Options include 'cwd', 'depth', 'strategy', 'type', and 'allowSymlinks'.

```javascript
import {findDown} from 'find-up';

// Find file in subdirectories (depth 1 by default)
const readmePath = await findDown('README.md', {
  cwd: '/Users/sindresorhus/project'
});
console.log(readmePath);
// => '/Users/sindresorhus/project/README.md'

// Search deeper with custom depth
const testFilePath = await findDown('test.js', {
  cwd: '/Users/sindresorhus/project',
  depth: 3
});
console.log(testFilePath);
// => '/Users/sindresorhus/project/src/utils/test.js'

// Use depth-first search strategy
const deepFilePath = await findDown('config.json', {
  cwd: '/Users/sindresorhus/project',
  depth: 5,
  strategy: 'depth'
});
console.log(deepFilePath);
// => '/Users/sindresorhus/project/packages/app/src/config.json'

// Find multiple file options
const configPath = await findDown(['config.yml', 'config.yaml'], {
  cwd: '/Users/sindresorhus/project',
  depth: 2
});
console.log(configPath);
// => '/Users/sindresorhus/project/config.yml'

// Find directory in subdirectories
const distPath = await findDown('dist', {
  cwd: '/Users/sindresorhus/project/packages',
  type: 'directory',
  depth: 2
});
console.log(distPath);
// => '/Users/sindresorhus/project/packages/app/dist'

```

--------------------------------

### findUp with custom matcher and stop condition

Source: https://github.com/sindresorhus/find-up/blob/main/readme.md

Illustrates using a custom matcher function with `findUp` to define complex search criteria. It also demonstrates how to use `findUpStop` to halt the search prematurely for performance optimization.

```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';
});
```

--------------------------------

### Advanced findUp and findDown Options Configuration

Source: https://context7.com/sindresorhus/find-up/llms.txt

Configure search behavior with options for path type filtering, symbolic link handling, search boundaries, and result limits. These options work with both upward and downward search functions.

```javascript
import {findUp, findUpMultiple, findDown} from 'find-up';
import {fileURLToPath} from 'node:url';

// Complete options example for findUp
const result1 = await findUp('config.json', {
  cwd: '/Users/sindresorhus/project/src/utils',  // Starting directory
  type: 'file',                                    // 'file' | 'directory' | 'both'
  allowSymlinks: true,                             // Follow symbolic links
  stopAt: '/Users/sindresorhus'                    // Stop search at this directory
});
console.log(result1);
// => '/Users/sindresorhus/project/config.json'

// Options with URL paths
const __dirname = fileURLToPath(new URL('.', import.meta.url));
const result2 = await findUp('.git', {
  cwd: new URL('file:///Users/sindresorhus/project'),
  type: 'both'
});
console.log(result2);
// => '/Users/sindresorhus/project/.git'

// Complete options example for findDown
const result3 = await findDown('test.js', {
  cwd: '/Users/sindresorhus/project',              // Starting directory
  depth: 3,                                         // Max depth to traverse
  type: 'file',                                     // 'file' | 'directory' | 'both'
  allowSymlinks: false,                             // Don't follow symlinks
  strategy: 'breadth'                               // 'breadth' | 'depth'
});
console.log(result3);
// => '/Users/sindresorhus/project/src/test.js'

// Limit results in multiple search
const result4 = await findUpMultiple('package.json', {
  limit: 3,                                         // Maximum matches to return
  stopAt: '/Users'
});
console.log(result4);
// => [...] (max 3 results)
```

--------------------------------

### findDownSync - Synchronous descendant directory search (JavaScript)

Source: https://context7.com/sindresorhus/find-up/llms.txt

Synchronous version of findDown for blocking filesystem traversal into subdirectories. Returns the first matching path or undefined. It allows configuration of 'cwd', 'type', 'depth', 'strategy', and 'allowSymlinks' for tailored searches.

```javascript
import {findDownSync} from 'find-up';

// Synchronous downward search
const indexPath = findDownSync('index.js', {
  cwd: '/Users/sindresorhus/project/src'
});
console.log(indexPath);
// => '/Users/sindresorhus/project/src/index.js'

// Search with depth and type filters
const buildDir = findDownSync('build', {
  cwd: '/Users/sindresorhus/project',
  type: 'directory',
  depth: 2,
  strategy: 'breadth'
});
console.log(buildDir);
// => '/Users/sindresorhus/project/packages/build'

// Disable symlink following
const realFilePath = findDownSync('data.json', {
  cwd: '/Users/sindresorhus/project',
  allowSymlinks: false,
  depth: 3
});
console.log(realFilePath);
// => '/Users/sindresorhus/project/data/data.json'

```

--------------------------------

### Async Single File Search Upward with find-up

Source: https://context7.com/sindresorhus/find-up/llms.txt

Searches for a single file or directory by walking up parent directories from the current working directory. It returns the first matching path found or undefined if no match exists. Supports searching for multiple files by name and filtering by type.

```javascript
import {findUp} from 'find-up';

// Find single file by name
const packagePath = await findUp('package.json');
console.log(packagePath);
// => '/Users/sindresorhus/project/package.json'

// Find first match from multiple options
const configPath = await findUp(['config.yml', 'config.yaml', '.config']);
console.log(configPath);
// => '/Users/sindresorhus/project/config.yml'

// Find with type specification
const gitPath = await findUp('.git', {type: 'both'});
console.log(gitPath);
// => '/Users/sindresorhus/project/.git' (file or directory)

// Find with custom starting directory
const licensePath = await findUp('LICENSE', {
  cwd: '/Users/sindresorhus/project/src/components'
});
console.log(licensePath);
// => '/Users/sindresorhus/project/LICENSE'
```

--------------------------------

### Sync Single File Search Upward with findUpSync

Source: https://context7.com/sindresorhus/find-up/llms.txt

Provides a synchronous version of findUp, which blocks execution until a match is found or the search completes. This is useful in scenarios where asynchronous operations are not feasible, such as during initial configuration loading.

```javascript
import {findUpSync} from 'find-up';

// Synchronous file search
const packagePath = findUpSync('package.json');
console.log(packagePath);
// => '/Users/sindresorhus/project/package.json'

// Search for directory with custom options
const nodeModulesPath = findUpSync('node_modules', {
  type: 'directory',
  cwd: process.cwd()
});
console.log(nodeModulesPath);
// => '/Users/sindresorhus/project/node_modules'

// Stop search at specific directory
const configPath = findUpSync('.eslintrc.js', {
  stopAt: '/Users/sindresorhus'
});
console.log(configPath);
// => undefined (if not found before stopAt)
```

--------------------------------

### Custom Search Logic with find-up Matcher Function

Source: https://context7.com/sindresorhus/find-up/llms.txt

Enables advanced search scenarios by using a custom matcher function. This function receives each directory path and can perform conditional matching, content inspection, or complex directory validation, returning a match or findUpStop for early termination.

```javascript
import path from 'node:path';
import {findUp, findUpStop} from 'find-up';
import {pathExists} from 'path-exists';

// Find directory containing specific file
const projectRoot = await findUp(async directory => {
  const hasPackageJson = await pathExists(path.join(directory, 'package.json'));
  return hasPackageJson && directory;
}, {type: 'directory'});
console.log(projectRoot);
// => '/Users/sindresorhus/project'

// Early termination with findUpStop
const configPath = await findUp(async directory => {
  // Stop if we reach home directory
  if (directory === '/Users/sindresorhus') {
    return findUpStop;
  }

  const configFile = path.join(directory, '.myconfig');
  const exists = await pathExists(configFile);
  return exists ? configFile : undefined;
});
console.log(configPath);
// => '/Users/sindresorhus/project/.myconfig' or undefined

// Find monorepo workspace root
const workspaceRoot = await findUp(async directory => {
  const lernaPath = path.join(directory, 'lerna.json');
  const hasLerna = await pathExists(lernaPath);
  return hasLerna && directory;
}, {type: 'directory'});
console.log(workspaceRoot);
// => '/Users/sindresorhus/monorepo'
```

--------------------------------

### findUpMultipleSync - Synchronous multiple file search upward (JavaScript)

Source: https://context7.com/sindresorhus/find-up/llms.txt

Synchronous version of findUpMultiple that returns all matching paths in the directory hierarchy. Blocks execution until the search completes. It can accept a custom matcher function for more complex search criteria and supports options like 'cwd', 'type', and 'limit'.

```javascript
import {findUpMultipleSync} from 'find-up';

// Synchronously find all matching files
const allPackageJsons = findUpMultipleSync('package.json', {
  cwd: '/Users/sindresorhus/project/packages/app/src'
});
console.log(allPackageJsons);
// => [
//   '/Users/sindresorhus/project/packages/app/package.json',
//   '/Users/sindresorhus/project/package.json'
// ]

// Find with custom matcher
const allProjectRoots = findUpMultipleSync(directory => {
  const fs = require('node:fs');
  try {
    const files = fs.readdirSync(directory);
    return files.includes('package.json') && directory;
  } catch {
    return undefined;
  }
}, {type: 'directory', limit: 3});
console.log(allProjectRoots);
// => ['/Users/sindresorhus/project/packages/app', ...] 

```

--------------------------------

### findUpMultiple - Find all matching files upward (JavaScript)

Source: https://context7.com/sindresorhus/find-up/llms.txt

Finds all occurrences of a file or directory by traversing up the directory tree. Returns an array of all matching paths in order from deepest to shallowest. Supports limiting the number of matches and searching for multiple file names. It can also filter by type (file/directory) and stop at a specific directory.

```javascript
import {findUpMultiple} from 'find-up';

// Find all .gitignore files in hierarchy
const gitignorePaths = await findUpMultiple('.gitignore');
console.log(gitignorePaths);
// => [
//   '/Users/sindresorhus/project/packages/utils/.gitignore',
//   '/Users/sindresorhus/project/.gitignore',
//   '/Users/sindresorhus/.gitignore'
// ]

// Limit number of matches
const limitedPaths = await findUpMultiple('package.json', {limit: 2});
console.log(limitedPaths);
// => [
//   '/Users/sindresorhus/project/packages/utils/package.json',
//   '/Users/sindresorhus/project/package.json'
// ]

// Find all config files with multiple names
const allConfigs = await findUpMultiple(['.eslintrc', '.eslintrc.js', '.eslintrc.json']);
console.log(allConfigs);
// => ['/Users/sindresorhus/project/.eslintrc.js', '/Users/.eslintrc']

// Find all directories of certain type
const allNodeModules = await findUpMultiple('node_modules', {
  type: 'directory',
  stopAt: '/Users'
});
console.log(allNodeModules);
// => ['/Users/sindresorhus/project/packages/utils/node_modules', ...] 

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.