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

jg-process

v1.7.0

Published

Run and stop child processes in Node.js without a shell: timeouts, output limits, abort signals, and whole process trees.

Readme

jg-process

Run and stop child processes in Node.js without a shell: timeouts, output limits, abort signals, and whole process trees.

Install

npm install jg-process

Usage

Run a command to completion and read its output. The run is bounded by a timeout and an output limit, and both stop the whole process tree:

import { runProcess } from 'jg-process';

const { exitCode, stdout, stderr, durationMs } = await runProcess({
  command: 'git',
  args: ['status', '--porcelain'],
  cwd: repositoryDirectory,
  timeoutSeconds: 30,
  signal: AbortSignal.timeout(60_000),
});

A non-zero exit code resolves, so callers decide what counts as failure. A timeout, too much output, or a failure to start rejects with PROCESS_TIMED_OUT, PROCESS_OUTPUT_TOO_LARGE, or PROCESS_START_FAILED. A timeout that isn't a positive number of at most 2,147,483 seconds, or an output limit that isn't a positive safe integer, such as a computed budget that ran out, rejects with INVALID_PROCESS_OPTIONS before anything starts. With encoding: 'buffer', stdout and stderr are the bytes the process wrote, for output that may not be valid UTF-8, such as file names.

Start a long-running process that you own, and stop it together with everything it started:

import { createShutdownSignal, startProcess, stopProcessTree } from 'jg-process';

const server = startProcess({ command: 'node', args: ['server.js'], cwd: 'apps/api' });
const shutdown = createShutdownSignal(); // Ctrl+C or SIGTERM, which sets the exit code to 130 or 143
shutdown.signal.addEventListener('abort', () => void stopProcessTree(server), { once: true });

createShutdownSignal turns SIGINT and SIGTERM, or the signals you pass, into an AbortSignal that aborts with PROCESS_INTERRUPTED at the first one, so one signal stops a script's or a service's work. It sets process.exitCode to 128 plus the signal's number, as a shell reports a process the signal stopped, unless setExitCode is false, and calls onSignal once, ignoring what it throws. It never calls process.exit, so the process exits once its work stops. A second signal is ignored, or, with forceOnRepeat, stops the process at once, for a shutdown that hangs. With disconnect: true, a child started with an IPC channel, such as by fork, also shuts down as with SIGTERM when its parent closes the channel or dies. dispose stops listening. On Windows, Ctrl+C sends SIGINT, but SIGTERM is never delivered.

Start a server and wait until it answers, or stop everything it started when it doesn't:

import { startProcessAndWait } from 'jg-process';

const api = await startProcessAndWait(
  { command: process.execPath, args: ['server.js'], cwd: 'apps/api' },
  { readyWhen: { url: 'http://127.0.0.1:3000/health' }, timeoutSeconds: 60 },
);

Run a package manager without a shell on every platform, including Windows, where its .cmd shim can't be spawned directly:

import { resolvePackageManagerCommand, runProcess } from 'jg-process';

await runProcess({ ...resolvePackageManagerCommand(['run', 'build']), timeoutSeconds: 600 });

Reserve a free port before handing it to a server, keeping the preferred one when it's free:

import { reservePort } from 'jg-process';

const reservation = await reservePort({ preferredPort: 3000 }); // 3000, or another free port
await reservation.release(); // right before the server binds it

Write a CLI script that parses its options strictly, reads piped input, and runs only when executed:

import { isMainModule, parseStrictArgs, readStdin } from 'jg-process';

if (isMainModule(import.meta.url)) {
  const { check, path } = parseStrictArgs(process.argv.slice(2), {
    check: { type: 'boolean' },
    path: { type: 'string', required: true },
  });
  const input = await readStdin({ maxBytes: 1_048_576 }); // STDIN_TOO_LARGE past 1 MiB
}

Read a request body or a socket's message within a limit, and still answer one that's too large:

import { createServer } from 'node:http';

import { hasErrorCode } from 'jg-exception';
import { ERRORS, readStream } from 'jg-process';

createServer((request, response) => {
  void readStream(request, { maxBytes: 65_536 }).then(
    (body) => response.end(body),
    (error: unknown) => {
      response.statusCode = hasErrorCode(error, ERRORS.STREAM_TOO_LARGE) ? 413 : 400;
      response.setHeader('connection', 'close');
      response.end();
    },
  );
});

parseStrictArgs refuses unknown options, positional arguments, an option given twice that isn't multiple, an empty value, and a missing required option, with INVALID_ARGUMENTS and data.option naming it. isMainModule compares real paths, so a script started through a symbolic link, such as an npm bin entry, counts. isProcessRunning(pid) tells whether a process, such as a lock's owner, is still running.

Documentation

The full API reference ships in the package as API.md, generated from its TSDoc for the installed version, and is at https://jg-packages.jesusgraterol.dev/packages/jg-process/.

Recipes for common jobs ship as RECIPES.md, with every block typechecked against the release, and are at https://jg-packages.jesusgraterol.dev/packages/jg-process/recipes/.

License

MIT