tywrap 0.1.0

package/src/runtime/protocol.ts

@@ -0,0 +1,2 @@
+export const TYWRAP_PROTOCOL = 'tywrap/1';
+export const TYWRAP_PROTOCOL_VERSION = 1;

package/src/runtime/pyodide.ts

@@ -0,0 +1,228 @@
+/**
+ * Pyodide runtime bridge (browser)
+ */
+
+import { RuntimeBridge } from './base.js';
+
+export interface PyodideBridgeOptions {
+  indexURL: string;
+  packages?: string[];
+}
+
+type LoadPyodide = (options: { indexURL: string }) => Promise<PyodideInstance>;
+
+interface PyodideInstance {
+  runPython: (code: string) => unknown;
+  runPythonAsync: (code: string) => Promise<unknown>;
+  globals: { get: (key: string) => unknown; set: (k: string, v: unknown) => void };
+  toPy: (obj: unknown) => unknown;
+  loadPackage: (name: string | string[]) => Promise<void>;
+}
+
+export class PyodideBridge extends RuntimeBridge {
+  private readonly indexURL: string;
+  private readonly packages: readonly string[];
+  private py?: PyodideInstance;
+  private initPromise?: Promise<void>;
+
+  constructor(options: PyodideBridgeOptions = { indexURL: 'https://cdn.jsdelivr.net/pyodide/' }) {
+    super();
+    this.indexURL = options.indexURL;
+    this.packages = [...(options.packages ?? [])];
+  }
+
+  private async ensureReady(): Promise<void> {
+    if (this.py) {
+      return;
+    }
+    // If already initializing, wait for that promise
+    if (this.initPromise) {
+      return this.initPromise;
+    }
+    // Start initialization and store the promise to prevent concurrent initialization
+    this.initPromise = this.doInit();
+    return this.initPromise;
+  }
+
+  private async doInit(): Promise<void> {
+    const loadPyodideFn: LoadPyodide | undefined = await this.resolveLoadPyodide();
+    if (!loadPyodideFn) {
+      throw new Error('Pyodide is not available in this environment');
+    }
+    this.py = await loadPyodideFn({ indexURL: this.indexURL });
+    if (this.packages.length > 0) {
+      await this.py.loadPackage([...this.packages]);
+    }
+    await this.bootstrapHelpers();
+  }
+
+  async init(): Promise<void> {
+    await this.ensureReady();
+  }
+
+  private async resolveLoadPyodide(): Promise<LoadPyodide | undefined> {
+    // Prefer global loadPyodide when present (browser script tag include)
+    const g = (globalThis as unknown as { loadPyodide?: LoadPyodide }) ?? {};
+    if (typeof g.loadPyodide === 'function') {
+      return g.loadPyodide;
+    }
+    try {
+      // Attempt dynamic import if available
+      const mod = (await import('pyodide')) as unknown as { loadPyodide?: LoadPyodide };
+      if (typeof mod.loadPyodide === 'function') {
+        return mod.loadPyodide;
+      }
+    } catch {
+      // Ignore import errors - pyodide may not be installed
+      // This is expected in most environments
+    }
+    return undefined;
+  }
+
+  private async bootstrapHelpers(): Promise<void> {
+    if (!this.py) {
+      return;
+    }
+    const helper = [
+      'import importlib',
+      '__tywrap_instances = {}',
+      'def __tywrap_call(module, function_name, args, kwargs):',
+      '    mod = importlib.import_module(module)',
+      '    fn = getattr(mod, function_name)',
+      '    return fn(*args, **(kwargs or {}))',
+      'def __tywrap_instantiate(module, class_name, args, kwargs):',
+      '    mod = importlib.import_module(module)',
+      '    cls = getattr(mod, class_name)',
+      '    obj = cls(*args, **(kwargs or {}))',
+      '    handle = str(id(obj))',
+      '    __tywrap_instances[handle] = obj',
+      '    return handle',
+      'def __tywrap_call_method(handle, method_name, args, kwargs):',
+      '    if handle not in __tywrap_instances:',
+      '        raise KeyError(f"Unknown handle: {handle}")',
+      '    obj = __tywrap_instances[handle]',
+      '    fn = getattr(obj, method_name)',
+      '    return fn(*args, **(kwargs or {}))',
+      'def __tywrap_dispose_instance(handle):',
+      '    return __tywrap_instances.pop(handle, None) is not None',
+    ].join('\n');
+    await this.py.runPythonAsync(helper);
+  }
+
+  async call<T = unknown>(
+    module: string,
+    functionName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    await this.ensureReady();
+    const py = this.py;
+    if (!py) {
+      throw new Error('Pyodide not initialized');
+    }
+    const fn = py.globals.get('__tywrap_call');
+    if (!fn) {
+      throw new Error('Pyodide helper not initialized');
+    }
+    const invoke = fn as (module: string, f: string, a: unknown, k: unknown) => unknown;
+    const pyArgs = py.toPy(args ?? []);
+    const pyKwargs = py.toPy(kwargs ?? {});
+    try {
+      const out = invoke(module, functionName, pyArgs, pyKwargs);
+      return out as T;
+    } finally {
+      this.destroyPyProxy(pyArgs);
+      this.destroyPyProxy(pyKwargs);
+      this.destroyPyProxy(fn);
+    }
+  }
+
+  async instantiate<T = unknown>(
+    module: string,
+    className: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    await this.ensureReady();
+    const py = this.py;
+    if (!py) {
+      throw new Error('Pyodide not initialized');
+    }
+    const fn = py.globals.get('__tywrap_instantiate');
+    if (!fn) {
+      throw new Error('Pyodide helper not initialized');
+    }
+    const invoke = fn as (module: string, c: string, a: unknown, k: unknown) => unknown;
+    const pyArgs = py.toPy(args ?? []);
+    const pyKwargs = py.toPy(kwargs ?? {});
+    try {
+      const out = invoke(module, className, pyArgs, pyKwargs);
+      return out as T;
+    } finally {
+      this.destroyPyProxy(pyArgs);
+      this.destroyPyProxy(pyKwargs);
+      this.destroyPyProxy(fn);
+    }
+  }
+
+  async callMethod<T = unknown>(
+    handle: string,
+    methodName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    await this.ensureReady();
+    const py = this.py;
+    if (!py) {
+      throw new Error('Pyodide not initialized');
+    }
+    const fn = py.globals.get('__tywrap_call_method');
+    if (!fn) {
+      throw new Error('Pyodide helper not initialized');
+    }
+    const invoke = fn as (h: string, m: string, a: unknown, k: unknown) => unknown;
+    const pyArgs = py.toPy(args ?? []);
+    const pyKwargs = py.toPy(kwargs ?? {});
+    try {
+      const out = invoke(handle, methodName, pyArgs, pyKwargs);
+      return out as T;
+    } finally {
+      this.destroyPyProxy(pyArgs);
+      this.destroyPyProxy(pyKwargs);
+      this.destroyPyProxy(fn);
+    }
+  }
+
+  async disposeInstance(handle: string): Promise<void> {
+    await this.ensureReady();
+    const py = this.py;
+    if (!py) {
+      throw new Error('Pyodide not initialized');
+    }
+    const fn = py.globals.get('__tywrap_dispose_instance');
+    if (!fn) {
+      throw new Error('Pyodide helper not initialized');
+    }
+    const invoke = fn as (h: string) => unknown;
+    try {
+      invoke(handle);
+    } finally {
+      this.destroyPyProxy(fn);
+    }
+  }
+
+  async dispose(): Promise<void> {
+    // Pyodide has no explicit dispose for instance; rely on GC
+    this.py = undefined;
+  }
+
+  private destroyPyProxy(value: unknown): void {
+    if (value && typeof (value as { destroy?: () => void }).destroy === 'function') {
+      try {
+        (value as { destroy: () => void }).destroy();
+      } catch {
+        // ignore cleanup failures
+      }
+    }
+  }
+}

