tywrap 0.1.1 → 0.2.0

package/dist/index.js

@@ -18,9 +18,9 @@ export { tywrap } from './tywrap.js';
 export { generate } from './tywrap.js';
 // Runtime detection utilities
 export { detectRuntime, isNodejs, isDeno, isBun, isBrowser } from './utils/runtime.js';
-export { decodeValue, decodeValueAsync, registerArrowDecoder, clearArrowDecoder, } from './utils/codec.js';
+export { decodeValue, decodeValueAsync, autoRegisterArrowDecoder, registerArrowDecoder, clearArrowDecoder, } from './utils/codec.js';
 // Version info
-export const VERSION = '0.1.1';
+export const VERSION = '0.2.0';
 /**
  * Quick setup function for getting started
  */

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE5F,2BAA2B;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAsC/C,WAAW;AACX,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,8BAA8B;AAC9B,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B,eAAe;AACf,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B;;GAEG;AACH,iCAAiC;AACjC,eAAe,MAAM,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE5F,2BAA2B;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAsC/C,WAAW;AACX,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,8BAA8B;AAC9B,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B,eAAe;AACf,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B;;GAEG;AACH,iCAAiC;AACjC,eAAe,MAAM,CAAC"}

package/dist/runtime/bridge-core.d.ts

@@ -0,0 +1,64 @@
+import { BridgeProtocolError, BridgeTimeoutError } from './errors.js';
+export type RpcMethod = 'call' | 'instantiate' | 'call_method' | 'dispose_instance' | 'meta';
+export interface RpcRequest {
+    id: number;
+    protocol: string;
+    method: RpcMethod;
+    params: unknown;
+}
+export interface RpcResponse<T = unknown> {
+    id: number;
+    protocol: string;
+    result?: T;
+    error?: {
+        type: string;
+        message: string;
+        traceback?: string;
+    };
+}
+export interface BridgeCoreTransport {
+    write: (data: string) => void;
+}
+export interface BridgeCoreOptions {
+    timeoutMs: number;
+    maxLineLength?: number;
+    maxStderrBytes?: number;
+    protocol?: string;
+    protocolVersion?: number;
+    decodeValue?: (value: unknown) => Promise<unknown>;
+    onFatalError?: (error: BridgeProtocolError) => void;
+    onTimeout?: (error: BridgeTimeoutError) => void;
+}
+export declare class BridgeCore {
+    private readonly transport;
+    private readonly options;
+    private readonly timedOutRequests;
+    private readonly pending;
+    private nextId;
+    private stdoutBuffer;
+    private stderrBuffer;
+    private protocolError;
+    constructor(transport: BridgeCoreTransport, options: BridgeCoreOptions);
+    getStderrTail(): string;
+    getPendingCount(): number;
+    clear(): void;
+    send<T>(payload: Omit<RpcRequest, 'id' | 'protocol'>): Promise<T>;
+    handleStdoutData(chunk: Buffer | string): void;
+    handleStderrData(chunk: Buffer | string): void;
+    handleProcessExit(): void;
+    handleProcessError(err: Error): void;
+    private handleResponseLine;
+    private errorFrom;
+    private normalizeErrorPayload;
+    private failRequest;
+    private rejectAll;
+    private handleProtocolError;
+    private handleFatalError;
+}
+export declare function validateBridgeInfo(info: unknown): void;
+export declare function getPathKey(...envs: Array<Record<string, string | undefined>>): string;
+export declare function ensurePythonEncoding(env: NodeJS.ProcessEnv): void;
+export declare function ensureJsonFallback(env: NodeJS.ProcessEnv, enabled: boolean): void;
+export declare function getMaxLineLengthFromEnv(env: NodeJS.ProcessEnv): number | undefined;
+export declare function normalizeEnv(baseEnv: Record<string, string | undefined>, overrides: Record<string, string | undefined>): NodeJS.ProcessEnv;
+//# sourceMappingURL=bridge-core.d.ts.map

