### Quick Start Example

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/README.md

Demonstrates how to use various empathic modules for common tasks like finding package.json, traversing directories, searching for config files, and checking write permissions.

```typescript
import { resolve } from 'node:path';
import * as find from 'empathic/find';
import * as pkg from 'empathic/package';
import * as walk from 'empathic/walk';
import * as access from 'empathic/access';

// Find the nearest package.json
const pkgfile = pkg.up();
// => "/home/user/project/package.json"

// Get all parent directories
const parents = walk.up('src/lib');
// => ['/home/user/project/src/lib', '/home/user/project/src', ...]

// Find a config file
const config = find.up('webpack.config.js', { cwd: 'src' });
// => "/home/user/project/webpack.config.js"

// Check permissions
if (access.writable('node_modules')) {
  // Safe to write cache files
  const cache = pkg.cache('my-tool', { create: true });
}
```

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

### Example Usage

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/walk.md

Demonstrates how to use the `walk.up` function to get all parent directories, with and without limiting the traversal depth, and with custom working directory.

```typescript
import * as walk from 'empathic/walk';

// Get all parents from /home/user/project/src/lib
const dirs = walk.up('/home/user/project/src/lib');
// Result:
// [
//   '/home/user/project/src/lib',
//   '/home/user/project/src',
//   '/home/user/project',
//   '/home/user',
//   '/home',
//   '/'
// ]

// Limit traversal to a specific directory
const limited = walk.up('/home/user/project/src/lib', {
  last: '/home/user'
});
// Result:
// [
//   '/home/user/project/src/lib',
//   '/home/user/project/src',
//   '/home/user/project',
//   '/home/user'
// ]

// Resolve relative paths from a custom cwd
const relative = walk.up('src/lib', {
  cwd: '/home/user/project'
});
// Result: Same as walk.up('/home/user/project/src/lib')
```

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

### Example usage of pkg.cache()

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/package.md

Demonstrates how to use the `cache` function to get a cache path, create a cache directory, use scoped cache locations, handle graceful failure, and utilize the `CACHE_DIR` environment variable.

```typescript
import * as pkg from 'empathic/package';

// Get cache path (without creating)
const cachePath = pkg.cache('my-tool');
// Result: "/home/user/project/node_modules/.cache/my-tool"

// Get and create cache directory
const cachePath2 = pkg.cache('my-tool', { create: true });
// Result: "/home/user/project/node_modules/.cache/my-tool"
// Directory is created if it doesn't exist

// Scoped cache location
const scoped = pkg.cache('build-cache', {
  cwd: '/home/user/project/src',
  create: true
});
// Result: "/home/user/project/node_modules/.cache/build-cache"

// Graceful failure when not writable
const result = pkg.cache('my-tool');
// Result: undefined (if node_modules is not writable)

// Using CACHE_DIR environment variable
process.env.CACHE_DIR = '/tmp/my-cache';
const custom = pkg.cache('my-tool');
// Result: "/tmp/my-cache/my-tool"
delete process.env.CACHE_DIR;
```

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

### Common Pattern: Traversing from root to starting point (reverse order)

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/walk.md

An example demonstrating how to reverse the order of parent directories to traverse from the root down to the starting point.

```typescript
const parents = walk.up('src');
const reversed = parents.reverse();
// Now walks from root (/) down to 'src'
```

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

### Running Benchmarks

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Instructions on how to install Deno and run the benchmarks, including enabling necessary permissions.

```sh
$ deno task fixtures <number of files per directory>
# enables access: fs read, env, system (for fs.access)
$ deno bench -RES
```

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

### Install

Source: https://github.com/lukeed/empathic/blob/main/readme.md

Install the empathic package using npm.

```sh
$ npm install empathic
```

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

### Example usage of pkg.up()

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/package.md

Demonstrates how to use the `up` function to find the nearest package.json file from the current directory or a specified subdirectory, and how to limit the search scope.

```typescript
import * as pkg from 'empathic/package';

// Find nearest package.json from current directory
const pkgfile = pkg.up();
// Result: "/home/user/project/package.json"

// Find from a specific subdirectory
const pkgfile2 = pkg.up({ cwd: '/home/user/project/src/lib' });
// Result: "/home/user/project/package.json"

// Limit search scope
const scoped = pkg.up({
  cwd: '/home/user/project/src',
  last: '/home/user/project'
});
// Stops searching at /home/user/project boundary
```

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

