thart

thart is a Node.js library for managing the lifecycle of multi-process applications. It provides a simple, flexible API for spawning and managing worker processes, handling graceful shutdowns, and coordinating between primary and worker processes.

IMPORTANT thart and all future versions are now installable from @ramplex/thart. The original thart package has been deprecated and will no longer be maintained.

Acknowledgements:

• thart was inspired by throng and shamelessly uses a lot of code from async-cleanup to manage process cleanup.

Features

• Spawn and manage multiple worker processes
• Support for both node:cluster and node:child_process worker types
• Graceful and coordinated shutdown handling
• Configurable startup and shutdown behaviors
• Timeout handling for worker startup
• Flexible API supporting various application structures

Installation

Thart is on the npm registry. Install it with your choice of npm, yarn, or pnpm.

1npm install @ramplex/thart
2yarn add @ramplex/thart
3pnpm add @ramplex/thart

Usage

thart can be imported via ES6 imports or CommonJS require as a default or named import.

1import thart from "@ramplex/thart";
2// or
3import { thart } from "@ramplex/thart";
4// or
5const thart = require("@ramplex/thart");
6// or
7const { thart } = require("@ramplex/thart");

View more examples in the examples directory.

Basic Example

1import thart from "@ramplex/thart";
2
3await thart({
4  worker: {
5    count: 4,
6    // allows TCP servers to be shared between workers
7    type: "cluster",
8    start: async (id) => {
9      console.log(`Worker ${id} starting`);
10      // Your worker logic here
11    },
12    stop: async () => {
13      console.log("Worker stopping");
14      // Cleanup logic here
15    },
16  },
17});

Primary and Worker Processes

1import thart from "@ramplex/thart";
2
3await thart({
4  primary: {
5    // this runs before any workers are forked
6    start: async () => {
7      console.log("Primary process started");
8      // Primary process initialization
9    },
10    // this runs after all workers have exited
11    stop: async () => {
12      console.log("Primary process stopping");
13      // Primary process cleanup
14    },
15  },
16  worker: {
17    count: 2,
18    type: "childProcess",
19    start: async (id) => {
20      console.log(`Worker ${id} started`);
21      // Worker process logic
22    },
23  },
24});

Multiple Worker Types

A powerful feature of thart is the ability to spawn multiple types of workers in the same application. This lets you seperate out, e.g., cron job processes from a cluster handling HTTP requests.

1import thart from "@ramplex/thart";
2
3await thart({
4  worker: [
5    {
6      count: 2,
7      type: "cluster",
8      start: async (id) => {
9        console.log(`Cluster worker ${id} started`);
10      },
11    },
12    {
13      count: 1,
14      type: "childProcess",
15      start: async (id) => {
16        console.log(`Child process worker ${id} started`);
17      },
18    },
19  ],
20});

Notes on Process Groups

When using thart to start up your node application, ensure you execute

1node entrypoint.js

directly instead of using package managers like pnpm to start your application. Package managers like pnpm seem to change the way signals are propagated, interfering with the libraries ability to shut down gracefully.

API

thart(options)

The main function to start your application.

Options

• grace (optional): Grace period in milliseconds for shutdown. Default: 10000 (10 seconds)
• primary (optional): Configuration for the primary process
  • start: Function to run when the primary process starts
  • stop (optional): Function to run when the primary process is shutting down
• worker: Configuration for worker processes. Can be a single object or an array of objects
  • count: Number of worker processes to spawn (when using an array of objects, this is optional and defaults to 1)
  • type: Type of worker process ('cluster' or 'childProcess')
  • start: Function to run in each worker process
  • stop (optional): Function to run when a worker process is shutting down
  • startupTimeoutMs (optional): Timeout for worker startup in milliseconds
  • killAfterCompleted (optional): If true, kills the worker after the start function completes

Types & Overloads

Types

