tywrap 0.2.1 → 0.4.0

package/src/index.ts

@@ -7,17 +7,31 @@
 
 import { tywrap } from './tywrap.js';
 
-export type { TywrapConfig } from './config/index.js';
+export type { TywrapConfig, ResolvedTywrapConfig } from './config/index.js';
 export { defineConfig, resolveConfig } from './config/index.js';
 // BoundedContext - unified abstraction for cross-boundary concerns
-export { BoundedContext, type ContextState, type ExecuteOptions } from './runtime/bounded-context.js';
+export {
+  BoundedContext,
+  type ContextState,
+  type ExecuteOptions,
+} from './runtime/bounded-context.js';
 // BridgeProtocol - unified BoundedContext + SafeCodec + Transport
 export { BridgeProtocol, type BridgeProtocolOptions } from './runtime/bridge-protocol.js';
 // SafeCodec - validation and serialization for JS<->Python boundary
 export { SafeCodec, type CodecOptions } from './runtime/safe-codec.js';
 // Transport - abstract I/O channel interface
-export type { Transport, TransportOptions, ProtocolMessage, ProtocolResponse } from './runtime/transport.js';
-export { PROTOCOL_ID, isTransport, isProtocolMessage, isProtocolResponse } from './runtime/transport.js';
+export type {
+  Transport,
+  TransportOptions,
+  ProtocolMessage,
+  ProtocolResponse,
+} from './runtime/transport.js';
+export {
+  PROTOCOL_ID,
+  isTransport,
+  isProtocolMessage,
+  isProtocolResponse,
+} from './runtime/transport.js';
 // Transport implementations
 export { ProcessIO, type ProcessIOOptions } from './runtime/process-io.js';
 export { HttpIO, type HttpIOOptions } from './runtime/http-io.js';