package/dist/runtime/bridge-core.d.ts.map

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

package/dist/runtime/bridge-core.js

@@ -0,0 +1,344 @@
+import { BridgeExecutionError, BridgeProtocolError, BridgeTimeoutError } from './errors.js';
+import { TYWRAP_PROTOCOL, TYWRAP_PROTOCOL_VERSION } from './protocol.js';
+import { TimedOutRequestTracker } from './timed-out-request-tracker.js';
+// Why: keep stdout lines bounded to prevent unbounded memory growth on malformed output.
+const DEFAULT_MAX_LINE_LENGTH = 1024 * 1024; // 1MB
+// Why: keep stderr snapshots small but useful for diagnostics on timeouts/exits.
+const DEFAULT_MAX_STDERR_BYTES = 8 * 1024; // 8KB
+const defaultDecodeValue = async (value) => value;
+const noop = () => { };
+const ANSI_ESCAPE_RE = new RegExp('\\u001b\\[[0-9;]*[A-Za-z]', 'g');
+const CONTROL_CHARS_RE = new RegExp('[\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F\\u0080-\\u009F]', 'g');
+const sanitizeStderr = (value) => value.replace(ANSI_ESCAPE_RE, '').replace(CONTROL_CHARS_RE, '');
+export class BridgeCore {
+    transport;
+    options;
+    timedOutRequests;
+    pending = new Map();
+    nextId = 1;
+    stdoutBuffer = '';
+    stderrBuffer = '';
+    protocolError = false;
+    constructor(transport, options) {
+        this.transport = transport;
+        this.options = {
+            timeoutMs: options.timeoutMs,
+            maxLineLength: options.maxLineLength ?? DEFAULT_MAX_LINE_LENGTH,
+            maxStderrBytes: options.maxStderrBytes ?? DEFAULT_MAX_STDERR_BYTES,
+            protocol: options.protocol ?? TYWRAP_PROTOCOL,
+            protocolVersion: options.protocolVersion ?? TYWRAP_PROTOCOL_VERSION,
+            decodeValue: options.decodeValue ?? defaultDecodeValue,
+            onFatalError: options.onFatalError ?? noop,
+            onTimeout: options.onTimeout ?? noop,
+        };
+        this.timedOutRequests = new TimedOutRequestTracker({
+            ttlMs: Math.max(1000, this.options.timeoutMs * 2),
+        });
+    }
+    getStderrTail() {
+        return this.stderrBuffer.trim();
+    }
+    getPendingCount() {
+        return this.pending.size;
+    }
+    clear() {
+        for (const [, pending] of this.pending) {
+            if (pending.timer) {
+                clearTimeout(pending.timer);
+            }
+        }
+        this.pending.clear();
+        this.timedOutRequests.clear();
+        this.stdoutBuffer = '';
+        this.stderrBuffer = '';
+        this.protocolError = false;
+    }
+    async send(payload) {
+        const id = this.nextId++;
+        const message = { ...payload, id, protocol: this.options.protocol };
+        let text;
+        try {
+            text = JSON.stringify(message);
+        }
+        catch (err) {
+            throw new BridgeProtocolError(`Failed to serialize request: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        let timer;
+        const promise = new Promise((resolve, reject) => {
+            timer = setTimeout(() => {
+                this.pending.delete(id);
+                this.timedOutRequests.mark(id);
+                const stderrTail = this.getStderrTail();
+                const msg = stderrTail
+                    ? `Python call timed out. Recent stderr from Python:\n${stderrTail}`
+                    : 'Python call timed out';
+                const timeoutError = new BridgeTimeoutError(msg);
+                reject(timeoutError);
+                this.options.onTimeout(timeoutError);
+            }, this.options.timeoutMs);
+            const resolveWrapped = (value) => {
+                resolve(value);
+            };
+            this.pending.set(id, { resolve: resolveWrapped, reject, timer });
+        });
+        try {
+            this.transport.write(`${text}\n`);
+        }
+        catch (err) {
+            const failure = new BridgeProtocolError(`IPC failure: ${err instanceof Error ? err.message : String(err)}`);
+            this.failRequest(id, failure);
+            this.handleFatalError(failure);
+        }
+        return promise;
+    }
+    handleStdoutData(chunk) {
+        this.stdoutBuffer += chunk.toString();
+        if (this.stdoutBuffer.length > this.options.maxLineLength &&
+            !this.stdoutBuffer.includes('\n')) {
+            const snippet = this.stdoutBuffer.slice(0, this.options.maxLineLength);
+            this.stdoutBuffer = '';
+            this.handleProtocolError(`Response line exceeded ${this.options.maxLineLength} bytes`, snippet);
+            return;
+        }
+        let idx;
+        while ((idx = this.stdoutBuffer.indexOf('\n')) !== -1) {
+            const line = this.stdoutBuffer.slice(0, idx);
+            this.stdoutBuffer = this.stdoutBuffer.slice(idx + 1);
+            if (!line.trim()) {
+                continue;
+            }
+            if (line.length > this.options.maxLineLength) {
+                const snippet = line.slice(0, this.options.maxLineLength);
+                this.handleProtocolError(`Response line exceeded ${this.options.maxLineLength} bytes`, snippet);
+                return;
+            }
+            this.handleResponseLine(line);
+        }
+    }
+    handleStderrData(chunk) {
+        try {
+            this.stderrBuffer += sanitizeStderr(chunk.toString());
+            if (this.stderrBuffer.length > this.options.maxStderrBytes) {
+                this.stderrBuffer = this.stderrBuffer.slice(this.stderrBuffer.length - this.options.maxStderrBytes);
+            }
+        }
+        catch {
+            // Ignore stderr buffering errors
+        }
+    }
+    handleProcessExit() {
+        const stderrTail = this.getStderrTail();
+        const msg = stderrTail
+            ? `Python process exited. Stderr:\n${stderrTail}`
+            : 'Python process exited';
+        this.rejectAll(new BridgeProtocolError(msg));
+    }
+    handleProcessError(err) {
+        const msg = `Python process error: ${err.message}`;
+        const error = new BridgeProtocolError(msg);
+        this.rejectAll(error);
+        this.handleFatalError(error);
+    }
+    handleResponseLine(line) {
+        let msg;
+        try {
+            const parsed = JSON.parse(line);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                this.handleProtocolError('Invalid response payload', line);
+                return;
+            }
+            msg = parsed;
+        }
+        catch (err) {
+            const parseMessage = err instanceof Error ? err.message : String(err);
+            this.handleProtocolError(`Invalid JSON: ${parseMessage}`, line);
+            return;
+        }
+        if (msg.protocol !== this.options.protocol) {
+            this.handleProtocolError(`Invalid protocol. Expected ${this.options.protocol} but received ${String(msg.protocol)}`, line);
+            return;
+        }
+        if (typeof msg.id !== 'number') {
+            this.handleProtocolError('Invalid response id', line);
+            return;
+        }
+        const pending = this.pending.get(msg.id);
+        if (!pending) {
+            if (this.timedOutRequests.consume(msg.id)) {
+                return;
+            }
+            this.handleProtocolError(`Unexpected response id ${msg.id}`, line);
+            return;
+        }
+        this.pending.delete(msg.id);
+        if (pending.timer) {
+            clearTimeout(pending.timer);
+        }
+        if ('error' in msg) {
+            const errorPayload = this.normalizeErrorPayload(msg.error);
+            pending.reject(this.errorFrom(errorPayload));
+            return;
+        }
+        Promise.resolve(this.options.decodeValue(msg.result))
+            .then(decoded => pending.resolve(decoded))
+            .catch(err => {
+            pending.reject(new BridgeProtocolError(`Failed to decode Python response: ${err instanceof Error ? err.message : String(err)}`));
+        });
+    }
+    errorFrom(err) {
+        const error = new BridgeExecutionError(`${err.type}: ${err.message}`);
+        error.traceback = err.traceback;
+        return error;
+    }
+    normalizeErrorPayload(err) {
+        if (err && typeof err === 'object') {
+            const candidate = err;
+            if (typeof candidate.type === 'string' && typeof candidate.message === 'string') {
+                const normalized = {
+                    type: candidate.type,
+                    message: candidate.message,
+                };
+                if (typeof candidate.traceback === 'string') {
+                    normalized.traceback = candidate.traceback;
+                }
+                return normalized;
+            }
+        }
+        return { type: 'UnknownError', message: String(err) };
+    }
+    failRequest(id, error) {
+        const pending = this.pending.get(id);
+        if (!pending) {
+            return;
+        }
+        this.pending.delete(id);
+        if (pending.timer) {
+            clearTimeout(pending.timer);
+        }
+        pending.reject(error);
+    }
+    rejectAll(error) {
+        for (const [, pending] of this.pending) {
+            if (pending.timer) {
+                clearTimeout(pending.timer);
+            }
+            pending.reject(error);
+        }
+        this.pending.clear();
+        this.timedOutRequests.clear();
+    }
+    handleProtocolError(details, line) {
+        if (this.protocolError) {
+            return;
+        }
+        this.protocolError = true;
+        const snippet = line ? (line.length > 500 ? `${line.slice(0, 500)}...` : line) : undefined;
+        const hint = 'Ensure your Python code does not print to stdout and that the bridge outputs only JSON lines.';
+        const msg = snippet
+            ? `Protocol error from Python bridge. ${details}\n${hint}\nOffending line: ${snippet}`
+            : `Protocol error from Python bridge. ${details}\n${hint}`;
+        const error = new BridgeProtocolError(msg);
+        this.rejectAll(error);
+        this.handleFatalError(error);
+    }
+    handleFatalError(error) {
+        try {
+            this.options.onFatalError(error);
+        }
+        catch {
+            // Ignore callback failures
+        }
+    }
+}
+export function validateBridgeInfo(info) {
+    if (!info || typeof info !== 'object') {
+        throw new BridgeProtocolError('Invalid bridge info payload');
+    }
+    const candidate = info;
+    if (candidate.protocol !== TYWRAP_PROTOCOL ||
+        candidate.protocolVersion !== TYWRAP_PROTOCOL_VERSION) {
+        throw new BridgeProtocolError('Invalid bridge info payload');
+    }
+    if (candidate.bridge !== 'python-subprocess') {
+        throw new BridgeProtocolError(`Unexpected bridge identifier: ${candidate.bridge}`);
+    }
+}
+export function getPathKey(...envs) {
+    for (const env of envs) {
+        const key = findPathKey(env);
+        if (key) {
+            return key;
+        }
+    }
+    return 'PATH';
+}
+export function ensurePythonEncoding(env) {
+    if (env.PYTHONUTF8 === undefined || env.PYTHONUTF8 === null || env.PYTHONUTF8 === '') {
+        env.PYTHONUTF8 = '1';
+    }
+    if (env.PYTHONIOENCODING === undefined ||
+        env.PYTHONIOENCODING === null ||
+        env.PYTHONIOENCODING === '') {
+        env.PYTHONIOENCODING = 'UTF-8';
+    }
+}
+export function ensureJsonFallback(env, enabled) {
+    if (enabled && !env.TYWRAP_CODEC_FALLBACK) {
+        env.TYWRAP_CODEC_FALLBACK = 'json';
+    }
+}
+export function getMaxLineLengthFromEnv(env) {
+    const raw = env.TYWRAP_CODEC_MAX_BYTES?.trim();
+    if (!raw) {
+        return undefined;
+    }
+    if (!/^\d+$/.test(raw)) {
+        return undefined;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return undefined;
+    }
+    return parsed;
+}
+export function normalizeEnv(baseEnv, overrides) {
+    // Why: normalize PATH casing (Windows) and drop undefined values to avoid spawn surprises.
+    const overridePathKey = findPathKey(overrides);
+    const basePathKey = findPathKey(baseEnv);
+    const pathKey = basePathKey ?? overridePathKey ?? 'PATH';
+    let pathValue;
+    if (overridePathKey !== null) {
+        // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
+        pathValue = overrides[overridePathKey];
+    }
+    else if (basePathKey) {
+        // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
+        pathValue = baseEnv[basePathKey];
+    }
+    const merged = { ...baseEnv, ...overrides };
+    const result = {};
+    if (pathValue !== undefined) {
+        // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
+        result[pathKey] = pathValue;
+    }
+    for (const [key, value] of Object.entries(merged)) {
+        if (value === undefined) {
+            continue;
+        }
+        if (key.toLowerCase() === 'path') {
+            continue;
+        }
+        // eslint-disable-next-line security/detect-object-injection -- env keys are dynamic by design
+        result[key] = value;
+    }
+    return result;
+}
+function findPathKey(env) {
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === 'path') {
+            return key;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=bridge-core.js.map

package/dist/runtime/bridge-core.js.map

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

package/dist/runtime/node.d.ts

@@ -1,36 +1,115 @@
 /**
- * Node.js runtime bridge (minimal MVP)
+ * Node.js Runtime Bridge with Optional Connection Pooling
+ *
+ * NodeBridge is the unified Node.js runtime bridge that supports both single-process
+ * (correctness-first) and multi-process (pooled) configurations. By default, it runs
+ * in single-process mode for maximum compatibility with the original NodeBridge behavior.
+ *
+ * For high-throughput workloads, configure pooling via minProcesses/maxProcesses options.
  */
 import type { BridgeInfo } from '../types/index.js';
 import { RuntimeBridge } from './base.js';
+/**
+ * Configuration options for NodeBridge.
+ *
+ * By default, NodeBridge runs in single-process mode (minProcesses=1, maxProcesses=1).
+ * For high-throughput workloads, increase these values to enable process pooling.
+ */
 export interface NodeBridgeOptions {
+    /** Minimum number of Python processes to keep alive. Default: 1 */
+    minProcesses?: number;
+    /** Maximum number of Python processes to spawn. Default: 1 (single-process mode) */
+    maxProcesses?: number;
+    /** Time in ms to keep idle processes alive before termination. Default: 300000 (5 min) */
+    maxIdleTime?: number;
+    /** Restart process after this many requests. Default: 1000 */
+    maxRequestsPerProcess?: number;
+    /** Path to Python executable. Auto-detected if not specified. */
     pythonPath?: string;
+    /** Path to python_bridge.py script. Auto-detected if not specified. */
     scriptPath?: string;
+    /** Path to Python virtual environment. */
     virtualEnv?: string;
+    /** Working directory for Python process. Default: process.cwd() */
     cwd?: string;
+    /** Timeout in ms for Python calls. Default: 30000 */
     timeoutMs?: number;
+    /** Maximum line length for JSONL protocol. */
+    maxLineLength?: number;
+    /** Inherit all environment variables from parent process. Default: false */
+    inheritProcessEnv?: boolean;
     /**
      * When true, sets TYWRAP_CODEC_FALLBACK=json for the Python process to prefer JSON encoding
      * for rich types (ndarray/dataframe/series). Default: false for fast-fail on Arrow path issues.
      */
     enableJsonFallback?: boolean;
-    /**
-     * Optional extra environment variables to pass to the Python subprocess.
-     */
+    /** Enable result caching for pure functions. Default: false */
+    enableCache?: boolean;
+    /** Optional extra environment variables to pass to the Python subprocess. */
     env?: Record<string, string | undefined>;
+    /** Commands to run on each process at startup for warming up. */
+    warmupCommands?: Array<{
+        method: string;
+        params: unknown;
+    }>;
+}
+interface BridgeStats {
+    totalRequests: number;
+    totalTime: number;
+    cacheHits: number;
+    poolHits: number;
+    poolMisses: number;
+    processSpawns: number;
+    processDeaths: number;
+    memoryPeak: number;
+    averageTime: number;
+    cacheHitRate: number;
+}
+interface BridgeStatsSnapshot extends BridgeStats {
+    poolSize: number;
+    busyWorkers: number;
+    memoryUsage: NodeJS.MemoryUsage;
+    workerStats: Array<{
+        id: string;
+        requestCount: number;
+        averageTime: number;
+        errorCount: number;
+        busy: boolean;
+        pendingRequests: number;
+    }>;
 }
+/**
+ * Node.js runtime bridge for executing Python code.
+ *
+ * By default, runs in single-process mode for correctness-first behavior.
+ * Configure minProcesses/maxProcesses for process pooling in high-throughput scenarios.
+ *
+ * @example
+ * ```typescript
+ * // Single-process mode (default)
+ * const bridge = new NodeBridge();
+ *
+ * // Multi-process pooling for high throughput
+ * const pooledBridge = new NodeBridge({
+ *   minProcesses: 2,
+ *   maxProcesses: 8,
+ *   enableCache: true,
+ * });
+ * ```
+ */
 export declare class NodeBridge extends RuntimeBridge {
-    private child?;
-    private nextId;
-    private readonly pending;
-    private readonly options;
-    private stderrBuffer;
+    private processPool;
+    private roundRobinIndex;
+    private cleanupTimer?;
+    private options;
+    private emitter;
     private disposed;
-    private protocolError;
-    private initPromise?;
     private bridgeInfo?;
+    private initPromise?;
+    private stats;
     constructor(options?: NodeBridgeOptions);
     init(): Promise<void>;
+    private doInit;
     getBridgeInfo(options?: {
         refresh?: boolean;
     }): Promise<BridgeInfo>;
@@ -38,11 +117,78 @@ export declare class NodeBridge extends RuntimeBridge {
     instantiate<T = unknown>(module: string, className: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
     callMethod<T = unknown>(handle: string, methodName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
     disposeInstance(handle: string): Promise<void>;
+    /**
+     * Execute request with intelligent process selection
+     */
+    private executeRequest;
+    /**
+     * Select optimal worker based on load and performance
+     */
+    private selectOptimalWorker;
+    /**
+     * Wait for any worker to become available
+     */
+    private waitForAvailableWorker;
+    /**
+     * Send request to specific worker
+     */
+    private sendToWorker;
+    private quarantineWorker;
+    /**
+     * Spawn new worker process with optimizations
+     */
+    private spawnProcess;
+    /**
+     * Setup event handlers for worker process
+     */
+    private setupProcessHandlers;
+    /**
+     * Handle worker process exit
+     */
+    private handleWorkerExit;
+    /**
+     * Warm up processes with configured commands
+     */
+    private warmupProcesses;
+    private safeCacheKey;
+    /**
+     * Heuristic to determine if function result should be cached
+     */
+    private isPureFunctionCandidate;
+    /**
+     * Update performance statistics
+     */
+    private updateStats;
+    /**
+     * Get performance statistics
+     */
+    getStats(): BridgeStatsSnapshot;
+    /**
+     * Cleanup idle processes
+     */
+    private cleanup;
+    /**
+     * Gracefully terminate a worker
+     */
+    private terminateWorker;
+    /**
+     * Start cleanup scheduler
+     */
+    private startCleanupScheduler;
+    /**
+     * Dispose all resources
+     */
     dispose(): Promise<void>;
-    private send;
-    private errorFrom;
-    private handleProtocolError;
-    private startProcess;
+    private buildEnv;
     private refreshBridgeInfo;
 }
+/**
+ * @deprecated Use NodeBridge with minProcesses/maxProcesses options instead.
+ * This alias is provided for backward compatibility.
+ */
+export { NodeBridge as OptimizedNodeBridge };
+/**
+ * @deprecated Use NodeBridgeOptions instead.
+ */
+export type { NodeBridgeOptions as ProcessPoolOptions };
 //# sourceMappingURL=node.d.ts.map