procxy

Procxy - A TypeScript library for transparent process-based proxy of class instances.

Overview

Procxy enables you to run class instances in isolated child processes while interacting with them as if they were local objects. All method calls become async and are transparently forwarded over IPC.

Key Features

• 🎯 Type-Safe: Full TypeScript support with IntelliSense
• ⚡ Fast: <10ms overhead per method call
• 🔄 Event Support: Transparent EventEmitter forwarding
• 🛡️ Error Handling: Complete error propagation with stack traces
• 🧹 Lifecycle: Automatic cleanup with disposable protocol support
• ⚙️ Configurable: Timeouts, retries, custom env/cwd

Quick Start

import { procxy } from 'procxy';

class Calculator {
  add(a: number, b: number) { return a + b; }
}

// Create remote instance
const calc = await procxy(Calculator, './calculator.js');

// Call methods (now async)
const result = await calc.add(5, 3); // 8

// Clean up
await calc.$terminate();

Using Disposables (Recommended)

// Automatic cleanup with await using
await using calc = await procxy(Calculator, './calculator.js');
const result = await calc.add(5, 3);
// Automatically terminated when scope exits

Configuration

Type Alias	Description
ProcxyOptions	Configuration for the procxy() function.
SerializationMode	Serialization mode for IPC messages exchanged between parent and child processes.

Core

Name	Description
Procxy	The proxy type returned by procxy() — a transparent async mirror of a remote class instance.
procxy	Main function to create a process-based proxy for a class instance.

Errors

Class	Description
ChildCrashedError	Thrown when the child process exits or is killed while the proxy is active.
ModuleResolutionError	Thrown when procxy cannot determine the file path of the class's module.
OptionsValidationError	Thrown when a value in ProcxyOptions fails validation before the child process is spawned.
ProcxyError	Base class for all errors thrown by Procxy.
SerializationError	Thrown when a constructor argument, method argument, or return value cannot be serialized across the IPC boundary.
TimeoutError	Thrown when a proxied method call or the INIT handshake exceeds the configured timeout.

Other

Name	Description
ErrorInfo	Error information serialized in Response messages. Preserves error message, stack trace, name, and optional code.
EventMessage	Event message sent from child to parent for EventEmitter events. Forwards events emitted in child to listeners in parent.
HandleAck	Handle acknowledgment sent from child to parent after handle is received.
HandleMessage	Handle transmission message sent from parent to child. Notifies child that a handle (socket, server, file descriptor) is being sent. The actual handle is passed separately via Node.js child.send(message, handle).
InitMessage	Initialization message sent from parent to child on startup. Contains module path, class name, constructor arguments, and serialization mode.
Request	Method invocation request sent from parent to child. Includes unique ID for request/response correlation.
Response	Method invocation response sent from child to parent. Either contains return value (RESULT) or error information (ERROR).
ChildToParentMessage	Union type of all IPC messages sent from child to parent.
ParentToChildMessage	Union type of all IPC messages sent from parent to child.

Runtime Utilities

Function	Description
isAdvancedMode	Runtime utilities for working with Procxy instances.
isHandleSupported	Runtime utilities for working with Procxy instances.
isProcxy	Runtime utilities for working with Procxy instances.

Serialization

Name	Description
V8Serializable	Union of all types that survive Node.js V8 structured-clone serialization across an IPC boundary.
sanitizeForV8	Strip non-V8-serializable properties from a value, returning a deep-cloned plain version.
sanitizeForV8Array	Apply sanitizeForV8 to each element of an array, returning a new sanitized array.

Type Utilities

Type Alias	Description
ChangeProcxyMode	Produce a new Procxy type identical to P except with a different serialization mode.
GetProcxyLifecycleMethods	Extract the lifecycle method and property names from a Procxy type.
GetProcxyMethods	Extract the union of user-defined method names available on a Procxy type.
GetProcxyMode	Extract the serialization mode from a Procxy type.
HasHandleSupport	Conditional type that resolves to true when P has $sendHandle support.
IsProcxy	Conditional type that resolves to true when P is a Procxy type.
IsProcxyIsomorphic	Conditional type that resolves to true when T <-> Procxy<T> form a consistent isomorphism.
ProcxyIsomorphism	Describes the bidirectional type mapping between T and Procxy<T>.
ToggleProcxyHandles	Produce a new Procxy type identical to P except with a different SupportHandles flag.
UnwrapProcxy	Extract the original type T from Procxy<T, Mode, SupportHandles>.
VerifyIsomorphism	Compile-time assertion that T round-trips through Procxy<T> without loss.

Types

Type Alias	Description
IsProcxiable	Conditional type that resolves to true when T can cross the IPC boundary in the given mode.
MaybeProxy	A value that is either the original type T or a Procxy<T> proxy for it.
PassableHandle	Union of OS-level handle types that can be transferred to the child process via $sendHandle.
Procxiable	The serializable type constraint for a given IPC mode.
Procxify	Extract only the serializable, non-method properties from a type — the "data shape" of a class.
SerializableConstructorArgs	Constrain constructor argument types to be serializable under the given mode.