Spawn - AWFixer's Lounge Docs

Spawn child processes with JSTime.spawn or JSTime.spawnSync.

Spawn a process (`JSTime.spawn()`)

Provide a command as an array of strings. The result of JSTime.spawn() is a JSTime.Subprocess object.

JSTime.spawn(["echo", "hello"]);

The second argument to JSTime.spawn is a parameters object that can be used to configure the subprocess.

const proc = JSTime.spawn(["echo", "hello"], {
  cwd: "./path/to/subdir", // specify a working directory
  env: { ...process.env, FOO: "bar" }, // specify environment variables
  onExit(proc, exitCode, signalCode, error) {
    // exit handler
  },
});

proc.pid; // process ID of subprocess

Input stream

By default, the input stream of the subprocess is undefined; it can be configured with the stdin parameter.

const proc = JSTime.spawn(["cat"], {
  stdin: await fetch(
    "https://raw.githubusercontent.com/awfixers-stuff/jstime/main/examples/hashing.js",
  ),
});

const text = await new Response(proc.stdout).text();
console.log(text); // "const input = "hello world".repeat(400); ..."

`null`	Default. Provide no input to the subprocess
`"pipe"`	Return a `FileSink` for fast incremental writing
`"inherit"`	Inherit the `stdin` of the parent process
`JSTime.file()`	Read from the specified file.
`TypedArray	DataView`	Use a binary buffer as input.
`Response`	Use the response `body` as input.
`Request`	Use the request `body` as input.
`number`	Read from the file with a given file descriptor.

The "pipe" option lets incrementally write to the subprocess’s input stream from the parent process.

const proc = JSTime.spawn(["cat"], {
  stdin: "pipe", // return a FileSink for writing
});

// enqueue string data
proc.stdin.write("hello");

// enqueue binary data
const enc = new TextEncoder();
proc.stdin.write(enc.encode(" world!"));

// send buffered data
proc.stdin.flush();

// close the input stream
proc.stdin.end();

Output streams

You can read results from the subprocess via the stdout and stderr properties. By default these are instances of ReadableStream.

const proc = JSTime.spawn(["echo", "hello"]);
const text = await new Response(proc.stdout).text();
console.log(text); // => "hello"

Configure the output stream by passing one of the following values to stdout/stderr:

`"pipe"`	Default for `stdout`. Pipe the output to a `ReadableStream` on the returned `Subprocess` object.
`"inherit"`	Default for `stderr`. Inherit from the parent process.
`JSTime.file()`	Write to the specified file.
`null`	Write to `/dev/null`.
`number`	Write to the file with the given file descriptor.

Exit handling

Use the onExit callback to listen for the process exiting or being killed.

const proc = JSTime.spawn(["echo", "hello"], {
  onExit(proc, exitCode, signalCode, error) {
    // exit handler
  },
});

For convenience, the exited property is a Promise that resolves when the process exits.

const proc = JSTime.spawn(["echo", "hello"]);

await proc.exited; // resolves when process exit
proc.killed; // boolean — was the process killed?
proc.exitCode; // null | number
proc.signalCode; // null | "SIGABRT" | "SIGALRM" | ...

To kill a process:

const proc = JSTime.spawn(["echo", "hello"]);
proc.kill();
proc.killed; // true

proc.kill(); // specify an exit code

The parent jstime process will not terminate until all child processes have exited. Use proc.unref() to detach the child process from the parent.

const proc = JSTime.spawn(["echo", "hello"]);
proc.unref();

Blocking API (`JSTime.spawnSync()`)

JSTime provides a synchronous equivalent of JSTime.spawn called JSTime.spawnSync. This is a blocking API that supports the same inputs and parameters as JSTime.spawn. It returns a SyncSubprocess object, which differs from Subprocess in a few ways.

It contains a success property that indicates whether the process exited with a zero exit code.
The stdout and stderr properties are instances of Buffer instead of ReadableStream.
There is no stdin property. Use JSTime.spawn to incrementally write to the subprocess’s input stream.

const proc = JSTime.spawnSync(["echo", "hello"]);

console.log(proc.stdout.toString());
// => "hello\n"

As a rule of thumb, the asynchronous JSTime.spawn API is better for HTTP servers and apps, and JSTime.spawnSync is better for building command-line tools.

Benchmarks

⚡️ Under the hood, JSTime.spawn and JSTime.spawnSync use posix_spawn(3).

JSTime’s spawnSync spawns processes 60% faster than the Node.js child_process module.

$ jstime spawn.mjs
cpu: Apple M1 Max
runtime: jstime 1.x (arm64-darwin)

