nodepyx 1.0.0

package/src/types/PythonTypeMapper.ts

@@ -0,0 +1,495 @@
+/**
+ * nodepyx — PythonTypeMapper
+ * Maps Python type annotation strings → TypeScript type strings.
+ *
+ * Handles:
+ *  - Python built-in types (str, int, float, bool, …)
+ *  - typing module generics (List[X], Dict[K,V], Optional[X], Union[A,B], …)
+ *  - numpy / pandas / torch special types
+ *  - Forward references (strings in quotes)
+ *  - PEP 604 union syntax (X | Y)
+ */
+
+export type TsType = string;
+
+/**
+ * Mapping entry — maps a Python canonical name to a TS type.
+ */
+export interface TypeMapEntry {
+  /** TypeScript type string */
+  tsType: TsType;
+  /** Whether this type needs an import statement */
+  needsImport?: boolean;
+  /** The import path (e.g. './DataFrameBridge') */
+  importFrom?: string;
+}
+
+/** Context passed to mapType for resolving generic parameters */
+export interface TypeMapContext {
+  /** Known class names from the current module */
+  knownClasses?: Set<string>;
+  /** Module name being inspected */
+  moduleName?: string;
+  /** Whether to emit strict types (never use `unknown`) */
+  strict?: boolean;
+}
+
+// ─── Core mapping table ────────────────────────────────────────────────────
+
+const BUILTIN_MAP: Readonly<Record<string, TypeMapEntry>> = {
+  // ── Primitives ──────────────────────────────────────────────────────────
+  'str':        { tsType: 'string' },
+  'int':        { tsType: 'number' },
+  'float':      { tsType: 'number' },
+  'complex':    { tsType: '{ real: number; imag: number }' },
+  'bool':       { tsType: 'boolean' },
+  'bytes':      { tsType: 'Uint8Array' },
+  'bytearray':  { tsType: 'Uint8Array' },
+  'memoryview': { tsType: 'Uint8Array' },
+
+  // ── None / null-like ────────────────────────────────────────────────────
+  'None':       { tsType: 'null' },
+  'NoneType':   { tsType: 'null' },
+  'type(None)': { tsType: 'null' },
+
+  // ── Collections (unparameterized) ───────────────────────────────────────
+  'list':       { tsType: 'unknown[]' },
+  'tuple':      { tsType: 'readonly unknown[]' },
+  'dict':       { tsType: 'Record<string, unknown>' },
+  'set':        { tsType: 'Set<unknown>' },
+  'frozenset':  { tsType: 'ReadonlySet<unknown>' },
+
+  // ── typing module ───────────────────────────────────────────────────────
+  'Any':            { tsType: 'unknown' },
+  'NoReturn':       { tsType: 'never' },
+  'Never':          { tsType: 'never' },
+  'ClassVar':       { tsType: 'unknown' },
+  'Final':          { tsType: 'unknown' },
+  'Literal':        { tsType: 'unknown' },
+
+  // ── IO / streams ────────────────────────────────────────────────────────
+  'IO':             { tsType: 'unknown' },
+  'TextIO':         { tsType: 'string' },
+  'BinaryIO':       { tsType: 'Uint8Array' },
+
+  // ── Callable ────────────────────────────────────────────────────────────
+  'Callable':       { tsType: '(...args: unknown[]) => unknown' },
+
+  // ── Numeric tower ───────────────────────────────────────────────────────
+  'Number':         { tsType: 'number' },
+  'Integer':        { tsType: 'number' },
+  'Float':          { tsType: 'number' },
+  'Decimal':        { tsType: 'number' },
+  'Fraction':       { tsType: 'number' },
+
+  // ── datetime ────────────────────────────────────────────────────────────
+  'datetime':           { tsType: 'Date' },
+  'date':               { tsType: 'Date' },
+  'time':               { tsType: 'Date' },
+  'timedelta':          { tsType: 'number' },
+  'datetime.datetime':  { tsType: 'Date' },
+  'datetime.date':      { tsType: 'Date' },
+  'datetime.time':      { tsType: 'Date' },
+  'datetime.timedelta': { tsType: 'number' },
+
+  // ── pathlib ─────────────────────────────────────────────────────────────
+  'Path':               { tsType: 'string' },
+  'PurePath':           { tsType: 'string' },
+  'PosixPath':          { tsType: 'string' },
+  'WindowsPath':        { tsType: 'string' },
+  'pathlib.Path':       { tsType: 'string' },
+
+  // ── uuid ─────────────────────────────────────────────────────────────────
+  'UUID':               { tsType: 'string' },
+  'uuid.UUID':          { tsType: 'string' },
+
+  // ── NumPy ────────────────────────────────────────────────────────────────
+  'ndarray':            { tsType: 'Float64Array | Float32Array | Int32Array | Uint8Array' },
+  'np.ndarray':         { tsType: 'Float64Array | Float32Array | Int32Array | Uint8Array' },
+  'numpy.ndarray':      { tsType: 'Float64Array | Float32Array | Int32Array | Uint8Array' },
+  'np.float32':         { tsType: 'Float32Array' },
+  'np.float64':         { tsType: 'Float64Array' },
+  'np.int32':           { tsType: 'Int32Array' },
+  'np.int64':           { tsType: 'BigInt64Array' },
+  'np.uint8':           { tsType: 'Uint8Array' },
+  'np.uint16':          { tsType: 'Uint16Array' },
+  'np.uint32':          { tsType: 'Uint32Array' },
+  'np.bool_':           { tsType: 'Uint8Array' },
+  'numpy.float64':      { tsType: 'number' },
+  'numpy.float32':      { tsType: 'number' },
+  'numpy.int64':        { tsType: 'number' },
+  'numpy.int32':        { tsType: 'number' },
+
+  // ── Pandas ───────────────────────────────────────────────────────────────
+  'DataFrame':          { tsType: 'DataFrameResult' },
+  'pd.DataFrame':       { tsType: 'DataFrameResult' },
+  'pandas.DataFrame':   { tsType: 'DataFrameResult' },
+  'Series':             { tsType: 'SeriesResult' },
+  'pd.Series':          { tsType: 'SeriesResult' },
+  'pandas.Series':      { tsType: 'SeriesResult' },
+  'Index':              { tsType: 'unknown[]' },
+  'pd.Index':           { tsType: 'unknown[]' },
+  'MultiIndex':         { tsType: 'unknown[][]' },
+
+  // ── PyTorch ───────────────────────────────────────────────────────────────
+  'Tensor':             { tsType: 'Float32Array | Float64Array' },
+  'torch.Tensor':       { tsType: 'Float32Array | Float64Array' },
+  'torch.nn.Module':    { tsType: 'PyProxy' },
+  'torch.optim.Optimizer': { tsType: 'PyProxy' },
+
+  // ── sklearn ───────────────────────────────────────────────────────────────
+  'BaseEstimator':       { tsType: 'PyProxy' },
+  'ClassifierMixin':     { tsType: 'PyProxy' },
+  'RegressorMixin':      { tsType: 'PyProxy' },
+  'TransformerMixin':    { tsType: 'PyProxy' },
+
+  // ── fallback ─────────────────────────────────────────────────────────────
+  'object':     { tsType: 'unknown' },
+  'type':       { tsType: 'PyProxy' },
+  'module':     { tsType: 'PyProxy' },
+};
+
+// ─── Generic type constructors ────────────────────────────────────────────
+
+/** Patterns for parameterized generics like List[str], Dict[str, int], … */
+const GENERIC_PATTERNS: Array<{
+  re: RegExp;
+  map: (params: string[], ctx: TypeMapContext) => TsType;
+}> = [
+  // Iterator[T]
+  {
+    re: /^Iterator\[(.+)\]$/i,
+    map: ([inner], ctx) => `AsyncIterator<${mapType(inner!, ctx)}>`,
+  },
+  // Set[T]
+  {
+    re: /^Set\[(.+)\]$/i,
+    map: ([inner], ctx) => `Set<${mapType(inner!, ctx)}>`,
+  },
+  // FrozenSet[T]
+  {
+    re: /^FrozenSet\[(.+)\]$/i,
+    map: ([inner], ctx) => `ReadonlySet<${mapType(inner!, ctx)}>`,
+  },
+  // Generator[YieldType, ...] — handled before the generic catch-all
+  {
+    re: /^Generator\[(.+)\]$/i,
+    map: ([inner], ctx) => {
+      const parts = splitGenericParams(inner!);
+      return `AsyncGenerator<${mapType(parts[0]!, ctx)}>`;
+    },
+  },
+  // List[T] / Sequence[T] / Iterable[T] / MutableSequence[T] / Collection[T] / etc.
+  {
+    re: /^(?:List|Sequence|Iterable|MutableSequence|Collection|AbstractSet|MutableSet|Deque|Queue)\[(.+)\]$/i,
+    map: ([inner], ctx) => `Array<${mapType(inner!, ctx)}>`,
+  },
+  // Tuple[A, B, C]
+  {
+    re: /^(?:Tuple)\[(.+)\]$/i,
+    map: ([inner], ctx) => {
+      if (inner === '...') {return `unknown[]`;}
+      const parts = splitGenericParams(inner!);
+      if (parts.length === 2 && parts[1] === '...') {
+        return `Array<${mapType(parts[0]!, ctx)}>`;
+      }
+      return `[${parts.map(p => mapType(p, ctx)).join(', ')}]`;
+    },
+  },
+  // Dict[K, V] / Mapping[K, V] / MutableMapping[K, V]
+  {
+    re: /^(?:Dict|Mapping|MutableMapping|OrderedDict|DefaultDict|ChainMap)\[(.+)\]$/i,
+    map: ([inner], ctx) => {
+      const parts = splitGenericParams(inner!);
+      if (parts.length === 2) {
+        return `Record<${mapType(parts[0]!, ctx)}, ${mapType(parts[1]!, ctx)}>`;
+      }
+      return `Record<string, unknown>`;
+    },
+  },
+  // Optional[T] → T | null
+  {
+    re: /^Optional\[(.+)\]$/i,
+    map: ([inner], ctx) => `${mapType(inner!, ctx)} | null`,
+  },
+  // Union[A, B, C]
+  {
+    re: /^Union\[(.+)\]$/i,
+    map: ([inner], ctx) => {
+      const parts = splitGenericParams(inner!);
+      return parts.map(p => mapType(p, ctx)).join(' | ');
+    },
+  },
+  // PEP 604 — A | B | C (raw union)
+  // Note: params[0] is the first capture group; we reconstruct the full string
+  // by combining all capture groups back with ' | ' to split properly.
+  {
+    re: /^(.+)\s*\|\s*(.+)$/,
+    map: (params: string[], ctx: TypeMapContext) => {
+      // params[0..n] are capture groups; rejoin and re-split at top-level pipes
+      const full = params.join(' | ');
+      const parts = splitPipeUnion(full);
+      return parts.map(p => mapType(p.trim(), ctx)).join(' | ');
+    },
+  },
+  // Callable[[A, B], R]
+  {
+    re: /^Callable\[\[(.*)?\],\s*(.+)\]$/i,
+    map: ([params, ret], ctx) => {
+      if (!params) {return `() => ${mapType(ret!, ctx)}`;}
+      const paramTypes = splitGenericParams(params).map((p, i) => `arg${i}: ${mapType(p, ctx)}`);
+      return `(${paramTypes.join(', ')}) => ${mapType(ret!, ctx)}`;
+    },
+  },
+  // Type[T] / ClassVar[T] / Final[T]
+  {
+    re: /^(?:Type|ClassVar|Final)\[(.+)\]$/i,
+    map: ([inner], ctx) => mapType(inner!, ctx),
+  },
+  // Awaitable[T] / Coroutine[…, T]
+  {
+    re: /^(?:Awaitable|Coroutine)\[.*?,?\s*(.+)\]$/i,
+    map: ([ret], ctx) => `Promise<${mapType(ret!, ctx)}>`,
+  },
+  // AsyncIterator[T] / AsyncIterable[T] / AsyncGenerator[T]
+  {
+    re: /^(?:AsyncIterator|AsyncIterable|AsyncGenerator)\[(.+)\]$/i,
+    map: ([inner], ctx) => `AsyncIterable<${mapType(inner!, ctx)}>`,
+  },
+];
+
+// ─── Main mapType function ────────────────────────────────────────────────
+
+/**
+ * Map a Python type annotation string to a TypeScript type string.
+ *
+ * @example
+ * ```typescript
+ * mapType('List[int]')               // → 'Array<number>'
+ * mapType('Dict[str, float]')        // → 'Record<string, number>'
+ * mapType('Optional[DataFrame]')     // → 'DataFrameResult | null'
+ * mapType('Union[str, int, None]')   // → 'string | number | null'
+ * mapType('Tuple[int, str, bool]')   // → '[number, string, boolean]'
+ * ```
+ */
+export function mapType(
+  pythonType: string,
+  ctx: TypeMapContext = {},
+): TsType {
+  if (!pythonType) {return 'unknown';}
+
+  const trimmed = pythonType.trim();
+
+  // ── Direct lookup ───────────────────────────────────────────────────────
+  const direct = BUILTIN_MAP[trimmed];
+  if (direct) {return direct.tsType;}
+
+  // ── Strip module qualifiers for a second lookup ─────────────────────────
+  const unqualified = trimmed.includes('.')
+    ? trimmed.split('.').pop()!
+    : trimmed;
+  const unqualLookup = BUILTIN_MAP[unqualified];
+  if (unqualLookup) {return unqualLookup.tsType;}
+
+  // ── Generic patterns ────────────────────────────────────────────────────
+  for (const pattern of GENERIC_PATTERNS) {
+    const match = trimmed.match(pattern.re);
+    if (match) {
+      const capturedGroups = match.slice(1);
+      // Pass the full raw string for PEP-604 union
+      return pattern.map(capturedGroups, ctx);
+    }
+  }
+
+  // ── Known class from current module ─────────────────────────────────────
+  if (ctx.knownClasses?.has(trimmed) || ctx.knownClasses?.has(unqualified)) {
+    return 'PyProxy';
+  }
+
+  // ── String forward reference (PEP 484) ──────────────────────────────────
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return mapType(trimmed.slice(1, -1), ctx);
+  }
+
+  // ── Fallback ─────────────────────────────────────────────────────────────
+  // Unknown types always map to 'unknown' (not PyProxy) for better type safety
+  return 'unknown';
+}
+
+// ─── mapReturnType (adds Promise<> wrapping) ────────────────────────────────
+
+/**
+ * Map a Python return type annotation.
+ * Automatically wraps the result in `Promise<>` since all Python calls
+ * are asynchronous from the JavaScript side.
+ *
+ * Generator / Iterator returns are mapped to `AsyncGenerator`.
+ * None → Promise<void>
+ */
+export function mapReturnType(
+  pythonReturnType: string,
+  ctx: TypeMapContext = {},
+): TsType {
+  if (!pythonReturnType || pythonReturnType === 'None' || pythonReturnType === 'NoneType') {
+    return 'Promise<void>';
+  }
+
+  if (pythonReturnType === 'NoReturn' || pythonReturnType === 'Never') {
+    return 'never';
+  }
+
+  // Generator → AsyncGenerator
+  if (/^Generator\[/.test(pythonReturnType)) {
+    const inner = pythonReturnType.match(/^Generator\[(.+)\]/)?.[1] ?? 'unknown';
+    const parts = splitGenericParams(inner);
+    return `AsyncGenerator<${mapType(parts[0]!, ctx)}>`;
+  }
+
+  // Coroutine / Awaitable → strip wrapper, it becomes the resolved type
+  const awaitMatch = pythonReturnType.match(/^(?:Awaitable|Coroutine)\[.*?,?\s*(.+)\]$/i);
+  if (awaitMatch) {
+    return `Promise<${mapType(awaitMatch[1]!, ctx)}>`;
+  }
+
+  const inner = mapType(pythonReturnType, ctx);
+  return `Promise<${inner}>`;
+}
+
+// ─── Parameter default value helper ──────────────────────────────────────────
+
+/**
+ * Convert a Python default value representation to a TypeScript literal.
+ */
+export function mapDefaultValue(pythonDefault: string): string {
+  if (pythonDefault === 'None') {return 'null';}
+  if (pythonDefault === 'True')  {return 'true';}
+  if (pythonDefault === 'False') {return 'false';}
+  if (/^-?\d+(\.\d+)?$/.test(pythonDefault)) {return pythonDefault;}
+  if (pythonDefault.startsWith("'") || pythonDefault.startsWith('"')) {
+    return pythonDefault.replace(/^'|'$/g, '"');
+  }
+  return `undefined /* ${pythonDefault} */`;
+}
+
+// ─── Splitting helpers ─────────────────────────────────────────────────────
+
+/**
+ * Split generic parameters at the top level (respects nested brackets).
+ * e.g. "str, Dict[str, int], bool" → ["str", "Dict[str, int]", "bool"]
+ */
+export function splitGenericParams(params: string): string[] {
+  const result: string[] = [];
+  let depth = 0;
+  let current = '';
+
+  for (const ch of params) {
+    if (ch === '[') {
+      depth++;
+      current += ch;
+    } else if (ch === ']') {
+      depth--;
+      current += ch;
+    } else if (ch === ',' && depth === 0) {
+      result.push(current.trim());
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+
+  if (current.trim()) {
+    result.push(current.trim());
+  }
+
+  return result;
+}
+
+/**
+ * Split a PEP 604 union "A | B | C" at top-level pipes.
+ */
+function splitPipeUnion(type: string): string[] {
+  const result: string[] = [];
+  let depth = 0;
+  let current = '';
+
+  for (const ch of type) {
+    if (ch === '[') { depth++; current += ch; }
+    else if (ch === ']') { depth--; current += ch; }
+    else if (ch === '|' && depth === 0) {
+      result.push(current.trim());
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+
+  if (current.trim()) {result.push(current.trim());}
+  return result;
+}
+
+// ─── PythonTypeMapper class (stateful, module-aware) ──────────────────────
+
+/**
+ * Stateful type mapper that accumulates required imports
+ * and knows which class names belong to the current module.
+ *
+ * @example
+ * ```typescript
+ * const mapper = new PythonTypeMapper({ moduleName: 'sklearn.linear_model' });
+ * mapper.registerClass('LinearRegression');
+ *
+ * mapper.map('LinearRegression')  // → 'LinearRegression' (local class ref)
+ * mapper.map('DataFrame')         // → 'DataFrameResult'
+ * ```
+ */
+export class PythonTypeMapper {
+  private readonly _ctx: TypeMapContext;
+  private readonly _imports = new Map<string, Set<string>>();
+
+  constructor(ctx: TypeMapContext = {}) {
+    this._ctx = {
+      ...ctx,
+      knownClasses: ctx.knownClasses ?? new Set(),
+    };
+  }
+
+  registerClass(name: string): void {
+    this._ctx.knownClasses!.add(name);
+  }
+
+  map(pyType: string): TsType {
+    const result = mapType(pyType, this._ctx);
+    // Auto-track imports for well-known result types
+    if (result === 'DataFrameResult') {
+      this.addImport('DataFrameResult', 'nodepyx');
+    } else if (result === 'SeriesResult') {
+      this.addImport('SeriesResult', 'nodepyx');
+    } else if (result === 'NumPyArrayResult') {
+      this.addImport('NumPyArrayResult', 'nodepyx');
+    }
+    return result;
+  }
+
+  mapReturn(pyType: string): TsType {
+    return mapReturnType(pyType, this._ctx);
+  }
+
+  addImport(symbol: string, from: string): void {
+    if (!this._imports.has(from)) {
+      this._imports.set(from, new Set());
+    }
+    this._imports.get(from)!.add(symbol);
+  }
+
+  generateImportBlock(): string {
+    const lines: string[] = [];
+    for (const [from, symbols] of this._imports) {
+      lines.push(`import type { ${[...symbols].join(', ')} } from '${from}';`);
+    }
+    return lines.join('\n');
+  }
+}
+