@psnext/slingcli 3.1.20260904-1 → 3.3.20260911-1

package/node_modules/@types/node/child_process.d.ts

@@ -1,20 +1,79 @@
-declare module "node:child_process" {
+/**
+ * The `node:child_process` module provides the ability to spawn subprocesses in
+ * a manner that is similar, but not identical, to [`popen(3)`](http://man7.org/linux/man-pages/man3/popen.3.html). This capability
+ * is primarily provided by the {@link spawn} function:
+ *
+ * ```js
+ * import { spawn } from 'node:child_process';
+ * const ls = spawn('ls', ['-lh', '/usr']);
+ *
+ * ls.stdout.on('data', (data) => {
+ *   console.log(`stdout: ${data}`);
+ * });
+ *
+ * ls.stderr.on('data', (data) => {
+ *   console.error(`stderr: ${data}`);
+ * });
+ *
+ * ls.on('close', (code) => {
+ *   console.log(`child process exited with code ${code}`);
+ * });
+ * ```
+ *
+ * By default, pipes for `stdin`, `stdout`, and `stderr` are established between
+ * the parent Node.js process and the spawned subprocess. These pipes have
+ * limited (and platform-specific) capacity. If the subprocess writes to
+ * stdout in excess of that limit without the output being captured, the
+ * subprocess blocks, waiting for the pipe buffer to accept more data. This is
+ * identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }` option if the output will not be consumed.
+ *
+ * The command lookup is performed using the `options.env.PATH` environment
+ * variable if `env` is in the `options` object. Otherwise, `process.env.PATH` is
+ * used. If `options.env` is set without `PATH`, lookup on Unix is performed
+ * on a default search path search of `/usr/bin:/bin` (see your operating system's
+ * manual for execvpe/execvp), on Windows the current processes environment
+ * variable `PATH` is used.
+ *
+ * On Windows, environment variables are case-insensitive. Node.js
+ * lexicographically sorts the `env` keys and uses the first one that
+ * case-insensitively matches. Only first (in lexicographic order) entry will be
+ * passed to the subprocess. This might lead to issues on Windows when passing
+ * objects to the `env` option that have multiple variants of the same key, such as `PATH` and `Path`.
+ *
+ * The {@link spawn} method spawns the child process asynchronously,
+ * without blocking the Node.js event loop. The {@link spawnSync} function provides equivalent functionality in a synchronous manner that blocks
+ * the event loop until the spawned process either exits or is terminated.
+ *
+ * For convenience, the `node:child_process` module provides a handful of
+ * synchronous and asynchronous alternatives to {@link spawn} and {@link spawnSync}. Each of these alternatives are implemented on
+ * top of {@link spawn} or {@link spawnSync}.
+ *
+ * * {@link exec}: spawns a shell and runs a command within that
+ * shell, passing the `stdout` and `stderr` to a callback function when
+ * complete.
+ * * {@link execFile}: similar to {@link exec} except
+ * that it spawns the command directly without first spawning a shell by
+ * default.
+ * * {@link fork}: spawns a new Node.js process and invokes a
+ * specified module with an IPC communication channel established that allows
+ * sending messages between parent and child.
+ * * {@link execSync}: a synchronous version of {@link exec} that will block the Node.js event loop.
+ * * {@link execFileSync}: a synchronous version of {@link execFile} that will block the Node.js event loop.
+ *
+ * For certain use cases, such as automating shell scripts, the `synchronous counterparts` may be more convenient. In many cases, however,
+ * the synchronous methods can have significant impact on performance due to
+ * stalling the event loop while spawned processes complete.
+ * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/child_process.js)
+ */
+declare module "child_process" {
     import { NonSharedBuffer } from "node:buffer";
+    import { Abortable, EventEmitter } from "node:events";
     import * as dgram from "node:dgram";
-    import { Abortable, EventEmitter, InternalEventEmitter } from "node:events";
     import * as net from "node:net";
     import { Readable, Stream, Writable } from "node:stream";
     import { URL } from "node:url";
     type Serializable = string | object | number | boolean | bigint;
     type SendHandle = net.Socket | net.Server | dgram.Socket | undefined;
-    interface ChildProcessEventMap {
-        "close": [code: number | null, signal: NodeJS.Signals | null];
-        "disconnect": [];
-        "error": [err: Error];
-        "exit": [code: number | null, signal: NodeJS.Signals | null];
-        "message": [message: Serializable, sendHandle: SendHandle];
-        "spawn": [];
-    }
     /**
      * Instances of the `ChildProcess` represent spawned child processes.
      *
@@ -23,7 +82,7 @@ declare module "node:child_process" {
      * instances of `ChildProcess`.
      * @since v2.2.0
      */
-    class ChildProcess implements EventEmitter {
+    class ChildProcess extends EventEmitter {
         /**
          * A `Writable Stream` that represents the child process's `stdin`.
          *
@@ -161,11 +220,6 @@ declare module "node:child_process" {
         /**
          * The `subprocess.exitCode` property indicates the exit code of the child process.
          * If the child process is still running, the field will be `null`.
-         *
-         * When the child process is terminated by a signal, `subprocess.exitCode` will be
-         * `null` and `subprocess.signalCode` will be set. To get the corresponding
-         * POSIX exit code, use
-         * `util.convertProcessSignalToExitCode(subprocess.signalCode)`.
          */
         readonly exitCode: number | null;
         /**
@@ -227,6 +281,7 @@ declare module "node:child_process" {
          * new process in a shell or with the use of the `shell` option of `ChildProcess`:
          *
          * ```js
+         * 'use strict';
          * import { spawn } from 'node:child_process';
          *
          * const subprocess = spawn(
@@ -403,7 +458,7 @@ declare module "node:child_process" {
          * as the connection may have been closed during the time it takes to send the
          * connection to the child.
          * @since v0.5.9
-         * @param sendHandle `undefined`, or a [`net.Socket`](https://nodejs.org/docs/latest-v26.x/api/net.html#class-netsocket), [`net.Server`](https://nodejs.org/docs/latest-v26.x/api/net.html#class-netserver), or [`dgram.Socket`](https://nodejs.org/docs/latest-v26.x/api/dgram.html#class-dgramsocket) object.
+         * @param sendHandle `undefined`, or a [`net.Socket`](https://nodejs.org/docs/latest-v22.x/api/net.html#class-netsocket), [`net.Server`](https://nodejs.org/docs/latest-v22.x/api/net.html#class-netserver), or [`dgram.Socket`](https://nodejs.org/docs/latest-v22.x/api/dgram.html#class-dgramsocket) object.
          * @param options The `options` argument, if present, is an object used to parameterize the sending of certain types of handles. `options` supports the following properties:
          */
         send(message: Serializable, callback?: (error: Error | null) => void): boolean;
@@ -469,8 +524,64 @@ declare module "node:child_process" {
          * @since v0.7.10
          */
         ref(): void;
+        /**
+         * events.EventEmitter
+         * 1. close
+         * 2. disconnect
+         * 3. error
+         * 4. exit
+         * 5. message
+         * 6. spawn
+         */
+        addListener(event: string, listener: (...args: any[]) => void): this;
+        addListener(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+        addListener(event: "disconnect", listener: () => void): this;
+        addListener(event: "error", listener: (err: Error) => void): this;
+        addListener(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+        addListener(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this;
+        addListener(event: "spawn", listener: () => void): this;
+        emit(event: string | symbol, ...args: any[]): boolean;
+        emit(event: "close", code: number | null, signal: NodeJS.Signals | null): boolean;
+        emit(event: "disconnect"): boolean;
+        emit(event: "error", err: Error): boolean;
+        emit(event: "exit", code: number | null, signal: NodeJS.Signals | null): boolean;
+        emit(event: "message", message: Serializable, sendHandle: SendHandle): boolean;
+        emit(event: "spawn", listener: () => void): boolean;
+        on(event: string, listener: (...args: any[]) => void): this;
+        on(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+        on(event: "disconnect", listener: () => void): this;
+        on(event: "error", listener: (err: Error) => void): this;
+        on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+        on(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this;
+        on(event: "spawn", listener: () => void): this;
+        once(event: string, listener: (...args: any[]) => void): this;
+        once(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+        once(event: "disconnect", listener: () => void): this;
+        once(event: "error", listener: (err: Error) => void): this;
+        once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+        once(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this;
+        once(event: "spawn", listener: () => void): this;
+        prependListener(event: string, listener: (...args: any[]) => void): this;
+        prependListener(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+        prependListener(event: "disconnect", listener: () => void): this;
+        prependListener(event: "error", listener: (err: Error) => void): this;
+        prependListener(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+        prependListener(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this;
+        prependListener(event: "spawn", listener: () => void): this;
+        prependOnceListener(event: string, listener: (...args: any[]) => void): this;
+        prependOnceListener(
+            event: "close",
+            listener: (code: number | null, signal: NodeJS.Signals | null) => void,
+        ): this;
+        prependOnceListener(event: "disconnect", listener: () => void): this;
+        prependOnceListener(event: "error", listener: (err: Error) => void): this;
+        prependOnceListener(
+            event: "exit",
+            listener: (code: number | null, signal: NodeJS.Signals | null) => void,
+        ): this;
+        prependOnceListener(event: "message", listener: (message: Serializable, sendHandle: SendHandle) => void): this;
+        prependOnceListener(event: "spawn", listener: () => void): this;
     }
-    interface ChildProcess extends InternalEventEmitter<ChildProcessEventMap> {}
     // return this object when stdio option is undefined or not specified
     interface ChildProcessWithoutNullStreams extends ChildProcess {
         stdin: Writable;
@@ -608,7 +719,6 @@ declare module "node:child_process" {
      *
      * ```js
      * import { spawn } from 'node:child_process';
-     * import { once } from 'node:events';
      * const ls = spawn('ls', ['-lh', '/usr']);
      *
      * ls.stdout.on('data', (data) => {
@@ -619,8 +729,9 @@ declare module "node:child_process" {
      *   console.error(`stderr: ${data}`);
      * });
      *
-     * const [code] = await once(ls, 'close');
-     * console.log(`child process exited with code ${code}`);
+     * ls.on('close', (code) => {
+     *   console.log(`child process exited with code ${code}`);
+     * });
      * ```
      *
      * Example: A very elaborate way to run `ps ax | grep ssh`
@@ -786,15 +897,16 @@ declare module "node:child_process" {
         encoding?: BufferEncoding | undefined;
     }
     interface ExecOptionsWithBufferEncoding extends ExecOptions {
-        encoding: "buffer" | null;
+        encoding: "buffer" | null; // specify `null`.
     }
-    interface ExecException extends Omit<NodeJS.ErrnoException, "code"> {
-        cmd: string;
-        code?: number | string;
+    // TODO: Just Plain Wrong™ (see also nodejs/node#57392)
+    interface ExecException extends Error {
+        cmd?: string;
         killed?: boolean;
+        code?: number;
         signal?: NodeJS.Signals;
-        stdout?: string | NonSharedBuffer;
-        stderr?: string | NonSharedBuffer;
+        stdout?: string;
+        stderr?: string;
     }
     /**
      * Spawns a shell then executes the `command` within that shell, buffering any
@@ -954,6 +1066,11 @@ declare module "node:child_process" {
     }
     /** @deprecated Use `ExecFileOptions` instead. */
     interface ExecFileOptionsWithOtherEncoding extends ExecFileOptions {}
+    // TODO: execFile exceptions can take many forms... this accurately describes none of them
+    type ExecFileException =
+        & Omit<ExecException, "code">
+        & Omit<NodeJS.ErrnoException, "code">
+        & { code?: string | number | null };
     /**
      * The `child_process.execFile()` function is similar to {@link exec} except that it does not spawn a shell by default. Rather, the specified
      * executable `file` is spawned directly as a new process making it slightly more
@@ -1021,36 +1138,36 @@ declare module "node:child_process" {
     // no `options` definitely means stdout/stderr are `string`.
     function execFile(
         file: string,
-        callback?: (error: ExecException | null, stdout: string, stderr: string) => void,
+        callback?: (error: ExecFileException | null, stdout: string, stderr: string) => void,
     ): ChildProcess;
     function execFile(
         file: string,
         args: readonly string[] | undefined | null,
-        callback?: (error: ExecException | null, stdout: string, stderr: string) => void,
+        callback?: (error: ExecFileException | null, stdout: string, stderr: string) => void,
     ): ChildProcess;
     // `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`.
     function execFile(
         file: string,
         options: ExecFileOptionsWithBufferEncoding,
-        callback?: (error: ExecException | null, stdout: NonSharedBuffer, stderr: NonSharedBuffer) => void,
+        callback?: (error: ExecFileException | null, stdout: NonSharedBuffer, stderr: NonSharedBuffer) => void,
     ): ChildProcess;
     function execFile(
         file: string,
         args: readonly string[] | undefined | null,
         options: ExecFileOptionsWithBufferEncoding,
-        callback?: (error: ExecException | null, stdout: NonSharedBuffer, stderr: NonSharedBuffer) => void,
+        callback?: (error: ExecFileException | null, stdout: NonSharedBuffer, stderr: NonSharedBuffer) => void,
     ): ChildProcess;
     // `options` with well-known or absent `encoding` means stdout/stderr are definitely `string`.
     function execFile(
         file: string,
         options: ExecFileOptionsWithStringEncoding,
-        callback?: (error: ExecException | null, stdout: string, stderr: string) => void,
+        callback?: (error: ExecFileException | null, stdout: string, stderr: string) => void,
     ): ChildProcess;
     function execFile(
         file: string,
         args: readonly string[] | undefined | null,
         options: ExecFileOptionsWithStringEncoding,
-        callback?: (error: ExecException | null, stdout: string, stderr: string) => void,
+        callback?: (error: ExecFileException | null, stdout: string, stderr: string) => void,
     ): ChildProcess;
     // fallback if nothing else matches. Worst case is always `string | Buffer`.
     function execFile(
@@ -1058,7 +1175,7 @@ declare module "node:child_process" {
         options: ExecFileOptions | undefined | null,
         callback:
             | ((
-                error: ExecException | null,
+                error: ExecFileException | null,
                 stdout: string | NonSharedBuffer,
                 stderr: string | NonSharedBuffer,
             ) => void)
@@ -1071,7 +1188,7 @@ declare module "node:child_process" {
         options: ExecFileOptions | undefined | null,
         callback:
             | ((
-                error: ExecException | null,
+                error: ExecFileException | null,
                 stdout: string | NonSharedBuffer,
                 stderr: string | NonSharedBuffer,
             ) => void)
@@ -1353,9 +1470,7 @@ declare module "node:child_process" {
         args?: readonly string[],
         options?: ExecFileSyncOptions,
     ): string | NonSharedBuffer;
-    /** @deprecated This deprecated alias will be removed in a future version. Use `ExecException` instead. */
-    interface ExecFileException extends ExecException {}
 }
-declare module "child_process" {
-    export * from "node:child_process";
+declare module "node:child_process" {
+    export * from "child_process";
 }