tywrap 0.3.0 → 0.5.0

package/src/index.ts

@@ -9,14 +9,14 @@ import { tywrap } from './tywrap.js';
 
 export type { TywrapConfig, ResolvedTywrapConfig } from './config/index.js';
 export { defineConfig, resolveConfig } from './config/index.js';
-// BoundedContext - unified abstraction for cross-boundary concerns
+// DisposableBase - lifecycle/resource base for cross-boundary components
 export {
-  BoundedContext,
+  DisposableBase,
   type ContextState,
   type ExecuteOptions,
 } from './runtime/bounded-context.js';
-// BridgeProtocol - unified BoundedContext + SafeCodec + Transport
-export { BridgeProtocol, type BridgeProtocolOptions } from './runtime/bridge-protocol.js';
+// RpcClient - the single correlated-RPC client (codec + transport), held by bridges
+export { RpcClient, type RpcClientOptions } from './runtime/rpc-client.js';
 // SafeCodec - validation and serialization for JS<->Python boundary
 export { SafeCodec, type CodecOptions } from './runtime/safe-codec.js';
 // Transport - abstract I/O channel interface
@@ -63,7 +63,7 @@ export {
 } from './runtime/validators.js';
 
 /**
- * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
+ * @deprecated Use DisposableBase instead. RuntimeBridge will be removed in the next major version.
  */
 export { RuntimeBridge } from './runtime/base.js';
 
@@ -77,7 +77,7 @@ export {
 } from './runtime/errors.js';
 export { getRuntimeBridge, setRuntimeBridge, clearRuntimeBridge } from './runtime/index.js';
 
-// Runtime-specific exports (Bridges using new BridgeProtocol architecture)
+// Runtime-specific exports (Bridge facades that HOLD an RpcClient)
 export { NodeBridge, type NodeBridgeOptions } from './runtime/node.js';
 export { PyodideBridge, type PyodideBridgeOptions } from './runtime/pyodide.js';
 export { HttpBridge, type HttpBridgeOptions } from './runtime/http.js';
