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

class CommandBuilder

implements PromiseLike<CommandResult>

import { CommandBuilder } from "https://deno.land/x/dax@0.31.1/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()

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

Shorthand for:

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

captureCombined(value?)

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[])

Sets the raw command to execute.

cwd(dirPath: string | URL | PathRef)

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?)

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()

Gets the text as an array of lines.

noThrow(value?)

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

printCommand(value?)

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")

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)

registerCommands(commands: Record<string, CommandHandler>)

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

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

spawn(): CommandChild

Explicit way to spawn a command.

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

stderr(kind: ShellPipeWriterKind)

Set the stderr kind.

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

Sets the stdin to use for the command.

stdinText(text: string)

Sets the stdin string to use for a command.

stdout(kind: ShellPipeWriterKind)

Set the stdout kind.

text()

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)

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)

Unregister a command.

[getRegisteredCommandNamesSymbol]()