@fuzdev/fuz_util 0.45.2 → 0.46.0

package/dist/process.js

@@ -2,161 +2,528 @@ import { spawn as spawn_child_process, } from 'node:child_process';
 import { styleText as st } from 'node:util';
 import { Logger } from './log.js';
 import { print_error, print_key_value } from './print.js';
+import { noop } from './function.js';
 const log = new Logger('process');
+//
+// Type Guards
+//
 /**
- * A convenient promise wrapper around `spawn_process`
- * intended for commands that have an end, not long running-processes like watchers.
- * Any more advanced usage should use `spawn_process` directly for access to the `child` process.
+ * Type guard for spawn errors (process failed to start).
  */
-export const spawn = (...args) => spawn_process(...args).closed;
+export const spawn_result_is_error = (result) => 'error' in result;
 /**
- * Similar to `spawn` but buffers and returns `stdout` and `stderr` as strings.
+ * Type guard for signal termination.
  */
-export const spawn_out = async (command, args = [], options) => {
-    const { child, closed } = spawn_process(command, args, { ...options, stdio: 'pipe' });
-    let stdout = null;
-    child.stdout.on('data', (data) => {
-        stdout = (stdout ?? '') + data.toString();
-    });
-    let stderr = null;
-    child.stderr.on('data', (data) => {
-        stderr = (stderr ?? '') + data.toString();
-    });
-    const result = await closed;
-    return { result, stdout, stderr };
-};
+export const spawn_result_is_signaled = (result) => 'signal' in result && result.signal !== null;
+/**
+ * Type guard for normal exit with code.
+ */
+export const spawn_result_is_exited = (result) => 'code' in result && result.code !== null;
+//
+// Internal Helpers
+//
 /**
- * Wraps the normal Node `childProcess.spawn` with graceful child shutdown behavior.
- * Also returns a convenient `closed` promise.
- * If you only need `closed`, prefer the shorthand function `spawn`.
- * @mutates global_spawn calls `register_global_spawn()` which adds to the module-level Set
+ * Creates a promise that resolves when the child process closes.
+ *
+ * Handles both 'error' and 'close' events with deduplication because Node.js
+ * can emit both for certain failures (e.g., spawn ENOENT emits 'error' then 'close').
+ * The `resolved` flag ensures we only resolve once with the first event's data.
  */
