@zokugun/exec-lite
v0.4.1
Published
A lightweight tool for running shell commands and reading their output easily.
Maintainers
Readme
@zokugun/exec-lite
Run external commands and manage their output easily. You get simple success or failure objects containing exit codes, execution time, and all captured text from standard output and error streams.
Features
- Process Management: Spawn and manage external commands with a clean API.
- Result Types: Get structured success and failure objects for every run.
- Unified Output: Combines stdout and stderr into a single stream for easier logging.
- Windows Normalization: Automatically handles
cmd.exeand path escaping for Windows. - Automated Resolution: Locate binaries automatically using PATH and file extensions.
- Process Piping: Chain multiple commands together to pass data between them.
- Abort Support: Cancel running processes using standard abort signals.
- Exit Tracking: Capture precise exit codes and signal codes from tasks.
- Execution Timing: Measure the exact duration of a command in milliseconds.
Installation
npm add @zokugun/exec-liteRequirements
- Node.js:
v18.20or higher - Modules: ECMAScript Modules (
ESM) or CommonJS (CJS)
Quick Start
1. Basic Execution
Run a command and wait for the final output. Use this when you only need the end result.
import { exec } from '@zokugun/exec-lite';
async function runSimpleCommand(): Promise<void> {
const result = await exec('echo', ['hello world']);
if(result.fails) {
console.error(`Failed with exit code: ${result.value.exitCode}`);
return;
}
const { stdout } = result.value;
console.log(`Output: ${stdout}`);
}2. Streaming Output
Iterate over the process output in real-time.
import { exec } from '@zokugun/exec-lite';
async function runPipedCommands(): Promise<void> {
const task = exec('npm', ['install']);
for await(const line of task) {
console.log(`Log: ${line}`);
}
if(task.failed) {
console.error(`Failed with exit code: ${task.exitCode}`);
}
}3. Piping Processes
Chain multiple commands together using the .pipe() method. The output of the first process is passed as the input to the second.
import { exec } from '@zokugun/exec-lite';
async function runPipedCommands(): Promise<void> {
const result = await exec('cat', ['package.json']).pipe('grep', ['dependencies']);
if(result.fails) {
console.log('Pipeline failed');
return;
}
console.log(`Filtered output: ${result.value.stdout}`);
}
await runPipedCommands();API Reference
Functions
exec
export function exec(
command: string,
args?: readonly string[] | null,
options?: Partial<Options>,
): Subprocess;Spawns a child process and returns a Subprocess instance. The process starts immediately on return.
Caveats:
execdoes not throw. Errors surface through thefailsflag of theResult.- On Windows, batch files (
.bat,.cmd) are wrapped incmd.exewith verbatim argument handling.
createCommand
import { createCommand } from '@zokugun/exec-lite';
const git = createCommand('git');
await git(['status'], { cwd: repository });
await git.withOptions({ cwd: repository })(['status']);
await git.toCwdFirst()(repository, 'status');
await git.toFlatArgs()('status');type Command = {
(args?: readonly string[] | null, options?: Partial<Options>): Subprocess;
toCwdFirst(): (cwd: string, ...args: string[]) => Subprocess;
toFlatArgs(): (...args: string[]) => Subprocess;
withOptions(options: Partial<Options>): Command;
}Creates a reusable command with optional default arguments and options.
Classes
ExecProcess
class ExecProcess implements Subprocess { ... }The class behind every subprocess returned by exec. You rarely need to construct it directly — use exec() instead.
Key properties:
| Property | Type | Description |
| ------------- | --------------------------- | ------------------------------------------------------ |
| .aborted | boolean | True if the process was aborted via signal |
| .error | Error \| undefined | The error that caused failure, if any |
| .exitCode | number \| undefined | Exit code after the process closes |
| .failed | boolean | True if exit code is non-zero or a signal was received |
| .killed | boolean | True if kill() was called |
| .pid | number \| undefined | OS process ID |
| .process | ChildProcess \| undefined | The raw Node.js child process handle |
| .signalCode | string \| undefined | Signal code that terminated the process |
Key methods:
| Method | Returns | Description |
| --------------------------------- | ------------ | ----------------------------------------------------------------- |
| .kill(signal?) | boolean | Sends a signal to the process. Returns false if no handle exists. |
| .pipe(command, args?, options?) | Subprocess | Chains another command, piping this stdout into its stdin. |
| .spawn() | void | Starts the process. Called automatically by exec(). |
Types
ExecResult
A structured success or failure result:
type ExecResult = Result<ExecSuccess, ExecFailure>;ExecSuccess
Returned when the process exits with code 0 and no error occurred.
type ExecSuccess = {
args: readonly string[];
command: string;
cwd: string;
durationMs: number;
exitCode: number;
merged: string; // combined stdout + stderr
stdout: string;
stderr: string;
};ExecFailure
Returned when the process errors, exits non-zero, or gets killed.
type ExecFailure = {
args: readonly string[];
canceled: boolean; // true if aborted via signal
command: string;
cwd?: string;
durationMs: number;
error?: Error;
exitCode?: number;
merged?: string;
signalCode?: string;
stderr?: string;
stdout?: string;
};Subprocess
The shape returned by exec(). It is:
- A promise-like — resolves to
ExecResultwhen awaited. - An async iterable — yields lines from stdout + stderr.
- A live handle — inspect
.exitCode,.pid, etc. at any time after spawn.
type Subprocess = AsyncIterable<string> & PromiseLike<ExecResult> & { ... };Options
Extended SpawnOptions with extra fields:
| Field | Type | Default | Description |
| ------------------- | ------------------------------------------ | -------------------- | -------------------------------------------------------------------------- |
| cwd | string | process.cwd() | Working directory |
| env | Record<string, string> | inherited + computed | Environment variables |
| localDir | string | cwd | Directory to resolve local paths from |
| onSuccess | (value: Success<ExecSuccess>) => unknown | none | Called for a successful result; its return value becomes the awaited value |
| onFailure | (error: Failure<ExecFailure>) => unknown | none | Called for a failed result; its return value becomes the awaited value |
| preferLocal | boolean | false | Prepends node_modules/.bin to PATH |
| signal | AbortSignal | none | Abort signal for cancellation |
| stdin | string \| Subprocess \| { process } | 'pipe' | Input source |
| stdio | | none | Standard I/O configurations. |
| stdout / stderr | StdioOption | none | Stream configuration |
| timeout | number | none | Auto-abort after N milliseconds |
Contributions
Contributions are most welcome. Please:
- Open issues and feature requests under the repository discussions.
- Follow the
CONTRIBUTING.md.
Donations
Support this project by becoming a financial contributor.
License
Copyright © 2026-present Baptiste Augrain
Licensed under the MIT license.