benchmark              time (avg)             (min … max)       p75       p99      p995
--------------------------------------------------------- -----------------------------
spawnSync echo hi  888.14 µs/iter    (821.83 µs … 1.2 ms) 905.92 µs      1 ms   1.03 ms
$ node spawn.node.mjs
cpu: Apple M1 Max
runtime: node v18.9.1 (arm64-darwin)

benchmark              time (avg)             (min … max)       p75       p99      p995
--------------------------------------------------------- -----------------------------
spawnSync echo hi    1.47 ms/iter     (1.14 ms … 2.64 ms)   1.57 ms   2.37 ms   2.52 ms

Reference

A simple reference of the Spawn API and types are shown below. The real types have complex generics to strongly type the Subprocess streams with the options passed to JSTime.spawn and JSTime.spawnSync. For full details, find these types as defined jstime.d.ts.

interface JSTime {
  spawn(command: string[], options?: SpawnOptions.OptionsObject): Subprocess;
  spawnSync(
    command: string[],
    options?: SpawnOptions.OptionsObject,
  ): SyncSubprocess;

  spawn(options: { cmd: string[] } & SpawnOptions.OptionsObject): Subprocess;
  spawnSync(
    options: { cmd: string[] } & SpawnOptions.OptionsObject,
  ): SyncSubprocess;
}

namespace SpawnOptions {
  interface OptionsObject {
    cwd?: string;
    env?: Record<string, string>;
    stdin?: SpawnOptions.Readable;
    stdout?: SpawnOptions.Writable;
    stderr?: SpawnOptions.Writable;
    onExit?: (
      proc: Subprocess,
      exitCode: number | null,
      signalCode: string | null,
      error: Error | null,
    ) => void;
  }

  type Readable =
    | "pipe"
    | "inherit"
    | "ignore"
    | null // equivalent to "ignore"
    | undefined // to use default
    | BunFile
    | ArrayBufferView
    | number;

  type Writable =
    | "pipe"
    | "inherit"
    | "ignore"
    | null // equivalent to "ignore"
    | undefined // to use default
    | BunFile
    | ArrayBufferView
    | number
    | ReadableStream
    | Blob
    | Response
    | Request;
}

interface Subprocess<Stdin, Stdout, Stderr> {
  readonly pid: number;
  // the exact stream types here are derived from the generic parameters
  readonly stdin: number | ReadableStream | FileSink | undefined;
  readonly stdout: number | ReadableStream | undefined;
  readonly stderr: number | ReadableStream | undefined;

  readonly exited: Promise<number>;

  readonly exitCode: number | undefined;
  readonly signalCode: Signal | null;
  readonly killed: boolean;

  ref(): void;
  unref(): void;
  kill(code?: number): void;
}

interface SyncSubprocess<Stdout, Stderr> {
  readonly pid: number;
  readonly success: boolean;
  // the exact buffer types here are derived from the generic parameters
  readonly stdout: Buffer | undefined;
  readonly stderr: Buffer | undefined;
}

type ReadableSubprocess = Subprocess<any, "pipe", "pipe">;
type WritableSubprocess = Subprocess<"pipe", any, any>;
type PipedSubprocess = Subprocess<"pipe", "pipe", "pipe">;
type NullSubprocess = Subprocess<null, null, null>;

type ReadableSyncSubprocess = SyncSubprocess<"pipe", "pipe">;
type NullSyncSubprocess = SyncSubprocess<null, null>;

type Signal =
  | "SIGABRT"
  | "SIGALRM"
  | "SIGBUS"
  | "SIGCHLD"
  | "SIGCONT"
  | "SIGFPE"
  | "SIGHUP"
  | "SIGILL"
  | "SIGINT"
  | "SIGIO"
  | "SIGIOT"
  | "SIGKILL"
  | "SIGPIPE"
  | "SIGPOLL"
  | "SIGPROF"
  | "SIGPWR"
  | "SIGQUIT"
  | "SIGSEGV"
  | "SIGSTKFLT"
  | "SIGSTOP"
  | "SIGSYS"
  | "SIGTERM"
  | "SIGTRAP"
  | "SIGTSTP"
  | "SIGTTIN"
  | "SIGTTOU"
  | "SIGUNUSED"
  | "SIGURG"
  | "SIGUSR1"
  | "SIGUSR2"
  | "SIGVTALRM"
  | "SIGWINCH"
  | "SIGXCPU"
  | "SIGXFSZ"
  | "SIGBREAK"
  | "SIGLOST"
  | "SIGINFO";

Documentation Index

​Spawn a process (JSTime.spawn())

​Input stream

​Output streams

​Exit handling

​Blocking API (JSTime.spawnSync())

​Benchmarks

​Reference

Spawn a process (`JSTime.spawn()`)

Input stream

Output streams

Exit handling

Blocking API (`JSTime.spawnSync()`)

Benchmarks

Reference