printable-shell-command 0.2.0 → 0.3.0

package/README.md

@@ -47,7 +47,11 @@ import { PrintableShellCommand } from "printable-shell-command";
 import { spawn } from "node:child_process";
 
 const command = new PrintableShellCommand(/* … */);
-const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`
+const child_process = spawn(...command.toCommandWithFlatAr()); // Note the `...`
+
+// or directly
+await command.spawnNode().success;
+await command.spawnNodeInherit().success;
 ```
 
 ### Spawn a process in `bun`
@@ -58,6 +62,10 @@ import { spawn } from "bun";
 
 const command = new PrintableShellCommand(/* … */);
 await spawn(command.toFlatCommand()).exited;
+
+// or directly
+await command.spawnBun().success;
+await command.spawnBunInherit().success;
 ```
 
 ## Protections

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "printable-shell-command",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"main": "./src/index.ts",
 	"type": "module",
 	"exports": {
@@ -9,11 +9,13 @@
 			"import": "./src/index.ts"
 		}
 	},
-	"dependencies": {
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.4",
 		"@types/bun": "^1.2.11",
 		"@types/node": "^22.15.3"
 	},
-	"devDependencies": {
-		"@biomejs/biome": "^1.9.4"
+	"optionalDependencies": {
+		"@types/bun": "^1.2.11",
+		"@types/node": "^22.15.3"
 	}
 }

package/src/index.ts

@@ -1,10 +1,10 @@
 import type {
 	ChildProcess as NodeChildProcess,
+	SpawnOptions as NodeSpawnOptions,
 	SpawnOptionsWithStdioTuple as NodeSpawnOptionsWithStdioTuple,
+	SpawnOptionsWithoutStdio as NodeSpawnOptionsWithoutStdio,
 	StdioNull as NodeStdioNull,
 	StdioPipe as NodeStdioPipe,
-	SpawnOptions as NodeSpawnOptions,
-SpawnOptionsWithoutStdio as NodeSpawnOptionsWithoutStdio,
 } from "node:child_process";
 import type {
 	SpawnOptions as BunSpawnOptions,
@@ -273,8 +273,9 @@ export class PrintableShellCommand {
 		return serializedEntries.join(this.#entrySeparator(options));
 	}
 
-	public print(options?: PrintOptions): void {
+	public print(options?: PrintOptions): PrintableShellCommand {
 		console.log(this.getPrintableCommand(options));
+		return this;
 	}
 
 	public spawnNode<
@@ -282,12 +283,58 @@ export class PrintableShellCommand {
 		Stdout extends NodeStdioNull | NodeStdioPipe,
 		Stderr extends NodeStdioNull | NodeStdioPipe,
 	>(
-		options: NodeSpawnOptions
-		| NodeSpawnOptionsWithoutStdio | NodeSpawnOptionsWithStdioTuple<Stdin, Stdout, Stderr>,
+		options?:
+			| NodeSpawnOptions
+			| NodeSpawnOptionsWithoutStdio
+			| NodeSpawnOptionsWithStdioTuple<Stdin, Stdout, Stderr>,
 	): // TODO: figure out how to return `ChildProcessByStdio<…>` without duplicating fragile boilerplate.
-	NodeChildProcess {
+	NodeChildProcess & { success: Promise<void> } {
 		const { spawn } = process.getBuiltinModule("node:child_process");
-		return spawn(...this.forNode(), options);
+		const subprocess = spawn(...this.forNode(), options) as NodeChildProcess & {
+			success: Promise<void>;
+		};
+		Object.defineProperty(subprocess, "success", {
+			get() {
+				return new Promise<void>((resolve, reject) =>
+					this.addListener(
+						"exit",
+						(exitCode: number /* we only use the first arg */) => {
+							if (exitCode === 0) {
+								resolve();
+							} else {
+								reject(`Command failed with non-zero exit code: ${exitCode}`);
+							}
+						},
+					),
+				);
+			},
+			enumerable: false,
+		});
+		return subprocess;
+	}
+
+	// A wrapper for `.spawnNode(…)` that sets stdio to `"inherit"` (common for
+	// invoking commands from scripts whose output and interaction should be
+	// surfaced to the user).
+	public spawnNodeInherit(
+		options?: Omit<NodeSpawnOptions, "stdio">,
+	): NodeChildProcess & { success: Promise<void> } {
+		if (options && "stdio" in options) {
+			throw new Error("Unexpected `stdio` field.");
+		}
+		return this.spawnNode({ ...options, stdio: "inherit" });
+	}
+
+	/** Equivalent to:
+	 *
+	 * ```
+	 *     await this.print().spawnNodeInherit().success;
+	 * ```
+	 */
+	public async shellOutNode(
+		options?: Omit<NodeSpawnOptions, "stdio">,
+	): Promise<void> {
+		await this.print().spawnNodeInherit(options).success;
 	}
 
 	// The returned subprocess includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
@@ -298,6 +345,9 @@ export class PrintableShellCommand {
 	>(
 		options?: Omit<BunSpawnOptions.OptionsObject<In, Out, Err>, "cmd">,
 	): BunSubprocess<In, Out, Err> & { success: Promise<void> } {
+		if (options && "cmd" in options) {
+			throw new Error("Unexpected `cmd` field.");
+		}
 		const { spawn } = process.getBuiltinModule("bun") as typeof import("bun");
 		const subprocess = spawn({
 			...options,
@@ -311,7 +361,11 @@ export class PrintableShellCommand {
 							if (exitCode === 0) {
 								resolve();
 							} else {
-								reject("Command failed.");
+								reject(
+									new Error(
+										`Command failed with non-zero exit code: ${exitCode}`,
+									),
+								);
 							}
 						})
 						.catch(reject),
@@ -321,4 +375,45 @@ export class PrintableShellCommand {
 		});
 		return subprocess;
 	}
+
+	// A wrapper for `.spawnBunInherit(…)` that sets stdio to `"inherit"` (common for
+	// invoking commands from scripts whose output and interaction should be
+	// surfaced to the user).
+	public spawnBunInherit(
+		options?: Omit<
+			Omit<
+				BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">,
+				"cmd"
+			>,
+			"stdio"
+		>,
+	): BunSubprocess<"inherit", "inherit", "inherit"> & {
+		success: Promise<void>;
+	} {
+		if (options && "stdio" in options) {
+			throw new Error("Unexpected `stdio` field.");
+		}
+		return this.spawnBun({
+			...options,
+			stdio: ["inherit", "inherit", "inherit"],
+		});
+	}
+
+	/** Equivalent to:
+	 *
+	 * ```
+	 *     await this.print().spawnBunInherit().success;
+	 * ```
+	 */
+	public async shellOutBun(
+		options?: Omit<
+			Omit<
+				BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">,
+				"cmd"
+			>,
+			"stdio"
+		>,
+	): Promise<void> {
+		await this.print().spawnBunInherit(options).success;
+	}
 }

package/test/simple-test-bun.ts

@@ -1,4 +1,3 @@
-import { spawn } from "bun";
 import { PrintableShellCommand } from "../src";
 
 const command = new PrintableShellCommand("ffmpeg", [
@@ -8,5 +7,4 @@ const command = new PrintableShellCommand("ffmpeg", [
 	"./test/My video (slow-mo).mov",
 ]);
 
-command.print();
-await spawn(command.toFlatCommand()).exited;
+await command.shellOutBun();

package/test/simple-test-node.ts

@@ -1,4 +1,3 @@
-import { spawn } from "node:child_process";
 import { PrintableShellCommand } from "../src";
 
 const command = new PrintableShellCommand("ffmpeg", [
@@ -8,7 +7,4 @@ const command = new PrintableShellCommand("ffmpeg", [
 	"./test/My video (slow-mo).mov",
 ]);
 
-command.print();
-await new Promise((resolve, reject) => {
-	spawn(...command.toCommandWithFlatArgs()).addListener("exit", resolve);
-});
+command.print().shellOutNode();