### up function example

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/find.md

Examples of using the up function to find files and directories.

```typescript
import * as find from 'empathic/find';

// Find nearest "package.json" from current directory
const pkg = find.up('package.json');
// Result: "/home/user/project/package.json"

// Find from a specific starting point
const config = find.up('tsconfig.json', {
  cwd: '/home/user/project/src/lib'
});
// Result: "/home/user/project/tsconfig.json"

// Limit search depth
const local = find.up('config.js', {
  cwd: '/home/user/project/src',
  last: '/home/user/project'
});
// Stops searching at /home/user/project boundary
```

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

### ok Example

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/access.md

Check basic visibility and with explicit mode.

```typescript
import * as access from 'empathic/access';

// Check basic visibility
if (access.ok('/etc/passwd')) {
  console.log('File is visible');
}

// Check with explicit mode
if (access.ok('/etc/passwd', fs.constants.R_OK)) {
  console.log('File is readable');
}
```

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

### any function example

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/find.md

Examples of using the any function to find files or directories based on a list of names.

```typescript
import * as find from 'empathic/find';

// Find closest config file by preference order
const config = find.any(
  ['tsconfig.json', 'jsconfig.json', '.babelrc'],
  { cwd: '/home/user/project/src' }
);
// Returns /home/user/project/tsconfig.json if it exists,
// otherwise /home/user/project/jsconfig.json, etc.

// Search order matters
const result = find.any(['license', 'readme.md']);
// Always checks for "license" first in each directory,
// then "readme.md", not filesystem order
```

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

### file function example

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/find.md

Examples of using the file function to find specific files.

```typescript
import * as find from 'empathic/find';

// Find nearest .env file
const env = find.file('.env', { cwd: 'src' });
// Result: "/home/user/project/.env" (not a directory)

// Ignores directories with the same name
const result = find.file('node_modules');
// Result: undefined (because node_modules is a directory)
```

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

### executable Example

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/access.md

Check if a path is executable.

```typescript
import * as access from 'empathic/access';

if (access.executable('/usr/bin/node')) {
  console.log('Node is executable');
}
```

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

### readable Example

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/access.md

Check if a file is readable.

```typescript
import * as access from 'empathic/access';

if (access.readable('config.json')) {
  // Safe to read the file
  const content = fs.readFileSync('config.json', 'utf8');
}
```

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

### writable Example

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/access.md

Check if a directory is writable.

```typescript
import * as access from 'empathic/access';

const dir = 'node_modules';

if (access.writable(dir)) {
  // Safe to create cache subdirectories
  fs.mkdirSync(`${dir}/.cache`, { recursive: true });
}
```

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

### Usage

Source: https://github.com/lukeed/empathic/blob/main/readme.md

Example usage of empathic utilities for finding files and managing package cache.

```ts
import { resolve } from 'node:path';
import * as find from 'empathic/find';
import * as pkg from 'empathic/package';

// Assumed example structure:
let cwd = resolve('path/to/acme/websites/dashboard');

// Find closest "foobar.config.js" file
let file = find.up('foobar.config.js', { cwd });
//=> "/.../path/to/acme/foobar.config.js"

// Find closest "package.json" file
let pkgfile = pkg.up({ cwd });
//=> "/.../path/to/acme/package.json"

// Construct (optionally create) "foobar" cache dir
let cache = pkg.cache('foobar', { cwd, create: true });
//=> "/.../path/to/acme/node_modules/.cache/foobar"
```

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

### Common Pattern: Finding parents up to workspace root

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/walk.md

An example of finding all parent directories up to a specific workspace root.

```typescript
const parents = walk.up('src', {
  cwd: '/home/user/monorepo/packages/lib',
  last: '/home/user/monorepo'
});
// Returns: ['...', '/home/user/monorepo/packages/lib', '/home/user/monorepo']
```

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

### Example Usage

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/resolve.md