1interface CommonThartOptions {
2  /**
3   * The grace period for shutting down worker processes in milliseconds.
4   * This determines how long to wait for workers to finish their tasks before forcefully terminating them.
5   *
6   * @default 10000 (10 seconds)
7   */
8  grace?: number;
9}
10
11type PrimaryFunction = {
12  /**
13   * A function to be executed in the primary process (there is only one primary process).
14   */
15  start: () => Promise<void> | void;
16  /**
17   * A function to be executed in the primary process when the primary process is shutting down.
18   * This gets invoked AFTER all worker processes have been shut down.
19   */
20  stop?: () => Promise<void> | void;
21};
22
23type WorkerCount = {
24  /**
25   * A function to be executed in each worker process when the worker process is shutting down.
26   * @param id - The id of the worker process.
27   * @returns A promise that resolves when the worker process has completed.
28   */
29  /**
30   * The number of worker processes to spawn.
31   */
32  count: number;
33};
34
35type WorkerFunction = {
36  /**
37   * A function to be executed in each worker process (there is no limit to the number of worker processes).
38   * @param id - The id of the worker process.
39   * @returns A promise that resolves when the worker process has completed.
40   */
41  start: (id: number) => Promise<void> | void;
42  /**
43   * The type of worker process to use.
44   * "childProcess" will use Node.js child processes.
45   * "cluster" will use Node.js cluster module.
46   *
47   * You should use:
48   * - "cluster" allows TCP servers to be shared between workers and is thus recommended when using TCP servers.
49   * - "childProcess" is recommended for CPU-bound tasks / jobs that can be run independently.
50   */
51  type: "childProcess" | "cluster";
52  /**
53   * Determines whether the worker process should be terminated after completing its task.
54   * By default, when all work in the process is done, the node process that executed the worker is still kept alive.
55   * If you want to terminate the node process after completing its task, set this to true.
56   *
57   * @default false
58   */
59  killAfterCompleted?: boolean;
60  /**
61   * A function to be executed in each worker process when the worker process is shutting down.
62   */
63  stop?: () => Promise<void> | void;
64  /**
65   * The timeout duration for the worker function in milliseconds.
66   * If the worker function takes longer than this duration, it will be forcefully terminated.
67   *
68   * @default 3000 (3 seconds)
69   */
70  startupTimeoutMs?: number;
71};

Signatures

