@gjsify/child_process 0.36.0 → 0.37.0

package/lib/types/index.d.ts

@@ -27,12 +27,8 @@ export interface ExecOptions {
     uid?: number;
     gid?: number;
     windowsHide?: boolean;
-    /**
-     * Allows aborting the child process via an `AbortController`. When the
-     * signal fires, the child is killed with `killSignal` (default `SIGTERM`)
-     * and the registered callback receives an `Error` with `name: 'AbortError'`.
-     * Reference: https://nodejs.org/api/child_process.html#child_processexeccommand-options-callback
-     */
+    /** On abort the child is killed with `killSignal` (default `SIGTERM`) and the
+     *  callback receives an `Error` with `name: 'AbortError'`. */
     signal?: AbortSignal;
 }
 export interface ExecSyncOptions {
@@ -61,42 +57,25 @@ export interface SpawnOptions {
     uid?: number;
     gid?: number;
     /**
-     * Override what the child process sees as `argv[0]`.
-     *
-     * `Gio.SubprocessLauncher` does not expose `set_child_setup` to GIR, so on
-     * POSIX this is implemented by wrapping the spawn through a shell's
-     * `exec -a "$0" "$@"`. Not expressible on Windows — throws there
-     * (`ERR_UNSUPPORTED_OPERATION`).
+     * `Gio.SubprocessLauncher` hides `set_child_setup` from GIR, so on POSIX
+     * argv[0] is overridden by wrapping the spawn in a shell's
+     * `exec -a "$0" "$@"`. Inexpressible on Windows — throws
+     * `ERR_UNSUPPORTED_OPERATION` there.
      */
     argv0?: string;
     /**
-     * Spawn the child as the leader of a new session/process group so it
-     * survives the parent exiting.
-     *
-     * POSIX: uses `setsid(1)` resolved from PATH. When no `setsid` binary
-     * exists (stock macOS, Windows) the child is still spawned and still
-     * outlives the parent, but is not promoted to a session leader — see the
-     * package README for the exact per-platform contract.
+     * Leader of a new session/process group, via `setsid(1)` from PATH. With no
+     * `setsid` binary (stock macOS, Windows) the child still spawns and still
+     * outlives the parent, it is just not promoted to session leader.
      */
     detached?: boolean;
-    /**
-     * Accepted and ignored on every platform: `Gio.SubprocessLauncher` exposes
-     * no `CreateProcess` creation flags, so the console-window suppression
-     * Node performs on Windows is unreachable from GIR.
-     */
+    /** Accepted and ignored everywhere: GIR exposes no `CreateProcess` creation flags. */
     windowsHide?: boolean;
-    /**
-     * Accepted and ignored on every platform: GLib always builds the Windows
-     * command line itself (`protect_argv()`), so its argument quoting cannot
-     * be bypassed the way libuv's can.
-     */
+    /** Accepted and ignored everywhere: GLib builds the Windows command line itself
+     *  (`protect_argv()`), so its quoting cannot be bypassed as libuv's can. */
     windowsVerbatimArguments?: boolean;
-    /**
-     * Allows aborting the child process via an `AbortController`. When the
-     * signal fires, the child is killed with `killSignal` (default `SIGTERM`)
-     * and an `error` event with `name: 'AbortError'` is emitted.
-     * Reference: https://nodejs.org/api/child_process.html#child_processspawncommand-args-options
-     */
+    /** On abort the child is killed with `killSignal` (default `SIGTERM`) and an
+     *  `error` event with `name: 'AbortError'` is emitted. */
     signal?: AbortSignal;
 }
 export interface SpawnSyncResult {
@@ -108,9 +87,6 @@ export interface SpawnSyncResult {
     signal: string | null;
     error?: Error;
 }
-/**
- * ChildProcess — EventEmitter wrapping Gio.Subprocess.
- */
 export declare class ChildProcess extends EventEmitter {
     pid?: number;
     exitCode: number | null;
@@ -121,42 +97,26 @@ export declare class ChildProcess extends EventEmitter {
     stdout: Readable | null;
     stderr: Readable | null;
     /**
-     * Node-compatible `stdio` tuple — `[stdin, stdout, stderr, ...extraFds]`.
-     * Index 0/1/2 mirror the named streams above. Slots 3+ are reserved for
-     * `options.stdio = ['pipe', 'pipe', 'pipe', 'pipe']` extra fds, which we
-     * don't surface yet — `null` placeholders match Node's shape when extras
-     * weren't requested. Consumers like execa iterate this array (e.g. to
-     * dispose streams on subprocess exit), so the property MUST exist even
-     * when nothing was piped.
+     * `[stdin, stdout, stderr]` only — extra fds from
+     * `options.stdio = [..., 'pipe']` are not surfaced, so the tuple never grows
+     * past index 2. Must exist even when nothing was piped: execa iterates it to
+     * dispose streams on subprocess exit.
      */
     get stdio(): Array<Writable | Readable | null>;
     private _subprocess;
     /**
-     * @internal Adopt the underlying Gio.Subprocess.
-     *
-     * `pid` is supplied by the caller (`_spawnSubprocess`) rather than read
-     * here via `proc.get_identifier()`, because that accessor is RACY for an
-     * instant-exit child: `g_subprocess_get_identifier()` returns the pid only
-     * while `subprocess->pid != 0`, and GSubprocess's child-watch (running on
-     * the GLib *worker thread*, not the main context — see
-     * `g_subprocess_exited` in glib's `gio/gsubprocess.c`) sets `pid = 0` the
-     * instant it reaps the child. For a fast child like `echo`, that reap can
-     * win the race against any synchronous JS read, leaving `get_identifier()`
-     * permanently null. Node guarantees `cp.pid` is a positive integer
-     * synchronously, so we capture the pid at spawn time — the one moment it
-     * is provably still alive — and hand it in here. See
-     * `_capturePidAtSpawn` / `_spawnSubprocess`.
+     * @internal The caller passes `pid` in rather than letting us read
+     * `proc.get_identifier()`, which is racy: GSubprocess's child-watch runs on
+     * the GLib worker thread and nulls the identifier the instant it reaps, so a
+     * fast child like `echo` can beat any synchronous JS read and leave the pid
+     * permanently unreadable. Node promises `cp.pid` synchronously, so
+     * `_capturePidAtSpawn` takes it at spawn time instead.
      */
     _setSubprocess(proc: Gio.Subprocess, pid: number): void;
     /**
-     * Send a signal to the child process.
-     *
-     * Accepts a numeric signal or a POSIX signal NAME (`'SIGTERM'`,
-     * `'SIGKILL'`, …). Unrecognised names default to SIGTERM the way
-     * Gio's `send_signal` does. Returns `true` on success / when the
-     * signal was at least dispatched, `false` if we no longer have a
-     * subprocess handle (matches Node's "no-op on already-reaped child"
-     * return shape).
+     * Accepts a signal number or POSIX name; an unrecognised name falls back to
+     * SIGTERM rather than throwing. `false` when there is no subprocess handle
+     * left — Node's "no-op on an already-reaped child" shape.
      */
     kill(signal?: string | number): boolean;
     ref(): this;
@@ -166,58 +126,26 @@ export declare function execSync(command: string, options?: ExecSyncOptions): Bu
 /**
  * Execute a command in a shell (async with callback).
  *
- * Supports the full Node option set (per
- * `refs/node/lib/child_process.js` and the
- * `refs/node-test/parallel/test-child-process-exec-*` tests):
- *   - `encoding`: `'utf8'` (default), other `BufferEncoding`, `'buffer'`
- *     or `null` (→ Buffer)
- *   - `timeout`: kill the child with `killSignal` (default `SIGTERM`)
- *     after N ms; the callback receives an Error with `killed: true`
- *     and `signal` set to the kill signal
- *   - `maxBuffer`: throw `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` when the
- *     captured stdout/stderr exceeds N bytes (default 1 MiB, matching
- *     Node's `MAX_BUFFER`); the child is killed and the truncated
- *     output is returned
- *   - `signal` (`AbortSignal`): kill the child on abort and surface an
- *     `AbortError` to the callback
- *   - `killSignal`: signal used by timeout / abort (default `SIGTERM`)
- *   - `cwd` / `env` / `shell` / `uid` / `gid` / `argv0` etc. via
- *     `_spawnSubprocess`
+ * Option semantics follow `refs/node/lib/child_process.js` and the
+ * `refs/node-test/parallel/test-child-process-exec-*` tests.
  */
 declare function _exec(command: string, options?: ExecOptions | ((error: ExecError | null, stdout: string | Buffer, stderr: string | Buffer) => void), callback?: (error: ExecError | null, stdout: string | Buffer, stderr: string | Buffer) => void): ChildProcess;
 export { _exec as exec };
-/**
- * Execute a file directly without shell (async).
- *
- * Shares the timeout / maxBuffer / signal / encoding plumbing with `exec`
- * via `_execImpl`. The only structural difference is argv construction
- * (no shell wrap).
- */
+/** Execute a file directly without shell (async). */
 export declare function execFile(file: string, args?: string[] | ((error: ExecError | null, stdout: string | Buffer, stderr: string | Buffer) => void), options?: ExecOptions | ((error: ExecError | null, stdout: string | Buffer, stderr: string | Buffer) => void), callback?: (error: ExecError | null, stdout: string | Buffer, stderr: string | Buffer) => void): ChildProcess;
 /**
- * Execute a file directly without shell (sync).
- *
- * Node's overloads accept `execFileSync(file)`, `execFileSync(file, args)`,
- * `execFileSync(file, options)` and `execFileSync(file, args, options)`.
- * Match all four — passing options as the 2nd positional must not be
- * spread into argv.
+ * Execute a file directly without shell (sync). All four Node overloads are
+ * accepted, so options as the 2nd positional must not be spread into argv.
  */
 export declare function execFileSync(file: string, args?: string[] | ExecSyncOptions, options?: ExecSyncOptions): Buffer | string;
 /**
  * Spawn a new process (async, with event-based API).
  *
- * Node accepts both `spawn(command, args, options)` and `spawn(command, options)`
- * — the second form omits args. Detect the overload at the boundary so callers
- * that pass options as the 2nd positional (e.g. `spawn('sh', { shell: true })`)
- * don't get the options object spread into argv.
+ * The `spawn(command, options)` overload is detected at the boundary so
+ * `spawn('sh', { shell: true })` does not spread the options object into argv.
  */
 export declare function spawn(command: string, argsOrOptions?: string[] | SpawnOptions, maybeOptions?: SpawnOptions): ChildProcess;
-/**
- * Spawn a new process (sync).
- *
- * Same overload as `spawn`: accepts both `(command, args, options)` and
- * `(command, options)`.
- */
+/** Spawn a new process (sync). Same overloads as `spawn`. */
 export declare function spawnSync(command: string, argsOrOptions?: string[] | ExecSyncOptions, maybeOptions?: ExecSyncOptions): SpawnSyncResult;
 declare const _default: {
     ChildProcess: typeof ChildProcess;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/child_process",
-    "version": "0.36.0",
+    "version": "0.37.0",
     "description": "Node.js child_process module for Gjs",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -37,18 +37,18 @@
         "child_process"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.36.0",
-        "@gjsify/dom-elements": "^0.36.0",
-        "@gjsify/unit": "^0.36.0",
+        "@gjsify/cli": "^0.37.0",
+        "@gjsify/dom-elements": "^0.37.0",
+        "@gjsify/unit": "^0.37.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
         "@girs/gio-2.0": "^4.1.0",
         "@girs/glib-2.0": "^4.1.0",
-        "@gjsify/buffer": "^0.36.0",
-        "@gjsify/events": "^0.36.0",
-        "@gjsify/utils": "^0.36.0"
+        "@gjsify/buffer": "^0.37.0",
+        "@gjsify/events": "^0.37.0",
+        "@gjsify/utils": "^0.37.0"
     },
     "gjsify": {
         "runtimes": {