Demonstrates how to use the `resolve.cwd` function to resolve module paths from the current working directory, including handling relative paths, optional dependencies, and errors.

```typescript
import * as resolve from 'empathic/resolve';

// Resolve from CWD
const pkg = resolve.cwd('lodash');
// Result: "/home/user/project/node_modules/lodash/index.js"

// Resolve relative path from CWD
const config = resolve.cwd('./config');
// Result: "/home/user/project/config.js"

// Graceful failure
const optional = resolve.cwd('optional-dep', true);
// Result: undefined (no error thrown)

// Error on missing
try {
  resolve.cwd('missing-module');
} catch (err) {
  console.log(err.code); // 'MODULE_NOT_FOUND'
}
```

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

### Path Resolution Example

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/types.md

Illustrates how input paths are resolved relative to the 'cwd' option.

```typescript
walk.up('src', { cwd: 'project' });
// Resolves 'project' relative to process.cwd() → '/home/user/project'
// Then walks parents of 'src' relative to that → '/home/user/project/src'
```

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

### any function signature

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/find.md

Get the first path that matches any of the provided names, respecting input order.

```typescript
function any(names: string[], options?: Options): string | undefined
```

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

### CACHE_DIR Environment Variable Examples

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/configuration.md

Demonstrates how to use the CACHE_DIR environment variable to control the cache directory for empathic/package.cache(). It shows setting a custom path, ignoring boolean-like values, and falling back to auto-discovery.

```typescript
import * as pkg from 'empathic/package';

// Use custom cache directory
process.env.CACHE_DIR = '/var/cache/my-app';
const path1 = pkg.cache('build');
// Result: "/var/cache/my-app/build"

// Ignore boolean-like values (fall back to auto-discovery)
process.env.CACHE_DIR = 'true';
const path2 = pkg.cache('build');
// Result: "/home/user/project/node_modules/.cache/build"

// Boolean false also triggers discovery
process.env.CACHE_DIR = '0';
const path3 = pkg.cache('build');
// Result: "/home/user/project/node_modules/.cache/build"

// No env var (auto-discovery)
delete process.env.CACHE_DIR;
const path4 = pkg.cache('build');
// Result: "/home/user/project/node_modules/.cache/build"
```

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

### Find nearest build directory

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/find.md

Finds the nearest directory named 'dist' starting the search from the 'src' directory.

```typescript
import * as find from 'empathic/find';

// Find nearest build directory
const buildDir = find.dir('dist', { cwd: 'src' });
// Result: "/home/user/project/dist"
```

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

### Boundary Control with 'last' Example

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/types.md

Demonstrates using the 'last' option to limit traversal scope.

```typescript
find.up('config.js', {
  cwd: '/home/user/monorepo/packages/app/src',
  last: '/home/user/monorepo'  // Don't search above the monorepo
});
```

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

### Benchmark Results: find.up (Walk 10 parent directories)

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Performance comparison for 'find.up' and related functions when searching in 10 parent directories.

```text
file:///.../empathic/src/find.bench.ts

benchmark                 time/iter (avg)        iter/s      (min … max)           p75      p99     p995
------------------------- ----------------------------- --------------------- --------------------------
find-up                          459.7 µs         2,175 (421.8 µs …   2.0 ms) 461.1 µs 547.8 µs   1.3 ms
find-up-simple                   374.7 µs         2,669 (340.2 µs …   1.7 ms) 383.1 µs 439.9 µs 458.6 µs
find-up-simple (sync)            187.8 µs         5,324 (182.3 µs … 456.3 µs) 188.8 µs 211.2 µs 217.5 µs
escalade                         511.4 µs         1,955 (438.9 µs … 816.5 µs) 514.9 µs 605.2 µs 702.7 µs
empathic/find.up (sync)           15.5 µs        64,410 ( 15.1 µs … 296.1 µs)  15.4 µs  18.1 µs  18.7 µs

summary
  empathic/find.up (sync)
    12.10x faster than find-up-simple (sync)
    24.13x faster than find-up-simple
    29.61x faster than find-up
    32.94x faster than escalade
```

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

### package.up (path.dirname) Benchmarks

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Benchmarks comparing empathic/package.up (path.dirname) with pkg-dir.

