@procwire/transport 0.2.0 → 0.3.0

package/dist/reconnect/manager.d.ts

@@ -0,0 +1,110 @@
+/**
+ * ReconnectManager implementation.
+ *
+ * @packageDocumentation
+ * @module Reconnect
+ */
+import { EventEmitter } from "../utils/events.js";
+import type { ReconnectOptions, ReconnectState, ReconnectEventMap, Reconnectable } from "./types.js";
+/**
+ * Manages automatic reconnection with exponential backoff and request queueing.
+ *
+ * The ReconnectManager implements exponential backoff with jitter to handle
+ * transient connection failures. It can optionally queue requests during
+ * reconnection and execute them once the connection is restored.
+ *
+ * @example
+ * ```typescript
+ * const reconnect = new ReconnectManager(dataTransport, {
+ *   initialDelay: 100,
+ *   maxDelay: 30000,
+ *   maxAttempts: 10,
+ * });
+ *
+ * reconnect.on('reconnect:success', ({ attempt }) => {
+ *   console.log(`Reconnected after ${attempt} attempts`);
+ * });
+ *
+ * reconnect.on('reconnect:failed', ({ lastError }) => {
+ *   console.error('Reconnection failed:', lastError);
+ * });
+ *
+ * // When disconnect is detected:
+ * const success = await reconnect.handleDisconnect(error);
+ * if (!success) {
+ *   // Handle permanent failure
+ * }
+ * ```
+ */
+export declare class ReconnectManager extends EventEmitter<ReconnectEventMap> {
+    private readonly options;
+    private readonly target;
+    private readonly requestQueue;
+    private state;
+    private cancelled;
+    /**
+     * Creates a new ReconnectManager.
+     *
+     * @param target - Object that can be reconnected (has connect() method)
+     * @param options - Configuration options (merged with defaults)
+     */
+    constructor(target: Reconnectable, options?: Partial<ReconnectOptions>);
+    /**
+     * Handle unexpected disconnect. Initiates reconnection if enabled.
+     *
+     * @param error - The error that caused the disconnect
+     * @returns Promise that resolves to true if reconnected, false if failed
+     */
+    handleDisconnect(error: Error): Promise<boolean>;
+    /**
+     * Queue a request to be executed after reconnection.
+     * Returns null if not currently reconnecting or queueing is disabled.
+     *
+     * @param method - Method name for logging
+     * @param execute - Function that executes the request
+     * @returns Promise that resolves with request result, or null if not queued
+     */
+    queueRequest<T>(method: string, execute: () => Promise<T>): Promise<T> | null;
+    /**
+     * Get current reconnection state (readonly).
+     */
+    getState(): Readonly<ReconnectState>;
+    /**
+     * Get current options (readonly).
+     */
+    getOptions(): Readonly<Required<ReconnectOptions>>;
+    /**
+     * Check if currently reconnecting.
+     */
+    isReconnecting(): boolean;
+    /**
+     * Cancel ongoing reconnection attempt.
+     * Rejects all queued requests.
+     */
+    cancel(): void;
+    /**
+     * Reset state for restart scenarios.
+     */
+    reset(): void;
+    /**
+     * Calculate delay for current attempt using exponential backoff with jitter.
+     */
+    private calculateDelay;
+    /**
+     * Flush queued requests after successful reconnection.
+     */
+    private flushQueue;
+    /**
+     * Reject all queued requests with given error.
+     */
+    private rejectQueue;
+    /**
+     * Remove a specific request from the queue.
+     */
+    private removeFromQueue;
+    /**
+     * Sleep for specified milliseconds.
+     */
+    private sleep;
+}
+//# sourceMappingURL=manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/reconnect/manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EAEjB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,iBAAiB,CAAC;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IAEpD,OAAO,CAAC,KAAK,CAMX;IAEF,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;;OAKG;gBACS,MAAM,EAAE,aAAa,EAAE,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAM;IAM1E;;;;;OAKG;IACG,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC;IA8DtD;;;;;;;OAOG;IACH,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IA+C7E;;OAEG;IACH,QAAQ,IAAI,QAAQ,CAAC,cAAc,CAAC;IAIpC;;OAEG;IACH,UAAU,IAAI,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAIlD;;OAEG;IACH,cAAc,IAAI,OAAO;IAIzB;;;OAGG;IACH,MAAM,IAAI,IAAI;IASd;;OAEG;IACH,KAAK,IAAI,IAAI;IAYb;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;OAEG;YACW,UAAU;IAiBxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd"}

package/dist/reconnect/manager.js

