tywrap 0.2.1 → 0.4.0

package/src/runtime/worker-pool.ts

@@ -39,6 +39,13 @@ export interface WorkerPoolOptions {
    * Use this for per-worker warmup (e.g., importing modules, running setup).
    */
   onWorkerReady?: (worker: PooledWorker) => Promise<void>;
+
+  /**
+   * Optional callback used only for background replacement workers after a
+   * fatal timeout/crash. This lets callers publish a replacement only after it
+   * is proven ready, without charging hidden work to normal request startup.
+   */
+  onReplacementWorkerReady?: (worker: PooledWorker) => Promise<void>;
 }
 
 /**
@@ -99,8 +106,12 @@ interface QueuedWaiter {
  * ```
  */
 export class WorkerPool extends BoundedContext {
-  private readonly options: Omit<Required<WorkerPoolOptions>, 'onWorkerReady'> & {
+  private readonly options: Omit<
+    Required<WorkerPoolOptions>,
+    'onWorkerReady' | 'onReplacementWorkerReady'
+  > & {
     onWorkerReady?: (worker: PooledWorker) => Promise<void>;
+    onReplacementWorkerReady?: (worker: PooledWorker) => Promise<void>;
   };
   private readonly workers: PooledWorker[] = [];
   private readonly waitQueue: QueuedWaiter[] = [];
@@ -135,6 +146,7 @@ export class WorkerPool extends BoundedContext {
       queueTimeoutMs: options.queueTimeoutMs ?? 30000,
       maxConcurrentPerWorker: options.maxConcurrentPerWorker ?? 1,
       onWorkerReady: options.onWorkerReady,
+      onReplacementWorkerReady: options.onReplacementWorkerReady,
     };
   }
 
@@ -150,13 +162,7 @@ export class WorkerPool extends BoundedContext {
    */
   protected async doInit(): Promise<void> {
     // Pre-spawn minimum workers if configured
-    if (this.options.minWorkers > 0) {
-      const spawns: Promise<PooledWorker>[] = [];
-      for (let i = 0; i < this.options.minWorkers; i++) {
-        spawns.push(this.createWorker());
-      }
-      await Promise.all(spawns);
-    }
+    await this.fillToMinimumWorkers();
   }
 
   /**
@@ -212,7 +218,7 @@ export class WorkerPool extends BoundedContext {
    */
   async acquire(): Promise<PooledWorker> {
     // Check for disposed state
-    if (this.isDisposed) {
+    if (this.isDisposed || this.state === 'disposing') {
       throw new BridgeExecutionError('Pool has been disposed');
     }
 
@@ -231,7 +237,12 @@ export class WorkerPool extends BoundedContext {
       this.pendingCreations++;
       try {
         const newWorker = await this.createWorker();
+        if (this.isShuttingDown()) {
+          this.removeWorker(newWorker);
+          throw new BridgeExecutionError('Pool has been disposed');
+        }
         newWorker.inFlightCount++;
+        this.publishAvailableWorker(newWorker);
         return newWorker;
       } finally {
         this.pendingCreations--;
@@ -258,16 +269,7 @@ export class WorkerPool extends BoundedContext {
 
     // Decrement in-flight count (minimum 0)
     worker.inFlightCount = Math.max(0, worker.inFlightCount - 1);
-
-    // If there are waiters and this worker has capacity, fulfill the first waiter
-    if (this.waitQueue.length > 0 && worker.inFlightCount < this.options.maxConcurrentPerWorker) {
-      const waiter = this.waitQueue.shift();
-      if (waiter) {
-        clearTimeout(waiter.timer);
-        worker.inFlightCount++;
-        waiter.resolve(worker);
-      }
-    }
+    this.publishAvailableWorker(worker);
   }
 
   /**
@@ -347,6 +349,9 @@ export class WorkerPool extends BoundedContext {
       worker.transport.dispose().catch(() => {
         // Ignore disposal errors for dead workers
       });
+      if (this.state === 'ready') {
+        this.scheduleReplacementWorker();
+      }
     }
   }
 
@@ -386,13 +391,89 @@ export class WorkerPool extends BoundedContext {
     return this.workers.find(w => w.inFlightCount < this.options.maxConcurrentPerWorker);
   }
 
+  private getMinimumWorkerDeficit(): number {
+    return Math.max(0, this.options.minWorkers - (this.workers.length + this.pendingCreations));
+  }
+
+  private isShuttingDown(): boolean {
+    return this.isDisposed || this.state === 'disposing';
+  }
+
+  private async fillToMinimumWorkers(): Promise<void> {
+    await this.spawnWorkers(this.getMinimumWorkerDeficit());
+  }
+
+  private async spawnWorkers(count: number): Promise<void> {
+    if (count === 0) {
+      return;
+    }
+    this.pendingCreations += count;
+    try {
+      await Promise.all(Array.from({ length: count }, () => this.spawnWorkerToPool()));
+    } finally {
+      this.pendingCreations = Math.max(0, this.pendingCreations - count);
+    }
+  }
+
+  /**
+   * Replace a removed worker in the background so the next caller does not pay
+   * the full worker cold-start penalty after a timeout or crash.
+   */
+  private scheduleReplacementWorker(): void {
+    if (this.state !== 'ready') {
+      return;
+    }
+    if (this.workers.length + this.pendingCreations >= this.options.maxWorkers) {
+      return;
+    }
+
+    this.pendingCreations++;
+    const replacementReady = this.options.onReplacementWorkerReady ?? this.options.onWorkerReady;
+    this.spawnWorkerToPool(replacementReady)
+      .catch(() => {
+        // Ignore background replacement failures. A later acquire() can retry.
+      })
+      .finally(() => {
+        this.pendingCreations = Math.max(0, this.pendingCreations - 1);
+      });
+  }
+
+  private async spawnWorkerToPool(onWorkerReady = this.options.onWorkerReady): Promise<void> {
+    if (this.isShuttingDown()) {
+      return;
+    }
+
+    const worker = await this.createWorker(onWorkerReady);
+    if (this.isShuttingDown()) {
+      this.removeWorker(worker);
+      return;
+    }
+
+    this.publishAvailableWorker(worker);
+  }
+
+  private publishAvailableWorker(worker: PooledWorker): void {
+    while (
+      this.waitQueue.length > 0 &&
+      worker.inFlightCount < this.options.maxConcurrentPerWorker
+    ) {
+      const waiter = this.waitQueue.shift();
+      if (!waiter) {
+        return;
+      }
+      clearTimeout(waiter.timer);
+      worker.inFlightCount++;
+      waiter.resolve(worker);
+    }
+  }
+
   /**
    * Create a new worker and add it to the pool.
    *
    * If onWorkerReady is configured, calls it after the transport is initialized.
    * This is useful for per-worker warmup (importing modules, running setup).
    */
-  private async createWorker(): Promise<PooledWorker> {
+  private async createWorker(onWorkerReady = this.options.onWorkerReady): Promise<PooledWorker> {
     const transport = this.options.createTransport();
 
     // Initialize the transport
@@ -403,13 +484,28 @@ export class WorkerPool extends BoundedContext {
       inFlightCount: 0,
     };
 
-    this.workers.push(worker);
+    try {
+      // Call onWorkerReady callback if provided
+      if (onWorkerReady) {
+        await onWorkerReady(worker);
+      }
+    } catch (error) {
+      // Ensure partially initialized workers do not leak when warmup fails.
+      await transport.dispose().catch(() => {
+        // Ignore disposal failures during warmup failure handling.
+      });
+      throw error;
+    }
 
-    // Call onWorkerReady callback if provided
-    if (this.options.onWorkerReady) {
-      await this.options.onWorkerReady(worker);
+    if (this.state === 'disposing' || this.state === 'disposed') {
+      await transport.dispose().catch(() => {
+        // Ignore disposal failures if the pool was torn down mid-creation.
+      });
+      throw new BridgeExecutionError('Pool disposed during worker creation');
     }
 
+    this.workers.push(worker);
+
     return worker;
   }
 

package/src/types/global.d.ts

@@ -8,13 +8,20 @@ declare namespace DenoTypes {
     deno: string;
   }
 
+  interface CommandOptions {
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+  }
+
   interface DenoGlobal {
     version: Version;
     readTextFile(path: string): Promise<string>;
     writeTextFile(path: string, content: string): Promise<void>;
     Command: new (
       cmd: string,
-      options?: { args?: string[] }
+      options?: CommandOptions
     ) => {
       output(): Promise<{ code: number; stdout: Uint8Array; stderr: Uint8Array }>;
     };
@@ -37,12 +44,15 @@ declare namespace BunTypes {
       options?: {
         stdout?: string;
         stderr?: string;
+        cwd?: string;
+        env?: Record<string, string>;
       }
     ): {
       stdout: ReadableStream;
       stderr: ReadableStream;
       exitCode?: number;
       exited: Promise<void>;
+      kill(signal?: number | string): void;
     };
   }
 }

package/src/types/index.ts

@@ -8,6 +8,7 @@ export interface PythonModule {
   version?: string;
   functions: PythonFunction[];
   classes: PythonClass[];
+  typeAliases?: PythonTypeAlias[];
   imports: PythonImport[];
   exports: string[];
 }
@@ -19,6 +20,7 @@ export interface PythonFunction {
   decorators: string[];
   isAsync: boolean;
   isGenerator: boolean;
+  typeParameters?: PythonGenericParameter[];
   returnType: PythonType;
   parameters: Parameter[];
 }
@@ -31,6 +33,23 @@ export interface PythonClass {
   docstring?: string;
   decorators: string[];
   kind?: 'class' | 'protocol' | 'typed_dict' | 'namedtuple' | 'dataclass' | 'pydantic';
+  typeParameters?: PythonGenericParameter[];
+}
+
+export interface PythonTypeAlias {
+  name: string;
+  type: PythonType;
+  typeParameters?: PythonGenericParameter[];
+}
+
+export type PythonGenericParameterKind = 'typevar' | 'paramspec' | 'typevartuple';
+
+export interface PythonGenericParameter {
+  name: string;
+  kind: PythonGenericParameterKind;
+  bound?: PythonType;
+  constraints?: PythonType[];
+  variance?: 'covariant' | 'contravariant' | 'invariant';
 }
 
 export interface PythonImport {
@@ -47,12 +66,15 @@ export interface Parameter {
   defaultValue?: unknown;
   varArgs: boolean;
   kwArgs: boolean;
+  positionalOnly?: boolean;
+  keywordOnly?: boolean;
 }
 
 export interface Property {
   name: string;
   type: PythonType;
   readonly: boolean;
+  optional?: boolean;
   setter?: boolean;
   getter?: boolean;
 }
@@ -76,6 +98,11 @@ export type PythonType =
   | AnnotatedType
   | CustomType
   | TypeVarType
+  | ParamSpecType
+  | ParamSpecArgsType
+  | ParamSpecKwargsType
+  | TypeVarTupleType
+  | UnpackType
   | FinalType
   | ClassVarType;
 
@@ -103,6 +130,7 @@ export interface OptionalType {
 export interface GenericType {
   kind: 'generic';
   name: string;
+  module?: string;
   typeArgs: PythonType[];
 }
 
@@ -115,6 +143,7 @@ export interface CustomType {
 export interface CallableType {
   kind: 'callable';
   parameters: PythonType[];
+  parameterSpec?: ParamSpecType;
   returnType: PythonType;
 }
 
@@ -137,6 +166,31 @@ export interface TypeVarType {
   variance?: 'covariant' | 'contravariant' | 'invariant';
 }
 
+export interface ParamSpecType {
+  kind: 'paramspec';
+  name: string;
+}
+
+export interface ParamSpecArgsType {
+  kind: 'paramspec_args';
+  name: string;
+}
+
+export interface ParamSpecKwargsType {
+  kind: 'paramspec_kwargs';
+  name: string;
+}
+
+export interface TypeVarTupleType {
+  kind: 'typevartuple';
+  name: string;
+}
+
+export interface UnpackType {
+  kind: 'unpack';
+  type: PythonType;
+}
+
 export interface FinalType {
   kind: 'final';
   type: PythonType;
@@ -242,10 +296,14 @@ export type RuntimeStrategy = 'pyodide' | 'node' | 'http' | 'auto';
 
 export interface TywrapOptions {
   pythonModules: Record<string, PythonModuleConfig>;
+  /**
+   * Additional Python import paths to prepend to PYTHONPATH during code generation
+   * and discovery (IR extraction). Useful for local modules not installed in site-packages.
+   */
+  pythonImportPath?: string[];
   output: OutputConfig;
   runtime: RuntimeConfig;
   performance: PerformanceConfig;
-  development: DevelopmentConfig;
   types?: TypeMappingConfig;
   debug?: boolean;
 }
@@ -255,9 +313,12 @@ export interface PythonModuleConfig {
   runtime: RuntimeStrategy;
   functions?: string[];
   classes?: string[];
+  /** Exclude specific exports by exact name. */
+  exclude?: string[];
+  /** Exclude exports matching one or more regex patterns (JavaScript RegExp source). */
+  excludePatterns?: string[];
   alias?: string;
   typeHints: 'strict' | 'loose' | 'ignore';
-  watch?: boolean;
 }
 
 export interface OutputConfig {
@@ -297,12 +358,6 @@ export interface PerformanceConfig {
   compression: 'auto' | 'gzip' | 'brotli' | 'none';
 }
 
-export interface DevelopmentConfig {
-  hotReload: boolean;
-  sourceMap: boolean;
-  validation: 'runtime' | 'compile' | 'both' | 'none';
-}
-
 export type TypePreset = 'numpy' | 'pandas' | 'pydantic' | 'stdlib' | 'scipy' | 'torch' | 'sklearn';
 
 export interface TypeMappingConfig {