tinyexec

By default, tinyexec prepends node_modules/.bin and the current node executable's directory to PATH, allowing you to run locally installed binaries directly (e.g., eslint). To disable this behavior, set {nodePath: false} in the options.

// Uses local node_modules/eslint
await x('eslint', ['.']);

// Disables automatic PATH prepending
await x('eslint', ['.'], {nodePath: false});

Install tinyexec as a dependency using npm.

$ npm i -S tinyexec

Use the .pipe() method to chain commands. The pipe method accepts the same options as a regular execution.

const proc1 = x('ls', ['-l']);
const proc2 = proc1.pipe('grep', ['.js']);
const result = await proc2;

console.log(result.stdout);

Pass an AbortSignal via the signal option. When the controller is aborted, the process is killed, and the aborted and killed properties on the result will be set to true.

const aborter = new AbortController();
const proc = x('node', ['./foo.mjs'], {
  signal: aborter.signal
});

// elsewhere...
aborter.abort();

await proc;

proc.aborted; // true
proc.killed; // true

You can iterate over the lines of output (stdout and stderr combined in the order they appear) using an async loop on the object returned by x().

import {x} from 'tinyexec';

const proc = x('ls', ['-l']);

for await (const line of proc) {
  // line will be from stderr/stdout in the order you'd see it in a term
}

To pass data to a process's standard input (useful for secrets or whitespace-sensitive values), use the stdin option.

const result = await x('gh', ['auth', 'login', '--with-token'], {
  stdin: process.env.GITHUB_TOKEN
});

console.log(result.exitCode);

Use the x function to spawn and await a child process. By default, tinyexec does not throw on non-zero exit codes; you should check result.exitCode or pass {throwOnError: true} in the options. Output is returned exactly as produced, including trailing newlines.

import {x} from 'tinyexec';

const result = await x('ls', ['-l']);

// result.stdout - the stdout as a string
// result.stderr - the stderr as a string
// result.exitCode - the process exit code as a number

You can manually kill a process using the .kill([signal]) method. If no signal is provided, it defaults to SIGTERM.

const proc = x('ls');

proc.kill();

// or with a signal
proc.kill('SIGHUP');

Use xSync for blocking, synchronous execution.

Limitations of xSync: Because it blocks the event loop, the following features are not supported in the synchronous API:

• signal (AbortSignal)
• persist
• kill() method
• stdin piping
• pipe() method

Other options like timeout, throwOnError, and nodeOptions work as expected.

import {xSync} from 'tinyexec';

const result = xSync('ls', ['-l']);

// result.stdout - the stdout as a string
// result.stderr - the stderr as a string
// result.exitCode - the process exit code as a number

// You can also iterate over lines synchronously
for (const line of result) {
  // from stdout then stderr
}

Pass an options object to x() to control process behavior. Available options include:

• signal: An AbortSignal to allow aborting the execution.
• timeout: Time in milliseconds at which the process will be forcibly killed.
• persist: If true, the process will continue after the host exits.
• stdin: A string or another Result to be used as input.
• nodeOptions: Any valid options to Node's underlying spawn function.
• throwOnError: If true, non-zero exit codes will throw an error.
• nodePath: If false, node_modules/.bin and the current node executable's directory will not be prepended to PATH (defaults to true).

await x('ls', [], {
  timeout: 1000
});