package/src/types/global.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Global type declarations for runtime environments
+ */
+
+// Deno runtime types
+declare namespace DenoTypes {
+  interface Version {
+    deno: string;
+  }
+
+  interface DenoGlobal {
+    version: Version;
+    readTextFile(path: string): Promise<string>;
+    writeTextFile(path: string, content: string): Promise<void>;
+    Command: new (
+      cmd: string,
+      options?: { args?: string[] }
+    ) => {
+      output(): Promise<{ code: number; stdout: Uint8Array; stderr: Uint8Array }>;
+    };
+  }
+}
+
+// Bun runtime types
+declare namespace BunTypes {
+  interface BunGlobal {
+    version: string;
+
+    file(path: string): {
+      text(): Promise<string>;
+    };
+
+    write(path: string, content: string): Promise<void>;
+
+    spawn(
+      cmd: string[],
+      options?: {
+        stdout?: string;
+        stderr?: string;
+      }
+    ): {
+      stdout: ReadableStream;
+      stderr: ReadableStream;
+      exitCode?: number;
+      exited: Promise<void>;
+    };
+  }
+}
+
+// Global runtime declarations
+declare global {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  var Deno: DenoTypes.DenoGlobal | undefined;
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  var Bun: BunTypes.BunGlobal | undefined;
+  // Node.js compat for atob in browser-less environments
+  function atob(data: string): string;
+}
+
+export {};

package/src/types/index.ts