-export const spawn_process = (command, args = [], options) => {
+const create_closed_promise = (child) => {
     let resolve;
+    let resolved = false;
     const closed = new Promise((r) => (resolve = r));
-    const child = spawn_child_process(command, args, { stdio: 'inherit', ...options });
-    const unregister = register_global_spawn(child);
+    child.once('error', (err) => {
+        if (resolved)
+            return;
+        resolved = true;
+        resolve({ ok: false, child, error: err });
+    });
     child.once('close', (code, signal) => {
-        unregister();
-        resolve(code ? { ok: false, child, code, signal } : { ok: true, child, code, signal });
+        if (resolved)
+            return;
+        resolved = true;
+        if (signal !== null) {
+            resolve({ ok: false, child, code: null, signal });
+        }
+        else {
+            resolve({ ok: code === 0, child, code: code ?? 0, signal: null });
+        }
     });
-    return { closed, child };
+    return closed;
 };
-export const print_child_process = (child) => `${st('gray', 'pid(')}${child.pid}${st('gray', ')')} ← ${st('green', child.spawnargs.join(' '))}`;
 /**
- * We register spawned processes gloabally so we can gracefully exit child processes.
- * Otherwise, errors can cause zombie processes, sometimes blocking ports even!
+ * Sets up abort signal handling for a child process.
+ * @returns cleanup function to remove the listener
  */
-export const global_spawn = new Set();
+const setup_abort_signal = (child, signal) => {
+    if (signal.aborted) {
+        child.kill();
+        return noop;
+    }
+    const on_abort = () => child.kill();
+    signal.addEventListener('abort', on_abort, { once: true });
+    return () => signal.removeEventListener('abort', on_abort);
+};
 /**
- * Returns a function that unregisters the `child`.
- * @param child the child process to register
- * @returns cleanup function that removes the child from `global_spawn`
- * @mutates global_spawn adds child to the module-level Set, and the returned function removes it
+ * Validates timeout_ms option.
+ * @throws if timeout_ms is negative
  */
-export const register_global_spawn = (child) => {
-    if (global_spawn.has(child)) {
-        log.error(st('red', 'already registered global spawn:'), print_child_process(child));
+const validate_timeout_ms = (timeout_ms) => {
+    if (timeout_ms !== undefined && timeout_ms < 0) {
+        throw new Error(`timeout_ms must be non-negative, got ${timeout_ms}`);
     }
-    global_spawn.add(child);
-    return () => {
-        if (!global_spawn.has(child)) {
-            log.error(st('red', 'spawn not registered:'), print_child_process(child));
-        }
-        global_spawn.delete(child);
-    };
 };
 /**
- * Kills a child process and returns a `SpawnResult`.
+ * Sets up timeout handling for a child process.
+ * Note: timeout_ms of 0 triggers immediate SIGTERM (use with caution).
+ * @returns cleanup function to clear the timeout
  */
-export const despawn = (child) => {
-    let resolve;
-    const closed = new Promise((r) => (resolve = r));
-    log.debug('despawning', print_child_process(child));
-    child.once('close', (code, signal) => {
-        resolve(code ? { ok: false, child, code, signal } : { ok: true, child, code, signal });
-    });
-    child.kill();
-    return closed;
+const setup_timeout = (child, timeout_ms) => {
+    const timeout_id = setTimeout(() => child.kill('SIGTERM'), timeout_ms);
+    return () => clearTimeout(timeout_id);
 };
+//
+// Process Registry
+//
+/**
+ * Manages a collection of spawned processes for lifecycle tracking and cleanup.
+ *
+ * The default instance `process_registry_default` is used by module-level functions.
+ * Create separate instances for isolated process groups or testing.
+ *
+ * @example
+ * ```ts
+ * // Use default registry via module functions
+ * const result = await spawn('echo', ['hello']);
+ *
+ * // Or create isolated registry for testing
+ * const registry = new ProcessRegistry();
+ * const {child, closed} = registry.spawn('node', ['server.js']);
+ * await registry.despawn_all();
+ * ```
+ */
+export class ProcessRegistry {
+    /** All currently tracked child processes */
+    processes = new Set();
+    #error_handler = null;
+    /**
+     * Spawns a process and tracks it in this registry.
+     * The process is automatically unregistered when it exits.
+     *
+     * @param command - The command to run
+     * @param args - Arguments to pass to the command
+     * @param options - Spawn options including `signal` and `timeout_ms`
+     * @returns Handle with `child` process and `closed` promise
+     */
+    spawn(command, args = [], options) {
+        const { signal, timeout_ms, ...spawn_options } = options ?? {};
+        validate_timeout_ms(timeout_ms);
+        const child = spawn_child_process(command, args, { stdio: 'inherit', ...spawn_options });
+        this.processes.add(child);
+        const closed = create_closed_promise(child);
+        let cleanup_abort;
+        if (signal) {
+            cleanup_abort = setup_abort_signal(child, signal);
+        }
+        let cleanup_timeout;
+        if (timeout_ms !== undefined) {
+            cleanup_timeout = setup_timeout(child, timeout_ms);
+        }
+        void closed.then(() => {
+            this.processes.delete(child);
+            cleanup_abort?.();
+            cleanup_timeout?.();
+        });
+        return { child, closed };
+    }
+    /**
+     * Spawns a process and captures stdout/stderr as strings.
+     * Sets `stdio: 'pipe'` automatically.
+     *
+     * @param command - The command to run
+     * @param args - Arguments to pass to the command
+     * @param options - Spawn options
+     * @returns Result with captured `stdout` and `stderr`.
+     *   - `null` means spawn failed (ENOENT, etc.) or stream was unavailable
+     *   - `''` (empty string) means process ran but produced no output
+     *   - non-empty string contains the captured output
+     */
+    async spawn_out(command, args = [], options) {
+        const { child, closed } = this.spawn(command, args, { ...options, stdio: 'pipe' });
+        const stdout_chunks = [];
+        const stderr_chunks = [];
+        // Track whether streams were available (not null)
+        const stdout_available = child.stdout !== null;
+        const stderr_available = child.stderr !== null;
+        const on_stdout = (data) => {
+            stdout_chunks.push(data.toString());
+        };
+        const on_stderr = (data) => {
+            stderr_chunks.push(data.toString());
+        };
+        child.stdout?.on('data', on_stdout);
+        child.stderr?.on('data', on_stderr);
+        const result = await closed;
+        // Clean up listeners explicitly
+        child.stdout?.off('data', on_stdout);
+        child.stderr?.off('data', on_stderr);
+        // If spawn failed (error result), streams are meaningless - return null
+        // Otherwise: '' = available but empty, string = has content
+        const spawn_failed = spawn_result_is_error(result);
+        const stdout = spawn_failed || !stdout_available ? null : stdout_chunks.join('');
+        const stderr = spawn_failed || !stderr_available ? null : stderr_chunks.join('');
+        return { result, stdout, stderr };
+    }
+    /**
+     * Kills a child process and waits for it to exit.
+     *
+     * @param child - The child process to kill
+     * @param options - Kill options including signal and timeout
+     * @returns The spawn result after the process exits
+     */
+    async despawn(child, options) {
+        const { signal = 'SIGTERM', timeout_ms } = options ?? {};
+        validate_timeout_ms(timeout_ms);
+        // Already exited with code
+        if (child.exitCode !== null) {
+            return {
+                ok: child.exitCode === 0,
+                child,
+                code: child.exitCode,
+                signal: null,
+            };
+        }
+        // Already terminated by signal
+        if (child.signalCode !== null) {
+            return {
+                ok: false,
+                child,
+                code: null,
+                signal: child.signalCode,
+            };
+        }
+        log.debug('despawning', print_child_process(child));
+        const closed = create_closed_promise(child);
+        // Escalate to SIGKILL after timeout
+        if (timeout_ms !== undefined) {
+            const timeout_id = setTimeout(() => child.kill('SIGKILL'), timeout_ms);
+            void closed.then(() => clearTimeout(timeout_id));
+        }
+        child.kill(signal);
+        return closed;
+    }
+    /**
+     * Kills all processes in this registry.
+     *
+     * @param options - Kill options applied to all processes
+     * @returns Array of spawn results
+     */
+    async despawn_all(options) {
+        return Promise.all([...this.processes].map((child) => this.despawn(child, options)));
+    }
+    /**
+     * Attaches an `uncaughtException` handler that kills all processes before exiting.
+     * Prevents zombie processes when the parent crashes.
+     *
+     * By default uses SIGKILL for immediate termination. Set `graceful_timeout_ms`
+     * to attempt SIGTERM first (allowing processes to clean up) before escalating
+     * to SIGKILL after the timeout.
+     *
+     * Note: Node's uncaughtException handler cannot await async operations, so
+     * graceful shutdown uses a blocking busy-wait. This may not be sufficient
+     * for processes that need significant cleanup time.
+     *
+     * @param options - Configuration options
+     * @param options.to_error_label - Customize error label, return `null` for default
+     * @param options.map_error_text - Customize error text, return `''` to silence
+     * @param options.handle_error - Called after cleanup, defaults to `process.exit(1)`
+     * @param options.graceful_timeout_ms - If set, sends SIGTERM first and waits this
+     *   many ms before SIGKILL. Recommended: 100-500ms. If null/undefined, uses
+     *   immediate SIGKILL (default).
+     * @returns Cleanup function to remove the handler
+     */
+    attach_error_handler(options) {
+        if (this.#error_handler) {
+            throw new Error('Error handler already attached to this registry');
+        }
+        const { to_error_label, map_error_text, handle_error = () => process.exit(1), graceful_timeout_ms, } = options ?? {};
+        this.#error_handler = (err, origin) => {
+            const label = to_error_label?.(err, origin) ?? origin;
+            if (label) {
+                const error_text = map_error_text?.(err, origin) ?? print_error(err);
+                if (error_text) {
+                    new Logger(label).error(error_text);
+                }
+            }
+            if (graceful_timeout_ms != null && graceful_timeout_ms > 0) {
+                // Attempt graceful shutdown with SIGTERM first
+                for (const child of this.processes) {
+                    child.kill('SIGTERM');
+                }
+                // Busy-wait (blocking) - only option in sync handler.
+                // Warning: This will peg the CPU during the wait period.
+                const deadline = Date.now() + graceful_timeout_ms;
+                while (Date.now() < deadline) {
+                    // spin
+                }
+            }
+            // Force kill all (including any that survived SIGTERM)
+            for (const child of this.processes) {
+                child.kill('SIGKILL');
+            }
+            this.processes.clear();
+            handle_error(err, origin);
+        };
+        process.on('uncaughtException', this.#error_handler);
+        return () => {
+            if (this.#error_handler) {
+                process.off('uncaughtException', this.#error_handler);
+                this.#error_handler = null;
+            }
+        };
+    }
+}
+//
+// Default Registry
+//
 /**
- * Kills all globally registered child processes.
- * @mutates global_spawn indirectly removes processes through `despawn()` calls
+ * Default process registry used by module-level spawn functions.
+ * For testing or isolated process groups, create a new `ProcessRegistry` instance.
  */
-export const despawn_all = () => Promise.all(Array.from(global_spawn, (child) => despawn(child)));
+export const process_registry_default = new ProcessRegistry();
+//
+// Module-Level Spawn Functions
+//
 /**
- * Attaches the `'uncoughtException'` event to despawn all processes,
- * and enables custom error logging with `to_error_label`.
- * @param to_error_label - Customize the error label or return `null` for the default `origin`.
- * @param map_error_text - Customize the error text. Return `''` to silence, or `null` for the default `print_error(err)`.
+ * Spawns a process with graceful shutdown behavior.
+ * Returns a handle with access to the `child` process and `closed` promise.
+ *
+ * @example
+ * ```ts
+ * const {child, closed} = spawn_process('node', ['server.js']);
+ * // Later...
+ * child.kill();
+ * const result = await closed;
+ * ```
  */
-export const attach_process_error_handlers = (to_error_label, map_error_text, handle_error = () => process.exit(1)) => {
-    process.on('uncaughtException', async (err, origin) => {
-        const label = to_error_label?.(err, origin) ?? origin;
-        if (label) {
-            const error_text = map_error_text?.(err, origin) ?? print_error(err);
-            if (error_text) {
-                new Logger(label).error(error_text);
-            }
-        }
-        await despawn_all();
-        handle_error(err, origin);
-    });
-};
+export const spawn_process = (command, args = [], options) => process_registry_default.spawn(command, args, options);
+/**
+ * Spawns a process and returns a promise that resolves when it exits.
+ * Use this for commands that complete (not long-running processes).
+ *
+ * @example
+ * ```ts
+ * const result = await spawn('npm', ['install']);
+ * if (!result.ok) console.error('Install failed');
+ * ```
+ */
+export const spawn = (command, args = [], options) => spawn_process(command, args, options).closed;
+/**
+ * Spawns a process and captures stdout/stderr as strings.
+ *
+ * @example
+ * ```ts
+ * const {result, stdout} = await spawn_out('git', ['status', '--porcelain']);
+ * if (result.ok && stdout) console.log(stdout);
+ * ```
+ */
+export const spawn_out = (command, args = [], options) => process_registry_default.spawn_out(command, args, options);
+/**
+ * Kills a child process and returns the result.
+ *
+ * @example
+ * ```ts
+ * const result = await despawn(child, {timeout_ms: 5000});
+ * // If process ignores SIGTERM, SIGKILL sent after 5s
+ * ```
+ */
+export const despawn = (child, options) => process_registry_default.despawn(child, options);
 /**
- * Formats a `SpawnResult` for printing.
+ * Kills all processes in the default registry.
+ */
+export const despawn_all = (options) => process_registry_default.despawn_all(options);
+/**
+ * Attaches an `uncaughtException` handler to the default registry.
+ *
+ * @see ProcessRegistry.attach_error_handler
+ */
+export const attach_process_error_handler = (options) => process_registry_default.attach_error_handler(options);
+//
+// Formatting Utilities
+//
+/**
+ * Formats a child process for display.
+ *
+ * @example `pid(1234) <- node server.js`
+ */
+export const print_child_process = (child) => `${st('gray', 'pid(')}${child.pid ?? 'none'}${st('gray', ')')} ← ${st('green', child.spawnargs.join(' '))}`;
+/**
+ * Formats a spawn result for display.
+ * Returns `'ok'` for success, or the error/signal/code for failures.
  */
 export const print_spawn_result = (result) => {
     if (result.ok)
         return 'ok';
-    let text = result.code === null ? '' : print_key_value('code', result.code);
-    if (result.signal !== null)
-        text += (text ? ' ' : '') + print_key_value('signal', result.signal);
-    return text;
+    if (spawn_result_is_error(result))
+        return result.error.message;
+    if (spawn_result_is_signaled(result))
+        return print_key_value('signal', result.signal);
+    return print_key_value('code', result.code);
 };
 /**
- * Like `spawn_process` but with `restart` and `kill`,
- * handling many concurrent `restart` calls gracefully.
+ * Formats a spawn result for use in error messages.
+ */
+export const spawn_result_to_message = (result) => {
+    if (spawn_result_is_error(result))
+        return `error: ${result.error.message}`;
+    if (spawn_result_is_signaled(result))
+        return `signal ${result.signal}`;
+    return `code ${result.code}`;
+};
+/**
+ * Spawns a process that can be restarted.
+ * Handles concurrent restart calls gracefully.
+ *
+ * Note: The `signal` and `timeout_ms` options are reapplied on each restart.
+ * If the AbortSignal is already aborted when `restart()` is called, the new
+ * process will be killed immediately.
+ *
+ * @example Simple restart on crash
+ * ```ts
+ * const rp = spawn_restartable_process('node', ['server.js']);
+ *
+ * while (rp.active) {
+ *   const result = await rp.closed;
+ *   if (result.ok) break; // Clean exit
+ *   await rp.restart();
+ * }
+ * ```
+ *
+ * @example Restart with backoff
+ * ```ts
+ * const rp = spawn_restartable_process('node', ['server.js']);
+ * let failures = 0;
+ *
+ * while (rp.active) {
+ *   const result = await rp.closed;
+ *   if (result.ok || ++failures > 5) break;
+ *   await new Promise((r) => setTimeout(r, 1000 * failures));
+ *   await rp.restart();
+ * }
+ * ```
  */
 export const spawn_restartable_process = (command, args = [], options) => {
-    let spawned = null;
-    let restarting = null;
-    const close = async () => {
-        if (!spawned)
+    let spawned_process = null;
+    let pending_close = null;
+    let pending_restart = null;
+    let pending_kill = null;
+    // Deferred promise - resolves when first process spawns
+    let closed_promise;
+    let resolve_closed;
+    const reset_closed_promise = () => {
+        closed_promise = new Promise((r) => (resolve_closed = r));
+    };
+    reset_closed_promise();
+    // Resolve when first spawn completes to avoid race conditions
+    let resolve_spawned;
+    const spawned = new Promise((r) => (resolve_spawned = r));
+    const do_close = async () => {
+        if (!spawned_process)
             return;
-        restarting = spawned.closed;
-        spawned.child.kill();
-        spawned = null;
-        await restarting;
-        restarting = null;
+        pending_close = spawned_process.closed;
+        spawned_process.child.kill();
+        spawned_process = null;
+        await pending_close;
+        pending_close = null;
     };
-    const restart = async () => {
-        if (restarting)
-            return restarting;
-        if (spawned)
-            await close();
-        spawned = spawn_process(command, args, { stdio: 'inherit', ...options });
+    const do_restart = async () => {
+        // Wait for any in-progress kill or close before restarting
+        if (pending_kill)
+            await pending_kill;
+        if (pending_close)
+            await pending_close;
+        if (spawned_process)
+            await do_close();
+        spawned_process = spawn_process(command, args, { stdio: 'inherit', ...options });
+        // Forward the spawned process's closed promise to our exposed one
+        void spawned_process.closed.then((result) => {
+            resolve_closed(result);
+        });
+    };
+    // Coalesce concurrent restart calls - multiple calls share one restart
+    const restart = () => {
+        if (!pending_restart) {
+            // Reset the closed promise for the new process
+            reset_closed_promise();
+            pending_restart = do_restart().finally(() => {
+                pending_restart = null;
+            });
+        }
+        return pending_restart;
     };
+    // Wait for any pending restart to complete first, ensuring we kill
+    // the newly spawned process rather than racing with it
     const kill = async () => {
-        if (restarting)
-            await restarting;
-        await close();
+        if (pending_kill)
+            return pending_kill;
+        pending_kill = (async () => {
+            if (pending_restart)
+                await pending_restart;
+            if (pending_close)
+                await pending_close;
+            await do_close();
+        })();
+        try {
+            await pending_kill;
+        }
+        finally {
+            pending_kill = null;
+        }
+    };
+    // Start immediately and resolve spawned promise when done
+    void restart().then(() => resolve_spawned());
+    return {
+        restart,
+        kill,
+        get active() {
+            return spawned_process !== null;
+        },
+        get child() {
+            return spawned_process?.child ?? null;
+        },
+        get closed() {
+            return closed_promise;
+        },
+        get spawned() {
+            return spawned;
+        },
     };
-    // Start immediately -- it sychronously starts the process so there's no need to await.
-    void restart();
-    return { restart, kill };
 };
+//
+// Utility Functions
+//
 /**
- * Check if a PID is still running.
+ * Checks if a process with the given PID is running.
+ * Uses signal 0 which checks existence without sending a signal.
+ *
+ * @param pid - The process ID to check (must be a positive integer)
+ * @returns `true` if the process exists (even without permission to signal it),
+ *   `false` if the process doesn't exist or if pid is invalid (non-positive, non-integer, NaN, Infinity)
  */
 export const process_is_pid_running = (pid) => {
+    // Handle NaN, Infinity, negative, zero, non-integers, and fractional values
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
     try {
-        // Sending signal 0 doesn't actually send a signal, just checks if process exists
         process.kill(pid, 0);
         return true;
     }
     catch (err) {
-        // ESRCH = no such process, EPERM = exists but no permission
-        return err.code === 'EPERM';
+        // ESRCH = no such process
+        // EPERM = process exists but we lack permission to signal it
+        // Safely access .code in case of unexpected error types
+        const code = err && typeof err === 'object' && 'code' in err ? err.code : undefined;
+        return code === 'EPERM';
     }
 };

package/dist/random.d.ts

@@ -19,7 +19,7 @@ export declare const random_boolean: (random?: () => number) => boolean;
 export declare const random_item: <T extends ReadonlyArray<any>>(arr: T, random?: () => number) => ArrayElement<T>;
 /**
  * Mutates `array` with random ordering.
- * @mutates array randomly reorders elements in place using Fisher-Yates shuffle
+ * @mutates array - randomly reorders elements in place using Fisher-Yates shuffle
  */
 export declare const shuffle: <T extends Array<any>>(array: T, random?: typeof random_int) => T;
 //# sourceMappingURL=random.d.ts.map

package/dist/random.js

@@ -18,7 +18,7 @@ export const random_boolean = (random = Math.random) => random() > 0.5;
 export const random_item = (arr, random = Math.random) => arr[random_int(0, arr.length - 1, random)];
 /**
  * Mutates `array` with random ordering.
- * @mutates array randomly reorders elements in place using Fisher-Yates shuffle
+ * @mutates array - randomly reorders elements in place using Fisher-Yates shuffle
  */
 export const shuffle = (array, random = random_int) => {
     const { length } = array;

package/dist/regexp.d.ts

@@ -6,7 +6,7 @@ export declare const escape_regexp: (str: string) => string;
 /**
  * Reset a RegExp's lastIndex to 0 for global and sticky patterns.
  * Ensures consistent behavior by clearing state that affects subsequent matches.
- * @mutates regexp sets lastIndex to 0 if regexp is global or sticky
+ * @mutates regexp - sets lastIndex to 0 if regexp is global or sticky
  */
 export declare const reset_regexp: <T extends RegExp>(regexp: T) => T;
 //# sourceMappingURL=regexp.d.ts.map