tywrap 0.2.1 → 0.4.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) {