```plaintext
file:///.../empathic/src/package.bench.ts

benchmark                    time/iter (avg)        iter/s      (min … max)           p75      p99     p995
---------------------------- ----------------------------- --------------------- --------------------------
pkg-dir                             281.3 µs         3,556 (257.5 µs … 466.2 µs) 286.5 µs 317.8 µs 337.8 µs
pkg-dir (sync)                      137.5 µs         7,272 (128.9 µs … 296.8 µs) 138.2 µs 152.2 µs 160.8 µs
empathic/package.up (sync)           12.5 µs        80,220 ( 12.1 µs … 218.5 µs)  12.4 µs  14.0 µs  15.1 µs

summary
  empathic/package.up (sync)
    11.03x faster than pkg-dir (sync)
    22.56x faster than pkg-dir
```

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

### Benchmark Results: find.up (Walk 6 parent directories)

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Performance comparison for 'find.up' and related functions when searching in 6 parent directories.

```text
file:///.../empathic/src/find.bench.ts

benchmark                 time/iter (avg)        iter/s      (min … max)           p75      p99     p995
------------------------- ----------------------------- --------------------- --------------------------
group level-6
find-up                          207.8 µs         4,812 (173.2 µs …   3.7 ms) 208.8 µs 393.1 µs 609.6 µs
find-up-simple                   156.0 µs         6,409 (137.5 µs …   1.1 ms) 157.8 µs 224.5 µs 241.3 µs
find-up-simple (sync)             71.9 µs        13,900 ( 66.3 µs … 291.8 µs)  72.0 µs  84.2 µs  88.9 µs
escalade                         235.4 µs         4,248 (221.6 µs … 397.5 µs) 238.5 µs 290.9 µs 298.8 µs
empathic/find.up (sync)            7.3 µs       137,800 (  7.1 µs …   7.6 µs)   7.4 µs   7.6 µs   7.6 µs

summary
  empathic/find.up (sync)
     9.91x faster than find-up-simple (sync)
    21.50x faster than find-up-simple
    28.64x faster than find-up
    32.44x faster than escalade
```

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

### Benchmark Results: find.up (Walk 15+ parent directories, target not found)

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Performance comparison for 'find.up' and related functions when searching in over 15 parent directories without finding the target.

```text
file:///.../empathic/src/find.bench.ts

benchmark                 time/iter (avg)        iter/s      (min … max)           p75      p99     p995
------------------------- ----------------------------- --------------------- --------------------------
find-up                          632.0 µs         1,582 (582.1 µs …   2.7 ms) 630.4 µs 697.7 µs   1.3 ms
find-up-simple                   507.5 µs         1,970 (465.8 µs …   1.7 ms) 514.1 µs 648.5 µs 733.3 µs
find-up-simple (sync)            273.9 µs         3,651 (268.7 µs … 592.2 µs) 274.2 µs 291.3 µs 298.5 µs
escalade                         862.6 µs         1,159 (811.9 µs …   1.2 ms) 871.3 µs   1.1 ms   1.1 ms
empathic/find.up (sync)           20.5 µs        48,860 ( 19.9 µs … 314.6 µs)  20.4 µs  23.0 µs  24.0 µs

summary
  empathic/find.up (sync)
    13.38x faster than find-up-simple (sync)
    24.80x faster than find-up-simple
    30.88x faster than find-up
    42.15x faster than escalade
```

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

### Benchmark: Walk 10 parent directories

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Performance comparison of empathic/find.any (sync) against locate-path and find-up when walking 10 parent directories.

