isolated-workers

⌘K

API Reference

Type-safe worker process library for Node.js. Define your message contracts with TypeScript and get full type inference for payloads and responses.

Categories

Core(2)Types(2)Configuration(2)Serialization(2)Drivers(4)Other(70)

Core

Functions

fcreateWorker- Create a worker process with type-safe messaging. By default, uses the child_process driver which spawns a separate Node.js process and communicates via Unix domain sockets (or named pipes on Windows). You can pass a different driver for alternative backends: - `WorkerThreadsDriver`: Uses worker_threads with MessagePort (shared memory capable)fstartWorkerServer- Start a worker server that listens for messages (type-safe version)

Types

Types

TDefineMessages- Type constructor for defining message sets. Use this to define your worker's message contract with full type safety.TWithResult- Extract keys that have a result defined.

Configuration

Types

THandlers- Handler function type for a message definition. Handlers receive the payload and return the result (or void if no result).TMiddleware- Middleware function type for message inspection/transformation. Applied sequentially in the order provided. Messages are sealed before being passed to middleware, so you can modify existing properties but cannot add new ones.

Serialization

Classes

CJsonSerializer- Default JSON serializer with newline terminator CSerializer- Abstract serializer class for custom message serialization. Includes terminator sequence to delimit messages in the stream. IMPORTANT: Must be a named class (not anonymous) for mismatch detection.

Drivers

Interfaces

IChildProcessCapabilities- Capability type for child_process driver. Child process workers support reconnection and detaching, but cannot use SharedArrayBuffer across the IPC boundary.IDriver- Driver interface for spawning workers. Drivers implement this interface to provide different worker communication backends.IDriverCapabilities- Driver capability flags. These flags indicate what features a driver supports, allowing higher-level code to make decisions based on available capabilities.IWorkerThreadsCapabilities- Capability type for worker_threads driver. Worker thread workers support SharedArrayBuffer but cannot be reconnected or detached from the parent.

Other

Functions

fcreateServer- Create a child process server for worker-side communication. This function takes startup data to determine the socket path and configuration, then creates a server listening for host connections.fcreateServer- Create a worker threads server for worker-side communication. This function uses parentPort from worker_threads to establish communication with the host process.fencodeStartupData- Encode startup data for passing to child_process via environment variable.fspawnWorker- Spawn a worker process and establish communication channel.fspawnWorker- Spawn a worker thread and establish communication channel.

Classes

CChildProcessChannel- Channel implementation for child process driver. Wraps a Connection and ChildProcess, providing the DriverChannel interface with optional reconnect and detach capabilities.CChildProcessServerChannel- Child process server channel implementation. Wraps a net.Server and provides the ServerChannel interface.CWorkerCrashedError CWorkerThreadsChannel- Channel implementation for worker threads driver. Wraps a Worker and provides the DriverChannel interface using MessagePort-based communication.CWorkerThreadsServerChannel- Worker threads server channel implementation. Wraps parentPort and provides the ServerChannel interface.

Interfaces

IBaseMessage- Base message with transaction ID for request/response pairing IChildProcessDriverOptions- Options for child process driver spawn IChildProcessStartupData- Startup data specific to child_process driver. Extends the base StartupData with child_process-specific fields.IConnection- Active connection interface IConnectionOptions- Connection options IDetachCapability- Detach capability mixin. Channels that support detaching expose this to indicate whether the worker is running detached from the parent.IDriverChannel- Communication channel returned by driver spawn. The channel provides a unified interface for sending messages, handling events, and managing the connection lifecycle.IDriverMessage- Message structure for driver communication. All messages sent through the driver layer follow this structure, enabling type-safe messaging with transaction tracking.ILogger- Logger interface - must implement all log level methods IMessageDef- Message definition shape - each message has a payload and optional result IMiddlewareContext- Context passed to middleware functions IReconnectCapability- Reconnect capability mixin. Channels that support reconnection implement this interface to allow disconnecting while keeping the worker alive.IServerChannel- Server channel interface for worker-side communication.IServerDriver- Driver interface for server-side usage. This is a minimal interface that drivers must satisfy for use with startWorkerServer. Both ChildProcessDriver and WorkerThreadsDriver satisfy this interface.IServerOptions- Options for creating a server channel ITypedMessage- Message with type discriminator ITypedResult- Result message with type discriminator IWorkerClient- Base worker client interface for type-safe messaging. The availability of certain methods depends on the driver's capabilities: - `disconnect()` / `reconnect()`: Only available with child_process driver - `pid`: Returns number for child_process, undefined for worker_threads IWorkerOptions- Worker options for spawning IWorkerServer- Active worker server IWorkerServerOptions- Server configuration options IWorkerThreadsDriverOptions- Options for worker threads driver spawn IWorkerThreadsResourceLimits- Resource limits for worker threads IWorkerThreadsStartupData- Startup data specific to worker_threads driver. Extends the base StartupData with worker_threads-specific fields.

Types

TAllMessages- Union of all message types in the definition.TAllResults- Union of all result types in the definition.TAnyMessage- Union of all message types (requests and responses). Use this for middleware, transaction ID generators, and other functions that handle any message type.TBuiltInTimeoutKey- Built-in timeout keys for worker lifecycle events TChildProcessDriverType- Type of the ChildProcessDriver TDriverOptionsFor- Driver-specific options mapping TLogLevel- Log level enum TMaybePromise- Utility type for values that may be promises TMessageDefs- Collection of message definitions TMessageHandler- Handler function type for message processing TMessageOf- Extract the full message type for a given key.TMessageResult- Map a message type to its corresponding result type.TMessageType TMiddlewareDirection- Direction for middleware context TPayloadOf- Extract the payload type for a given message key.TResponseFunction- Function to send a response back to the host TResponseFunction- Function to send a response back to the host TResultOf- Extract the full result type for a given key.TResultPayloadOf- Extract the result type for a given message key.TShutdownReason TTimeoutConfig- Timeout configuration allowing per-message-type timeouts. Built-in keys: - `WORKER_STARTUP`: Time to wait for worker to start (default: 10s) - `SERVER_CONNECT`: Time for server to wait for host connection (default: 30s) - `WORKER_MESSAGE`: Default timeout for all messages (default: 5min) You can also specify timeouts for specific message types by their key name. Message-specific timeouts take precedence over WORKER_MESSAGE.TTransactionIdGenerator- Transaction ID generator function type. Receives a message and returns a unique transaction ID string.TUnexpectedShutdownConfig TUnexpectedShutdownStrategy TWorkerHandler- Handler function type for worker messages TWorkerHandlers- Collection of handlers for different message types TWorkerThreadsDriverType- Type of the WorkerThreadsDriver

Variables

VChildProcessDriver- Child process driver. Uses child_process.fork() with Unix domain sockets for IPC. Supports disconnect/reconnect and detached workers.VChildProcessDriverOptions VDEFAULT_SERVER_CONNECT_TIMEOUT- Default server connect timeout (30 seconds)VdefaultLogger- Default console-based logger VSTARTUP_DATA_ENV_KEY- Environment variable key for startup data VSTARTUP_DATA_WORKER_KEY- workerData key for startup data VWorkerThreadsDriver- Worker threads driver. Uses worker_threads module with MessagePort for IPC. Supports SharedArrayBuffer for shared memory.VWorkerThreadsDriverOptions VWorkerThreadsResourceLimits