proc

A high-level way to run child processes that is easy, flexible, powerful, and prevents resource leaks.

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

• Simple Examples for Input and Output Handlers
• Playing Sounds with aplay
• Count the Unique Words in War and Peace
• Use PushIterable to Implement Workers

Related Projects

• deno-asynciter

Input and Output Types

proc uses input and output handlers that let you choose both the types and behaviors for your data. It also lets you customize stderr and error handling. With just a little code for definition, you can work with bytes or text, synchronous or asynchronous, buffered or unbuffered.

An Example

To get you started, here is an example where we pass a text string to a process and get back a Uint8Array - text compressed to bytes using gzip. This uses the "short-form" function that takes a string as input and returns a Uint8array as output.

/**
 * 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 proc.runSB({ cmd: ["gzip", "-c"] }, text);
}

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

ℹ️ Short Form The short form run functions are new. It seems a little odd to have so many different typed functions, but it cuts out a lot of boilerplate. This feature will most likely be under development for some time. See runner.ts for available short form run functions.

Input Types

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

Output Types

^* - 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's output won't be fully read, and therefore the process 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.

Direct Control Over stderr

For most of the output handlers, the first argument is optional and allows you to pass a function to process stderr yourself.

• The function is passed one argument - an AsyncIterator<Uint8Array> of stderr in Uint8Array form (unbuffered); use toLines(...) to convert into text lines
• You can optionally return an unknown (anything) from this function; this are attached to the ProcessExitError if the process returns a non-zero error code
• You can throw an error from this function; this allows you to scrape stderr and do special error handling

The examples use this feature a couple of times.

See stderr-support.ts for some functions that provide non-default stderr bahaviors. You can use these directly, and they also serve as good working examples.

Overriding the Default Exit-Code Error Handling Behavior

For most of the output handlers, the second argument is optional and allows you to redefine the way that proc raises errors based on the process exit code.

This doesn't come up very often, but occasionally you may not want to treat all non-zero exit codes as an error. You also may want to throw your own error rather than the standard ProcessExitError.

The default error handling definition is defined in error-support.ts. Refer to this code if you want to create a custom error handler.