```typescript
file:///.../empathic/src/locate.bench.ts

benchmark                  time/iter (avg)        iter/s      (min … max)           p75      p99     p995
-------------------------- ----------------------------- --------------------- --------------------------
locate-path                       111.6 µs         8,960 ( 85.9 µs … 785.8 µs) 113.6 µs 148.4 µs 158.7 µs
locate-path (sync)                112.8 µs         8,865 (103.8 µs … 676.8 µs) 114.6 µs 132.0 µs 139.1 µs
locate-path (order)               111.1 µs         9,004 ( 87.0 µs … 776.6 µs) 113.5 µs 141.8 µs 151.1 µs
find-up                             1.9 ms           539 (  1.7 ms …   2.7 ms)   1.9 ms   2.5 ms   2.6 ms
find-up (sync)                      2.1 ms           478 (  2.0 ms …   2.8 ms)   2.1 ms   2.3 ms   2.5 ms
escalade                          512.7 µs         1,951 (490.3 µs … 742.4 µs) 518.1 µs 581.1 µs 642.0 µs
empathic/find.any (sync)          105.1 µs         9,514 (103.3 µs … 414.6 µs) 104.6 µs 111.8 µs 116.3 µs

summary
  empathic/find.any (sync)
     1.06x faster than locate-path (order)
     1.06x faster than locate-path
     1.07x faster than locate-path (sync)
     4.88x faster than escalade
    17.64x faster than find-up
    19.89x faster than find-up (sync)
```

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

### Benchmark: Walk 6 parent directories

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Performance comparison of empathic/find.any (sync) against locate-path and find-up when walking 6 parent directories.

```typescript
file:///.../empathic/src/locate.bench.ts

benchmark                  time/iter (avg)        iter/s      (min … max)           p75      p99     p995
-------------------------- ----------------------------- --------------------- --------------------------
locate-path                       112.8 µs         8,862 ( 83.2 µs …   3.6 ms) 113.2 µs 248.3 µs 277.5 µs
locate-path (sync)                105.3 µs         9,493 ( 97.8 µs … 442.1 µs) 105.9 µs 126.2 µs 133.8 µs
locate-path (order)               111.6 µs         8,959 ( 84.9 µs … 497.2 µs) 113.8 µs 152.5 µs 315.3 µs
find-up                             1.8 ms           545 (  1.7 ms …   2.3 ms)   1.8 ms   2.2 ms   2.2 ms
find-up (sync)                      1.9 ms           524 (  1.7 ms …   2.3 ms)   2.0 ms   2.2 ms   2.2 ms
escalade                          237.1 µs         4,219 (224.3 µs … 416.1 µs) 240.0 µs 287.7 µs 308.3 µs
empathic/find.any (sync)           48.4 µs        20,680 ( 47.4 µs … 255.0 µs)  48.1 µs  52.5 µs  55.2 µs

summary
  empathic/find.any (sync)
     2.18x faster than locate-path (sync)
     2.31x faster than locate-path (order)
     2.33x faster than locate-path
     4.90x faster than escalade
    37.89x faster than find-up
    39.41x faster than find-up (sync)
```

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

### Benchmark: Walk 15+ parent directories (no target found)

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Performance comparison of empathic/find.any (sync) against locate-path and find-up when walking 15+ parent directories without finding any targets.

```typescript
file:///.../empathic/src/locate.bench.ts

benchmark                  time/iter (avg)        iter/s      (min … max)           p75      p99     p995
-------------------------- ----------------------------- --------------------- --------------------------
locate-path                       111.0 µs         9,013 ( 87.8 µs … 797.2 µs) 112.9 µs 147.1 µs 156.2 µs
locate-path (sync)                118.0 µs         8,473 (114.6 µs … 877.2 µs) 118.2 µs 128.0 µs 132.4 µs
locate-path (order)               110.9 µs         9,021 ( 87.2 µs … 877.8 µs) 113.3 µs 143.3 µs 152.8 µs
find-up                             1.9 ms           519 (  1.7 ms …   6.4 ms)   1.9 ms   3.0 ms   3.2 ms
find-up (sync)                      2.3 ms           439 (  2.2 ms …   3.0 ms)   2.3 ms   2.7 ms   3.0 ms
escalade                          997.4 µs         1,003 (834.0 µs …   4.2 ms)   1.0 ms   2.3 ms   3.0 ms
empathic/find.any (sync)          135.4 µs         7,384 (131.0 µs … 410.4 µs) 134.9 µs 173.9 µs 202.0 µs

summary
  locate-path (order)
     1.00x faster than locate-path
     1.06x faster than locate-path (sync)
     1.22x faster than empathic/find.any (sync)
     9.00x faster than escalade
    17.37x faster than find-up
    20.53x faster than find-up (sync)
```

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

### package.up Benchmarks

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Benchmarks comparing empathic/package.up with package-up and pkg-up.

