npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@zokugun/exec-lite

v0.4.1

Published

A lightweight tool for running shell commands and reading their output easily.

Readme

@zokugun/exec-lite

License: MIT NPM Version NodeJS Version Modules Ko-fi Liberapay PayPal

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.exe and 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-lite

Requirements

  • Node.js: v18.20 or 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:

  • exec does not throw. Errors surface through the fails flag of the Result.
  • On Windows, batch files (.bat, .cmd) are wrapped in cmd.exe with 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 ExecResult when 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.