Registry / devops / which-promise

which-promise

JSON →
library1.0.0jsnpmunverified

which-promise is a JavaScript utility library that provides a Promise-based API for locating executable programs within a user's system `PATH` environment variable. It functions as a direct, promisified wrapper around the robust and widely used `node-which` library, offering a modern, asynchronous interface to a fundamental system operation. The package is currently at version 1.0.0, indicating a stable and mature API that is unlikely to see frequent breaking changes. As a wrapper, its release cadence is closely tied to updates and bug fixes in its underlying dependency, `node-which`, primarily focusing on stability and compatibility across different Node.js versions and operating systems. Its primary differentiator is simplifying the asynchronous lookup of executables by leveraging native JavaScript Promises, making it straightforward to integrate into contemporary `async/await` workflows, which is a significant improvement over traditional callback-based approaches. It is particularly valuable in Node.js development for scripting, tooling, and applications that require programmatic discovery of system binaries.

devops
npm install which-promise
github ↗package ↗
INSTALL
IMPORT
SIG · WHICH-PROMISE
W
which-promise
devopsjavascriptv1.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

whichPromise
✓ const whichPromise = require('which-promise');
✗ import whichPromise from '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
✓ const whichPromise = require('which-promise');
✗ import { whichPromise } from '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
✓ // No specific type import needed for basic usage, but for TypeScript: import whichPromise = require('which-promise');
✗ import type { whichPromise } from '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.

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();
Debug
Known issues
gotchaThe `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');`.
affects: >=1.0.0
gotchaThe 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`.
affects: >=1.0.0
gotchaSince `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.
affects: >=1.0.0
deprecatedFor 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);`
affects: >=1.0.0
Errors
Common errors & fixes
Error: not found: [command-name]
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
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.
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.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies
whichrequiredCore functionality is provided by node-which; this package is a promisified wrapper around it.
Agent activity
6 hits · last 30 days
node
6
Resources
githubhttps://github.com/shinnn/which-promise ↗
packagehttps://www.npmjs.com/package/which-promise ↗