exec-utils

A modern, promise-based utility package for Node.js that provides enhanced child process execution with robust error handling, timeouts, and input streaming support.

Description

exec-utils wraps Node.js child process functions with additional features that make command execution more reliable and convenient:

Promise-based API - Clean async/await pattern for process execution
Timeout support - Automatically kill long-running processes
AbortSignal integration - Cancel operations from outside
Input streaming - Easily pipe data to child processes
Unified error handling - Consistent error format with exit codes
Buffer size limits - Prevent memory issues with large outputs
Configurable encoding - Control output encoding
Typescript support - Full type definitions included

Installation

NPM

npm i exec-utils

GitHub

npm i https://github.com/lacherogwu/exec-utils

Requirements

Node.js 16 or higher

Usage

Basic Usage

import { spawn, exec } from 'exec-utils';

// Using spawn for commands with arguments
const { data } = await spawn('echo', ['Hello', 'World']);
console.log(data); // 'Hello World\n'

// Using exec for shell commands
const { data: execData } = await exec('echo "Hello World"');
console.log(execData); // 'Hello World\n'

With Timeout

// Kill process after 5 seconds
const { error } = await spawn('sleep', ['10'], { timeout: 5000 });
if (error) {
    console.log(error.message); // "Command timed out after 5000ms"
    console.log(error.code); // -1
}

With Input

// Provide input to a command
const { data } = await spawn('grep', ['good'], {
    input: 'no errors here\nthis line has an error\nall good',
});
console.log(data); // 'all good\n'

// JSON processing with jq
const { data: jsonData } = await spawn('jq', ['.name'], {
    input: JSON.stringify({ name: 'John', age: 30 }),
});
console.log(jsonData.trim()); // '"John"'

With AbortController

// Cancel execution from outside
const controller = new AbortController();
const { signal } = controller;

// Start a process
const processPromise = spawn('sleep', ['10'], { signal });

// Cancel it after 2 seconds
setTimeout(() => {
    controller.abort();
}, 2000);

const { error } = await processPromise;
if (error) {
    console.log(error.message); // "Operation aborted"
    console.log(error.code); // -1
}

Error Handling

// Handle errors and non-zero exit codes
const { error, data } = await spawn('ls', ['non-existent-directory']);

if (error) {
    console.error(`Command failed with code ${error.code}`);
    console.error(error.message); // Contains stderr output
} else {
    console.log(data);
}

API

`spawn(command: string, args: string[], options?: SpawnOptions): Promise<CommandResult>`

Executes a command with arguments.

Parameters:
- command: Command to execute
- args: Array of arguments
- options: Optional configuration object
Returns:
- Promise resolving to a CommandResult object

`exec(command: string, options?: ExecOptions): Promise<CommandResult>`

Executes a shell command.

Parameters:
- command: Shell command to execute
- options: Optional configuration object
Returns:
- Promise resolving to a CommandResult object

Options

interface SpawnOptions {
    // Timeout in milliseconds
    timeout?: number;

    // Maximum buffer size in bytes (default: 80MB)
    maxBuffer?: number;

    // Output encoding (default: 'utf8')
    encoding?: BufferEncoding;

    // AbortSignal for cancellation
    signal?: AbortSignal;

    // Data to write to stdin
    input?: string | Buffer | NodeJS.ReadableStream;

    // Plus all Node.js child_process.SpawnOptions
}

interface ExecOptions {
    // Same as SpawnOptions plus all Node.js child_process.ExecOptions
}

Result Object

type CommandResult =
    | {
            // Process succeeded
            data: string; // Process output as string
            dataAsBuffer: Buffer; // Raw output buffer
            error: null; // No error
            process: ChildProcess; // Process reference
      }
    | {
            // Process failed
            data: null; // No data
            dataAsBuffer: null; // No data buffer
            error: ExecUtilsError; // Error with message and code
            process: ChildProcess; // Process reference
      };

License

MIT