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

A helper class to construct shell commands in a way that allows printing them.

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 {};