@bearz/exec

Overview

The exec module makes it easy to spawn child_processes across different runtimes (NodeJS, Bun, Deno) and different operating systems (Windows, Linux, Mac) and include additional utilities like splatting arguments and looking up executables on the path.

Documentation

Documentation is available on jsr.io

A list of other modules can be found at github.com/bearz-io/js

Usage

import { Command, cmd, run, exec, output, type SplatObject, which } from "@bearz/exec";

console.log( await (which("git"))); //path to git

// string, array, or objects can be used for "args".
const cmd1 = new Command("git", "show-ref master", {
    env: { "MY_VAR": "TEST" },
    cwd: "../parent"
});
const output = await cmd1.output();

console.log(output); // ->
// {
//    code: 0,
//    signal: undefined,
//    success: true
//    stdout: Uint8Array([01, 12..])
//    stderr: Uint8Array([0])
// }

// the output result has different methods on it..
console.log(output.text()) // text
console.log(output.lines()) // string[]
console.log(output.json()) // will throw if output is not valid json

const cmd2 = cmd("git", ["show-ref", "master");

// these are the same.
console.log(await cmd2.output()) 
console.log(await cmd2); 
console.log(await new Command("git", ["show-ref", "master"]));

console.log(await cmd2.text()); // get only the text from stdout instead

// pipe commands together
const result = await cmd("echo", ["my test"])
    .pipe("grep", ["test"])
    .pipe("cat")
    .output();

console.log(result.code);
console.log(result.stdout);

// output is the short hand for new Command().output()
// and output defaults stdout and stderr to 'piped'
// which returns the stdout and stderr streams a as Uint8Array
const text = await output("git", ["show-ref", "master"]).then(o => o.text());

console.log(text);

// exec will let you use a string for the command which will use
// splitArguments on the string and pass those to the cmd function.
console.log(await exec("git show-ref master").text());

Classes

• Command - A command/syscall that spawns a child process.
• Options - An interface that respresents the output of a command.
• PathFinder - A registry of executable paths, which can include additional paths to find the executable in case its not yet available in the PATH.
• ShellCommand - A command/syscall that spawns a child process for shells like pwsh, powershell, bash, sh, etc.

Functions

• cmd - Creates a new command.
• exec - Creates a new command from a string.
• output & outputSync - Creates a new command and sets the standard streams to 'piped' which allow you to capture the output and executes the command.
• run & runSync - Creates a new command sets the standard streams to inherit executes the command.
• setLogger - Sets a global logger that logs comamnds and its parameters any time a command is executed.
• spawn - Spawns a child process and lets you interact with the child process.
• splitArguments - Splits a string into commandline/cli arguments handling spaces, quotes, etc. This includes multiline strings that use \ or ``` to put parameters on additional lines similar to bash or powershell.
• splat - Takes an object and options and converts the object into command line parameters.
• which & whichSync - Determines if a command/app is available on the environment path and returns the full path if found.

License

MIT License