CommandBuilder | /src/command.ts | dax@0.34.0

class CommandBuilder

implements PromiseLike<CommandResult>

import { CommandBuilder } from "https://deno.land/x/dax@0.34.0/src/command.ts";

Underlying builder API for executing commands.

This is what $ uses to execute commands. Using this provides a way to provide a raw text command or an array of arguments.

Command builders are immutable where each method call creates a new command builder.

const builder = new CommandBuilder()
 .cwd("./src")
 .command("echo $MY_VAR");

// outputs 5
console.log(await builder.env("MY_VAR", "5").text());
// outputs 6
console.log(await builder.env("MY_VAR", "6").text());

Methods

bytes(): Promise<Uint8Array>

Sets stdout as quiet, spawns the command, and gets stdout as a Uint8Array.

Shorthand for:

const data = (await $`command`.quiet("stdout")).stdoutBytes;

captureCombined(value?): CommandBuilder

Whether to capture a combined buffer of both stdout and stderr.

This will set both stdout and stderr to "piped" if not already "piped" or "inheritPiped".

command(command: string | string[]): CommandBuilder

Sets the raw command to execute.

cwd(dirPath: string | URL | PathRef): CommandBuilder

Sets the current working directory to use when executing this command.

env(items: Record<string, string | undefined>): CommandBuilder

Sets multiple environment variables to use at the same time via an object literal.

env(name: string, value: string | undefined): CommandBuilder

Sets a single environment variable to use.

exportEnv(value?): CommandBuilder

Exports the environment of the command to the executing process.

So for example, changing the directory in a command or exporting an environment variable will actually change the environment of the executing process.

await $`cd src && export SOME_VALUE=5`;
console.log(Deno.env.get("SOME_VALUE")); // 5
console.log(Deno.cwd()); // will be in the src directory

json<TResult = any>(): Promise<TResult>

Sets stdout as quiet, spawns the command, and gets stdout as JSON.

Shorthand for:

const data = (await $`command`.quiet("stdout")).stdoutJson;

lines(): Promise<string[]>

Gets the text as an array of lines.

noThrow(value?): CommandBuilder

The command should not throw when it fails or times out.

printCommand(value?): CommandBuilder

Prints the command text before executing the command.

For example:

const text = "example";
await $`echo ${text}`.printCommand();

Outputs:

> echo example
example

quiet(kind?: "stdout" | "stderr" | "both"): CommandBuilder

Ensures stdout and stderr are piped if they have the default behaviour or are inherited.

// ensure both stdout and stderr is not logged to the console
await $`echo 1`.quiet();
// ensure stdout is not logged to the console
await $`echo 1`.quiet("stdout");
// ensure stderr is not logged to the console
await $`echo 1`.quiet("stderr");

registerCommand(command: string, handleFn: CommandHandler): CommandBuilder

registerCommands(commands: Record<string, CommandHandler>): CommandBuilder

setPrintCommandLogger(logger: (...args: any[]) => void): void

Mutates the command builder to change the logger used for printCommand().

signal(killSignal: KillSignal): CommandBuilder

Sets the command signal that will be passed to all commands created with this command builder.

spawn(): CommandChild

Explicit way to spawn a command.

This is an alias for awaiting the command builder or calling .then(...)

stderr(kind: ShellPipeWriterKind): CommandBuilder

Set the stderr kind.

stdin(reader: ShellPipeReader | Uint8Array | ReadableStream<Uint8Array>): CommandBuilder

Sets the stdin to use for the command.

stdinText(text: string): CommandBuilder

Sets the stdin string to use for a command.

stdout(kind: ShellPipeWriterKind): CommandBuilder

Set the stdout kind.

text(): Promise<string>

Sets stdout as quiet, spawns the command, and gets stdout as a string without the last newline.

Shorthand for:

const data = (await $`command`.quiet("stdout")).stdout.replace(/\r?\n$/, "");

timeout(delay: Delay | undefined): CommandBuilder

Specifies a timeout for the command. The command will exit with exit code 124 (timeout) if it times out.

Note that when using .noThrow() this won't cause an error to be thrown when timing out.

unregisterCommand(command: string): CommandBuilder

Unregister a command.

[getRegisteredCommandNamesSymbol]()