escalade: Ascend Parent Directories

Common errors

• TypeError: escalade(...).then is not a function

  cause Attempting to use `await` or `.then()` on the synchronous `escalade/sync` function.
  fix Ensure you are importing the correct version of escalade. If you need asynchronous behavior, import from `'escalade'`. If you intend to use the synchronous version from `'escalade/sync'`, remove `await` keywords as it returns its value directly.

• TS2307: Cannot find module 'escalade' or its corresponding type declarations.

  cause TypeScript compilation issue due to incorrect module resolution or outdated type definitions.
  fix Ensure your `tsconfig.json` has appropriate `moduleResolution` settings (e.g., `Node16` or `NodeNext`). If using `escalade@3.1.2`, ensure `nodenext` is configured. For `escalade@3.2.0` and newer, separate ESM/CJS type definitions are provided, which should resolve most ambiguity issues. Clear `node_modules` and reinstall if issue persists.

• Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'escalade/sync' imported from ...

  cause Node.js or build tool failing to resolve the `escalade/sync` subpath export, often due to an environment not fully supporting `exports` maps.
  fix Verify your Node.js version is compatible (>=12.17.0 for stable `exports` support). Ensure bundlers or module loaders are configured to handle `exports` maps. Updating `escalade` to the latest version (`v3.1.1` fixed some specific Node 13.x issues) can also help.

Warnings

• gotcha escalade strictly traverses direct parent directories and will not explore sibling directories of any parent. Its search scope is limited to the direct ancestral chain.
  Fix: If you need to search sibling directories or a broader filesystem scope, a different utility or manual directory traversal logic is required.
• breaking In `v3.2.0`, separate TypeScript definitions for ESM and CommonJS were introduced. Previously, only ESM definitions were shipped, which could cause tool or resolution ambiguity in certain TypeScript configurations. While a fix, it might require adjustments for existing TypeScript users.
  Fix: Ensure your `tsconfig.json`'s `moduleResolution` and `module` options are correctly configured for your environment (e.g., `Node16` or `NodeNext`). This change primarily resolves issues rather than introducing new ones, but older tooling might need updates.
• gotcha Users running Node.js versions 13.0 through 13.6 (inclusive) might have encountered issues with `require()` due to early, partial support of the `exports` map behavior in those specific Node.js releases. This was patched in `v3.1.1`.
  Fix: Update to `escalade@3.1.1` or newer. Alternatively, avoid Node.js versions 13.0-13.6 if using older `escalade` versions with CommonJS `require()`.
• gotcha The `escalade/sync` module is not Promise-based. Attempting to `await` its return value will result in a runtime error because the function does not return a Promise.
  Fix: When importing from `escalade/sync`, remove any `await` keywords and handle the return value directly, as it is synchronous. For asynchronous operations, import from the default `'escalade'` path.

Install

• npm install escalade npm
• yarn add escalade yarn
• pnpm add escalade pnpm

Imports

• escalade
  wrong:

  const escalade = require('escalade');

  correct:

  import escalade from 'escalade';

  This is the primary (async) ES Module export. For CommonJS, use `require('escalade')`. Since v3.2.0, separate TypeScript definitions are provided for ESM and CJS.
• escalade (sync version)
  wrong:

  const escaladeSync = require('escalade'); // Wrong path
  import escaladeSync from 'escalade'; // Not the sync version

  correct:

  import escaladeSync from 'escalade/sync';

  To use the synchronous version, import from the specific subpath `'escalade/sync'`. This is available for both ES Modules and CommonJS (`require('escalade/sync')`).
• escalade (CommonJS)
  wrong:

  import escalade from 'escalade';

  correct:

  const escalade = require('escalade');

  This is the primary (async) CommonJS export. Ensure your environment supports `exports` map resolution or use an older Node.js version where CJS resolution was default.

Quickstart

This example demonstrates how to use the async `escalade` function to traverse parent directories from a given starting path to find the nearest `package.json` file. It then logs the path and the package name if found.

import { join } from 'path';
import escalade from 'escalade';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = join(__filename, '..');

// Assuming a file structure like:
// project-root/
//   package.json
//   src/
//     index.js
//     features/
//       my-feature.js

const startPath = join(__dirname, 'features', 'my-feature.js');

console.log(`Starting search from: ${startPath}`);

async function findPackageJson() {
  const pkgPath = await escalade(startPath, (dir, names) => {
    console.log(`  Searching in: ${dir}`);
    if (names.includes('package.json')) {
      return 'package.json';
    }
  });

  if (pkgPath) {
    console.log(`Found package.json at: ${pkgPath}`);
    const packageJson = await import(pkgPath, { assert: { type: 'json' } });
    console.log(`Package name: ${packageJson.default.name}`);
  } else {
    console.log('package.json not found in parent directories.');
  }
}

findPackageJson().catch(console.error);