tywrap 0.2.0 → 0.3.0

package/dist/runtime/node.d.ts

@@ -1,29 +1,23 @@
 /**
- * Node.js Runtime Bridge with Optional Connection Pooling
+ * Node.js runtime bridge for BridgeProtocol.
  *
- * 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.
+ * NodeBridge extends BridgeProtocol and uses ProcessIO transports with
+ * optional pooling for concurrent Python execution.
  *
- * For high-throughput workloads, configure pooling via minProcesses/maxProcesses options.
+ * @see https://github.com/bbopen/tywrap/issues/149
  */
-import type { BridgeInfo } from '../types/index.js';
-import { RuntimeBridge } from './base.js';
+import { BridgeProtocol } from './bridge-protocol.js';
+import type { CodecOptions } from './safe-codec.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;
+    /** Maximum concurrent requests per process. Default: 10 */
+    maxConcurrentPerProcess?: number;
     /** Path to Python executable. Auto-detected if not specified. */
     pythonPath?: string;
     /** Path to python_bridge.py script. Auto-detected if not specified. */
@@ -34,161 +28,134 @@ export interface NodeBridgeOptions {
     cwd?: string;
     /** Timeout in ms for Python calls. Default: 30000 */
     timeoutMs?: number;
-    /** Maximum line length for JSONL protocol. */
-    maxLineLength?: number;
+    /** Timeout in ms for waiting in pool queue. Default: 30000 */
+    queueTimeoutMs?: 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;
     /** 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>;
+    /** Codec options for validation/serialization */
+    codec?: CodecOptions;
     /** Commands to run on each process at startup for warming up. */
     warmupCommands?: Array<{
+        module: string;
+        functionName: string;
+        args?: unknown[];
+    } | {
         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;
-    }>;
+    /**
+     * @deprecated No longer used. Pool idle time is managed by WorkerPool.
+     */
+    maxIdleTime?: number;
+    /**
+     * @deprecated No longer used. Process restart is managed by ProcessIO.
+     */
+    maxRequestsPerProcess?: number;
+    /**
+     * @deprecated Use codec.bytesHandling option instead.
+     */
+    enableJsonFallback?: boolean;
+    /**
+     * @deprecated Use ProcessIO options instead.
+     */
+    maxLineLength?: 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.
+ * NodeBridge provides subprocess-based Python execution with optional pooling
+ * for high-throughput workloads. By default, it runs in single-process mode.
+ *
+ * Features:
+ * - Single or multi-process execution via process pooling
+ * - Virtual environment support
+ * - Full SafeCodec validation (NaN/Infinity rejection, key validation)
+ * - Automatic Arrow decoding for DataFrames/ndarrays
+ * - Optional result caching for pure functions
+ * - Process warmup commands
  *
  * @example
  * ```typescript
  * // Single-process mode (default)
  * const bridge = new NodeBridge();
+ * await bridge.init();
  *
+ * const result = await bridge.call('math', 'sqrt', [16]);
+ * console.log(result); // 4.0
+ *
+ * await bridge.dispose();
+ * ```
+ *
+ * @example
+ * ```typescript
  * // Multi-process pooling for high throughput
  * const pooledBridge = new NodeBridge({
- *   minProcesses: 2,
- *   maxProcesses: 8,
+ *   maxProcesses: 4,
+ *   maxConcurrentPerProcess: 2,
  *   enableCache: true,
  * });
+ * await pooledBridge.init();
  * ```
  */
-export declare class NodeBridge extends RuntimeBridge {
-    private processPool;
-    private roundRobinIndex;
-    private cleanupTimer?;
-    private options;
-    private emitter;
-    private disposed;
-    private bridgeInfo?;
-    private initPromise?;
-    private stats;
-    constructor(options?: NodeBridgeOptions);
-    init(): Promise<void>;
-    private doInit;
-    getBridgeInfo(options?: {
-        refresh?: boolean;
-    }): Promise<BridgeInfo>;
-    call<T = unknown>(module: string, functionName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
-    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;
+export declare class NodeBridge extends BridgeProtocol {
+    private readonly resolvedOptions;
+    private readonly pooledTransport;
     /**
-     * Send request to specific worker
+     * Create a new NodeBridge instance.
+     *
+     * @param options - Configuration options for the bridge
      */
-    private sendToWorker;
-    private quarantineWorker;
+    constructor(options?: NodeBridgeOptions);
     /**
-     * Spawn new worker process with optimizations
+     * Initialize the bridge.
+     *
+     * Validates the bridge script exists, registers Arrow decoder,
+     * and initializes the transport pool (which runs warmup commands per-worker).
      */
-    private spawnProcess;
+    protected doInit(): Promise<void>;
     /**
-     * Setup event handlers for worker process
+     * Override call() to add optional caching.
      */
-    private setupProcessHandlers;
+    call<T = unknown>(module: string, functionName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
     /**
-     * Handle worker process exit
-     */
-    private handleWorkerExit;
+     * Get current pool statistics.
+     */
+    getPoolStats(): {
+        workerCount: number;
+        queueLength: number;
+        totalInFlight: number;
+    };
+    /**
+     * Get bridge statistics.
+     *
+     * @deprecated Use getPoolStats() instead. This method is provided for
+     * backwards compatibility and returns a subset of the previous stats.
+     */
+    getStats(): {
+        totalRequests: number;
+        totalTime: number;
+        cacheHits: number;
+        poolHits: number;
+        poolMisses: number;
+        processSpawns: number;
+        processDeaths: number;
+        memoryPeak: number;
+        averageTime: number;
+        cacheHitRate: number;
+        poolSize: number;
+        busyWorkers: number;
+    };
     /**
-     * Warm up processes with configured commands
+     * Generate a cache key, returning null if generation fails.
      */
-    private warmupProcesses;
     private safeCacheKey;
     /**
-     * Heuristic to determine if function result should be cached
+     * 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 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

package/dist/runtime/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/runtime/node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/runtime/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,EAAE,cAAc,EAA8B,MAAM,sBAAsB,CAAC;AAIlF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAQpD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,2DAA2D;IAC3D,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B,+DAA+D;IAC/D,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAEzC,iDAAiD;IACjD,KAAK,CAAC,EAAE,YAAY,CAAC;IAErB,iEAAiE;IACjE,cAAc,CAAC,EAAE,KAAK,CACpB;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CACjG,CAAC;IAMF;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAsKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,UAAW,SAAQ,cAAc;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAElD;;;;OAIG;gBACS,OAAO,GAAE,iBAAsB;IAyE3C;;;;;OAKG;cACsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBhD;;OAEG;IACY,IAAI,CAAC,CAAC,GAAG,OAAO,EAC7B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC;IAkCb;;OAEG;IACH,YAAY,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE;IAQnF;;;;;OAKG;IACH,QAAQ,IAAI;QACV,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB;IAwBD;;OAEG;IACH,OAAO,CAAC,YAAY;IAQpB;;OAEG;IACH,OAAO,CAAC,uBAAuB;CA2BhC"}