```plaintext
file:///.../empathic/src/package.bench.ts

benchmark                    time/iter (avg)        iter/s      (min … max)           p75      p99     p995
---------------------------- ----------------------------- --------------------- --------------------------
package-up                          286.7 µs         3,488 (257.5 µs … 628.8 µs) 290.9 µs 347.4 µs 362.0 µs
package-up (sync)                   134.8 µs         7,417 (123.4 µs … 242.3 µs) 135.0 µs 164.3 µs 170.0 µs
pkg-up                              360.0 µs         2,778 (319.7 µs …   3.9 ms) 359.3 µs 693.2 µs 871.6 µs
pkg-up (sync)                       156.0 µs         6,409 (139.2 µs … 731.4 µs) 158.1 µs 175.6 µs 179.8 µs
empathic/package.up (sync)           12.5 µs        80,310 ( 12.1 µs … 216.2 µs)  12.4 µs  13.7 µs  15.2 µs

summary
  empathic/package.up (sync)
    10.83x faster than package-up (sync)
    12.53x faster than pkg-up (sync)
    23.02x faster than package-up
    28.91x faster than pkg-up
```

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

### package.cache Benchmarks

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Benchmarks comparing empathic/package.cache with find-cache-dir.

```plaintext
file:///.../empathic/src/package.bench.ts

benchmark                    time/iter (avg)        iter/s      (min … max)           p75      p99     p995
---------------------------- ----------------------------- --------------------- --------------------------
find-cache-dir                      192.7 µs         5,190 (182.3 µs … 367.0 µs) 194.3 µs 207.9 µs 218.9 µs
empathic/package.cache               17.6 µs        56,920 ( 17.1 µs … 237.6 µs)  17.5 µs  20.1 µs  20.4 µs

summary
  empathic/package.cache
    10.97x faster than find-cache-dir
```

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

### resolve.from Benchmarks

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Benchmarks comparing empathic/resolve.from with resolve-from.

```plaintext
file:///.../empathic/src/resolve.bench.ts

benchmark               time/iter (avg)        iter/s      (min … max)           p75      p99     p995
----------------------- ----------------------------- --------------------- --------------------------
resolve-from                    36.9 µs        27,130 ( 35.6 µs … 213.0 µs)  36.8 µs  42.3 µs  46.1 µs
empathic/resolve.from           27.7 µs        36,100 ( 26.5 µs … 275.9 µs)  27.7 µs  31.5 µs  35.0 µs

summary
  empathic/resolve.from
     1.33x faster than resolve-from
```

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

### executable

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/access.md

Check if the current process can execute a path.

```typescript
function executable(path: PathLike): boolean
```

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

### ok

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/access.md

Check if the current process has a specific access mode to a path.

```typescript
function ok(path: PathLike, mode?: number): boolean
```

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

### up function signature

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/find.md

Find an item (file or directory) by name, walking parent directories until found.

```typescript
function up(name: string, options?: Options): string | undefined
```

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

### walk Benchmarks

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Benchmarks for empathic/walk.up.

```plaintext
file:///.../empathic/src/walk.bench.ts

benchmark              time/iter (avg)        iter/s      (min … max)           p75      p99     p995
---------------------- ----------------------------- --------------------- --------------------------
empathic/walk.up                8.0 µs       125,300 (  7.5 µs …  61.5 µs)   7.8 µs   9.4 µs  33.3 µs
```

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

### resolve.cwd Benchmarks

Source: https://github.com/lukeed/empathic/blob/main/benchmarks.md

Benchmarks comparing empathic/resolve.cwd with resolve-cwd.

```plaintext
file:///.../empathic/src/resolve.bench.ts

benchmark               time/iter (avg)        iter/s      (min … max)           p75      p99     p995
----------------------- ----------------------------- --------------------- --------------------------
resolve-cwd                     36.8 µs        27,160 ( 35.9 µs … 161.5 µs)  36.8 µs  41.5 µs  44.3 µs
empathic/resolve.cwd            32.2 µs        31,030 ( 31.3 µs … 205.8 µs)  32.2 µs  35.8 µs  38.5 µs

summary
  empathic/resolve.cwd
     1.14x faster than resolve-cwd
```

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

