velt/process/child

API reference

Runs other programs. Programs are found through PATH and arguments are passed as-is, with no shell quoting. For a walkthrough, read the guide.

import { exec, execSync, spawn } from "velt/process/child";

Exports

spawnStarts program with args.execRuns program with args to completion; resolves with its exit code and output.execShellRuns a command line through the platform shell (sh -c / cmd /C).execShellSyncexecShell that blocks the calling thread.execSyncexec that blocks the calling thread (for scripts and CLIs).ExecResultWhat a finished program produced (output decoded as UTF-8, invalid bytes as U+FFFD).ChildProcessA started program: a Copy handle like std/net's TcpStream (async methods take this by copy, so await p.readStdout() can be called repeatedly), released by close() (after which the methods of every copy throw IoError EBADF and exitCode is null).ExecOptionsOptions of exec/execSync.SpawnOptionsOptions shared by every way of running a program.

function

spawn

#std/process/child/child_process.vlt:106

Re-exported from velt/process/child/child_process

function spawn(
  program: string,
  args: string[] = [],
  opts: SpawnOptions = {},
): ChildProcess

Starts program with args. Stdio defaults to "inherit"; use "pipe" to talk to it.

functionasync

exec

#std/process/child/exec.vlt:13

Re-exported from velt/process/child/exec

async function exec(
  program: string,
  args: string[] = [],
  opts: ExecOptions = {},
): Promise<ExecResult>

Runs program with args to completion; resolves with its exit code and output.

functionasync

execShell

#std/process/child/exec.vlt:39

Re-exported from velt/process/child/exec

async function execShell(
  command: string,
  opts: ExecOptions = {},
): Promise<ExecResult>

Runs a command line through the platform shell (sh -c / cmd /C). Never pass untrusted text: the shell interprets it.

function

execShellSync

#std/process/child/exec.vlt:47

Re-exported from velt/process/child/exec

function execShellSync(command: string, opts: ExecOptions = {}): ExecResult

execShell that blocks the calling thread.

function

execSync

#std/process/child/exec.vlt:23

Re-exported from velt/process/child/exec

function execSync(
  program: string,
  args: string[] = [],
  opts: ExecOptions = {},
): ExecResult

exec that blocks the calling thread (for scripts and CLIs).

class

ExecResult

#std/process/child/exec_result.vlt:4

Re-exported from velt/process/child/exec_result

What a finished program produced (output decoded as UTF-8, invalid bytes as U+FFFD).

Returned byexecexecSyncexecShellexecShellSync

code: number

Exit code; 128 + n when killed by signal n (Unix).

stdout: stringNo doc comment yet

stderr: stringNo doc comment yet

constructor(code: number, stdout: string, stderr: string)No doc comment yet

get ok(): bool

Whether the program exited with code 0.

struct

ChildProcess

#std/process/child/child_process.vlt:45

Re-exported from velt/process/child/child_process

A started program: a Copy handle like std/net's TcpStream (async methods take this by copy, so await p.readStdout() can be called repeatedly), released by close() (after which the methods of every copy throw IoError EBADF and exitCode is null). Closing does not stop the program (it is reaped in the background): kill it or wait for it.

Returned byspawn

Field	Type	Description
pid	`number`	The OS process id.

async write(data: string): Promise<void>

Writes to stdin (spawned with stdin: "pipe"); resolves once everything is written.

async closeStdin(): Promise<void>

Closes stdin: the program reads end of input.

async readStdout(max: u64 = 0): Promise<string>

The next chunk of stdout as text ("" = end of output); requires stdout: "pipe".

async readStderr(max: u64 = 0): Promise<string>

The next chunk of stderr as text ("" = end of output); requires stderr: "pipe".

async readStdoutBytes(max: u64 = 0): Promise<u8[]>

The next 1..max bytes of stdout (empty = end of output; max 0 = up to 64 KiB).

async readStderrBytes(max: u64 = 0): Promise<u8[]>

The next 1..max bytes of stderr (empty = end of output).

async wait(): Promise<i64>

Resolves with the exit code once the program has finished.

get exitCode(): i64 | null

The exit code if the program has finished, else null.

kill(signal: string = "SIGTERM")

Sends a signal ("SIGTERM" default, "SIGKILL", "SIGINT", "SIGHUP", "SIGQUIT"); on Windows every signal terminates the process. Does nothing once the program has finished.

close()

Releases the handle (operations in flight finish first; the program keeps running).

struct

ExecOptions

#std/process/child/exec_options.vlt:4

Re-exported from velt/process/child/exec_options

Options of exec/execSync.

Parameter ofexecexecSyncexecShellexecShellSync

Field	Type	Description
cwd?	`string`	—
env?	`Map<string, string>`	—
clearEnv?	`bool`	—
input?	`string`	Written to the program's stdin, which is then closed (default: empty stdin).

struct

SpawnOptions

#std/process/child/spawn_options.vlt:4

Re-exported from velt/process/child/spawn_options

Options shared by every way of running a program.

Parameter ofspawn

Field	Type	Description
cwd?	`string`	Working directory (default: the current one).
env?	`Map<string, string>`	Variables added to (or replacing ones in) the inherited environment.
clearEnv?	`bool`	Start from an empty environment (only `env` is set).
stdin?	`string`	"pipe", "inherit" (default) or "ignore", for `spawn` only.
stdout?	`string`	—
stderr?	`string`	—