tywrap 0.2.1 → 0.3.0

package/src/core/mapper.ts

@@ -9,7 +9,13 @@ import type {
   UnionType as PyUnionType,
   OptionalType as PyOptionalType,
   GenericType as PyGenericType,
+  CallableType as PyCallableType,
   TypeVarType as PyTypeVarType,
+  ParamSpecType as PyParamSpecType,
+  ParamSpecArgsType as PyParamSpecArgsType,
+  ParamSpecKwargsType as PyParamSpecKwargsType,
+  TypeVarTupleType as PyTypeVarTupleType,
+  UnpackType as PyUnpackType,
   FinalType as PyFinalType,
   ClassVarType as PyClassVarType,
   TypescriptType,
@@ -62,6 +68,16 @@ export class TypeMapper {
         return this.mapPythonType(pythonType.base, context);
       case 'typevar':
         return this.mapTypeVarType(pythonType, context);
+      case 'paramspec':
+        return this.mapParamSpecType(pythonType);
+      case 'paramspec_args':
+        return this.mapParamSpecArgsType(pythonType);
+      case 'paramspec_kwargs':
+        return this.mapParamSpecKwargsType();
+      case 'typevartuple':
+        return this.mapTypeVarTupleType(pythonType);
+      case 'unpack':
+        return this.mapUnpackType(pythonType, context);
       case 'final':
         return this.mapFinalType(pythonType, context);
       case 'classvar':
@@ -103,6 +119,17 @@ export class TypeMapper {
 
     // tuple[T1, T2, ...] -> [T1, T2, ...] (exact arity)
     if (type.name === 'tuple') {
+      if (
+        type.itemTypes.length === 2 &&
+        type.itemTypes[1]?.kind === 'custom' &&
+        (type.itemTypes[1] as { kind: 'custom'; name: string }).name === '...'
+      ) {
+        return {
+          kind: 'array',
+          elementType: this.mapPythonType(type.itemTypes[0] ?? { kind: 'primitive', name: 'None' }),
+        } satisfies TSArrayType;
+      }
+
       const elementTypes: TypescriptType[] =
         type.itemTypes.length > 0
           ? type.itemTypes.map(t => this.mapPythonType(t))
@@ -167,11 +194,17 @@ export class TypeMapper {
     };
   }
 
-  mapGenericType(type: PyGenericType, context: MappingContext = 'value'): TSGenericType {
+  mapGenericType(type: PyGenericType, context: MappingContext = 'value'): TypescriptType {
+    const normalized = this.normalizeCustomType({ name: type.name, module: type.module });
+    const typeArgs = type.typeArgs.map(t => this.mapPythonType(t, context));
+    const knownGenericType = this.mapKnownGenericType(normalized, typeArgs);
+    if (knownGenericType) {
+      return knownGenericType;
+    }
     return {
       kind: 'generic',
-      name: type.name,
-      typeArgs: type.typeArgs.map(t => this.mapPythonType(t, context)),
+      name: normalized.name,
+      typeArgs,
     };
   }
 
@@ -226,39 +259,9 @@ export class TypeMapper {
       };
     }
 
-    // Async types
-    if (name === 'Awaitable' || fullName === 'typing.Awaitable') {
-      return {
-        kind: 'generic',
-        name: 'Promise',
-        typeArgs: [{ kind: 'primitive', name: 'unknown' }],
-      };
-    }
-    if (name === 'Coroutine' || fullName === 'typing.Coroutine') {
-      return {
-        kind: 'generic',
-        name: 'Promise',
-        typeArgs: [{ kind: 'primitive', name: 'unknown' }],
-      };
-    }
-
-    // Collection types that should be generics
-    if (name === 'Sequence' || fullName === 'typing.Sequence') {
-      return {
-        kind: 'generic',
-        name: 'Array',
-        typeArgs: [{ kind: 'primitive', name: 'unknown' }],
-      };
-    }
-    if (name === 'Mapping' || fullName === 'typing.Mapping') {
-      return {
-        kind: 'object',
-        properties: [],
-        indexSignature: {
-          keyType: { kind: 'primitive', name: 'string' },
-          valueType: { kind: 'primitive', name: 'unknown' },
-        },
-      };
+    const knownGenericType = this.mapKnownGenericType(this.normalizeCustomType(type));
+    if (knownGenericType) {
+      return knownGenericType;
     }
 
     const presetType = this.mapPresetType(type);
@@ -266,16 +269,19 @@ export class TypeMapper {
       return presetType;
     }
 
+    // The generator does not synthesize TS generic parameters from Python typing
+    // helpers, so unsupported placeholders must degrade to unknown instead of
+    // leaking undeclared identifiers like T, P, or Ts into emitted code.
+    if (type.module === 'typing' || type.module === 'typing_extensions') {
+      return { kind: 'primitive', name: 'unknown' };
+    }
+
     // Forward references and user types
     const normalized = this.normalizeCustomType(type);
     return { kind: 'custom', name: normalized.name, module: normalized.module };
   }
 
-  mapCallableType(type: {
-    kind: 'callable';
-    parameters: PythonType[];
-    returnType: PythonType;
-  }): TSFunctionType {
+  mapCallableType(type: PyCallableType): TSFunctionType {
     // Support Callable[[...], R] → (...args: unknown[]) => R
     const onlyEllipsis =
       type.parameters.length === 1 &&
@@ -285,21 +291,30 @@ export class TypeMapper {
     return {
       kind: 'function',
       isAsync: false,
-      parameters: onlyEllipsis
+      parameters: type.parameterSpec
         ? ([
             {
               name: 'args',
-              type: { kind: 'array', elementType: { kind: 'primitive', name: 'unknown' } },
+              type: this.mapParamSpecType(type.parameterSpec),
               optional: false,
               rest: true,
             },
           ] as const satisfies TSFunctionType['parameters'])
-        : type.parameters.map((p, i) => ({
-            name: `arg${i}`,
-            type: this.mapPythonType(p, 'value'),
-            optional: false,
-            rest: false,
-          })),
+        : onlyEllipsis
+          ? ([
+              {
+                name: 'args',
+                type: { kind: 'array', elementType: { kind: 'primitive', name: 'unknown' } },
+                optional: false,
+                rest: true,
+              },
+            ] as const satisfies TSFunctionType['parameters'])
+          : type.parameters.map((p, i) => ({
+              name: `arg${i}`,
+              type: this.mapPythonType(p, 'value'),
+              optional: false,
+              rest: false,
+            })),
       returnType: this.mapPythonType(type.returnType, 'return'),
     } satisfies TSFunctionType;
   }
@@ -312,8 +327,15 @@ export class TypeMapper {
   }
 
   mapTypeVarType(type: PyTypeVarType, _context: MappingContext = 'value'): TSCustomType {
-    // TypeVar maps to a generic type parameter in TypeScript
-    // Bounds and constraints are not directly expressible in TypeScript type system
+    // TypeVar maps to a generic type parameter in TypeScript.
+    return {
+      kind: 'custom',
+      name: type.name,
+      module: 'typing',
+    };
+  }
+
+  mapParamSpecType(type: PyParamSpecType): TSCustomType {
     return {
       kind: 'custom',
       name: type.name,
@@ -321,6 +343,32 @@ export class TypeMapper {
     };
   }
 
+  mapParamSpecArgsType(_type: PyParamSpecArgsType): TSArrayType {
+    return {
+      kind: 'array',
+      elementType: { kind: 'primitive', name: 'unknown' },
+    };
+  }
+
+  mapParamSpecKwargsType(): TSObjectType {
+    return {
+      kind: 'object',
+      properties: [],
+      indexSignature: {
+        keyType: { kind: 'primitive', name: 'string' },
+        valueType: { kind: 'primitive', name: 'unknown' },
+      },
+    };
+  }
+
+  mapTypeVarTupleType(_type: PyTypeVarTupleType): TSPrimitiveType {
+    return { kind: 'primitive', name: 'unknown' };
+  }
+
+  mapUnpackType(_type: PyUnpackType, _context: MappingContext = 'value'): TSPrimitiveType {
+    return { kind: 'primitive', name: 'unknown' };
+  }
+
   mapFinalType(type: PyFinalType, context: MappingContext = 'value'): TypescriptType {
     // Final[T] maps to T in TypeScript (no direct Final equivalent)
     // The Final qualifier is more of a static analysis hint
@@ -333,6 +381,58 @@ export class TypeMapper {
     return this.mapPythonType(type.type, context);
   }
 
+  private mapKnownGenericType(
+    type: { name: string; module?: string },
+    typeArgs: TypescriptType[] = []
+  ): TypescriptType | undefined {
+    const unknownType: TSPrimitiveType = { kind: 'primitive', name: 'unknown' };
+    const isKnownTypingModule =
+      type.module === undefined ||
+      type.module === 'typing' ||
+      type.module === 'typing_extensions' ||
+      type.module === 'collections.abc';
+
+    if (!isKnownTypingModule) {
+      return undefined;
+    }
+
+    if (type.name === 'Awaitable') {
+      return {
+        kind: 'generic',
+        name: 'Promise',
+        typeArgs: [typeArgs[0] ?? unknownType],
+      } satisfies TSGenericType;
+    }
+
+    if (type.name === 'Coroutine') {
+      return {
+        kind: 'generic',
+        name: 'Promise',
+        typeArgs: [typeArgs[typeArgs.length - 1] ?? unknownType],
+      } satisfies TSGenericType;
+    }
+
+    if (type.name === 'Sequence') {
+      return {
+        kind: 'array',
+        elementType: typeArgs[0] ?? unknownType,
+      } satisfies TSArrayType;
+    }
+
+    if (type.name === 'Mapping') {
+      return {
+        kind: 'object',
+        properties: [],
+        indexSignature: {
+          keyType: this.asIndexKeyType(typeArgs[0] ?? unknownType),
+          valueType: typeArgs[1] ?? unknownType,
+        },
+      } satisfies TSObjectType;
+    }
+
+    return undefined;
+  }
+
   private asIndexKeyType(key: TypescriptType): TSPrimitiveType {
     if (key.kind === 'primitive' && (key.name === 'string' || key.name === 'number')) {
       return key;
@@ -449,6 +549,13 @@ export class TypeMapper {
       }
     }
 
+    if (this.hasPreset('pydantic')) {
+      const allowModule = !moduleName || moduleName.startsWith('pydantic');
+      if (allowModule && name === 'BaseModel') {
+        return recordObject;
+      }
+    }
+
     if (this.hasPreset('scipy')) {
       const allowModule = !moduleName || moduleName.startsWith('scipy');
       if (allowModule) {

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,
@@ -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;
 }