1/**
2 * Start your node application with a primary process only.
3 * @param {PrimaryThartOptions} opts
4 * @param {number} opts.grace (optional) The grace period in milliseconds to allow for the primary process to shut down before forcefully exiting. Default is 10000 (10 seconds).
5 * @param {PrimaryFunction} opts.primary The primary function configuration to be executed in the primary process
6 * @param {PrimaryFunction["start"]} opts.primary.start The function to be executed in the primary process when the primary process starts
7 * @param {PrimaryFunction["stop"]} opts.primary.stop (optional) The function to be executed in the primary process when the primary process is shutting down
8 * @returns {Promise<void>}
9 */
10export async function thart(opts: PrimaryThartOptions): Promise<void>;
11/**
12 * Start your node application by spawning `count` workers
13 * @param {WorkerThartOptions} opts
14 * @param {number} opts.grace (optional) The grace period in milliseconds to allow for the primary process to shut down before forcefully exiting. Default is 10000 (10 seconds).
15 * @param {WorkerFunction} opts.worker The worker function configuration to be executed in every worker process
16 * @param {WorkerFunction["start"]} opts.worker.start The function to be executed in each worker process
17 * @param {WorkerFunction["type"]} opts.worker.type The type of child process to use.
18 *  - `childProcess` uses `node:child_process` `fork`
19 *  - `cluster` uses `node:cluster` `fork`
20 * @param {WorkerFunction["count"]} opts.worker.count The number of worker processes to spawn
21 * @param {WorkerFunction["stop"]}  opts.worker.stop (optional) The function to be executed in the each worker process when shut down.
22 *  If it is not provided, nothing is processed on process death.
23 * @param {WorkerFunction["startupTimeoutMs"]} opts.worker.startupTimeoutMs (optional) The time to wait for each workers start function to finish executing.
24 *  - If the worker fails to start in the allotted time, the worker process is exited.
25 *  - If it is not provided, there is no timeout.
26 *  - In the event a stop function was provided, it is not invoked.
27 * @param {WorkerFunction["killAfterCompleted"]} opts.worker.killAfterCompleted (optional) When set to `true`, the process will exit after the start function is completed.
28 * @returns {Promise<void>}
29 */
30export async function thart(opts: WorkerThartOptions): Promise<void>;
31/**
32 * Start your node application by spawning multiple types of workers
33 * @param {WorkerArrayThartOptions} opts
34 * @param {number} opts.grace (optional) The grace period in milliseconds to allow for the primary process to shut down before forcefully exiting. Default is 10000 (10 seconds)
35 * @param {(WorkerFunction & Partial<WorkerCount>)[]} opts.worker An array of worker configurations
36 * @param {WorkerFunction["start"]} opts.worker[].start The function to be executed in this worker process
37 * @param {WorkerFunction["type"]} opts.worker[].type The type of child process to use in this worker process
38 *  - `childProcess` uses `node:child_process` `fork`
39 *  - `cluster` uses `node:cluster` `fork`
40 * @param {WorkerFunction["count"]} [opts.worker[].count] (optional) The number of worker processes to spawn for this worker configuration. Defaults to 1 if not specified
41 * @param {WorkerFunction["stop"]} [opts.worker[].stop] (optional) The function to be executed in this worker process when shut down
42 *  If it is not provided, nothing is processed on process death.
43 * @param {WorkerFunction["startupTimeoutMs"]} [opts.worker[].startupTimeoutMs] (optional) The time to wait for this worker's start function to finish executing.
44 *  - If the worker fails to start in the allotted time, the worker process is exited.
45 *  - If it is not provided, there is no timeout.
46 *  - In the event a stop function was provided, it is not invoked.
47 * @param {WorkerFunction["killAfterCompleted"]} [opts.worker[].killAfterCompleted] (optional) When set to `true`, the process will exit after the start function is completed.
48 * @returns {Promise<void>}
49 */
50export async function thart(opts: WorkerArrayThartOptions): Promise<void>;
51/**
52 * Start your node application with both a primary process and a single type of worker processes
53 * @param {PrimaryAndSingleWorkerOptions} opts
54 * @param {number} [opts.grace] (optional) The grace period in milliseconds to allow for processes to shut down before forcefully exiting. Default is 10000 (10 seconds).
55 * @param {PrimaryFunction} opts.primary The primary function configuration to be executed in the primary process
56 * @param {PrimaryFunction["start"]} opts.primary.start The function to be executed in the primary process when it starts
57 * @param {PrimaryFunction["stop"]} [opts.primary.stop] (optional) The function to be executed in the primary process when it's shutting down
58 * @param {WorkerFunction & WorkerCount} opts.worker The worker function configuration to be executed in every worker process
59 * @param {WorkerFunction["start"]} opts.worker.start The function to be executed in each worker process
60 * @param {WorkerFunction["type"]} opts.worker.type The type of child process to use.
61 *  - `childProcess` uses `node:child_process` `fork`
62 *  - `cluster` uses `node:cluster` `fork`
63 * @param {WorkerCount["count"]} opts.worker.count The number of worker processes to spawn
64 * @param {WorkerFunction["stop"]} [opts.worker.stop] (optional) The function to be executed in each worker process when shutting down.
65 *  If not provided, nothing is computed on process termination.
66 * @param {WorkerFunction["startupTimeoutMs"]} [opts.worker.startupTimeoutMs] (optional) The time in milliseconds to wait for each worker's start function to finish executing.
67 *  - If the worker fails to start in the allotted time, the worker process is exited.
68 *  - If not provided, there is no timeout.
69 *  - In the event a stop function was provided, it is not invoked on timeout.
70 * @param {WorkerFunction["killAfterCompleted"]} [opts.worker.killAfterCompleted] (optional) When set to `true`, the worker process will exit after its start function is completed.
71 * @returns {Promise<void>}
72 */
73export async function thart(opts: PrimaryAndSingleWorkerOptions): Promise<void>;
74/**
75 * Start your node application with both a primary process and multiple types of worker processes
76 * @param {PrimaryAndArrayWorkerOptions} opts
77 * @param {number} [opts.grace] (optional) The grace period in milliseconds to allow for processes to shut down before forcefully exiting. Default is 10000 (10 seconds).
78 * @param {PrimaryFunction} opts.primary The primary function configuration to be executed in the primary process
79 * @param {PrimaryFunction["start"]} opts.primary.start The function to be executed in the primary process when it starts
80 * @param {PrimaryFunction["stop"]} [opts.primary.stop] (optional) The function to be executed in the primary process when it's shutting down
81 * @param {(WorkerFunction & Partial<WorkerCount>)[]} opts.worker An array of worker configurations
82 * @param {WorkerFunction["start"]} opts.worker[].start The function to be executed in the worker processes spawned from this config
83 * @param {WorkerFunction["type"]} opts.worker[].type The type of child process to use for this worker type.
84 *  - `childProcess` uses `node:child_process` `fork`
85 *  - `cluster` uses `node:cluster` `fork`
86 * @param {WorkerFunction["count"]} [opts.worker[].count] (optional) The number of worker processes to spawn for this worker type. Defaults to 1 if not specified.
87 * @param {WorkerFunction["stop"]} [opts.worker[].stop] (optional) The function to be executed in the worker processes spawned from this config when shutting down.
88 *  If not provided, nothing is computed on process termination.
89 * @param {WorkerFunction["startupTimeoutMs"]} [opts.worker[].startupTimeoutMs] (optional) The time in milliseconds to wait for each worker's start function to finish executing.
90 *  - If the worker fails to start in the allotted time, the worker process is exited.
91 *  - If not provided, there is no timeout.
92 *  - In the event a stop function was provided, it is not invoked on timeout.
93 * @param {WorkerFunction["killAfterCompleted"]} [opts.worker[].killAfterCompleted] (optional) When set to `true`, the worker process will exit after its start function is completed.
94 * @returns {Promise<void>}
95 */
96export async function thart(opts: PrimaryAndArrayWorkerOptions): Promise<void>;

License

thart is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.