es-toolkit 1.46.1-dev.1806 → 1.46.1-dev.1808

package/dist/server/exec.d.mts

@@ -0,0 +1,63 @@
+import { SpawnOptions } from "node:child_process";
+
+//#region src/server/exec.d.ts
+interface ExecOptions {
+  signal?: AbortSignal;
+  timeout?: number;
+  stdin?: string;
+  spawnOptions?: SpawnOptions;
+  throwOnNonZeroExitCode?: boolean;
+}
+interface ExecResult {
+  pid: number | undefined;
+  stderr: string;
+  stdout: string;
+  exitCode: number | null;
+}
+/**
+ * Executes a command and captures its output.
+ *
+ * This function spawns a child process, collects its stdout and stderr, and resolves with the
+ * process result when execution finishes. By default, it throws an {@link ExecError} when the
+ * process exits with a non-zero exit code.
+ *
+ * @param {string} _command - The command to execute.
+ * @param {string[]} args - The arguments passed to the command.
+ * @param {ExecOptions} options - The options object.
+ * @param {AbortSignal} options.signal - An optional AbortSignal used to abort the process.
+ * @param {number} options.timeout - An optional timeout in milliseconds. When provided, the
+ * process is aborted after the timeout expires.
+ * @param {string} options.stdin - An optional string written to the process stdin.
+ * @param {SpawnOptions} options.spawnOptions - Additional options forwarded to `child_process.spawn`.
+ * @param {boolean} options.throwOnNonZeroExitCode - Whether to throw an {@link ExecError} when the
+ * process exits with a non-zero exit code. Defaults to `true`.
+ * @returns {Promise<ExecResult>} A promise that resolves with the process result.
+ * @throws {ExecError} Throws when `throwOnNonZeroExitCode` is enabled and the process exits with a
+ * non-zero exit code.
+ *
+ * @example
+ * const result = await exec('echo', ['hello']);
+ *
+ * console.log(result.stdout.trim());
+ * // => 'hello'
+ *
+ * @example
+ * const result = await exec('git', ['diff', '--quiet'], {
+ *   throwOnNonZeroExitCode: false,
+ * });
+ *
+ * console.log(result.exitCode);
+ * // => 1 when there are changes
+ */
+declare function exec(_command: string, args?: string[], options?: ExecOptions): Promise<ExecResult>;
+/**
+ * Represents an error thrown when a process exits with a non-zero exit code.
+ *
+ * @param {ExecResult} result - The captured process result.
+ */
+declare class ExecError extends Error {
+  readonly result: ExecResult;
+  constructor(result: ExecResult);
+}
+//#endregion
+export { ExecError, exec };

package/dist/server/exec.d.ts

@@ -0,0 +1,63 @@
+import { SpawnOptions } from "node:child_process";
+
+//#region src/server/exec.d.ts
+interface ExecOptions {
+  signal?: AbortSignal;
+  timeout?: number;
+  stdin?: string;
+  spawnOptions?: SpawnOptions;
+  throwOnNonZeroExitCode?: boolean;
+}
+interface ExecResult {
+  pid: number | undefined;
+  stderr: string;
+  stdout: string;
+  exitCode: number | null;
+}
+/**
+ * Executes a command and captures its output.
+ *
+ * This function spawns a child process, collects its stdout and stderr, and resolves with the
+ * process result when execution finishes. By default, it throws an {@link ExecError} when the
+ * process exits with a non-zero exit code.
+ *
+ * @param {string} _command - The command to execute.
+ * @param {string[]} args - The arguments passed to the command.
+ * @param {ExecOptions} options - The options object.
+ * @param {AbortSignal} options.signal - An optional AbortSignal used to abort the process.
+ * @param {number} options.timeout - An optional timeout in milliseconds. When provided, the
+ * process is aborted after the timeout expires.
+ * @param {string} options.stdin - An optional string written to the process stdin.
+ * @param {SpawnOptions} options.spawnOptions - Additional options forwarded to `child_process.spawn`.
+ * @param {boolean} options.throwOnNonZeroExitCode - Whether to throw an {@link ExecError} when the
+ * process exits with a non-zero exit code. Defaults to `true`.
+ * @returns {Promise<ExecResult>} A promise that resolves with the process result.
+ * @throws {ExecError} Throws when `throwOnNonZeroExitCode` is enabled and the process exits with a
+ * non-zero exit code.
+ *
+ * @example
+ * const result = await exec('echo', ['hello']);
+ *
+ * console.log(result.stdout.trim());
+ * // => 'hello'
+ *
+ * @example
+ * const result = await exec('git', ['diff', '--quiet'], {
+ *   throwOnNonZeroExitCode: false,
+ * });
+ *
+ * console.log(result.exitCode);
+ * // => 1 when there are changes
+ */
+declare function exec(_command: string, args?: string[], options?: ExecOptions): Promise<ExecResult>;
+/**
+ * Represents an error thrown when a process exits with a non-zero exit code.
+ *
+ * @param {ExecResult} result - The captured process result.
+ */
+declare class ExecError extends Error {
+  readonly result: ExecResult;
+  constructor(result: ExecResult);
+}
+//#endregion
+export { ExecError, exec };

