@theholocron/fs-utils 1.10.0 → 1.11.0

package/README.md

@@ -11,7 +11,7 @@ pnpm add @theholocron/fs-utils
 ## Usage
 
 ```typescript
-import { findRoot, findUpward, hasGitEntry } from "@theholocron/fs-utils";
+import { findExecutable, findExecutableSync, findRoot, findUpward, hasGitEntry } from "@theholocron/fs-utils";
 
 // nearest ancestor holding a marker file or directory
 const repoRoot = await findRoot(process.cwd(), ".git");
@@ -62,6 +62,28 @@ working directory up front, so results are always absolute.
 const root = findRootSync(cwd, ".git", { fallback: "start", realpath: true });
 ```
 
+### `findExecutable(bin, options?)` / `findExecutableSync(...)`
+
+The first runnable file named `bin` on `options.path` (default `process.env.PATH`),
+or `undefined` — a `which`. Directories and files without the exec bit don't
+count. `bin` must be a bare command name (an empty string, `.`, `..` or anything
+with a path separator throws a `TypeError`), as does any filesystem error other
+than "not there" / "not permitted".
+
+- `options.path` — directories to search, delimited like `PATH` on the target
+  platform (`:` on POSIX, `;` on Windows). Empty entries are skipped; relative
+  ones are resolved against the working directory when the call starts, so
+  results are always absolute.
+- `options.pathExt` / `options.platform` — on Windows there is no exec bit:
+  `bin` is tried with each `PATHEXT` extension (default `.COM;.EXE;.BAT;.CMD`)
+  unless it already ends in one. An extension containing a path separator
+  throws a `TypeError`.
+
+```typescript
+// a project-local binary first, then the real PATH
+const tsc = findExecutableSync("tsc", { path: join(cwd, "node_modules", ".bin") }) ?? findExecutableSync("tsc");
+```
+
 ### `hasGitEntry(dir)`
 
 Returns `true` when `dir` has a `.git` entry — a directory in a normal

package/dist/index.d.mts

@@ -1,3 +1,35 @@
+//#region src/find-executable.d.ts
+export interface FindExecutableOptions {
+  /**
+   * Directories to search, delimited the way `PATH` is on `platform` (`:` on
+   * POSIX, `;` on Windows). Defaults to `process.env.PATH`. Empty entries are
+   * skipped rather than read as the working directory; relative ones are
+   * resolved against the working directory when the call starts.
+   */
+  path?: string;
+  /**
+   * Windows only: the extensions that make a file runnable, delimited with
+   * `;`. Defaults to `process.env.PATHEXT`, else `.COM;.EXE;.BAT;.CMD`. Each
+   * must be a bare extension — one with a path separator throws a `TypeError`,
+   * since it would otherwise reach outside the searched directory.
+   */
+  pathExt?: string;
+  /** Defaults to `process.platform`. Windows has no exec bit, so only the extension decides. */
+  platform?: NodeJS.Platform;
+}
+/**
+ * The first runnable file named `bin` in `options.path` (default
+ * `process.env.PATH`), as an absolute path, or `undefined`.
+ * Directories and files without the exec bit don't count.
+ *
+ * `bin` must be a bare name — an empty string, `.`, `..` or anything with a
+ * path separator throws a `TypeError`, as does any filesystem error other
+ * than "not there" / "not permitted".
+ */
+export declare function findExecutable(bin: string, options?: FindExecutableOptions): Promise<string | undefined>;
+/** Synchronous twin of {@link findExecutable}. */
+export declare function findExecutableSync(bin: string, options?: FindExecutableOptions): string | undefined;
+//#endregion
 //#region src/find-root.d.ts
 export interface FindRootOptions {
   /**

package/dist/index.mjs

@@ -1,6 +1,77 @@
-import { realpathSync, statSync } from "node:fs";
-import { realpath, stat } from "node:fs/promises";
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
+//#region src/find-executable.ts
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+/** A bare command name, joined onto each search directory — never a path of its own. */
+function assertBare(bin) {
+	if (bin === "" || bin === "." || bin === ".." || /[\\/]/.test(bin) || bin.includes("\0")) throw new TypeError(`findExecutable: bin must be a bare command name, got ${JSON.stringify(bin)}`);
+}
+/**
+* Every file name `bin` could run as in one directory, in the order they are
+* tried. Computed once per call so the order can't shift mid-search if the
+* environment changes underneath an in-flight lookup.
+*/
+function namesFor(bin, options) {
+	if ((options.platform ?? process.platform) !== "win32") return [bin];
+	const exts = (options.pathExt ?? process.env["PATHEXT"] ?? DEFAULT_PATHEXT).split(";").filter(Boolean);
+	for (const ext of exts) if (/[\\/]/.test(ext) || ext.includes("\0")) throw new TypeError(`findExecutable: pathExt entries must not contain path separators, got ${JSON.stringify(ext)}`);
+	if (exts.some((ext) => bin.toLowerCase().endsWith(ext.toLowerCase()))) return [bin];
+	return exts.map((ext) => bin + ext);
+}
+/** The search directories, absolute, so a `chdir` during the awaits can't change what a relative entry means. */
+function dirsOf(options) {
+	const win = (options.platform ?? process.platform) === "win32";
+	return (options.path ?? process.env["PATH"] ?? "").split(win ? ";" : ":").filter(Boolean).map((dir) => resolve(dir));
+}
+/** Only "nothing there" or "not runnable" means this candidate isn't it; anything else is real. */
+const isMiss = (err) => {
+	const code = err?.code;
+	return code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM";
+};
+/**
+* The first runnable file named `bin` in `options.path` (default
+* `process.env.PATH`), as an absolute path, or `undefined`.
+* Directories and files without the exec bit don't count.
+*
+* `bin` must be a bare name — an empty string, `.`, `..` or anything with a
+* path separator throws a `TypeError`, as does any filesystem error other
+* than "not there" / "not permitted".
+*/
+async function findExecutable(bin, options = {}) {
+	assertBare(bin);
+	const win = (options.platform ?? process.platform) === "win32";
+	const dirs = dirsOf(options);
+	const names = namesFor(bin, options);
+	for (const dir of dirs) for (const name of names) {
+		const candidate = join(dir, name);
+		try {
+			if (!(await stat(candidate)).isFile()) continue;
+			if (!win) await access(candidate, constants.X_OK);
+			return candidate;
+		} catch (err) {
+			if (!isMiss(err)) throw err;
+		}
+	}
+}
+/** Synchronous twin of {@link findExecutable}. */
+function findExecutableSync(bin, options = {}) {
+	assertBare(bin);
+	const win = (options.platform ?? process.platform) === "win32";
+	const dirs = dirsOf(options);
+	const names = namesFor(bin, options);
+	for (const dir of dirs) for (const name of names) {
+		const candidate = join(dir, name);
+		try {
+			if (!statSync(candidate).isFile()) continue;
+			if (!win) accessSync(candidate, constants.X_OK);
+			return candidate;
+		} catch (err) {
+			if (!isMiss(err)) throw err;
+		}
+	}
+}
+//#endregion
 //#region src/find-upward.ts
 /**
 * Walks upward from `startDir` — `startDir` itself first, then its parent,
@@ -119,4 +190,4 @@ function findRootSync(startDir, marker, options = {}) {
 	}
 }
 //#endregion
-export { findRoot, findRootSync, findUpward, hasGitEntry };
+export { findExecutable, findExecutableSync, findRoot, findRootSync, findUpward, hasGitEntry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/fs-utils",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Walk a directory tree upward to find the nearest match or project root.",
   "keywords": [
     "filesystem",