### file function signature

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/find.md

Find a file by name, walking parent directories until found.

```typescript
function file(name: string, options?: Options): string | undefined
```

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

### Ignores files with the same name

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/find.md

Demonstrates that find.dir ignores files with the matching name, returning undefined.

```typescript
// Ignores files with the same name
const result = find.dir('package.json');
// Result: undefined (because package.json is a file)
```

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

### up function signature

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/package.md

The TypeScript signature for the `up` function, which finds the closest "package.json" file.

```typescript
function up(options?: find.Options): string | undefined
```

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

### dir function signature

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/find.md

Find a directory by name, walking parent directories until found.

```typescript
function dir(name: string, options?: Options): string | undefined
```

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

### Import Patterns

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/README.md

Illustrates two ways to import empathic modules: importing entire modules using a namespace or importing specific exports.

```typescript
// Import entire modules
import * as find from 'empathic/find';
import * as pkg from 'empathic/package';

// Use specific exports
const pkgfile = pkg.up();
const config = find.up('config.js');
```

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

### from

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/resolve.md

Resolve a module path from a given root directory, supporting both relative and node_modules identifiers.

```typescript
function from(root: URL | string, ident: string, silent: true): string | undefined;
function from(root: URL | string, ident: string, silent?: false): string;
function from(root: URL | string, ident: string, silent?: boolean): string | undefined;
```

```typescript
import * as resolve from 'empathic/resolve';

// Resolve from a directory path
const pkg = resolve.from('/home/user/project', 'lodash');
// Result: "/home/user/project/node_modules/lodash/index.js"

// Resolve relative paths
const lib = resolve.from('/home/user/project', './src/utils');
// Result: "/home/user/project/src/utils.js" or "/home/user/project/src/utils/index.js"

// Resolve from a file URL
const fromUrl = resolve.from(
  new URL('file:///home/user/project'),
  'lodash'
);
// Result: "/home/user/project/node_modules/lodash/index.js"

// Graceful failure
const optional = resolve.from('/some/path', 'missing-module', true);
// Result: undefined (no error thrown)

// Error on missing
try {
  resolve.from('/some/path', 'missing-module');
} catch (err) {
  console.log(err.code); // 'MODULE_NOT_FOUND'
}
```

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

### readable

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/access.md

Check if the current process can read a path.

```typescript
function readable(path: PathLike): boolean
```

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

### absolute

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/resolve.md

Resolve an absolute path from a base directory, but only if the input isn't already absolute.

```typescript
function absolute(input: string, root?: string): string
```

```typescript
import * as resolve from 'empathic/resolve';

// Absolute path passes through
const abs = resolve.absolute('/etc/config');
// Result: "/etc/config"

// Relative path is resolved
const rel = resolve.absolute('config/app.json');
// Result: "/home/user/project/config/app.json"

// Custom root for resolution
const custom = resolve.absolute('app.json', '/etc');
// Result: "/etc/app.json"
```

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

### writable

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/access.md

Check if the current process can write to a path.

```typescript
function writable(path: PathLike): boolean
```

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

### Function Signature

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/walk.md

The TypeScript signature for the `up` function.

```typescript
function up(base: string, options?: Options): string[]
```

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

### cwd

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/resolve.md

Resolve a module path from the current working directory.

```typescript
function cwd(ident: string, silent: true): string | undefined;
function cwd(ident: string, silent?: false): string;
function cwd(ident: string, silent?: boolean): string | undefined;
```

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

### Options Type Definition

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/types.md

Defines the configuration options for traversal functions.

```typescript
type Options = {
  cwd?: string;
  last?: string;
}
```

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

### cache function signature

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/api-reference/package.md

The TypeScript signature for the `cache` function, which constructs a path to a node_modules cache directory.

```typescript
function cache(
  name: string,
  options?: find.Options & { create?: boolean }
): string | undefined
```

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

### CacheOptions Type Definition

Source: https://github.com/lukeed/empathic/blob/main/_autodocs/types.md

Extends the base Options type with a 'create' property for package cache operations.

```typescript
type CacheOptions = Options & {
  create?: boolean;
}
```

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