package/dist/server/exec.js

@@ -0,0 +1,103 @@
+let node_child_process = require("node:child_process");
+let node_path = require("node:path");
+//#region src/server/exec.ts
+/**
+* Executes a command and captures its output.
+*
+* This function spawns a child process, collects its stdout and stderr, and resolves with the
+* process result when execution finishes. By default, it throws an {@link ExecError} when the
+* process exits with a non-zero exit code.
+*
+* @param {string} _command - The command to execute.
+* @param {string[]} args - The arguments passed to the command.
+* @param {ExecOptions} options - The options object.
+* @param {AbortSignal} options.signal - An optional AbortSignal used to abort the process.
+* @param {number} options.timeout - An optional timeout in milliseconds. When provided, the
+* process is aborted after the timeout expires.
+* @param {string} options.stdin - An optional string written to the process stdin.
+* @param {SpawnOptions} options.spawnOptions - Additional options forwarded to `child_process.spawn`.
+* @param {boolean} options.throwOnNonZeroExitCode - Whether to throw an {@link ExecError} when the
+* process exits with a non-zero exit code. Defaults to `true`.
+* @returns {Promise<ExecResult>} A promise that resolves with the process result.
+* @throws {ExecError} Throws when `throwOnNonZeroExitCode` is enabled and the process exits with a
+* non-zero exit code.
+*
+* @example
+* const result = await exec('echo', ['hello']);
+*
+* console.log(result.stdout.trim());
+* // => 'hello'
+*
+* @example
+* const result = await exec('git', ['diff', '--quiet'], {
+*   throwOnNonZeroExitCode: false,
+* });
+*
+* console.log(result.exitCode);
+* // => 1 when there are changes
+*/
+async function exec(_command, args = [], options = {}) {
+	const command = (0, node_path.normalize)(_command);
+	const signal = parseAbortSignal(options);
+	const resolver = Promise.withResolvers();
+	const process = (0, node_child_process.spawn)(command, args, {
+		windowsHide: true,
+		...options.spawnOptions,
+		signal
+	});
+	handleStdin(process, options);
+	process.once("close", () => {
+		resolver.resolve();
+	});
+	process.once("error", (error) => {
+		resolver.reject(error);
+	});
+	const stdoutPromise = process.stdout != null ? streamToString(process.stdout) : Promise.resolve("");
+	const stderrPromise = process.stderr != null ? streamToString(process.stderr) : Promise.resolve("");
+	await resolver.promise;
+	const stdout = await stdoutPromise;
+	const stderr = await stderrPromise;
+	if ((options.throwOnNonZeroExitCode ?? true) && process.exitCode !== 0) throw new ExecError({
+		pid: process.pid,
+		stdout,
+		stderr,
+		exitCode: process.exitCode
+	});
+	return {
+		pid: process.pid,
+		stdout,
+		stderr,
+		exitCode: process.exitCode
+	};
+}
+/**
+* Represents an error thrown when a process exits with a non-zero exit code.
+*
+* @param {ExecResult} result - The captured process result.
+*/
+var ExecError = class extends Error {
+	result;
+	constructor(result) {
+		super(`Process exited with non-zero exit code (${result.exitCode})`);
+		this.result = result;
+		this.name = "ExecError";
+	}
+};
+async function streamToString(stream) {
+	return Buffer.concat(await stream.toArray()).toString("utf-8");
+}
+function handleStdin(process, options) {
+	if (options.stdin == null) return;
+	if (typeof options.stdin === "string") process.stdin?.end(options.stdin);
+}
+function parseAbortSignal(options) {
+	const signals = [];
+	if (options.signal != null) signals.push(options.signal);
+	if (options.timeout != null) signals.push(AbortSignal.timeout(options.timeout));
+	if (options.spawnOptions?.signal != null) signals.push(options.spawnOptions.signal);
+	if (signals.length === 0) return;
+	return AbortSignal.any(signals);
+}
+//#endregion
+exports.ExecError = ExecError;
+exports.exec = exec;

package/dist/server/exec.mjs

