tywrap 0.2.0 → 0.3.0

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

@@ -0,0 +1,184 @@
+/**
+ * BridgeProtocol - Unified abstraction for JS<->Python communication.
+ *
+ * Combines BoundedContext + SafeCodec + Transport into a single base class
+ * that handles all cross-boundary concerns:
+ * - Lifecycle management (init/dispose state machine)
+ * - Request/response encoding with validation
+ * - Transport-agnostic message passing
+ * - Bounded execution (timeout, retry, abort)
+ *
+ * Subclasses (NodeBridge, HttpBridge, PyodideBridge) only need to:
+ * 1. Create their transport in their constructor
+ * 2. Pass it to super() via BridgeProtocolOptions
+ * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+import type { BridgeInfo } from '../types/index.js';
+import { BoundedContext, type ExecuteOptions } from './bounded-context.js';
+import { SafeCodec, type CodecOptions } from './safe-codec.js';
+import { type Transport, type ProtocolMessage } from './transport.js';
+export interface GetBridgeInfoOptions {
+    /**
+     * If true, bypasses the cached info and queries the bridge again.
+     * This is useful when you want up-to-date instance counts or diagnostics.
+     */
+    refresh?: boolean;
+}
+/**
+ * Configuration options for BridgeProtocol.
+ */
+export interface BridgeProtocolOptions {
+    /** The transport to use for communication */
+    transport: Transport;
+    /** Codec options for validation/serialization */
+    codec?: CodecOptions;
+    /** Default timeout for operations in ms. Default: 30000 (30s) */
+    defaultTimeoutMs?: number;
+}
+/**
+ * BridgeProtocol combines BoundedContext + SafeCodec + Transport
+ * into a unified abstraction for all JS<->Python communication.
+ *
+ * This class provides:
+ * - Automatic transport lifecycle management
+ * - Request encoding with guardrails (special float rejection, key validation)
+ * - Response decoding with Arrow support
+ * - Full RuntimeExecution interface implementation
+ *
+ * Subclasses should:
+ * 1. Create their transport in their constructor
+ * 2. Pass it to super() via BridgeProtocolOptions
+ * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ *
+ * @example
+ * ```typescript
+ * class NodeBridge extends BridgeProtocol {
+ *   constructor(options: NodeBridgeOptions) {
+ *     const transport = new ProcessIO(options);
+ *     super({ transport, defaultTimeoutMs: options.timeout });
+ *   }
+ * }
+ * ```
+ */
+export declare class BridgeProtocol extends BoundedContext {
+    /** Codec instance for validation and serialization */
+    protected readonly codec: SafeCodec;
+    /** Transport instance for message passing */
+    protected readonly transport: Transport;
+    /** Default timeout for operations in milliseconds */
+    protected readonly defaultTimeoutMs: number;
+    /** Counter for generating unique request IDs */
+    private requestId;
+    /** Cached bridge diagnostics info (populated by getBridgeInfo). */
+    private bridgeInfoCache?;
+    /**
+     * Create a new BridgeProtocol instance.
+     *
+     * @param options - Configuration options including transport and codec settings
+     */
+    constructor(options: BridgeProtocolOptions);
+    /**
+     * Initialize the protocol.
+     *
+     * Initializes the underlying transport. Subclasses can override this
+     * to add additional initialization logic, but must call super.doInit().
+     */
+    protected doInit(): Promise<void>;
+    /**
+     * Dispose the protocol.
+     *
+     * The transport is tracked as a resource and will be disposed automatically
+     * by BoundedContext. Subclasses can override this to add additional cleanup,
+     * but should not need to dispose the transport manually.
+     */
+    protected doDispose(): Promise<void>;
+    /**
+     * Send a protocol message and receive a typed response.
+     *
+     * This method:
+     * 1. Generates a unique request ID
+     * 2. Encodes the request with validation (special float rejection, etc.)
+     * 3. Sends via transport with timeout/abort support
+     * 4. Decodes and validates the response
+     *
+     * @param message - The protocol message (without id field)
+     * @param options - Execution options (timeout, retries, validation)
+     * @returns The typed response from Python
+     *
+     * @throws BridgeProtocolError if encoding/decoding fails
+     * @throws BridgeExecutionError if Python returns an error
+     * @throws BridgeTimeoutError if the operation times out
+     */
+    protected sendMessage<T>(message: Omit<ProtocolMessage, 'id' | 'protocol'>, options?: ExecuteOptions<T>): Promise<T>;
+    /**
+     * Async version that uses decodeResponseAsync for Arrow support.
+     *
+     * Use this method when the response may contain encoded DataFrames,
+     * ndarrays, or other Arrow-encoded data structures.
+     *
+     * @param message - The protocol message (without id field)
+     * @param options - Execution options (timeout, retries, validation)
+     * @returns The typed response from Python with Arrow decoding applied
+     *
+     * @throws BridgeProtocolError if encoding/decoding fails
+     * @throws BridgeExecutionError if Python returns an error
+     * @throws BridgeTimeoutError if the operation times out
+     */
+    protected sendMessageAsync<T>(message: Omit<ProtocolMessage, 'id' | 'protocol'>, options?: ExecuteOptions<T>): Promise<T>;
+    /**
+     * Generate a unique request ID.
+     *
+     * Returns a monotonically increasing integer that ensures uniqueness
+     * within a process lifetime.
+     */
+    private generateId;
+    /**
+     * Call a Python function.
+     *
+     * @param module - Python module path (e.g., 'numpy', 'mypackage.submodule')
+     * @param functionName - Function name to call
+     * @param args - Positional arguments
+     * @param kwargs - Keyword arguments
+     * @returns The function result
+     */
+    call<T = unknown>(module: string, functionName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Instantiate a Python class.
+     *
+     * @param module - Python module path containing the class
+     * @param className - Class name to instantiate
+     * @param args - Positional constructor arguments
+     * @param kwargs - Keyword constructor arguments
+     * @returns A handle to the created instance
+     */
+    instantiate<T = unknown>(module: string, className: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Call a method on a Python instance.
+     *
+     * @param handle - Instance handle returned from instantiate()
+     * @param methodName - Method name to call
+     * @param args - Positional arguments
+     * @param kwargs - Keyword arguments
+     * @returns The method result
+     */
+    callMethod<T = unknown>(handle: string, methodName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Dispose a Python instance.
+     *
+     * Releases the instance handle on the Python side, allowing
+     * the object to be garbage collected.
+     *
+     * @param handle - Instance handle to dispose
+     */
+    disposeInstance(handle: string): Promise<void>;
+    /**
+     * Fetch bridge diagnostics and feature availability.
+     *
+     * The Python bridge supports a `meta` method that returns protocol and environment info
+     * (including optional codec availability and current instance count).
+     */
+    getBridgeInfo(options?: GetBridgeInfoOptions): Promise<BridgeInfo>;
+}
+//# sourceMappingURL=bridge-protocol.d.ts.map

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

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

package/dist/runtime/bridge-protocol.js

@@ -0,0 +1,344 @@
+/**
+ * BridgeProtocol - Unified abstraction for JS<->Python communication.
+ *
+ * Combines BoundedContext + SafeCodec + Transport into a single base class
+ * that handles all cross-boundary concerns:
+ * - Lifecycle management (init/dispose state machine)
+ * - Request/response encoding with validation
+ * - Transport-agnostic message passing
+ * - Bounded execution (timeout, retry, abort)
+ *
+ * Subclasses (NodeBridge, HttpBridge, PyodideBridge) only need to:
+ * 1. Create their transport in their constructor
+ * 2. Pass it to super() via BridgeProtocolOptions
+ * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+import { BoundedContext } from './bounded-context.js';
+import { BridgeProtocolError } from './errors.js';
+import { SafeCodec } from './safe-codec.js';
+import { TYWRAP_PROTOCOL_VERSION } from './protocol.js';
+import { PROTOCOL_ID } from './transport.js';
+function validateBridgeInfoPayload(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        const kind = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+        throw new BridgeProtocolError(`Invalid bridge info payload: expected object, got ${kind}`);
+    }
+    const formatValue = (val) => {
+        try {
+            const serialized = JSON.stringify(val);
+            return serialized ?? String(val);
+        }
+        catch {
+            return String(val);
+        }
+    };
+    const obj = value;
+    const protocol = obj.protocol;
+    if (protocol !== PROTOCOL_ID) {
+        throw new BridgeProtocolError(`Invalid bridge info payload: protocol expected "${PROTOCOL_ID}", got ${formatValue(protocol)}`);
+    }
+    const protocolVersion = obj.protocolVersion;
+    if (protocolVersion !== TYWRAP_PROTOCOL_VERSION) {
+        throw new BridgeProtocolError(`Invalid bridge info payload: protocolVersion expected ${TYWRAP_PROTOCOL_VERSION}, got ${formatValue(protocolVersion)}`);
+    }
+    const bridge = obj.bridge;
+    if (bridge !== 'python-subprocess') {
+        throw new BridgeProtocolError(`Invalid bridge info payload: bridge expected "python-subprocess", got ${formatValue(bridge)}`);
+    }
+    const pythonVersion = obj.pythonVersion;
+    if (typeof pythonVersion !== 'string' || pythonVersion.length === 0) {
+        throw new BridgeProtocolError(`Invalid bridge info payload: pythonVersion expected non-empty string, got ${formatValue(pythonVersion)}`);
+    }
+    const pid = obj.pid;
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
+        throw new BridgeProtocolError(`Invalid bridge info payload: pid expected positive integer, got ${formatValue(pid)}`);
+    }
+    const codecFallback = obj.codecFallback;
+    if (codecFallback !== 'json' && codecFallback !== 'none') {
+        throw new BridgeProtocolError(`Invalid bridge info payload: codecFallback expected "json" or "none", got ${formatValue(codecFallback)}`);
+    }
+    const arrowAvailable = obj.arrowAvailable;
+    if (typeof arrowAvailable !== 'boolean') {
+        throw new BridgeProtocolError(`Invalid bridge info payload: arrowAvailable expected boolean, got ${formatValue(arrowAvailable)}`);
+    }
+    const scipyAvailable = obj.scipyAvailable;
+    if (typeof scipyAvailable !== 'boolean') {
+        throw new BridgeProtocolError(`Invalid bridge info payload: scipyAvailable expected boolean, got ${formatValue(scipyAvailable)}`);
+    }
+    const torchAvailable = obj.torchAvailable;
+    if (typeof torchAvailable !== 'boolean') {
+        throw new BridgeProtocolError(`Invalid bridge info payload: torchAvailable expected boolean, got ${formatValue(torchAvailable)}`);
+    }
+    const sklearnAvailable = obj.sklearnAvailable;
+    if (typeof sklearnAvailable !== 'boolean') {
+        throw new BridgeProtocolError(`Invalid bridge info payload: sklearnAvailable expected boolean, got ${formatValue(sklearnAvailable)}`);
+    }
+    const instances = obj.instances;
+    if (typeof instances !== 'number' || !Number.isInteger(instances) || instances < 0) {
+        throw new BridgeProtocolError(`Invalid bridge info payload: instances expected non-negative integer, got ${formatValue(instances)}`);
+    }
+    return {
+        protocol: PROTOCOL_ID,
+        protocolVersion: TYWRAP_PROTOCOL_VERSION,
+        bridge: 'python-subprocess',
+        pythonVersion,
+        pid,
+        codecFallback,
+        arrowAvailable,
+        scipyAvailable,
+        torchAvailable,
+        sklearnAvailable,
+        instances,
+    };
+}
+// =============================================================================
+// BRIDGE PROTOCOL BASE CLASS
+// =============================================================================
+/**
+ * BridgeProtocol combines BoundedContext + SafeCodec + Transport
+ * into a unified abstraction for all JS<->Python communication.
+ *
+ * This class provides:
+ * - Automatic transport lifecycle management
+ * - Request encoding with guardrails (special float rejection, key validation)
+ * - Response decoding with Arrow support
+ * - Full RuntimeExecution interface implementation
+ *
+ * Subclasses should:
+ * 1. Create their transport in their constructor
+ * 2. Pass it to super() via BridgeProtocolOptions
+ * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ *
+ * @example
+ * ```typescript
+ * class NodeBridge extends BridgeProtocol {
+ *   constructor(options: NodeBridgeOptions) {
+ *     const transport = new ProcessIO(options);
+ *     super({ transport, defaultTimeoutMs: options.timeout });
+ *   }
+ * }
+ * ```
+ */
+export class BridgeProtocol extends BoundedContext {
+    /** Codec instance for validation and serialization */
+    codec;
+    /** Transport instance for message passing */
+    transport;
+    /** Default timeout for operations in milliseconds */
+    defaultTimeoutMs;
+    /** Counter for generating unique request IDs */
+    requestId = 0;
+    /** Cached bridge diagnostics info (populated by getBridgeInfo). */
+    bridgeInfoCache;
+    /**
+     * Create a new BridgeProtocol instance.
+     *
+     * @param options - Configuration options including transport and codec settings
+     */
+    constructor(options) {
+        super();
+        this.codec = new SafeCodec(options.codec);
+        this.transport = options.transport;
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? 30000;
+        // Track the transport for automatic cleanup during dispose
+        this.trackResource(this.transport);
+    }
+    // ===========================================================================
+    // LIFECYCLE
+    // ===========================================================================
+    /**
+     * Initialize the protocol.
+     *
+     * Initializes the underlying transport. Subclasses can override this
+     * to add additional initialization logic, but must call super.doInit().
+     */
+    async doInit() {
+        await this.transport.init();
+    }
+    /**
+     * Dispose the protocol.
+     *
+     * The transport is tracked as a resource and will be disposed automatically
+     * by BoundedContext. Subclasses can override this to add additional cleanup,
+     * but should not need to dispose the transport manually.
+     */
+    async doDispose() {
+        this.bridgeInfoCache = undefined;
+        // Transport is tracked and will be disposed by BoundedContext
+        // Subclasses can override to add additional cleanup
+    }
+    // ===========================================================================
+    // MESSAGE SENDING
+    // ===========================================================================
+    /**
+     * Send a protocol message and receive a typed response.
+     *
+     * This method:
+     * 1. Generates a unique request ID
+     * 2. Encodes the request with validation (special float rejection, etc.)
+     * 3. Sends via transport with timeout/abort support
+     * 4. Decodes and validates the response
+     *
+     * @param message - The protocol message (without id field)
+     * @param options - Execution options (timeout, retries, validation)
+     * @returns The typed response from Python
+     *
+     * @throws BridgeProtocolError if encoding/decoding fails
+     * @throws BridgeExecutionError if Python returns an error
+     * @throws BridgeTimeoutError if the operation times out
+     */
+    async sendMessage(message, options) {
+        const fullMessage = {
+            ...message,
+            id: this.generateId(),
+            protocol: PROTOCOL_ID,
+        };
+        return this.execute(async () => {
+            // 1. Encode request (validates args)
+            const encoded = this.codec.encodeRequest(fullMessage);
+            // 2. Send via transport
+            const responseStr = await this.transport.send(encoded, options?.timeoutMs ?? this.defaultTimeoutMs, options?.signal);
+            // 3. Decode response (validates result)
+            return this.codec.decodeResponse(responseStr);
+        }, options);
+    }
+    /**
+     * Async version that uses decodeResponseAsync for Arrow support.
+     *
+     * Use this method when the response may contain encoded DataFrames,
+     * ndarrays, or other Arrow-encoded data structures.
+     *
+     * @param message - The protocol message (without id field)
+     * @param options - Execution options (timeout, retries, validation)
+     * @returns The typed response from Python with Arrow decoding applied
+     *
+     * @throws BridgeProtocolError if encoding/decoding fails
+     * @throws BridgeExecutionError if Python returns an error
+     * @throws BridgeTimeoutError if the operation times out
+     */
+    async sendMessageAsync(message, options) {
+        const fullMessage = {
+            ...message,
+            id: this.generateId(),
+            protocol: PROTOCOL_ID,
+        };
+        return this.execute(async () => {
+            // 1. Encode request (validates args)
+            const encoded = this.codec.encodeRequest(fullMessage);
+            // 2. Send via transport
+            const responseStr = await this.transport.send(encoded, options?.timeoutMs ?? this.defaultTimeoutMs, options?.signal);
+            // 3. Decode response with Arrow support
+            return this.codec.decodeResponseAsync(responseStr);
+        }, options);
+    }
+    /**
+     * Generate a unique request ID.
+     *
+     * Returns a monotonically increasing integer that ensures uniqueness
+     * within a process lifetime.
+     */
+    generateId() {
+        return ++this.requestId;
+    }
+    // ===========================================================================
+    // RUNTIME EXECUTION INTERFACE
+    // ===========================================================================
+    /**
+     * Call a Python function.
+     *
+     * @param module - Python module path (e.g., 'numpy', 'mypackage.submodule')
+     * @param functionName - Function name to call
+     * @param args - Positional arguments
+     * @param kwargs - Keyword arguments
+     * @returns The function result
+     */
+    async call(module, functionName, args, kwargs) {
+        return this.sendMessageAsync({
+            method: 'call',
+            params: {
+                module,
+                functionName,
+                args,
+                kwargs,
+            },
+        });
+    }
+    /**
+     * Instantiate a Python class.
+     *
+     * @param module - Python module path containing the class
+     * @param className - Class name to instantiate
+     * @param args - Positional constructor arguments
+     * @param kwargs - Keyword constructor arguments
+     * @returns A handle to the created instance
+     */
+    async instantiate(module, className, args, kwargs) {
+        return this.sendMessageAsync({
+            method: 'instantiate',
+            params: {
+                module,
+                className,
+                args,
+                kwargs,
+            },
+        });
+    }
+    /**
+     * Call a method on a Python instance.
+     *
+     * @param handle - Instance handle returned from instantiate()
+     * @param methodName - Method name to call
+     * @param args - Positional arguments
+     * @param kwargs - Keyword arguments
+     * @returns The method result
+     */
+    async callMethod(handle, methodName, args, kwargs) {
+        return this.sendMessageAsync({
+            method: 'call_method',
+            params: {
+                handle,
+                methodName,
+                args,
+                kwargs,
+            },
+        });
+    }
+    /**
+     * Dispose a Python instance.
+     *
+     * Releases the instance handle on the Python side, allowing
+     * the object to be garbage collected.
+     *
+     * @param handle - Instance handle to dispose
+     */
+    async disposeInstance(handle) {
+        await this.sendMessageAsync({
+            method: 'dispose_instance',
+            params: {
+                handle,
+            },
+        });
+    }
+    /**
+     * Fetch bridge diagnostics and feature availability.
+     *
+     * The Python bridge supports a `meta` method that returns protocol and environment info
+     * (including optional codec availability and current instance count).
+     */
+    async getBridgeInfo(options = {}) {
+        if (!options.refresh && this.bridgeInfoCache) {
+            return this.bridgeInfoCache;
+        }
+        const info = await this.sendMessage({
+            method: 'meta',
+            params: {},
+        }, {
+            validate: validateBridgeInfoPayload,
+        });
+        this.bridgeInfoCache = info;
+        return info;
+    }
+}
+//# sourceMappingURL=bridge-protocol.js.map

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

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

package/dist/runtime/disposable.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Disposable interface for resources that need cleanup.
+ *
+ * This interface enables the BoundedContext resource tracking system
+ * to automatically dispose of owned resources when the context is disposed.
+ */
+/**
+ * Interface for resources that require explicit cleanup.
+ */
+export interface Disposable {
+    /**
+     * Release resources held by this object.
+     * This method should be idempotent (safe to call multiple times).
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Type guard to check if a value implements the Disposable interface.
+ *
+ * @param value - The value to check
+ * @returns True if the value has a dispose method
+ */
+export declare function isDisposable(value: unknown): value is Disposable;
+/**
+ * Safely dispose a value if it implements Disposable.
+ * Does nothing if the value is not disposable.
+ *
+ * @param value - The value to dispose
+ * @returns Promise that resolves when disposal is complete
+ */
+export declare function safeDispose(value: unknown): Promise<void>;
+/**
+ * Dispose multiple resources, collecting any errors.
+ * All resources will be attempted even if some fail.
+ *
+ * @param resources - Iterable of Disposable resources
+ * @returns Array of errors that occurred during disposal (empty if all succeeded)
+ */
+export declare function disposeAll(resources: Iterable<Disposable>): Promise<Error[]>;
+//# sourceMappingURL=disposable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disposable.d.ts","sourceRoot":"","sources":["../../src/runtime/disposable.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAMhE;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/D;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,SAAS,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAYlF"}

package/dist/runtime/disposable.js

@@ -0,0 +1,49 @@
+/**
+ * Disposable interface for resources that need cleanup.
+ *
+ * This interface enables the BoundedContext resource tracking system
+ * to automatically dispose of owned resources when the context is disposed.
+ */
+/**
+ * Type guard to check if a value implements the Disposable interface.
+ *
+ * @param value - The value to check
+ * @returns True if the value has a dispose method
+ */
+export function isDisposable(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value.dispose === 'function');
+}
+/**
+ * Safely dispose a value if it implements Disposable.
+ * Does nothing if the value is not disposable.
+ *
+ * @param value - The value to dispose
+ * @returns Promise that resolves when disposal is complete
+ */
+export async function safeDispose(value) {
+    if (isDisposable(value)) {
+        await value.dispose();
+    }
+}
+/**
+ * Dispose multiple resources, collecting any errors.
+ * All resources will be attempted even if some fail.
+ *
+ * @param resources - Iterable of Disposable resources
+ * @returns Array of errors that occurred during disposal (empty if all succeeded)
+ */
+export async function disposeAll(resources) {
+    const errors = [];
+    for (const resource of resources) {
+        try {
+            await resource.dispose();
+        }
+        catch (e) {
+            errors.push(e instanceof Error ? e : new Error(String(e)));
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=disposable.js.map

package/dist/runtime/disposable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposable.js","sourceRoot":"","sources":["../../src/runtime/disposable.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAQ,KAAoB,CAAC,OAAO,KAAK,UAAU,CACpD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAc;IAC9C,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,SAA+B;IAC9D,MAAM,MAAM,GAAY,EAAE,CAAC;IAE3B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/runtime/errors.d.ts

@@ -11,6 +11,16 @@ export declare class BridgeTimeoutError extends BridgeError {
 }
 export declare class BridgeDisposedError extends BridgeError {
 }
+export declare class BridgeCodecError extends BridgeError {
+    codecPhase?: string;
+    valueType?: string;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+        codecPhase?: string;
+        valueType?: string;
+    });
+}
 export declare class BridgeExecutionError extends BridgeError {
     traceback?: string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,WAAY,SAAQ,KAAK;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;gBACF,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQ1E;AAED,qBAAa,mBAAoB,SAAQ,WAAW;CAAG;AACvD,qBAAa,kBAAmB,SAAQ,WAAW;CAAG;AACtD,qBAAa,mBAAoB,SAAQ,WAAW;CAAG;AAEvD,qBAAa,oBAAqB,SAAQ,WAAW;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,WAAY,SAAQ,KAAK;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;gBACF,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQ1E;AAED,qBAAa,mBAAoB,SAAQ,WAAW;CAAG;AACvD,qBAAa,kBAAmB,SAAQ,WAAW;CAAG;AACtD,qBAAa,mBAAoB,SAAQ,WAAW;CAAG;AAEvD,qBAAa,gBAAiB,SAAQ,WAAW;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;gBAGjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;CAMxF;AAED,qBAAa,oBAAqB,SAAQ,WAAW;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}