postal-transport-childprocess

child_process and cluster IPC transport for postal — bridges pub/sub across Node.js processes.

Installation

npm install postal postal-transport-childprocess

Usage

child_process

Parent:

import { fork } from "child_process";
import { addTransport, getChannel } from "postal";
import { connectToChild } from "postal-transport-childprocess";

const child = fork("./worker.js");
const transport = await connectToChild(child);
const remove = addTransport(transport);

// Clean up when the child exits
child.on("exit", () => remove());

Child (worker.js):

import { addTransport, getChannel } from "postal";
import { connectToParent } from "postal-transport-childprocess";

const transport = await connectToParent();
addTransport(transport);

cluster

Primary:

import cluster from "cluster";
import { addTransport } from "postal";
import { connectToClusterWorker } from "postal-transport-childprocess/cluster";

const worker = cluster.fork();
const transport = await connectToClusterWorker(worker);
const remove = addTransport(transport);

worker.on("exit", () => remove());

Worker:

import { addTransport } from "postal";
import { connectToClusterPrimary } from "postal-transport-childprocess/cluster";

const transport = await connectToClusterPrimary();
addTransport(transport);

API

connectToChild(child, options?)

Initiates a handshake from the parent to a forked child. Rejects if the child's IPC channel is closed or the handshake times out.

connectToParent(options?)

Waits for a SYN from the parent. Rejects immediately if the process has no IPC channel (not spawned with fork()).

connectToClusterWorker(worker, options?)

Same as connectToChild but accepts a cluster.Worker.

connectToClusterPrimary(options?)

Same as connectToParent but for cluster workers.

createIPCTransport(endpoint)

Low-level factory. Accepts any object with send(), on('message'), and removeListener('message'). Use this if you manage the handshake yourself.

Options

| Option | Type | Default | Description | | --------- | -------- | ------- | --------------------------------- | | timeout | number | 5000 | Handshake timeout in milliseconds |

Known Limitations

• Binary payloads: Node IPC uses JSON serialization. Buffer and ArrayBuffer values are serialized as JSON objects — they arrive intact but as plain objects, not typed array instances. Base64-encode binary data before sending it across processes.
• Reconnection: This transport does not attempt to reconnect if the IPC channel closes. Wire up child.on('exit') / process.on('disconnect') to dispose the transport and re-establish if needed.