@@ -0,0 +1,102 @@
+import { spawn } from "node:child_process";
+import { normalize } from "node:path";
+//#region src/server/exec.ts
+/**
+* Executes a command and captures its output.
+*
+* This function spawns a child process, collects its stdout and stderr, and resolves with the
+* process result when execution finishes. By default, it throws an {@link ExecError} when the
+* process exits with a non-zero exit code.
+*
+* @param {string} _command - The command to execute.
+* @param {string[]} args - The arguments passed to the command.
+* @param {ExecOptions} options - The options object.
+* @param {AbortSignal} options.signal - An optional AbortSignal used to abort the process.
+* @param {number} options.timeout - An optional timeout in milliseconds. When provided, the
+* process is aborted after the timeout expires.
+* @param {string} options.stdin - An optional string written to the process stdin.
+* @param {SpawnOptions} options.spawnOptions - Additional options forwarded to `child_process.spawn`.
+* @param {boolean} options.throwOnNonZeroExitCode - Whether to throw an {@link ExecError} when the
+* process exits with a non-zero exit code. Defaults to `true`.
+* @returns {Promise<ExecResult>} A promise that resolves with the process result.
+* @throws {ExecError} Throws when `throwOnNonZeroExitCode` is enabled and the process exits with a
+* non-zero exit code.
+*
+* @example
+* const result = await exec('echo', ['hello']);
+*
+* console.log(result.stdout.trim());
+* // => 'hello'
+*
+* @example
+* const result = await exec('git', ['diff', '--quiet'], {
+*   throwOnNonZeroExitCode: false,
+* });
+*
+* console.log(result.exitCode);
+* // => 1 when there are changes
+*/
+async function exec(_command, args = [], options = {}) {
+	const command = normalize(_command);
+	const signal = parseAbortSignal(options);
+	const resolver = Promise.withResolvers();
+	const process = spawn(command, args, {
+		windowsHide: true,
+		...options.spawnOptions,
+		signal
+	});
+	handleStdin(process, options);
+	process.once("close", () => {
+		resolver.resolve();
+	});
+	process.once("error", (error) => {
+		resolver.reject(error);
+	});
+	const stdoutPromise = process.stdout != null ? streamToString(process.stdout) : Promise.resolve("");
+	const stderrPromise = process.stderr != null ? streamToString(process.stderr) : Promise.resolve("");
+	await resolver.promise;
+	const stdout = await stdoutPromise;
+	const stderr = await stderrPromise;
+	if ((options.throwOnNonZeroExitCode ?? true) && process.exitCode !== 0) throw new ExecError({
+		pid: process.pid,
+		stdout,
+		stderr,
+		exitCode: process.exitCode
+	});
+	return {
+		pid: process.pid,
+		stdout,
+		stderr,
+		exitCode: process.exitCode
+	};
+}
+/**
+* Represents an error thrown when a process exits with a non-zero exit code.
+*
+* @param {ExecResult} result - The captured process result.
+*/
+var ExecError = class extends Error {
+	result;
+	constructor(result) {
+		super(`Process exited with non-zero exit code (${result.exitCode})`);
+		this.result = result;
+		this.name = "ExecError";
+	}
+};
+async function streamToString(stream) {
+	return Buffer.concat(await stream.toArray()).toString("utf-8");
+}
+function handleStdin(process, options) {
+	if (options.stdin == null) return;
+	if (typeof options.stdin === "string") process.stdin?.end(options.stdin);
+}
+function parseAbortSignal(options) {
+	const signals = [];
+	if (options.signal != null) signals.push(options.signal);
+	if (options.timeout != null) signals.push(AbortSignal.timeout(options.timeout));
+	if (options.spawnOptions?.signal != null) signals.push(options.spawnOptions.signal);
+	if (signals.length === 0) return;
+	return AbortSignal.any(signals);
+}
+//#endregion
+export { ExecError, exec };

package/dist/server/index.d.mts

@@ -1,3 +1,4 @@
 import { ColorFunction } from "./colors/types.mjs";
 import { colors } from "./colors/index.mjs";
-export { type ColorFunction, colors };
+import { ExecError, exec } from "./exec.mjs";
+export { type ColorFunction, ExecError, colors, exec };

package/dist/server/index.d.ts

@@ -1,3 +1,4 @@
 import { ColorFunction } from "./colors/types.js";
 import { colors } from "./colors/index.js";
-export { type ColorFunction, colors };
+import { ExecError, exec } from "./exec.js";
+export { type ColorFunction, ExecError, colors, exec };

package/dist/server/index.js

@@ -1,3 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_index = require("./colors/index.js");
+const require_exec = require("./exec.js");
+exports.ExecError = require_exec.ExecError;
 exports.colors = require_index.colors;
+exports.exec = require_exec.exec;

package/dist/server/index.mjs

@@ -1,2 +1,3 @@
 import { colors } from "./colors/index.mjs";
-export { colors };
+import { ExecError, exec } from "./exec.mjs";
+export { ExecError, colors, exec };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-toolkit",
-  "version": "1.46.1-dev.1806+e105eb93",
+  "version": "1.46.1-dev.1808+66f2610f",
   "description": "A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.",
   "homepage": "https://es-toolkit.dev",
   "bugs": "https://github.com/toss/es-toolkit/issues",