proc

An easy way to run processes like a shell script - in Deno.

proc lets you write process-handling code in readable, idiomatic Typescript using async/await and AsyncIterator promisy goodness. It provides a variety of powerful and flexible input and output handlers, making using processes comfortable and intuitive. And proc handles closing and shutting down process-related resources in a sane manner - because you have enough to worry about, right?

For more ramblings, see Key Concepts.

Documentation

deno doc --reload https://deno.land/x/proc/mod.ts 2> /dev/null

Examples

deno-asynciter

Input and Output Types

Processes really just deal with one type of data - bytes, in streams. Many programs will take this one step further and internally translate to and from text data, processing this data one line at a time.

proc treats process data as either Uint8Array or AsyncIterable<Uint8Array> for byte data, or string or AsyncIterable<string> (as lines of text) for text. It defines a set of standard input and output handlers that provide both type information and data handling behavior to the runner.

An Example

To get you started, here is a simple example where we pass a text string to a process and get back a Uint8Array - text compressed to bytes using gzip.

/**
 * Use `gzip` to compress some text.
 * @param text The text to compress.
 * @return The text compressed into bytes.
 */
async function gzip(text: string): Promise<Uint8Array> {
  return await runner(stringInput(), bytesOutput())().run({
    cmd: ["gzip", "-c"],
  }, text);
}

console.dir(await gzip("Hello, world."));
/* prints an array of bytes to console. */

Input Types

Name	Description
`emptyInput()`	There is no process input.
`stringInput()`	Process input is a `string`.
`stringArrayInput()`	Process input is a `string[]`.
`bytesInput()`	Process input is a `Uint8Array`.
`readerInput()`^*	Process input is a `Deno.Reader & Deno.Closer`.
`readerUnbufferedInput()`^*	Process input is a `Deno.Reader & Deno.Closer`, unbuffered.
`stringIterableInput()`	Process input is an `AsyncIterable<string>`.
`stringIterableUnbufferedInput()`	Process input is an `AsyncIterable<string>`, unbuffered.
`bytesIterableInput()`	Process input is an `AsyncIterable<Uint8Array>`.
`bytesIterableUnbufferedInput()`	Process input is an `AsyncIterable<Uint8Array>`, unbuffered.

^* - readerInput() and readerUnbufferedInput() are special input types that do not have corresponding output types.

Output Types

Name	Description
`stringOutput()`	Process output is a `string`.
`stringArrayOutput()`	Process output is a `string[]`.
`bytesOutput()`	Process output is a `Uint8Array`.
`stringIterableOutput()`	Process output is an `AsyncIterable<string>`.
`stringIterableUnbufferedOutput()`	Process output is an `AsyncIterable<string>`, unbuffered.
`bytesIterableOutput()`	Process output is an `AsyncIterable<Uint8Array>`.
`bytesIterableUnbufferedOutput()`	Process output is an `AsyncIterable<Uint8Array>`, unbuffered.
`stderrToStdoutStringIterableOutput()`^*	`stdout` and `stderr` are converted to text lines (`string`) and multiplexed together.

^* - Special output handler that mixes stdout and stderr together. stdout must be text data. stdout is unbuffered to allow the text lines to be multiplexed as accurately as possible.

ℹ️ You must fully consume Iterable outputs. If you only partially consume Iterables, process errors will not propagate properly. For correct behavior, we have to return all the data from the process streams before we can propagate an error.

Running a Command

proc is easiest to use with a wildcard import.

import * as proc from "https://deno.land/x/proc@0.0.0/mod.ts";

First, create a template. The template is a static definition and may be reused. The input and output handlers determine the data types used by your runner.

const template = proc.runner(proc.emptyInput(), proc.stringOutput());

Next, create a runner by binding the template to a group.

const pg = proc.group();
const runner: proc.Runner<void, string> = template(pg);

Finally, use the runner to execute a command.

try {
  console.log(runner.run({ cmd: ["ls", "-la"] }));
} finally {
  pg.close();
}

A Simpler Alternative - The Global Group

It is not strictly necessary to create and close a local Group. If you don’t specify a group, proc will use the global Group that exists for the lifetime of the Deno process.

const runner = proc.runner(proc.emptyInput(), proc.stringOutput())();
console.log(runner.run({ cmd: ["ls", "-la"] }));

Notice the empty parentheses at the end of the first line in the second example. This is using the implicit global Group (which you don’t need to close manually).

Most of the time, proc can automatically clean up processes. In some cases where the output of one process feeds into the input of another, the first process won’t be fully processed and therefore cannot be automatically shut down. This can also happen if you don’t fully process AsyncIterable output of a process. This will result in resource leakage. If your program is short and does not start many processes, or if you are sure that the way you are using processes is well behaved (either non-streaming output or all output data is fully consumed), you can use the short form safely.