function run
run<S>(
options: ProcessOptions<S>,
...cmd: Cmd,
): ProcessEnumerable<S>

Run a child process with a fluent, composable API.

This is the primary entry point for deno-proc. Unlike Deno's built-in Deno.Command, this function returns a ProcessEnumerable (extends AsyncIterable) that makes it trivial to:

  • Chain processes together with .run()
  • Transform output with .map(), .filter(), etc.
  • Parse lines with .lines property
  • Handle errors gracefully
  • Avoid common pitfalls like deadlocks and resource leaks

Why use this instead of Deno.Command?

Deno's Deno.Command requires manual stream handling, careful resource management, and verbose boilerplate. With deno-proc:

  • No manual stream reading/writing
  • Automatic resource cleanup
  • Composable operations via AsyncIterable
  • Built-in line parsing and transformations
  • Proper error propagation

Important: Error Handling

Processes that exit with non-zero codes throw ExitCodeError when you consume their output. You must consume stdout (via .lines, .collect(), etc.) or the process will leak resources.

Important: Resource Management

Always consume the process output or explicitly handle the stream. Unconsumed stdout will cause resource leaks. Use .lines.collect(), .lines.forEach(), or similar to consume output.

Examples

Basic command execution

import { run } from "jsr:@j50n/proc";

// Get output as lines - .lines is a property, .collect() is a method
const result = await run("echo", "hello").lines.collect();
// ["hello"]

Pipe commands together

import { run } from "jsr:@j50n/proc";

// Chain processes with .run() - .lines is a property, .first is a property
const result = await run("echo", "HELLO")
  .run("tr", "A-Z", "a-z")
  .lines
  .first;
// "hello"

Process and transform output

import { run } from "jsr:@j50n/proc";

// Map over lines and collect results
const numbers = await run("echo", "-e", "1\\n2\\n3")
  .lines
  .map(line => parseInt(line))
  .collect();
// [1, 2, 3]

Handle errors from failed processes

import { run } from "jsr:@j50n/proc";

try {
  await run("false").lines.collect();
} catch (error) {
  if (error.code) {
    console.error(`Process failed with exit code ${error.code}`);
  }
}

Check exit status without throwing

import { run } from "jsr:@j50n/proc";

const p = run("some-command");
await p.lines.collect(); // Consume output
const status = await p.status; // .status is a property returning Promise<CommandStatus>
if (status.code !== 0) {
  console.error(`Failed with code ${status.code}`);
}

Type Parameters

Parameters

options: ProcessOptions<S>

Process options (optional).

...cmd: Cmd

Return Type

A ProcessEnumerable for chaining operations.

run(...cmd: Cmd): ProcessEnumerable<unknown>

Run a child process with a fluent, composable API.

Parameters

...cmd: Cmd

Return Type

A ProcessEnumerable for chaining operations.

Usage

import { run } from ".";