@@ -0,0 +1,264 @@
+/**
+ * ReconnectManager implementation.
+ *
+ * @packageDocumentation
+ * @module Reconnect
+ */
+import { EventEmitter } from "../utils/events.js";
+import { DEFAULT_RECONNECT_OPTIONS } from "./constants.js";
+/**
+ * Manages automatic reconnection with exponential backoff and request queueing.
+ *
+ * The ReconnectManager implements exponential backoff with jitter to handle
+ * transient connection failures. It can optionally queue requests during
+ * reconnection and execute them once the connection is restored.
+ *
+ * @example
+ * ```typescript
+ * const reconnect = new ReconnectManager(dataTransport, {
+ *   initialDelay: 100,
+ *   maxDelay: 30000,
+ *   maxAttempts: 10,
+ * });
+ *
+ * reconnect.on('reconnect:success', ({ attempt }) => {
+ *   console.log(`Reconnected after ${attempt} attempts`);
+ * });
+ *
+ * reconnect.on('reconnect:failed', ({ lastError }) => {
+ *   console.error('Reconnection failed:', lastError);
+ * });
+ *
+ * // When disconnect is detected:
+ * const success = await reconnect.handleDisconnect(error);
+ * if (!success) {
+ *   // Handle permanent failure
+ * }
+ * ```
+ */
+export class ReconnectManager extends EventEmitter {
+    options;
+    target;
+    requestQueue = [];
+    state = {
+        attempt: 0,
+        isReconnecting: false,
+        reconnectStartedAt: null,
+        queueSize: 0,
+        lastError: null,
+    };
+    cancelled = false;
+    /**
+     * Creates a new ReconnectManager.
+     *
+     * @param target - Object that can be reconnected (has connect() method)
+     * @param options - Configuration options (merged with defaults)
+     */
+    constructor(target, options = {}) {
+        super();
+        this.target = target;
+        this.options = { ...DEFAULT_RECONNECT_OPTIONS, ...options };
+    }
+    /**
+     * Handle unexpected disconnect. Initiates reconnection if enabled.
+     *
+     * @param error - The error that caused the disconnect
+     * @returns Promise that resolves to true if reconnected, false if failed
+     */
+    async handleDisconnect(error) {
+        if (!this.options.enabled || this.state.isReconnecting) {
+            return false;
+        }
+        this.cancelled = false;
+        this.state.isReconnecting = true;
+        this.state.reconnectStartedAt = Date.now();
+        this.state.attempt = 0;
+        this.state.lastError = error;
+        while (this.state.attempt < this.options.maxAttempts && !this.cancelled) {
+            this.state.attempt++;
+            const delay = this.calculateDelay();
+            this.emit("reconnect:attempting", {
+                attempt: this.state.attempt,
+                delay,
+                error: this.state.lastError,
+            });
+            await this.sleep(delay);
+            // Check if cancelled during sleep
+            if (this.cancelled) {
+                break;
+            }
+            try {
+                // Check cancellation again right before connect
+                if (this.cancelled) {
+                    break;
+                }
+                await this.target.connect();
+                const totalTimeMs = Date.now() - this.state.reconnectStartedAt;
+                this.emit("reconnect:success", {
+                    attempt: this.state.attempt,
+                    totalTimeMs,
+                });
+                this.state.isReconnecting = false;
+                await this.flushQueue();
+                return true;
+            }
+            catch (connectError) {
+                this.state.lastError = connectError;
+                // Continue to next attempt
+            }
+        }
+        // Max attempts exceeded or cancelled
+        this.emit("reconnect:failed", {
+            attempts: this.state.attempt,
+            lastError: this.state.lastError,
+        });
+        this.state.isReconnecting = false;
+        this.rejectQueue(this.state.lastError);
+        return false;
+    }
+    /**
+     * Queue a request to be executed after reconnection.
+     * Returns null if not currently reconnecting or queueing is disabled.
+     *
+     * @param method - Method name for logging
+     * @param execute - Function that executes the request
+     * @returns Promise that resolves with request result, or null if not queued
+     */
+    queueRequest(method, execute) {
+        if (!this.state.isReconnecting || !this.options.queueRequests) {
+            return null;
+        }
+        if (this.requestQueue.length >= this.options.maxQueueSize) {
+            throw new Error(`Request queue full (max ${this.options.maxQueueSize}). ` +
+                `Consider increasing maxQueueSize or reducing request rate.`);
+        }
+        return new Promise((resolve, reject) => {
+            const queuedAt = Date.now();
+            const timeoutHandle = setTimeout(() => {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                this.removeFromQueue(request);
+                const waitedMs = Date.now() - queuedAt;
+                this.emit("reconnect:request-timeout", { method, waitedMs });
+                reject(new Error(`Request '${method}' timed out after ${waitedMs}ms waiting for reconnection`));
+            }, this.options.queueTimeout);
+            const request = {
+                method,
+                execute,
+                resolve,
+                reject,
+                queuedAt,
+                timeoutHandle,
+            };
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            this.requestQueue.push(request);
+            this.state.queueSize = this.requestQueue.length;
+            this.emit("reconnect:request-queued", {
+                method,
+                queueSize: this.state.queueSize,
+            });
+        });
+    }
+    /**
+     * Get current reconnection state (readonly).
+     */
+    getState() {
+        return { ...this.state, queueSize: this.requestQueue.length };
+    }
+    /**
+     * Get current options (readonly).
+     */
+    getOptions() {
+        return { ...this.options };
+    }
+    /**
+     * Check if currently reconnecting.
+     */
+    isReconnecting() {
+        return this.state.isReconnecting;
+    }
+    /**
+     * Cancel ongoing reconnection attempt.
+     * Rejects all queued requests.
+     */
+    cancel() {
+        if (!this.state.isReconnecting) {
+            return;
+        }
+        this.cancelled = true;
+        // Note: isReconnecting will be set to false when the loop exits
+    }
+    /**
+     * Reset state for restart scenarios.
+     */
+    reset() {
+        this.cancelled = false;
+        this.rejectQueue(new Error("ReconnectManager reset"));
+        this.state = {
+            attempt: 0,
+            isReconnecting: false,
+            reconnectStartedAt: null,
+            queueSize: 0,
+            lastError: null,
+        };
+    }
+    /**
+     * Calculate delay for current attempt using exponential backoff with jitter.
+     */
+    calculateDelay() {
+        // Exponential backoff: initialDelay * multiplier^(attempt-1)
+        const exponentialDelay = this.options.initialDelay * Math.pow(this.options.multiplier, this.state.attempt - 1);
+        // Cap at maxDelay
+        const cappedDelay = Math.min(exponentialDelay, this.options.maxDelay);
+        // Add jitter: delay * (1 + random(-jitter, +jitter))
+        const jitterRange = cappedDelay * this.options.jitter;
+        const jitter = (Math.random() * 2 - 1) * jitterRange;
+        return Math.round(cappedDelay + jitter);
+    }
+    /**
+     * Flush queued requests after successful reconnection.
+     */
+    async flushQueue() {
+        const queue = [...this.requestQueue];
+        this.requestQueue.length = 0;
+        this.state.queueSize = 0;
+        for (const request of queue) {
+            clearTimeout(request.timeoutHandle);
+            try {
+                const result = await request.execute();
+                request.resolve(result);
+            }
+            catch (error) {
+                request.reject(error);
+            }
+        }
+    }
+    /**
+     * Reject all queued requests with given error.
+     */
+    rejectQueue(error) {
+        const queue = [...this.requestQueue];
+        this.requestQueue.length = 0;
+        this.state.queueSize = 0;
+        for (const request of queue) {
+            clearTimeout(request.timeoutHandle);
+            request.reject(error);
+        }
+    }
+    /**
+     * Remove a specific request from the queue.
+     */
+    removeFromQueue(request) {
+        const index = this.requestQueue.indexOf(request);
+        if (index !== -1) {
+            this.requestQueue.splice(index, 1);
+            this.state.queueSize = this.requestQueue.length;
+        }
+    }
+    /**
+     * Sleep for specified milliseconds.
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/reconnect/manager.js.map

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

package/dist/reconnect/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Auto-reconnect manager types.
+ *
+ * @packageDocumentation
+ * @module Reconnect
+ */
+import type { EventMap } from "../utils/events.js";
+/**
+ * Configuration options for ReconnectManager.
+ */
+export interface ReconnectOptions {
+    /**
+     * Enable auto-reconnect for data channel.
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Initial delay before first retry in milliseconds.
+     * @default 100
+     */
+    initialDelay: number;
+    /**
+     * Maximum delay between retries in milliseconds.
+     * @default 30000
+     */
+    maxDelay: number;
+    /**
+     * Backoff multiplier. Delay doubles each retry by default.
+     * @default 2
+     */
+    multiplier: number;
+    /**
+     * Jitter factor (0-1) to randomize retry timing.
+     * Helps prevent thundering herd when multiple connections retry.
+     * @default 0.1
+     */
+    jitter: number;
+    /**
+     * Maximum number of retry attempts. Use Infinity for unlimited.
+     * @default Infinity
+     */
+    maxAttempts: number;
+    /**
+     * Queue requests while reconnecting instead of failing immediately.
+     * @default true
+     */
+    queueRequests: boolean;
+    /**
+     * Maximum number of requests to queue during reconnect.
+     * @default 100
+     */
+    maxQueueSize: number;
+    /**
+     * Timeout for queued requests in milliseconds.
+     * Requests waiting longer than this will be rejected.
+     * @default 60000
+     */
+    queueTimeout: number;
+}
+/**
+ * Internal state of the ReconnectManager.
+ */
+export interface ReconnectState {
+    /** Current attempt number (1-based) */
+    attempt: number;
+    /** Whether currently attempting to reconnect */
+    isReconnecting: boolean;
+    /** Timestamp when reconnection started */
+    reconnectStartedAt: number | null;
+    /** Number of requests currently queued */
+    queueSize: number;
+    /** Last error that caused disconnect */
+    lastError: Error | null;
+}
+/**
+ * Event map for ReconnectManager events.
+ */
+export interface ReconnectEventMap extends EventMap {
+    /**
+     * Emitted before each reconnection attempt.
+     */
+    "reconnect:attempting": {
+        attempt: number;
+        delay: number;
+        error: Error;
+    };
+    /**
+     * Emitted after successful reconnection.
+     */
+    "reconnect:success": {
+        attempt: number;
+        totalTimeMs: number;
+    };
+    /**
+     * Emitted when max attempts exceeded or unrecoverable error.
+     */
+    "reconnect:failed": {
+        attempts: number;
+        lastError: Error;
+    };
+    /**
+     * Emitted when a request is queued during reconnection.
+     */
+    "reconnect:request-queued": {
+        method: string;
+        queueSize: number;
+    };
+    /**
+     * Emitted when a queued request times out.
+     */
+    "reconnect:request-timeout": {
+        method: string;
+        waitedMs: number;
+    };
+}
+/**
+ * Internal queued request representation.
+ */
+export interface QueuedRequest<T = unknown> {
+    method: string;
+    execute: () => Promise<T>;
+    resolve: (value: T) => void;
+    reject: (error: Error) => void;
+    queuedAt: number;
+    timeoutHandle: ReturnType<typeof setTimeout>;
+}
+/**
+ * Interface for objects that can be reconnected.
+ * Used by ReconnectManager to abstract over different transport types.
+ */
+export interface Reconnectable {
+    /**
+     * Attempt to establish connection.
+     */
+    connect(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/reconnect/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/reconnect/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAEhB,gDAAgD;IAChD,cAAc,EAAE,OAAO,CAAC;IAExB,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAElB,wCAAwC;IACxC,SAAS,EAAE,KAAK,GAAG,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,QAAQ;IACjD;;OAEG;IACH,sBAAsB,EAAE;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,KAAK,CAAC;KACd,CAAC;IAEF;;OAEG;IACH,mBAAmB,EAAE;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IAEF;;OAEG;IACH,kBAAkB,EAAE;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,KAAK,CAAC;KAClB,CAAC;IAEF;;OAEG;IACH,0BAA0B,EAAE;QAC1B,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAEF;;OAEG;IACH,2BAA2B,EAAE;QAC3B,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

package/dist/reconnect/types.js

@@ -0,0 +1,8 @@
+/**
+ * Auto-reconnect manager types.
+ *
+ * @packageDocumentation
+ * @module Reconnect
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/reconnect/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/reconnect/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/resilience/handle.d.ts

@@ -0,0 +1,112 @@
+/**
+ * ResilientProcessHandle implementation.
+ *
+ * Wraps a ProcessHandle with heartbeat monitoring, auto-reconnect,
+ * and graceful shutdown capabilities.
+ *
+ * @packageDocumentation
+ * @module Resilience
+ */
+import type { ProcessHandle, ProcessState } from "../process/types.js";
+import type { Channel } from "../channel/types.js";
+import type { Unsubscribe } from "../utils/disposables.js";
+import type { ShutdownReason } from "../protocol/reserved-types.js";
+import type { IResilientProcessHandle, ResilientProcessEvents, ResilientProcessOptions } from "./types.js";
+/**
+ * Default resilient process options.
+ *
+ * Note: Reconnect is disabled by default for ProcessHandle because stdio-based
+ * transports cannot be reconnected. See createReconnectable() for details.
+ */
+export declare const DEFAULT_RESILIENT_OPTIONS: Required<ResilientProcessOptions>;
+/**
+ * A process handle with resilience features.
+ *
+ * Combines heartbeat monitoring, auto-reconnect, and graceful shutdown
+ * with a standard ProcessHandle.
+ *
+ * @example
+ * ```typescript
+ * const resilientHandle = new ResilientProcessHandle(processHandle, {
+ *   heartbeat: { intervalMs: 5000, timeoutMs: 1000, maxMissed: 3 },
+ *   reconnect: { maxAttempts: 5, initialDelay: 100 },
+ *   shutdown: { gracefulTimeoutMs: 5000 },
+ * });
+ *
+ * resilientHandle.on('heartbeatDead', () => {
+ *   console.log('Worker is unresponsive');
+ * });
+ *
+ * resilientHandle.on('reconnected', ({ attempt }) => {
+ *   console.log(`Reconnected after ${attempt} attempts`);
+ * });
+ *
+ * resilientHandle.start();
+ *
+ * // Later
+ * await resilientHandle.shutdown('user_requested');
+ * ```
+ */
+export declare class ResilientProcessHandle implements IResilientProcessHandle {
+    private readonly _handle;
+    private readonly events;
+    private heartbeatManager;
+    private reconnectManager;
+    private shutdownManager;
+    private readonly handleEventSubscriptions;
+    private readonly resilienceSubscriptions;
+    private _isHealthy;
+    private killFn;
+    /**
+     * Creates a new ResilientProcessHandle.
+     *
+     * @param handle - The underlying ProcessHandle
+     * @param options - Resilience configuration options
+     * @param killFn - Function to kill the process (injected for testability)
+     */
+    constructor(handle: ProcessHandle, options?: ResilientProcessOptions, killFn?: (signal?: string) => void);
+    get id(): string;
+    get pid(): number | null;
+    get state(): ProcessState;
+    get isHealthy(): boolean;
+    get isReconnecting(): boolean;
+    get controlChannel(): Channel;
+    get dataChannel(): Channel | null;
+    get handle(): ProcessHandle;
+    /**
+     * Sends a request, optionally queueing during reconnection.
+     * Successful requests signal activity to the heartbeat manager (implicit heartbeat).
+     */
+    request(method: string, params?: unknown, timeout?: number): Promise<unknown>;
+    notify(method: string, params?: unknown): Promise<void>;
+    requestViaData(method: string, params?: unknown, timeout?: number): Promise<unknown>;
+    /**
+     * Initiates graceful shutdown of the process.
+     */
+    shutdown(reason?: ShutdownReason): Promise<void>;
+    close(): Promise<void>;
+    on<K extends keyof ResilientProcessEvents>(event: K, handler: (data: ResilientProcessEvents[K]) => void): Unsubscribe;
+    /**
+     * Starts resilience features.
+     */
+    start(): void;
+    /**
+     * Stops resilience features.
+     * Note: Base handle event forwarding continues after stop().
+     */
+    stop(): void;
+    private setupHeartbeatListeners;
+    private setupReconnectListeners;
+    private setupShutdownListeners;
+    private setupHandleEventForwarding;
+    private setupHeartbeatPongListener;
+    /**
+     * Force kills the process with SIGKILL.
+     */
+    private forceKill;
+    /**
+     * Cleanup all subscriptions (called by close()).
+     */
+    private cleanupAllSubscriptions;
+}
+//# sourceMappingURL=handle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../../src/resilience/handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAuB,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAGzF,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AA4DpB;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,uBAAuB,CAIvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,sBAAuB,YAAW,uBAAuB;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;IAErE,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,eAAe,CAAgC;IAEvD,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAqB;IAC9D,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAqB;IAC7D,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,MAAM,CAA4C;IAE1D;;;;;;OAMG;gBAED,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,uBAA4B,EACrC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI;IAyCpC,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,IAAI,GAAG,IAAI,MAAM,GAAG,IAAI,CAEvB;IAED,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,IAAI,WAAW,IAAI,OAAO,GAAG,IAAI,CAEhC;IAED,IAAI,MAAM,IAAI,aAAa,CAE1B;IAED;;;OAGG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB7E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO1F;;OAEG;IACG,QAAQ,CAAC,MAAM,GAAE,cAAiC,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BlE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,EAAE,CAAC,CAAC,SAAS,MAAM,sBAAsB,EACvC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,GACjD,WAAW;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;;OAGG;IACH,IAAI,IAAI,IAAI;IAaZ,OAAO,CAAC,uBAAuB;IAkB/B,OAAO,CAAC,uBAAuB;IAgB/B,OAAO,CAAC,sBAAsB;IAgB9B,OAAO,CAAC,0BAA0B;IAgBlC,OAAO,CAAC,0BAA0B;IAsBlC;;OAEG;IACH,OAAO,CAAC,SAAS;IAYjB;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAWhC"}