Promisified Node Which

Common errors

• Error: not found: [command-name]

  cause The specified command-name executable could not be found within any directories listed in the system's PATH environment variable, or it lacks execution permissions.
  fix Verify that the command-name is correctly spelled and that its containing directory is included in your system's PATH. On Linux/macOS, check file permissions with `ls -l $(which command-name)`. You can also provide a custom `path` option to `whichPromise(cmd, { path: '/custom/bin' })`.

• TypeError: whichPromise is not a function

  cause This typically occurs when attempting to use ES Module `import` syntax (e.g., `import whichPromise from 'which-promise';` or `import { whichPromise } from 'which-promise';`) with a CommonJS-only package, or incorrectly requiring the module.
  fix Ensure you are using the correct CommonJS `require` syntax: `const whichPromise = require('which-promise');`. If in an ESM module, consider dynamic import (`import('which-promise').then(m => m)`) or `createRequire`.

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... from ... not supported.

  cause While less common for `which-promise` itself (which is CJS), this error indicates you are trying to `require()` an ES Module in a CommonJS context. If `node-which` or any transitive dependency *becomes* ESM-only, this could manifest.
  fix Ensure all dependencies are compatible with your module system. If `which-promise` or `node-which` ever transitions to ESM-only, you would need to adjust your project to use ESM `import` statements or dynamic `import()` where appropriate.

Warnings

• gotcha The `which-promise` package is a CommonJS (CJS) module. Attempting to use the `import` statement directly in an ES Module (ESM) context without a bundler (like Webpack or Rollup) or Node.js's specific CJS-ESM interop settings (e.g., `"type": "module"` in package.json with `createRequire`) may lead to errors like 'whichPromise is not a function' or 'ERR_REQUIRE_ESM'.
  Fix: For ESM projects, use `const whichPromise = require('which-promise');` if within `createRequire`, or consider dynamic `import('which-promise').then(m => m.default)`. For most direct usage in Node.js, stick to `const whichPromise = require('which-promise');`.
• gotcha The behavior of `which-promise` (and its underlying `node-which` dependency) is heavily influenced by the `PATH` environment variable. If `PATH` is incorrectly configured or does not include the directory where an executable resides, `which-promise` will correctly report that the command was not found, even if it exists elsewhere on the system.
  Fix: Ensure the `PATH` environment variable is correctly set for your operating system and user. When `which-promise` returns 'not found', it indicates the command is not accessible via the configured `PATH`.
• gotcha Since `which-promise` is a wrapper around `node-which`, its functionality and any subtle behaviors (e.g., Windows executable extension handling, permissions checks) are inherited from `node-which`. Changes or nuances in `node-which` behavior will directly affect `which-promise`.
  Fix: Refer to the documentation for `node-which` (github.com/npm/node-which) for detailed information on platform-specific behaviors or advanced options that can be passed through `which-promise`'s `options` argument.
• deprecated For newer Node.js applications, consider using `util.promisify(require('which'))` directly. This approach might reduce dependency count if `which-promise` is the only external wrapper used for `which`, leveraging native Node.js Promise utility.
  Fix: Replace `const whichPromise = require('which-promise');` with `const which = require('which'); const whichPromise = require('util').promisify(which);`

Install

• npm install which-promise npm
• yarn add which-promise yarn
• pnpm add which-promise pnpm

Imports

• whichPromise
  wrong:

  import whichPromise from 'which-promise';

  correct:

  const whichPromise = require('which-promise');

  As of v1.0.0, this package is CommonJS-only and exports a single function. Direct ES Module `import` syntax will typically fail without a bundler or specific Node.js module resolution settings.
• whichPromise
  wrong:

  import { whichPromise } from 'which-promise';

  correct:

  const whichPromise = require('which-promise');

  The package exports a default function. Attempting to de-structure a named export for `whichPromise` will result in an error or `undefined`.
• WhichPromiseFunction
  wrong:

  import type { whichPromise } from 'which-promise';

  correct:

  // No specific type import needed for basic usage, but for TypeScript:
  import whichPromise = require('which-promise');

  While TypeScript definitions might exist externally or be inferred, the package itself is not primarily designed with explicit type exports. Using CommonJS-style `import = require()` is the common pattern for typing CJS modules in TypeScript.

Quickstart

This quickstart demonstrates how to use `which-promise` to asynchronously locate common executables like 'node' and 'npm' in the system's PATH, and handles the case where a command is not found.

const whichPromise = require('which-promise');

async function findExecutables() {
  try {
    // Find the 'node' executable in the system's PATH
    const nodePath = await whichPromise('node');
    console.log(`Node.js executable found at: ${nodePath}`);

    // Find the 'npm' executable
    const npmPath = await whichPromise('npm');
    console.log(`npm executable found at: ${npmPath}`);

    // Example of a command that might not exist
    const nonExistentCommand = 'nonexistent-tool-123';
    await whichPromise(nonExistentCommand);
    console.log(`This line will not be reached if '${nonExistentCommand}' is not found.`);
  } catch (err) {
    if (err.message.startsWith('not found')) {
      console.error(`Error: ${err.message}`);
    } else {
      console.error(`An unexpected error occurred: ${err.message}`);
    }
  }
}

findExecutables();