@alphahydrae/exec 0.2.2 → 0.2.4

package/README.md

@@ -11,7 +11,7 @@ console.log(`
   This will never print because the executing Node.js
   program is replaced by the executed command, keeping
   the same process ID and file descriptors.
-`)
+`);
 ```
 
 If you're familiar with Bash's `exec` function, this is the same for Node.js.
@@ -20,6 +20,15 @@ This package was developed to be used in Node.js scripts that are frontends to
 execute other commands. For example, a script that would build and execute a
 complex SSH or Ansible command.
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Installation](#installation)
+- [Support matrix](#support-matrix)
+- [Credits](#credits)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Installation
 
 ```bash
@@ -40,3 +49,17 @@ npm i @alphahydrae/exec
 > The `exec` family of functions is part of the
 > [POSIX](https://en.wikipedia.org/wiki/POSIX) operating system API, so it will
 > not work on Windows.
+
+## Credits
+
+This package is a re-implementation of
+https://github.com/jprichardson/node-kexec in Rust, also inspired by the
+following conversations:
+
+- [A way to call execl, execle, execlp, execv, execvP or execvp from Node.js](https://stackoverflow.com/a/77774287/249893)
+- [execve in node](https://groups.google.com/g/nodejs/c/4vtWG1KCQC4)
+
+Also a big thank you to the following Rust projects for making it easy:
+
+- [NAPI-RS](https://napi.rs) (build pre-compiled Node.js addons in Rust)
+- [nix](https://docs.rs/nix) (Rust-friendly bindings to the various *nix system functions)

package/exec.d.ts

@@ -1 +1,18 @@
-export declare function execvp(file: string, args: Array<string>): void;
+/**
+ * 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
+ * replaced by the new one. An error may be thrown, with an error message
+ * containing the error code returned by execvp.
+ *
+ * @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.
+ * @throws {Error} If the execvp system call fails.
+ */
+export declare function execvp(file: string, args: string[]): void;

package/exec.js

@@ -1,8 +1,26 @@
 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
+ * 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. The `file`
+ *                        argument is automatically prepended to the arguments.
+ * @throws {Error} If the execvp system call fails.
+ */
 module.exports.execvp = function (file, args) {
   native.doNotCloseOnExit(process.stdin.fd);
   native.doNotCloseOnExit(process.stdout.fd);
   native.doNotCloseOnExit(process.stderr.fd);
-  native.execvp(file, [process.argv0, ...args]);
+  native.execvp(file, [file, ...args]);
 };

package/index.d.ts

@@ -3,5 +3,41 @@
 
 /* auto-generated by NAPI-RS */
 
+/**
+ * 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
+ * replaced by the new one. An error may be thrown, with an error message
+ * containing the error code returned by execvp.
+ *
+ * Note that the close-on-exec flag should be cleared for the process's file
+ * descriptors. Otherwise, they will be closed automatically when the new
+ * process is executed, which will likely make it fail. Use the
+ * `doNotCloseOnExit` function to clear the flag for a file descriptor.
+ *
+ * @example
+ * import { execvp } from '@alphahydrae/exec';
+ * execvp('ls', ['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.
+ * @throws {Error} If the execvp system call fails.
+ */
 export declare function execvp(file: string, args: Array<string>): void
+/**
+ * Clears the close-on-exec flag for the given file descriptor, preventing it
+ * from being closed automatically when a new process is executed with the exec
+ * family of functions.
+ *
+ * @example
+ * doNotCloseOnExit(process.stdout.fd);
+ *
+ * @param {number} file The file descriptor to close (e.g. `process.stdout.fd`).
+ * @returns {undefined}
+ * @throws {Error} If the fcntl system call fails.
+ */
 export declare function doNotCloseOnExit(fd: number): void

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphahydrae/exec",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "The execvp function for Node.js",
   "main": "exec.js",
   "repository": {
@@ -39,6 +39,7 @@
     "build:debug": "napi build --platform",
     "check": "npm run lint && npm run format",
     "check:write": "npm run lint && npm run format:write",
+    "doctoc": "doctoc --github --notitle README.md && prettier --write README.md",
     "format": "npm run format:cargo && npm run format:prettier",
     "format:cargo": "cargo fmt --check",
     "format:cargo:write": "cargo fmt",
@@ -53,7 +54,7 @@
   "devDependencies": {
     "@napi-rs/cli": "^2.18.4",
     "@swc-node/register": "^1.10.6",
-    "@swc/core": "^1.6.13",
+    "@swc/core": "^1.10.12",
     "chalk": "^5.3.0",
     "doctoc": "^2.2.1",
     "jest": "^29.7.0",
@@ -65,11 +66,11 @@
     "node": "^18 || ^20 || ^22"
   },
   "optionalDependencies": {
-    "@alphahydrae/exec-darwin-x64": "0.2.2",
-    "@alphahydrae/exec-linux-x64-gnu": "0.2.2",
-    "@alphahydrae/exec-linux-x64-musl": "0.2.2",
-    "@alphahydrae/exec-darwin-arm64": "0.2.2",
-    "@alphahydrae/exec-linux-arm64-gnu": "0.2.2",
-    "@alphahydrae/exec-linux-arm64-musl": "0.2.2"
+    "@alphahydrae/exec-darwin-x64": "0.2.4",
+    "@alphahydrae/exec-linux-x64-gnu": "0.2.4",
+    "@alphahydrae/exec-linux-x64-musl": "0.2.4",
+    "@alphahydrae/exec-darwin-arm64": "0.2.4",
+    "@alphahydrae/exec-linux-arm64-gnu": "0.2.4",
+    "@alphahydrae/exec-linux-arm64-musl": "0.2.4"
   }
 }