init project

2026-07-31 13:12:54 -04:00
parent 0da92d5e02
commit f3863f760c
7215 changed files with 1860260 additions and 1 deletions
@@ -0,0 +1,121 @@
+# which-command
+
+> Find the absolute path to a command's executable, like the Unix [`which`](https://en.wikipedia.org/wiki/Which_(command)) command
+
+Useful for locating an executable in `PATH` before spawning it, checking whether a tool is installed, or building your own CLI tooling.
+
+Works cross-platform, including Windows `PATHEXT` handling and App Execution Aliases.
+
+## Install
+
+```sh
+npm install which-command
+```
+
+## Usage
+
+```js
+import {whichCommand, whichCommandSync, whichCommandAll} from 'which-command';
+
+await whichCommand('node');
+//=> '/usr/local/bin/node'
+
+await whichCommand('does-not-exist');
+//=> undefined
+
+whichCommandSync('node');
+//=> '/usr/local/bin/node'
+
+await whichCommandAll('node');
+//=> ['/usr/local/bin/node', '/opt/homebrew/bin/node']
+```
+
+## API
+
+### whichCommand(command, options?)
+
+Returns a `Promise` for the absolute path to the first matching executable, or `undefined` if not found.
+
+### whichCommandSync(command, options?)
+
+Same as `whichCommand()`, but synchronous.
+
+### whichCommandAll(command, options?)
+
+Returns a `Promise` for an array of the absolute paths to all matching executables in `PATH` order, or an empty array if none are found. Like `which -a`.
+
+### whichCommandAllSync(command, options?)
+
+Same as `whichCommandAll()`, but synchronous.
+
+#### command
+
+Type: `string`
+
+The command name to look for, or a path to check directly.
+
+If it contains a directory separator (like `./foo` or `/usr/bin/foo`), it's resolved directly instead of being searched for in `PATH`.
+
+#### options
+
+Type: `object`
+
+##### cwd
+
+Type: `string`\
+Default: [`process.cwd()`](https://nodejs.org/api/process.html#processcwd)
+
+The directory to resolve relative paths against.
+
+Relative `path` entries and commands that contain a directory separator are resolved against this. On Windows, this directory is also searched before `PATH`.
+
+##### path
+
+Type: `string`\
+Default: [`process.env.PATH`](https://en.wikipedia.org/wiki/PATH_(variable))
+
+The `PATH` to search.
+
+Empty entries are ignored. Unlike a POSIX shell, an empty entry is not treated as the current directory, since implicitly searching the current directory is a security risk.
+
+##### pathExt
+
+Type: `string`\
+Default: `process.env.PATHEXT`
+
+The executable file extensions to look for, as a `;`-separated string.
+
+Only used on Windows. Corresponds to the [`PATHEXT`](https://learn.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ee537574(v=office.14)) environment variable.
+
+## CLI
+
+```sh
+$ npx which-command --help
+
+  Usage
+    $ which-command <command> …
+
+  Options
+    --all, -a     List all matching paths, not just the first
+    --silent, -s  Suppress output; the exit code still reflects whether all commands were found
+
+  Examples
+    $ which-command node
+    /usr/local/bin/node
+
+    $ which-command --all node
+    /usr/local/bin/node
+    /opt/homebrew/bin/node
+
+  Exits with code 1 if any of the commands could not be found.
+```
+
+## FAQ
+
+### How is it better than the [`which`](https://github.com/npm/node-which) package?
+
+- Returns `undefined` when a command is not found, instead of throwing.
+- `whichCommandAll()` deduplicates results, so duplicate `PATH` entries don't produce duplicate matches.
+- Safer by default: empty `PATH` entries are ignored instead of implicitly searching the current directory.
+- Finds Windows App Execution Aliases (like the `python` and `winget` stubs in `WindowsApps`), which `which` skips.
+- Modern: pure ESM with bundled TypeScript types.