@procwire/transport 1.0.0

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * @procwire/transport
+ *
+ * Core IPC transport library with zero runtime dependencies.
+ * Provides modular, type-safe building blocks for inter-process communication.
+ *
+ * Architecture layers (bottom to top):
+ * - Transport: Raw byte transfer (stdio, pipes, sockets)
+ * - Framing: Message boundary detection
+ * - Serialization: Object <-> binary conversion
+ * - Protocol: Request/response messaging
+ * - Channel: High-level communication API
+ * - Process: Child process lifecycle management
+ *
+ * @packageDocumentation
+ */
+// Core types
+export * from "./transport/index.js";
+export * from "./framing/index.js";
+export * from "./serialization/index.js";
+export * from "./protocol/index.js";
+export * from "./channel/index.js";
+export * from "./process/index.js";
+// Utilities
+export * from "./utils/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,aAAa;AACb,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AAEnC,YAAY;AACZ,cAAc,kBAAkB,CAAC"}

package/dist/process/handle.d.ts

@@ -0,0 +1,64 @@
+import type { ProcessHandle as IProcessHandle, ProcessHandleEvents, ProcessState } from "./types.js";
+import type { Channel } from "../channel/types.js";
+import type { Unsubscribe } from "../utils/disposables.js";
+/**
+ * Process handle implementation.
+ * Encapsulates a managed process and its communication channels.
+ */
+export declare class ProcessHandle implements IProcessHandle {
+    private readonly _id;
+    private _pid;
+    private _state;
+    private readonly _controlChannel;
+    private readonly _dataChannel;
+    private readonly events;
+    constructor(id: string, pid: number | null, controlChannel: Channel, dataChannel?: Channel | null);
+    get id(): string;
+    get pid(): number | null;
+    get state(): ProcessState;
+    get controlChannel(): Channel;
+    get dataChannel(): Channel | null;
+    /**
+     * Updates process ID.
+     * @internal Used by ProcessManager
+     */
+    setPid(pid: number | null): void;
+    /**
+     * Updates process state and emits state change event.
+     * @internal Used by ProcessManager
+     */
+    setState(newState: ProcessState): void;
+    /**
+     * Sends a request via control channel.
+     */
+    request(method: string, params?: unknown, timeout?: number): Promise<unknown>;
+    /**
+     * Sends a notification via control channel.
+     */
+    notify(method: string, params?: unknown): Promise<void>;
+    /**
+     * Sends a request via data channel.
+     * @throws {Error} if data channel is not available
+     */
+    requestViaData(method: string, params?: unknown, timeout?: number): Promise<unknown>;
+    /**
+     * Closes the handle and its channels.
+     * Does not terminate the process.
+     */
+    close(): Promise<void>;
+    /**
+     * Subscribes to handle events.
+     */
+    on<K extends keyof ProcessHandleEvents>(event: K, handler: (data: ProcessHandleEvents[K]) => void): Unsubscribe;
+    /**
+     * Emits an exit event.
+     * @internal Used by ProcessManager
+     */
+    emitExit(code: number | null, signal: string | null): void;
+    /**
+     * Emits an error event.
+     * @internal Used by ProcessManager
+     */
+    emitError(error: Error): void;
+}
+//# sourceMappingURL=handle.d.ts.map

package/dist/process/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../../src/process/handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,IAAI,cAAc,EAC/B,mBAAmB,EACnB,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG3D;;;GAGG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2C;gBAGhE,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,cAAc,EAAE,OAAO,EACvB,WAAW,GAAE,OAAO,GAAG,IAAW;IASpC,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,IAAI,GAAG,IAAI,MAAM,GAAG,IAAI,CAEvB;IAED,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,IAAI,WAAW,IAAI,OAAO,GAAG,IAAI,CAEhC;IAED;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIhC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAUtC;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAInF;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D;;;OAGG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC;IAOnB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;OAEG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,mBAAmB,EACpC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,GAC9C,WAAW;IAId;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI1D;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAG9B"}

package/dist/process/handle.js

