{"id":16275,"library":"which-promise","title":"Promisified Node Which","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/shinnn/which-promise","tags":["javascript","which","bin","binary","path","executable","resolve","find","check"],"install":[{"cmd":"npm install which-promise","lang":"bash","label":"npm"},{"cmd":"yarn add which-promise","lang":"bash","label":"yarn"},{"cmd":"pnpm add which-promise","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core functionality is provided by node-which; this package is a promisified wrapper around it.","package":"which","optional":false}],"imports":[{"note":"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.","wrong":"import whichPromise from 'which-promise';","symbol":"whichPromise","correct":"const whichPromise = require('which-promise');"},{"note":"The package exports a default function. Attempting to de-structure a named export for `whichPromise` will result in an error or `undefined`.","wrong":"import { whichPromise } from 'which-promise';","symbol":"whichPromise","correct":"const whichPromise = require('which-promise');"},{"note":"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.","wrong":"import type { whichPromise } from 'which-promise';","symbol":"WhichPromiseFunction","correct":"// No specific type import needed for basic usage, but for TypeScript:\nimport whichPromise = require('which-promise');"}],"quickstart":{"code":"const whichPromise = require('which-promise');\n\nasync function findExecutables() {\n  try {\n    // Find the 'node' executable in the system's PATH\n    const nodePath = await whichPromise('node');\n    console.log(`Node.js executable found at: ${nodePath}`);\n\n    // Find the 'npm' executable\n    const npmPath = await whichPromise('npm');\n    console.log(`npm executable found at: ${npmPath}`);\n\n    // Example of a command that might not exist\n    const nonExistentCommand = 'nonexistent-tool-123';\n    await whichPromise(nonExistentCommand);\n    console.log(`This line will not be reached if '${nonExistentCommand}' is not found.`);\n  } catch (err) {\n    if (err.message.startsWith('not found')) {\n      console.error(`Error: ${err.message}`);\n    } else {\n      console.error(`An unexpected error occurred: ${err.message}`);\n    }\n  }\n}\n\nfindExecutables();","lang":"javascript","description":"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."},"warnings":[{"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');`.","message":"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'.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Replace `const whichPromise = require('which-promise');` with `const which = require('which'); const whichPromise = require('util').promisify(which);`","message":"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.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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' })`.","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.","error":"Error: not found: [command-name]"},{"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`.","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.","error":"TypeError: whichPromise is not a function"},{"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.","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.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... from ... not supported."}],"ecosystem":"npm"}