@@ -0,0 +1,410 @@
+/**
+ * Core type definitions for tywrap
+ */
+
+export interface PythonModule {
+  name: string;
+  path?: string;
+  version?: string;
+  functions: PythonFunction[];
+  classes: PythonClass[];
+  imports: PythonImport[];
+  exports: string[];
+}
+
+export interface PythonFunction {
+  name: string;
+  signature: FunctionSignature;
+  docstring?: string;
+  decorators: string[];
+  isAsync: boolean;
+  isGenerator: boolean;
+  returnType: PythonType;
+  parameters: Parameter[];
+}
+
+export interface PythonClass {
+  name: string;
+  bases: string[];
+  methods: PythonFunction[];
+  properties: Property[];
+  docstring?: string;
+  decorators: string[];
+  kind?: 'class' | 'protocol' | 'typed_dict' | 'namedtuple' | 'dataclass' | 'pydantic';
+}
+
+export interface PythonImport {
+  module: string;
+  name?: string;
+  alias?: string;
+  fromImport: boolean;
+}
+
+export interface Parameter {
+  name: string;
+  type: PythonType;
+  optional: boolean;
+  defaultValue?: unknown;
+  varArgs: boolean;
+  kwArgs: boolean;
+}
+
+export interface Property {
+  name: string;
+  type: PythonType;
+  readonly: boolean;
+  setter?: boolean;
+  getter?: boolean;
+}
+
+export interface FunctionSignature {
+  parameters: Parameter[];
+  returnType: PythonType;
+  isAsync: boolean;
+  isGenerator: boolean;
+}
+
+// Python type system
+export type PythonType =
+  | PrimitiveType
+  | CollectionType
+  | UnionType
+  | OptionalType
+  | GenericType
+  | CallableType
+  | LiteralType
+  | AnnotatedType
+  | CustomType
+  | TypeVarType
+  | FinalType
+  | ClassVarType;
+
+export interface PrimitiveType {
+  kind: 'primitive';
+  name: 'int' | 'float' | 'str' | 'bool' | 'bytes' | 'None';
+}
+
+export interface CollectionType {
+  kind: 'collection';
+  name: 'list' | 'dict' | 'tuple' | 'set' | 'frozenset';
+  itemTypes: PythonType[];
+}
+
+export interface UnionType {
+  kind: 'union';
+  types: PythonType[];
+}
+
+export interface OptionalType {
+  kind: 'optional';
+  type: PythonType;
+}
+
+export interface GenericType {
+  kind: 'generic';
+  name: string;
+  typeArgs: PythonType[];
+}
+
+export interface CustomType {
+  kind: 'custom';
+  name: string;
+  module?: string;
+}
+
+export interface CallableType {
+  kind: 'callable';
+  parameters: PythonType[];
+  returnType: PythonType;
+}
+
+export interface LiteralType {
+  kind: 'literal';
+  value: string | number | boolean | null;
+}
+
+export interface AnnotatedType {
+  kind: 'annotated';
+  base: PythonType;
+  metadata: readonly unknown[];
+}
+
+export interface TypeVarType {
+  kind: 'typevar';
+  name: string;
+  bound?: PythonType;
+  constraints?: PythonType[];
+  variance?: 'covariant' | 'contravariant' | 'invariant';
+}
+
+export interface FinalType {
+  kind: 'final';
+  type: PythonType;
+}
+
+export interface ClassVarType {
+  kind: 'classvar';
+  type: PythonType;
+}
+
+// TypeScript type system
+export type TypescriptType =
+  | TSPrimitiveType
+  | TSArrayType
+  | TSTupleType
+  | TSObjectType
+  | TSUnionType
+  | TSFunctionType
+  | TSGenericType
+  | TSLiteralType
+  | TSCustomType;
+
+export interface TSPrimitiveType {
+  kind: 'primitive';
+  name:
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'null'
+    | 'undefined'
+    | 'void'
+    | 'unknown'
+    | 'never'
+    | 'object';
+}
+
+export interface TSArrayType {
+  kind: 'array';
+  elementType: TypescriptType;
+}
+
+export interface TSTupleType {
+  kind: 'tuple';
+  elementTypes: TypescriptType[];
+}
+
+export interface TSObjectType {
+  kind: 'object';
+  properties: TSProperty[];
+  indexSignature?: TSIndexSignature;
+}
+
+export interface TSProperty {
+  name: string;
+  type: TypescriptType;
+  optional: boolean;
+  readonly: boolean;
+}
+
+export interface TSIndexSignature {
+  keyType: TypescriptType;
+  valueType: TypescriptType;
+}
+
+export interface TSUnionType {
+  kind: 'union';
+  types: TypescriptType[];
+}
+
+export interface TSFunctionType {
+  kind: 'function';
+  parameters: TSParameter[];
+  returnType: TypescriptType;
+  isAsync: boolean;
+}
+
+export interface TSParameter {
+  name: string;
+  type: TypescriptType;
+  optional: boolean;
+  rest: boolean;
+}
+
+export interface TSGenericType {
+  kind: 'generic';
+  name: string;
+  typeArgs: TypescriptType[];
+}
+
+export interface TSCustomType {
+  kind: 'custom';
+  name: string;
+  module?: string;
+}
+
+export interface TSLiteralType {
+  kind: 'literal';
+  value: string | number | boolean | null;
+}
+
+// Runtime and configuration types
+export type RuntimeStrategy = 'pyodide' | 'node' | 'http' | 'auto';
+
+export interface TywrapOptions {
+  pythonModules: Record<string, PythonModuleConfig>;
+  output: OutputConfig;
+  runtime: RuntimeConfig;
+  performance: PerformanceConfig;
+  development: DevelopmentConfig;
+  types?: TypeMappingConfig;
+  debug?: boolean;
+}
+
+export interface PythonModuleConfig {
+  version?: string;
+  runtime: RuntimeStrategy;
+  functions?: string[];
+  classes?: string[];
+  alias?: string;
+  typeHints: 'strict' | 'loose' | 'ignore';
+  watch?: boolean;
+}
+
+export interface OutputConfig {
+  dir: string;
+  format: 'esm' | 'cjs' | 'both';
+  declaration: boolean;
+  sourceMap: boolean;
+  annotatedJSDoc?: boolean;
+}
+
+export interface RuntimeConfig {
+  pyodide?: PyodideConfig;
+  node?: NodeConfig;
+  http?: HttpConfig;
+}
+
+export interface PyodideConfig {
+  indexURL?: string;
+  packages?: string[];
+}
+
+export interface NodeConfig {
+  pythonPath?: string;
+  virtualEnv?: string;
+  timeout?: number;
+}
+
+export interface HttpConfig {
+  baseURL: string;
+  timeout?: number;
+  headers?: Record<string, string>;
+}
+
+export interface PerformanceConfig {
+  caching: boolean;
+  batching: boolean;
+  compression: 'auto' | 'gzip' | 'brotli' | 'none';
+}
+
+export interface DevelopmentConfig {
+  hotReload: boolean;
+  sourceMap: boolean;
+  validation: 'runtime' | 'compile' | 'both' | 'none';
+}
+
+export type TypePreset = 'numpy' | 'pandas' | 'pydantic' | 'stdlib' | 'scipy' | 'torch' | 'sklearn';
+
+export interface TypeMappingConfig {
+  presets?: TypePreset[];
+}
+
+export interface BridgeInfo {
+  protocol: string;
+  protocolVersion: number;
+  bridge: 'python-subprocess';
+  pythonVersion: string;
+  pid: number;
+  codecFallback: 'json' | 'none';
+  arrowAvailable: boolean;
+  instances: number;
+}
+
+// Analysis and generation results
+export interface AnalysisResult {
+  module: PythonModule;
+  errors: AnalysisError[];
+  warnings: AnalysisWarning[];
+  dependencies: string[];
+  statistics: AnalysisStatistics;
+}
+
+export interface AnalysisError {
+  type: 'syntax' | 'import' | 'type' | 'unsupported';
+  message: string;
+  line?: number;
+  column?: number;
+  file?: string;
+}
+
+export interface AnalysisWarning {
+  type: 'missing-type' | 'deprecated' | 'performance' | 'compatibility';
+  message: string;
+  line?: number;
+  column?: number;
+  file?: string;
+}
+
+export interface AnalysisStatistics {
+  functionsAnalyzed: number;
+  classesAnalyzed: number;
+  typeHintsCoverage: number;
+  estimatedComplexity: number;
+}
+
+export interface GeneratedCode {
+  typescript: string;
+  declaration: string;
+  sourceMap?: string;
+  metadata: GenerationMetadata;
+}
+
+export interface GenerationMetadata {
+  generatedAt: Date;
+  sourceFiles: string[];
+  runtime: RuntimeStrategy;
+  optimizations: string[];
+}
+
+// Runtime bridge interface
+export interface RuntimeExecution {
+  call<T = unknown>(
+    module: string,
+    functionName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T>;
+
+  instantiate<T = unknown>(
+    module: string,
+    className: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T>;
+
+  callMethod<T = unknown>(
+    handle: string,
+    methodName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T>;
+
+  disposeInstance(handle: string): Promise<void>;
+
+  dispose(): Promise<void>;
+}
+
+// Utility types
+export type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
+};
+
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+export type RequiredKeys<T> = {
+  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+
+export type OptionalKeys<T> = {
+  [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
+}[keyof T];