@@ -55,6 +69,7 @@ export { RuntimeBridge } from './runtime/base.js';
 
 export {
   BridgeError,
+  BridgeCodecError,
   BridgeProtocolError,
   BridgeTimeoutError,
   BridgeDisposedError,
@@ -72,13 +87,27 @@ export type {
   PythonModule,
   PythonFunction,
   PythonClass,
+  PythonTypeAlias,
   PythonType,
+  PythonGenericParameter,
+  PythonGenericParameterKind,
   PrimitiveType,
   CollectionType,
   UnionType,
   OptionalType,
   CustomType,
   GenericType,
+  CallableType,
+  LiteralType,
+  AnnotatedType,
+  TypeVarType,
+  ParamSpecType,
+  ParamSpecArgsType,
+  ParamSpecKwargsType,
+  TypeVarTupleType,
+  UnpackType,
+  FinalType,
+  ClassVarType,
   Parameter,
   Property,
   PythonImport,
@@ -92,7 +121,6 @@ export type {
   NodeConfig,
   HttpConfig,
   PerformanceConfig,
-  DevelopmentConfig,
   TypeMappingConfig,
   TypePreset,
   BridgeInfo,
@@ -106,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';
@@ -118,7 +147,7 @@ export {
 } from './utils/codec.js';
 
 // Version info
-export const VERSION = '0.2.1';
+export const VERSION = '0.3.0';
 
 /**
  * Quick setup function for getting started

package/src/runtime/bridge-core.ts

@@ -252,17 +252,34 @@ export class BridgeCore {
       return;
     }
 
-    this.pending.delete(msg.id);
-    if (pending.timer) {
-      clearTimeout(pending.timer);
+    const hasResult = Object.prototype.hasOwnProperty.call(msg, 'result');
+    const hasError = Object.prototype.hasOwnProperty.call(msg, 'error');
+
+    if (hasResult && hasError) {
+      this.handleProtocolError('Response cannot include both "result" and "error"', line);
+      return;
     }
 
-    if ('error' in msg) {
+    if (hasError) {
       const errorPayload = this.normalizeErrorPayload(msg.error);
+      if (!errorPayload) {
+        const reason = this.describeInvalidErrorPayload(msg.error);
+        this.handleProtocolError(`Invalid response "error" payload: ${reason}`, line);
+        return;
+      }
+      this.pending.delete(msg.id);
+      if (pending.timer) {
+        clearTimeout(pending.timer);
+      }
       pending.reject(this.errorFrom(errorPayload));
       return;
     }
 
+    this.pending.delete(msg.id);
+    if (pending.timer) {
+      clearTimeout(pending.timer);
+    }
+
     Promise.resolve(this.options.decodeValue(msg.result))
       .then(decoded => pending.resolve(decoded))
       .catch(err => {
@@ -280,21 +297,44 @@ export class BridgeCore {
     return error;
   }
 
-  private normalizeErrorPayload(err: unknown): { type: string; message: string; traceback?: string } {
-    if (err && typeof err === 'object') {
-      const candidate = err as { type?: unknown; message?: unknown; traceback?: unknown };
-      if (typeof candidate.type === 'string' && typeof candidate.message === 'string') {
-        const normalized: { type: string; message: string; traceback?: string } = {
-          type: candidate.type,
-          message: candidate.message,
-        };
-        if (typeof candidate.traceback === 'string') {
-          normalized.traceback = candidate.traceback;
-        }
-        return normalized;
-      }
+  private normalizeErrorPayload(
+    err: unknown
+  ): { type: string; message: string; traceback?: string } | null {
+    if (!err || typeof err !== 'object' || Array.isArray(err)) {
+      return null;
+    }
+    const candidate = err as { type?: unknown; message?: unknown; traceback?: unknown };
+    if (typeof candidate.type !== 'string' || typeof candidate.message !== 'string') {
+      return null;
+    }
+    if (candidate.traceback !== undefined && typeof candidate.traceback !== 'string') {
+      return null;
+    }
+    const normalized: { type: string; message: string; traceback?: string } = {
+      type: candidate.type,
+      message: candidate.message,
+    };
+    if (typeof candidate.traceback === 'string') {
+      normalized.traceback = candidate.traceback;
+    }
+    return normalized;
+  }
+
+  private describeInvalidErrorPayload(err: unknown): string {
+    if (!err || typeof err !== 'object' || Array.isArray(err)) {
+      return 'expected an object with string "type" and "message" fields';
+    }
+    const candidate = err as { type?: unknown; message?: unknown; traceback?: unknown };
+    if (typeof candidate.type !== 'string') {
+      return '"type" must be a string';
+    }
+    if (typeof candidate.message !== 'string') {
+      return '"message" must be a string';
+    }
+    if (candidate.traceback !== undefined && typeof candidate.traceback !== 'string') {
+      return '"traceback" must be a string when provided';
     }
-    return { type: 'UnknownError', message: String(err) };
+    return 'expected an object with string "type" and "message" fields';
   }
 
   private failRequest(id: number, error: Error): void {

package/src/runtime/bridge-protocol.ts

@@ -16,14 +16,26 @@
  * @see https://github.com/bbopen/tywrap/issues/149
  */
 
+import type { BridgeInfo } from '../types/index.js';
+
 import { BoundedContext, type ExecuteOptions } from './bounded-context.js';
+import { BridgeProtocolError } from './errors.js';
 import { SafeCodec, type CodecOptions } from './safe-codec.js';
+import { TYWRAP_PROTOCOL_VERSION } from './protocol.js';
 import { PROTOCOL_ID, type Transport, type ProtocolMessage } from './transport.js';
 
 // =============================================================================
 // TYPES
 // =============================================================================
 
+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.
  */
@@ -38,6 +50,129 @@ export interface BridgeProtocolOptions {
   defaultTimeoutMs?: number;
 }
 
+function validateBridgeInfoPayload(value: unknown): BridgeInfo {
+  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}`);
+  }
+
+  interface BridgeInfoWire {
+    protocol?: unknown;
+    protocolVersion?: unknown;
+    bridge?: unknown;
+    pythonVersion?: unknown;
+    pid?: unknown;
+    codecFallback?: unknown;
+    arrowAvailable?: unknown;
+    scipyAvailable?: unknown;
+    torchAvailable?: unknown;
+    sklearnAvailable?: unknown;
+    instances?: unknown;
+  }
+
+  const formatValue = (val: unknown): string => {
+    try {
+      const serialized = JSON.stringify(val);
+      return serialized ?? String(val);
+    } catch {
+      return String(val);
+    }
+  };
+
+  const obj = value as BridgeInfoWire;
+
+  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
 // =============================================================================
@@ -80,6 +215,9 @@ export class BridgeProtocol extends BoundedContext {
   /** Counter for generating unique request IDs */
   private requestId = 0;
 
+  /** Cached bridge diagnostics info (populated by getBridgeInfo). */
+  private bridgeInfoCache?: BridgeInfo;
+
   /**
    * Create a new BridgeProtocol instance.
    *
@@ -117,6 +255,7 @@ export class BridgeProtocol extends BoundedContext {
    * but should not need to dispose the transport manually.
    */
   protected async doDispose(): Promise<void> {
+    this.bridgeInfoCache = undefined;
     // Transport is tracked and will be disposed by BoundedContext
     // Subclasses can override to add additional cleanup
   }
@@ -316,4 +455,29 @@ export class BridgeProtocol extends BoundedContext {
       },
     });
   }
+
+  /**
+   * 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: GetBridgeInfoOptions = {}): Promise<BridgeInfo> {
+    if (!options.refresh && this.bridgeInfoCache) {
+      return this.bridgeInfoCache;
+    }
+
+    const info = await this.sendMessage<BridgeInfo>(
+      {
+        method: 'meta',
+        params: {},
+      },
+      {
+        validate: validateBridgeInfoPayload,
+      }
+    );
+
+    this.bridgeInfoCache = info;
+    return info;
+  }
 }

package/src/runtime/errors.ts

@@ -14,6 +14,20 @@ export class BridgeProtocolError extends BridgeError {}
 export class BridgeTimeoutError extends BridgeError {}
 export class BridgeDisposedError extends BridgeError {}
 
+export class BridgeCodecError extends BridgeError {
+  codecPhase?: string;
+  valueType?: string;
+
+  constructor(
+    message: string,
+    options?: { code?: string; cause?: unknown; codecPhase?: string; valueType?: string }
+  ) {
+    super(message, { code: options?.code, cause: options?.cause });
+    this.codecPhase = options?.codecPhase;
+    this.valueType = options?.valueType;
+  }
+}
+
 export class BridgeExecutionError extends BridgeError {
   traceback?: string;
 }

package/src/runtime/http-io.ts

@@ -135,7 +135,8 @@ export class HttpIO implements Transport {
 
     // Determine effective timeout
     // 0 = no timeout (per interface contract), negative = use default
-    const effectiveTimeout = timeoutMs === 0 ? 0 : timeoutMs > 0 ? timeoutMs : this.defaultTimeoutMs;
+    const effectiveTimeout =
+      timeoutMs === 0 ? 0 : timeoutMs > 0 ? timeoutMs : this.defaultTimeoutMs;
 
     // Create abort controller for timeout
     const controller = new AbortController();

package/src/runtime/http.ts

@@ -10,6 +10,7 @@
 import { BridgeProtocol, type BridgeProtocolOptions } from './bridge-protocol.js';
 import { HttpIO } from './http-io.js';
 import type { CodecOptions } from './safe-codec.js';
+import { autoRegisterArrowDecoder } from '../utils/codec.js';
 
 // =============================================================================
 // OPTIONS
@@ -83,4 +84,10 @@ export class HttpBridge extends BridgeProtocol {
 
     super(protocolOptions);
   }
+
+  protected async doInit(): Promise<void> {
+    // Best-effort: keep apache-arrow optional and avoid breaking non-Node runtimes.
+    await autoRegisterArrowDecoder();
+    await super.doInit();
+  }
 }