@@ -121,7 +121,6 @@ export type {
   NodeConfig,
   HttpConfig,
   PerformanceConfig,
-  DevelopmentConfig,
   TypeMappingConfig,
   TypePreset,
   BridgeInfo,
@@ -135,6 +134,7 @@ export type {
 // Main API
 export { tywrap } from './tywrap.js';
 export { generate } from './tywrap.js';
+export type { GenerateFailure, GenerateResult, GenerateRunOptions } from './tywrap.js';
 
 // Runtime detection utilities
 export { detectRuntime, isNodejs, isDeno, isBun, isBrowser } from './utils/runtime.js';

package/src/runtime/base.ts

@@ -1,24 +1,24 @@
 /**
  * Base runtime bridge
  *
- * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
+ * @deprecated Use DisposableBase instead. RuntimeBridge will be removed in the next major version.
  */
 
-import { BoundedContext } from './bounded-context.js';
+import { DisposableBase } from './bounded-context.js';
 
 /**
- * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
+ * @deprecated Use DisposableBase instead. RuntimeBridge will be removed in the next major version.
  *
- * All bridges now extend BoundedContext which provides:
+ * All bridges now build on DisposableBase which provides:
  * - Lifecycle management (init/dispose state machine)
  * - Validation helpers
  * - Error classification
  * - Bounded execution (timeout, retry)
  * - Resource ownership tracking
  *
- * @see BoundedContext
+ * @see DisposableBase
  */
-export abstract class RuntimeBridge extends BoundedContext {}
+export abstract class RuntimeBridge extends DisposableBase {}
 
-// Re-export BoundedContext for backwards compatibility
-export { BoundedContext };
+// Re-export DisposableBase for backwards compatibility
+export { DisposableBase };

package/src/runtime/bounded-context.ts

@@ -1,19 +1,20 @@
 /**
- * BoundedContext - Unified abstraction for cross-boundary concerns.
+ * DisposableBase - Lifecycle-and-resource base for cross-boundary components.
  *
- * This base class provides consistent handling of:
- * - Lifecycle management (init/dispose state machine)
- * - Validation helpers
- * - Error classification
- * - Bounded execution (timeout, retry)
- * - Resource ownership tracking
+ * Provides ONLY: init/dispose state machine, validation helpers, error
+ * classification, bounded execution (timeout/retry/abort), and resource
+ * ownership tracking. It carries ZERO RPC methods by design — the
+ * cross-boundary RPC contract (call/instantiate/callMethod/disposeInstance)
+ * is PythonRuntime, implemented only by the bridge facades, never by a base
+ * class or a transport. This separation is what keeps transports (ProcessIO,
+ * PooledTransport, WorkerPool, PyodideIO) and RpcClient from having to stub
+ * RPC methods they do not implement.
  *
- * All runtime bridges (NodeBridge, PyodideBridge, HttpBridge) extend this class.
+ * Reused by RpcClient and all transports.
  *
  * @see https://github.com/bbopen/tywrap/issues/149
  */
 
-import type { RuntimeExecution } from '../types/index.js';
 import {
   BridgeDisposedError,
   BridgeError,
@@ -36,7 +37,7 @@ import {
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Lifecycle states for a BoundedContext.
+ * Lifecycle states for a DisposableBase.
  *
  * State transitions:
  * - idle → initializing → ready (on successful init)
@@ -63,16 +64,15 @@ export interface ExecuteOptions<T = unknown> {
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
-// BOUNDED CONTEXT BASE CLASS
+// DISPOSABLE BASE CLASS
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Abstract base class for runtime bridges with unified boundary management.
- *
- * Provides lifecycle management, validation, error classification,
- * bounded execution, and resource tracking.
+ * Abstract lifecycle/resource base. Provides lifecycle management, validation,
+ * error classification, bounded execution, and resource tracking — and nothing
+ * about RPC. See the file header for the DisposableBase vs PythonRuntime split.
  */
-export abstract class BoundedContext implements RuntimeExecution {
+export abstract class DisposableBase {
   // ═══════════════════════════════════════════════════════════════════════════
   // STATE
   // ═══════════════════════════════════════════════════════════════════════════
@@ -103,7 +103,7 @@ export abstract class BoundedContext implements RuntimeExecution {
   }
 
   // ═══════════════════════════════════════════════════════════════════════════
-  // LIFECYCLE (addresses #142, #148)
+  // LIFECYCLE
   // ═══════════════════════════════════════════════════════════════════════════
 
   /**
@@ -566,43 +566,4 @@ export abstract class BoundedContext implements RuntimeExecution {
   protected get resourceCount(): number {
     return this._resources.size;
   }
-
-  // ═══════════════════════════════════════════════════════════════════════════
-  // ABSTRACT METHODS (RuntimeExecution interface)
-  // ═══════════════════════════════════════════════════════════════════════════
-
-  /**
-   * Call a Python function.
-   */
-  abstract call<T = unknown>(
-    module: string,
-    functionName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T>;
-
-  /**
-   * Instantiate a Python class.
-   */
-  abstract instantiate<T = unknown>(
-    module: string,
-    className: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T>;
-
-  /**
-   * Call a method on a Python instance.
-   */
-  abstract callMethod<T = unknown>(
-    handle: string,
-    methodName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T>;
-
-  /**
-   * Dispose a Python instance.
-   */
-  abstract disposeInstance(handle: string): Promise<void>;
 }

package/src/runtime/http.ts

@@ -1,16 +1,20 @@
 /**
- * HTTP runtime bridge for BridgeProtocol.
+ * HTTP runtime bridge.
  *
- * HttpBridge extends BridgeProtocol and uses HttpIO transport for
- * stateless HTTP POST-based communication with a Python server.
+ * HttpBridge is a thin facade: it extends DisposableBase (lifecycle/resources)
+ * and implements PythonRuntime by HOLDING an RpcClient over an HttpIO transport
+ * for stateless HTTP POST-based communication with a Python server.
  *
  * @see https://github.com/bbopen/tywrap/issues/149
  */
 
-import { BridgeProtocol, type BridgeProtocolOptions } from './bridge-protocol.js';
+import type { PythonRuntime, BridgeInfo } from '../types/index.js';
+import { autoRegisterArrowDecoder } from '../utils/codec.js';
+
+import { DisposableBase } from './bounded-context.js';
+import { RpcClient, type GetBridgeInfoOptions } from './rpc-client.js';
 import { HttpIO } from './http-io.js';
 import type { CodecOptions } from './safe-codec.js';
-import { autoRegisterArrowDecoder } from '../utils/codec.js';
 
 // =============================================================================
 // OPTIONS
@@ -61,33 +65,101 @@ export interface HttpBridgeOptions {
  * await bridge.dispose();
  * ```
  */
-export class HttpBridge extends BridgeProtocol {
+export class HttpBridge extends DisposableBase implements PythonRuntime {
+  private readonly rpc: RpcClient;
+
   /**
    * Create a new HttpBridge instance.
    *
    * @param options - Configuration options for the bridge
    */
   constructor(options: HttpBridgeOptions) {
-    // Create HTTP transport
+    super();
+
     const transport = new HttpIO({
       baseURL: options.baseURL,
       headers: options.headers,
       defaultTimeoutMs: options.timeoutMs,
     });
 
-    // Initialize BridgeProtocol with transport and codec options
-    const protocolOptions: BridgeProtocolOptions = {
+    this.rpc = new RpcClient({
       transport,
       codec: options.codec,
       defaultTimeoutMs: options.timeoutMs,
-    };
-
-    super(protocolOptions);
+    });
+    // One disposal chain: facade -> rpc -> transport.
+    this.trackResource(this.rpc);
   }
 
+  // ===========================================================================
+  // LIFECYCLE
+  // ===========================================================================
+
   protected async doInit(): Promise<void> {
     // Best-effort: keep apache-arrow optional and avoid breaking non-Node runtimes.
     await autoRegisterArrowDecoder();
-    await super.doInit();
+    await this.rpc.init();
+  }
+
+  /**
+   * No facade-specific teardown: the RpcClient (and its transport) is tracked
+   * as a resource and disposed automatically by DisposableBase.
+   */
+  protected async doDispose(): Promise<void> {
+    // Intentionally empty; tracked resources handle disposal.
+  }
+
+  // ===========================================================================
+  // RPC METHODS (delegate to the held RpcClient)
+  // ===========================================================================
+
+  async call<T = unknown>(
+    module: string,
+    functionName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    await this.ensureReady();
+    return this.rpc.call<T>(module, functionName, args, kwargs);
+  }
+
+  async instantiate<T = unknown>(
+    module: string,
+    className: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    await this.ensureReady();
+    return this.rpc.instantiate<T>(module, className, args, kwargs);
+  }
+
+  async callMethod<T = unknown>(
+    handle: string,
+    methodName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    await this.ensureReady();
+    return this.rpc.callMethod<T>(handle, methodName, args, kwargs);
+  }
+
+  async disposeInstance(handle: string): Promise<void> {
+    await this.ensureReady();
+    return this.rpc.disposeInstance(handle);
+  }
+
+  async getBridgeInfo(options?: GetBridgeInfoOptions): Promise<BridgeInfo> {
+    await this.ensureReady();
+    return this.rpc.getBridgeInfo(options);
+  }
+
+  /**
+   * Ensure the facade is initialized before delegating an RPC, replicating the
+   * auto-init that the bounded execute path provided pre-composition.
+   */
+  private async ensureReady(): Promise<void> {
+    if (!this.isReady) {
+      await this.init();
+    }
   }
 }