@@ -0,0 +1,107 @@
+import { EventEmitter } from "../utils/events.js";
+/**
+ * Process handle implementation.
+ * Encapsulates a managed process and its communication channels.
+ */
+export class ProcessHandle {
+    _id;
+    _pid;
+    _state;
+    _controlChannel;
+    _dataChannel;
+    events = new EventEmitter();
+    constructor(id, pid, controlChannel, dataChannel = null) {
+        this._id = id;
+        this._pid = pid;
+        this._state = "starting";
+        this._controlChannel = controlChannel;
+        this._dataChannel = dataChannel;
+    }
+    get id() {
+        return this._id;
+    }
+    get pid() {
+        return this._pid;
+    }
+    get state() {
+        return this._state;
+    }
+    get controlChannel() {
+        return this._controlChannel;
+    }
+    get dataChannel() {
+        return this._dataChannel;
+    }
+    /**
+     * Updates process ID.
+     * @internal Used by ProcessManager
+     */
+    setPid(pid) {
+        this._pid = pid;
+    }
+    /**
+     * Updates process state and emits state change event.
+     * @internal Used by ProcessManager
+     */
+    setState(newState) {
+        if (newState === this._state) {
+            return;
+        }
+        const from = this._state;
+        this._state = newState;
+        this.events.emit("stateChange", { from, to: newState });
+    }
+    /**
+     * Sends a request via control channel.
+     */
+    async request(method, params, timeout) {
+        return this._controlChannel.request(method, params, timeout);
+    }
+    /**
+     * Sends a notification via control channel.
+     */
+    async notify(method, params) {
+        return this._controlChannel.notify(method, params);
+    }
+    /**
+     * Sends a request via data channel.
+     * @throws {Error} if data channel is not available
+     */
+    async requestViaData(method, params, timeout) {
+        if (!this._dataChannel) {
+            throw new Error(`Data channel not available for process '${this._id}'`);
+        }
+        return this._dataChannel.request(method, params, timeout);
+    }
+    /**
+     * Closes the handle and its channels.
+     * Does not terminate the process.
+     */
+    async close() {
+        await Promise.all([
+            this._controlChannel.close(),
+            this._dataChannel ? this._dataChannel.close() : Promise.resolve(),
+        ]);
+    }
+    /**
+     * Subscribes to handle events.
+     */
+    on(event, handler) {
+        return this.events.on(event, handler);
+    }
+    /**
+     * Emits an exit event.
+     * @internal Used by ProcessManager
+     */
+    emitExit(code, signal) {
+        this.events.emit("exit", { code, signal });
+    }
+    /**
+     * Emits an error event.
+     * @internal Used by ProcessManager
+     */
+    emitError(error) {
+        this.events.emit("error", error);
+    }
+}
+//# sourceMappingURL=handle.js.map

package/dist/process/handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.js","sourceRoot":"","sources":["../../src/process/handle.ts"],"names":[],"mappings":"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"}

