printable-shell-command 1.1.1 → 1.1.2

package/dist/lib/printable-shell-command/index.d.ts

@@ -0,0 +1,150 @@
+import type { ChildProcess as NodeChildProcess, SpawnOptions as NodeSpawnOptions, SpawnOptionsWithoutStdio as NodeSpawnOptionsWithoutStdio, SpawnOptionsWithStdioTuple as NodeSpawnOptionsWithStdioTuple, StdioNull as NodeStdioNull, StdioPipe as NodeStdioPipe } from "node:child_process";
+import { styleText } from "node:util";
+import type { SpawnOptions as BunSpawnOptions, Subprocess as BunSubprocess } from "bun";
+type SingleArgument = string;
+type FlagArgumentPair = [string, string];
+type ArgsEntry = SingleArgument | FlagArgumentPair;
+type Args = ArgsEntry[];
+export interface PrintOptions {
+    /** Defaults to "" */
+    mainIndentation?: string;
+    /** Defaults to "  " */
+    argIndentation?: string;
+    /**
+     * - `"auto"`: Quote only arguments that need it for safety. This tries to be
+     *   portable and safe across shells, but true safety and portability is hard
+     *   to guarantee.
+     * - `"extra-safe"`: Quote all arguments, even ones that don't need it. This is
+     *   more likely to be safe under all circumstances.
+     */
+    quoting?: "auto" | "extra-safe";
+    /** Line wrapping to use between arguments. Defaults to `"by-entry"`. */
+    argumentLineWrapping?: "by-entry" | "nested-by-entry" | "by-argument" | "inline";
+    /**
+     * Style text using `node`'s [`styleText(…)`](https://nodejs.org/api/util.html#utilstyletextformat-text-options)
+     *
+     * Example usage:
+     *
+     * ```
+     * new PrintableShellCommand("echo", ["hi"]).print({
+     *   styleTextFormat: ["gray", "bold"],
+     * });
+     * */
+    styleTextFormat?: Parameters<typeof styleText>[0];
+}
+export declare class PrintableShellCommand {
+    #private;
+    private args;
+    constructor(commandName: string, args?: Args);
+    get commandName(): string;
+    /** For use with `bun`.
+     *
+     * Usage example:
+     *
+     * ```
+     * import { PrintableShellCommand } from "printable-shell-command";
+     * import { spawn } from "bun";
+     *
+     * const command = new PrintableShellCommand( … );
+     * await spawn(command.toFlatCommand()).exited;
+     * ```
+     */
+    toFlatCommand(): string[];
+    /**
+     * Convenient alias for `toFlatCommand()`.
+     *
+     * Usage example:
+     *
+     * ```
+     * import { PrintableShellCommand } from "printable-shell-command";
+     * import { spawn } from "bun";
+     *
+     * const command = new PrintableShellCommand( … );
+     * await spawn(command.forBun()).exited;
+     * ```
+     *
+     * */
+    forBun(): string[];
+    /**
+     * For use with `node:child_process`
+     *
+     * Usage example:
+     *
+     * ```
+     * import { PrintableShellCommand } from "printable-shell-command";
+     * import { spawn } from "node:child_process";
+     *
+     * const command = new PrintableShellCommand( … );
+     * const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`
+     * ```
+     *
+     */
+    toCommandWithFlatArgs(): [string, string[]];
+    /**
+     * For use with `node:child_process`
+     *
+     * Usage example:
+     *
+     * ```
+     * import { PrintableShellCommand } from "printable-shell-command";
+     * import { spawn } from "node:child_process";
+     *
+     * const command = new PrintableShellCommand( … );
+     * const child_process = spawn(...command.forNode()); // Note the `...`
+     * ```
+     *
+     * Convenient alias for `toCommandWithFlatArgs()`.
+     */
+    forNode(): [string, string[]];
+    getPrintableCommand(options?: PrintOptions): string;
+    print(options?: PrintOptions): PrintableShellCommand;
+    /**
+     * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
+     */
+    spawnNode<Stdin extends NodeStdioNull | NodeStdioPipe, Stdout extends NodeStdioNull | NodeStdioPipe, Stderr extends NodeStdioNull | NodeStdioPipe>(options?: NodeSpawnOptions | NodeSpawnOptionsWithoutStdio | NodeSpawnOptionsWithStdioTuple<Stdin, Stdout, Stderr>): // TODO: figure out how to return `ChildProcessByStdio<…>` without duplicating fragile boilerplate.
+    NodeChildProcess & {
+        success: Promise<void>;
+    };
+    /** 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). */
+    spawnNodeInherit(options?: Omit<NodeSpawnOptions, "stdio">): NodeChildProcess & {
+        success: Promise<void>;
+    };
+    /** Equivalent to:
+     *
+     * ```
+     * await this.print().spawnNodeInherit().success;
+     * ```
+     */
+    shellOutNode(options?: Omit<NodeSpawnOptions, "stdio">): Promise<void>;
+    /**
+     * The returned subprocess includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
+     */
+    spawnBun<const In extends BunSpawnOptions.Writable = "ignore", const Out extends BunSpawnOptions.Readable = "pipe", const Err extends BunSpawnOptions.Readable = "inherit">(options?: Omit<BunSpawnOptions.OptionsObject<In, Out, Err>, "cmd">): BunSubprocess<In, Out, Err> & {
+        success: Promise<void>;
+    };
+    /**
+     * 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).
+     */
+    spawnBunInherit(options?: Omit<Omit<BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">, "cmd">, "stdio">): BunSubprocess<"inherit", "inherit", "inherit"> & {
+        success: Promise<void>;
+    };
+    /** Equivalent to:
+     *
+     * ```
+     * new Response(this.spawnBun(options).stdout);
+     * ```
+     */
+    spawnBunStdout(options?: Omit<Omit<BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">, "cmd">, "stdio">): Response;
+    /** Equivalent to:
+     *
+     * ```
+     * await this.print().spawnBunInherit().success;
+     * ```
+     */
+    shellOutBun(options?: Omit<Omit<BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">, "cmd">, "stdio">): Promise<void>;
+}
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "printable-shell-command",
-	"version": "1.1.1",
+	"version": "1.1.2",
 	"main": "./src/index.ts",
 	"devDependencies": {
 		"@biomejs/biome": "^2.1.4",
@@ -23,5 +23,8 @@
 		"./dist/",
 		"./src/"
 	],
-	"type": "module"
+	"type": "module",
+	"scripts": {
+		"prepublishOnly": "make prepublishOnly"
+	}
 }