@alphahydrae/exec 1.0.2 → 2.0.0

package/README.md

@@ -41,7 +41,7 @@ npm i @alphahydrae/exec
 
 ## Support matrix
 
-| OS & Architecture | Node.js 18 | Node.js 20 | Node.js 22 |
+| OS & Architecture | Node.js 20 | Node.js 22 | Node.js 24 |
 | :---------------- | :--------: | :--------: | :--------: |
 | macOS x64         |     ✅     |     ✅     |     ✅     |
 | macOS arm64       |     ✅     |     ✅     |     ✅     |

package/exec.d.ts

@@ -1,18 +1,29 @@
+export type ExecvpOptions = {
+  readonly arg0?: string | null;
+};
+
 /**
  * Performs the execvp system call with the given file and arguments, replacing
  * the current process image with the new one.
  *
- *     execvp('ls', ['-l', '.']);
- *
- * This function does not return if successful, as the current process is
+ * This function does not return if successful, as the current process image is
  * replaced by the new one. An error may be thrown, with an error message
  * containing the error code returned by execvp.
  *
+ * @example
+ * import { execvp } from '@alphahydrae/exec';
+ * execvp('ls', ['-l', '.']);
+ *
  * @param {string} file The file to execute. If not a path, the PATH environment
  *                      variable is searched.
- * @param {string[]} args The arguments to pass to the new process.
- *                        `process.argv0` is automatically prepended to the
- *                        arguments.
+ * @param {string[]} args The arguments to pass to the new process. The `file`
+ *                        argument is automatically prepended to the arguments
+ *                        and passed as the first argument to the `execvp`
+ *                        system call.
+ * @param {Object} [options] Optional options.
+ * @param {string} [options.arg0=file] The value to pass as the first argument
+ *                                     to the `execvp` system call. Defaults to
+ *                                     the `file` argument.
  * @throws {Error} If the execvp system call fails.
  */
-export declare function execvp(file: string, args: string[]): void;
+export declare function execvp(file: string, args: string[], options?: ExecvpOptions): void;

package/exec.js

@@ -4,7 +4,7 @@ const native = require('./index.js');
  * Performs the execvp system call with the given file and arguments, replacing
  * the current process image with the new one.
  *
- * This function does not return if successful, as the current process is
+ * This function does not return if successful, as the current process image is
  * replaced by the new one. An error may be thrown, with an error message
  * containing the error code returned by execvp.
  *
@@ -15,12 +15,23 @@ const native = require('./index.js');
  * @param {string} file The file to execute. If not a path, the PATH environment
  *                      variable is searched.
  * @param {string[]} args The arguments to pass to the new process. The `file`
- *                        argument is automatically prepended to the arguments.
+ *                        argument is automatically prepended to the arguments
+ *                        and passed as the first argument to the `execvp`
+ *                        system call.
+ * @param {Object} [options] Optional options.
+ * @param {string} [options.arg0=file] The value to pass as the first argument
+ *                                     to the `execvp` system call. Defaults to
+ *                                     the `file` argument.
  * @throws {Error} If the execvp system call fails.
  */
-module.exports.execvp = function (file, args) {
+module.exports.execvp = function (file, args, options = {}) {
+  const arg0 = options.arg0 ?? file;
+
+  // Prevent the standard streams from being closed when the process is
+  // replaced.
   native.doNotCloseOnExit(process.stdin.fd);
   native.doNotCloseOnExit(process.stdout.fd);
   native.doNotCloseOnExit(process.stderr.fd);
-  native.execvp(file, [file, ...args]);
+
+  native.execvp(file, [arg0, ...args]);
 };

package/index.d.ts

@@ -18,13 +18,13 @@
  *
  * @example
  * import { execvp } from '@alphahydrae/exec';
- * execvp('ls', ['ls', '-l', '.']);
+ * execvp('ls', ['/bin/ls', '-l', '.']);
  *
  * @param {string} file The file to execute. If not a path, the PATH environment
  *                      variable is searched.
  * @param {string[]} args The arguments to pass to the new process. Note that
- *                        the first argument should be the name of the file
- *                        being executed.
+ *                        the first argument, by convention, should point to
+ *                        the filename associated with the file being executed.
  * @throws {Error} If the execvp system call fails.
  */
 export declare function execvp(file: string, args: Array<string>): void

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphahydrae/exec",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "description": "The execvp function for Node.js",
   "main": "exec.js",
   "repository": {
@@ -38,9 +38,10 @@
     "build": "napi build --platform --release",
     "build:debug": "napi build --platform",
     "build:package": "node scripts/build-packages.mjs",
-    "check": "npm run lint && npm run format",
-    "check:write": "npm run lint && npm run format:write",
+    "check": "npm test && npm run lint && npm run format",
+    "check:write": "npm test && npm run lint && npm run format:write",
     "doctoc": "doctoc --github --notitle README.md && prettier --write README.md",
+    "docs": "jsdoc --destination docs --readme README.md exec.js",
     "format": "npm run format:cargo && npm run format:prettier",
     "format:cargo": "cargo fmt --check",
     "format:cargo:write": "cargo fmt",
@@ -59,19 +60,20 @@
     "chalk": "^5.3.0",
     "doctoc": "^2.2.1",
     "jest": "^29.7.0",
+    "jsdoc": "^4.0.4",
     "npm-run-all2": "^7.0.0",
     "prettier": "^3.4.2",
     "typescript": "^5.5.3"
   },
   "engines": {
-    "node": "^18 || ^20 || ^22"
+    "node": "^20 || ^22 || ^24"
   },
   "optionalDependencies": {
-    "@alphahydrae/exec-darwin-x64": "1.0.2",
-    "@alphahydrae/exec-linux-x64-gnu": "1.0.2",
-    "@alphahydrae/exec-linux-x64-musl": "1.0.2",
-    "@alphahydrae/exec-darwin-arm64": "1.0.2",
-    "@alphahydrae/exec-linux-arm64-gnu": "1.0.2",
-    "@alphahydrae/exec-linux-arm64-musl": "1.0.2"
+    "@alphahydrae/exec-darwin-x64": "2.0.0",
+    "@alphahydrae/exec-linux-x64-gnu": "2.0.0",
+    "@alphahydrae/exec-linux-x64-musl": "2.0.0",
+    "@alphahydrae/exec-darwin-arm64": "2.0.0",
+    "@alphahydrae/exec-linux-arm64-gnu": "2.0.0",
+    "@alphahydrae/exec-linux-arm64-musl": "2.0.0"
   }
 }