tywrap 0.1.2 → 0.2.0

package/README.md

@@ -1,12 +1,13 @@
 # tywrap
 
 [![npm version](https://img.shields.io/npm/v/tywrap.svg)](https://www.npmjs.com/package/tywrap)
+[![PyPI version](https://img.shields.io/pypi/v/tywrap-ir.svg)](https://pypi.org/project/tywrap-ir/)
 [![CI](https://github.com/bbopen/tywrap/actions/workflows/ci.yml/badge.svg)](https://github.com/bbopen/tywrap/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 TypeScript wrapper for Python libraries with full type safety.
 
-> **⚠️ Experimental Software (v0.1.2)** - APIs may change between versions. Not recommended for production use until v1.0.0.
+> **⚠️ Experimental Software (v0.2.0)** - APIs may change between versions. Not recommended for production use until v1.0.0.
 
 ## Features
 
@@ -18,14 +19,19 @@ TypeScript wrapper for Python libraries with full type safety.
 ## Requirements
 
 - Node.js 20+ (or Bun 1.1+ / Deno 1.46+)
-- Python 3.10+
+- Python 3.10+ with `tywrap-ir`:
+
+  ```bash
+  pip install tywrap-ir
+  ```
 
 ## Quick Start
 
 ```bash
 npm install tywrap
-npx tywrap init      # Create config (and package.json scripts if present)
-npx tywrap generate  # Generate wrappers
+pip install tywrap-ir  # Python component for code generation
+npx tywrap init        # Create config (and package.json scripts if present)
+npx tywrap generate    # Generate wrappers
 ```
 
 For CI (or to verify a dependency upgrade didn’t change the generated surface):
@@ -149,4 +155,5 @@ MIT © [tywrap contributors](LICENSE)
 
 - [GitHub](https://github.com/bbopen/tywrap)
 - [npm](https://www.npmjs.com/package/tywrap)
+- [PyPI](https://pypi.org/project/tywrap-ir/)
 - [Issues](https://github.com/bbopen/tywrap/issues)

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export { tywrap } from './tywrap.js';
 export { generate } from './tywrap.js';
 export { detectRuntime, isNodejs, isDeno, isBun, isBrowser } from './utils/runtime.js';
 export { decodeValue, decodeValueAsync, autoRegisterArrowDecoder, registerArrowDecoder, clearArrowDecoder, } from './utils/codec.js';
-export declare const VERSION = "0.1.2";
+export declare const VERSION = "0.2.0";
 /**
  * Quick setup function for getting started
  */

package/dist/index.js

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

package/dist/runtime/node.d.ts

@@ -1,35 +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 core?;
-    private readonly options;
+    private processPool;
+    private roundRobinIndex;
+    private cleanupTimer?;
+    private options;
+    private emitter;
     private disposed;
-    private initPromise?;
     private bridgeInfo?;
+    private initPromise?;
+    private stats;
     constructor(options?: NodeBridgeOptions);
     init(): Promise<void>;
+    private doInit;
     getBridgeInfo(options?: {
         refresh?: boolean;
     }): Promise<BridgeInfo>;
@@ -37,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 startProcess;
     private buildEnv;
-    private resetProcess;
     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":"AAAA;;GAEG;AAUH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAa1C,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAoCD,qBAAa,UAAW,SAAQ,aAAa;IAC3C,OAAO,CAAC,KAAK,CAAC,CAAuC;IACrD,OAAO,CAAC,IAAI,CAAC,CAAa;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAC,CAAgB;IACpC,OAAO,CAAC,UAAU,CAAC,CAAa;gBAEpB,OAAO,GAAE,iBAAsB;IAoBrC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBrB,aAAa,CAAC,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAWvE,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,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;IAKP,WAAW,CAAC,CAAC,GAAG,OAAO,EAC3B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC;IAKP,UAAU,CAAC,CAAC,GAAG,OAAO,EAC1B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC;IAKP,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAMhB,IAAI;YAUJ,YAAY;IAwE1B,OAAO,CAAC,QAAQ;IAyChB,OAAO,CAAC,YAAY;YAiBN,iBAAiB;CAKhC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/runtime/node.ts"],"names":[],"mappings":"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"}