tywrap 0.2.0 → 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,11 +7,69 @@
 
 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';
+// 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';
+// Transport implementations
+export { ProcessIO, type ProcessIOOptions } from './runtime/process-io.js';
+export { HttpIO, type HttpIOOptions } from './runtime/http-io.js';
+export { PyodideIO, type PyodideIOOptions } from './runtime/pyodide-io.js';
+// WorkerPool - concurrent transport management
+export { WorkerPool, type WorkerPoolOptions, type PooledWorker } from './runtime/worker-pool.js';
+// PooledTransport - Transport adapter that wraps WorkerPool
+export { PooledTransport, type PooledTransportOptions } from './runtime/pooled-transport.js';
+export type { Disposable } from './runtime/disposable.js';
+export { isDisposable, safeDispose, disposeAll } from './runtime/disposable.js';
+export {
+  ValidationError,
+  isFiniteNumber,
+  isPositiveNumber,
+  isNonNegativeNumber,
+  isNonEmptyString,
+  isPlainObject,
+  assertFiniteNumber,
+  assertPositive,
+  assertNonNegative,
+  assertString,
+  assertNonEmptyString,
+  assertArray,
+  assertObject,
+  containsSpecialFloat,
+  assertNoSpecialFloats,
+  sanitizeForFilename,
+  containsPathTraversal,
+} from './runtime/validators.js';
+
+/**
+ * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
+ */
 export { RuntimeBridge } from './runtime/base.js';
+
 export {
   BridgeError,
+  BridgeCodecError,
   BridgeProtocolError,
   BridgeTimeoutError,
   BridgeDisposedError,
@@ -19,23 +77,37 @@ export {
 } from './runtime/errors.js';
 export { getRuntimeBridge, setRuntimeBridge, clearRuntimeBridge } from './runtime/index.js';
 
-// Runtime-specific exports
-export { NodeBridge } from './runtime/node.js';
-export { PyodideBridge } from './runtime/pyodide.js';
-export { HttpBridge } from './runtime/http.js';
+// Runtime-specific exports (Bridges using new BridgeProtocol architecture)
+export { NodeBridge, type NodeBridgeOptions } from './runtime/node.js';
+export { PyodideBridge, type PyodideBridgeOptions } from './runtime/pyodide.js';
+export { HttpBridge, type HttpBridgeOptions } from './runtime/http.js';
 
 // Core types
 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,
@@ -75,7 +147,7 @@ export {
 } from './utils/codec.js';
 
 // Version info
-export const VERSION = '0.2.0';
+export const VERSION = '0.3.0';
 
 /**
  * Quick setup function for getting started

package/src/runtime/base.ts

@@ -1,32 +1,24 @@
 /**
  * Base runtime bridge
+ *
+ * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
  */
 
-import type { RuntimeExecution } from '../types/index.js';
+import { BoundedContext } from './bounded-context.js';
 
-export abstract class RuntimeBridge implements RuntimeExecution {
-  abstract call<T = unknown>(
-    module: string,
-    functionName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T>;
-
-  abstract instantiate<T = unknown>(
-    module: string,
-    className: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T>;
-
-  abstract callMethod<T = unknown>(
-    handle: string,
-    methodName: string,
-    args: unknown[],
-    kwargs?: Record<string, unknown>
-  ): Promise<T>;
-
-  abstract disposeInstance(handle: string): Promise<void>;
+/**
+ * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
+ *
+ * All bridges now extend BoundedContext which provides:
+ * - Lifecycle management (init/dispose state machine)
+ * - Validation helpers
+ * - Error classification
+ * - Bounded execution (timeout, retry)
+ * - Resource ownership tracking
+ *
+ * @see BoundedContext
+ */
+export abstract class RuntimeBridge extends BoundedContext {}
 
-  abstract dispose(): Promise<void>;
-}
+// Re-export BoundedContext for backwards compatibility
+export { BoundedContext };