package/dist/process/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Process management layer - manages child process lifecycle with restart policies.
+ *
+ * Key features:
+ * - Spawn and manage multiple child processes
+ * - Dual-channel architecture: control (stdio) + data (pipe/socket)
+ * - Automatic restart with exponential backoff
+ * - Graceful termination with force-kill fallback
+ * - Event-driven lifecycle management
+ *
+ * @example
+ * ```ts
+ * const manager = new ProcessManager({
+ *   restartPolicy: {
+ *     enabled: true,
+ *     maxRestarts: 3,
+ *     backoffMs: 1000,
+ *     maxBackoffMs: 30000
+ *   }
+ * });
+ *
+ * const handle = await manager.spawn('worker-1', {
+ *   executablePath: 'node',
+ *   args: ['worker.js'],
+ *   dataChannel: { enabled: true }
+ * });
+ *
+ * const result = await handle.request('compute', { task: 'heavy' });
+ * await manager.terminate('worker-1');
+ * ```
+ *
+ * @module process
+ */
+export { ProcessManager } from "./manager.js";
+export { ProcessHandle } from "./handle.js";
+export type { ProcessState, RestartPolicy, ChannelConfig, DataChannelConfig, SpawnOptions, ProcessManagerConfig, ProcessManagerEvents, ProcessHandleEvents, ProcessHandle as IProcessHandle, ProcessManager as IProcessManager, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/process/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/process/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,YAAY,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,IAAI,cAAc,EAC/B,cAAc,IAAI,eAAe,GAClC,MAAM,YAAY,CAAC"}

package/dist/process/index.js

@@ -0,0 +1,37 @@
+/**
+ * Process management layer - manages child process lifecycle with restart policies.
+ *
+ * Key features:
+ * - Spawn and manage multiple child processes
+ * - Dual-channel architecture: control (stdio) + data (pipe/socket)
+ * - Automatic restart with exponential backoff
+ * - Graceful termination with force-kill fallback
+ * - Event-driven lifecycle management
+ *
+ * @example
+ * ```ts
+ * const manager = new ProcessManager({
+ *   restartPolicy: {
+ *     enabled: true,
+ *     maxRestarts: 3,
+ *     backoffMs: 1000,
+ *     maxBackoffMs: 30000
+ *   }
+ * });
+ *
+ * const handle = await manager.spawn('worker-1', {
+ *   executablePath: 'node',
+ *   args: ['worker.js'],
+ *   dataChannel: { enabled: true }
+ * });
+ *
+ * const result = await handle.request('compute', { task: 'heavy' });
+ * await manager.terminate('worker-1');
+ * ```
+ *
+ * @module process
+ */
+// Core classes
+export { ProcessManager } from "./manager.js";
+export { ProcessHandle } from "./handle.js";
+//# sourceMappingURL=index.js.map

package/dist/process/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/process/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,eAAe;AACf,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/process/manager.d.ts

@@ -0,0 +1,58 @@
+import type { ProcessManager as IProcessManager, ProcessManagerConfig, ProcessManagerEvents, SpawnOptions } from "./types.js";
+import type { ProcessHandle as IProcessHandle } from "./types.js";
+import type { Unsubscribe } from "../utils/disposables.js";
+/**
+ * Process manager implementation.
+ * Manages the lifecycle of multiple child processes with restart capability.
+ */
+export declare class ProcessManager implements IProcessManager {
+    private readonly config;
+    private readonly processes;
+    private readonly events;
+    constructor(config?: ProcessManagerConfig);
+    /**
+     * Spawns a new managed process.
+     */
+    spawn(id: string, options: SpawnOptions): Promise<IProcessHandle>;
+    /**
+     * Terminates a managed process.
+     */
+    terminate(id: string): Promise<void>;
+    /**
+     * Terminates all managed processes.
+     */
+    terminateAll(): Promise<void>;
+    /**
+     * Gets a process handle by ID.
+     */
+    getHandle(id: string): IProcessHandle | null;
+    /**
+     * Checks if a process is running.
+     */
+    isRunning(id: string): boolean;
+    /**
+     * Subscribes to manager events.
+     */
+    on<K extends keyof ProcessManagerEvents>(event: K, handler: (data: ProcessManagerEvents[K]) => void): Unsubscribe;
+    /**
+     * Handles process exit event.
+     */
+    private handleProcessExit;
+    /**
+     * Restarts a crashed process.
+     */
+    private restartProcess;
+    /**
+     * Cleans up process resources.
+     */
+    private cleanupProcess;
+    /**
+     * Builds control channel from stdio transport.
+     */
+    private buildControlChannel;
+    /**
+     * Builds data channel from pipe transport.
+     */
+    private buildDataChannel;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/process/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/process/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,IAAI,eAAe,EACjC,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EAGb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,aAAa,IAAI,cAAc,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AA8B3D;;;GAGG;AACH,qBAAa,cAAe,YAAW,eAAe;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;gBAEvD,MAAM,GAAE,oBAAyB;IAc7C;;OAEG;IACG,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAsFvE;;OAEG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe1C;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAQnC;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAI5C;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAK9B;;OAEG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,oBAAoB,EACrC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,IAAI,GAC/C,WAAW;IAId;;OAEG;YACW,iBAAiB;IAiE/B;;OAEG;YACW,cAAc;IA+E5B;;OAEG;YACW,cAAc;IAiB5B;;OAEG;YACW,mBAAmB;IA6CjC;;OAEG;YACW,gBAAgB;CA2C/B"}