throng

Throng is a small npm library that wraps Node.js’s built-in cluster module to make running a clustered app a one-line call. Instead of hand-writing the fork loop, signal listeners, and worker-revival logic that cluster requires, a developer passes a single worker function to throng() and it forks one worker process per CPU core by default, restarts any worker that crashes, and cleanly proxies shutdown signals (SIGTERM/SIGINT) to every worker with a configurable grace period.

The library became a common pattern for scaling stateless Node.js web servers and background workers on platforms like Heroku, where clustering across CPU cores on a single dyno was a simple way to use available capacity without introducing a separate process manager. It supports an optional master-process callback for one-time setup, a lifetime option to bound how long a cluster stays alive, and legacy call signatures (passing a function directly, or a worker count) preserved for backward compatibility with earlier versions of the library.

What You Get

• A one-line throng(workerFn) call that forks one worker per available CPU core using Node’s built-in cluster module
• Automatic worker revival — crashed workers are forked again automatically until the cluster’s lifetime expires
• Signal handling for SIGTERM/SIGINT that proxies shutdown signals to every worker and force-kills them after a configurable grace period
• An optional master callback that runs once in the master process before workers are forked, useful for one-time setup
• A disconnect() helper passed to each worker for graceful, async cleanup before the worker exits
• Backward-compatible call signatures — a bare function, a worker count number, or a full options object — for apps written against older Throng versions

Common Use Cases

• Scaling a stateless Express or HTTP server across every CPU core on a single host or dyno without a separate process manager
• Running clustered background job workers that need to survive individual worker crashes without operator intervention
• Deploying Node.js apps on Heroku or similar single-dyno platforms where clustering is the simplest way to use all available CPU capacity
• Adding graceful shutdown behavior (finishing in-flight requests, closing connections) to an existing clustered app via the disconnect() callback

Under The Hood

Architecture Throng is a single-file module (lib/throng.js) that wraps Node’s built-in cluster module rather than layering new abstractions on top of it. The exported throng() function merges caller options with defaults via lodash’s defaultsDeep, then branches on cluster.isWorker: worker processes simply invoke the caller’s worker function with a disconnect helper, while the master process registers a disconnect listener that revives crashed workers (revive()) and OS signal handlers (shutdown()) that proxy SIGTERM/SIGINT to every worker with a grace-period force-kill fallback. A parseOptions function preserves several legacy calling conventions (bare function, worker count, or options object) for backward compatibility, which is the one source of incidental complexity in an otherwise minimal, single-responsibility module.

Tech Stack Throng is plain CommonJS JavaScript with no build step or transpilation — it targets Node >= 10 directly. Its only runtime dependency is lodash, used solely for defaultsDeep config merging; it otherwise relies entirely on Node’s built-in cluster and os modules. Tests use Mocha and Chai. CI is configured via a legacy Travis config testing against lts/*, node, and node 10, and the repo ships a Dockerfile (node:14, non-root node user) used to run tests inside docker-compose.

Code Quality The test suite spawns real child processes against fixture scripts to exercise actual cluster behavior — worker counts, crash-and-revive cycles, signal handling, and lifetime bounds — rather than mocking the cluster module, which is an appropriate integration-style approach for process-management code. There is no TypeScript and no visible linter configuration, so type safety and static style enforcement are absent; error handling is limited to a single explicit throw for a missing worker function, with the rest relying on promise rejection propagation. Naming is clear and the module is well-commented, including candid inline notes about legacy option-parsing decisions.

API Design Throng’s entire value proposition is ergonomic: reducing clustering to throng(workerFn) instead of hand-written cluster.fork()/signal-handling boilerplate. It layers a small, well-scoped set of conveniences — auto-revival, graceful shutdown with a grace period, an async disconnect() callback, and an optional one-time master setup hook — directly on top of Node’s existing cluster primitives rather than introducing a new one. This is a thin, focused convenience wrapper rather than a novel technical approach, but the API surface is small and easy to learn from the README alone.