tywrap 0.1.0

package/src/index.ts

@@ -0,0 +1,83 @@
+/**
+ * tywrap - TypeScript wrapper for Python libraries with full type safety
+ *
+ * @description Build-time code generation system that makes Python libraries
+ * feel native in TypeScript with zero runtime overhead
+ */
+
+import { tywrap } from './tywrap.js';
+
+export type { TywrapConfig } from './config/index.js';
+export { defineConfig, resolveConfig } from './config/index.js';
+export { RuntimeBridge } from './runtime/base.js';
+export {
+  BridgeError,
+  BridgeProtocolError,
+  BridgeTimeoutError,
+  BridgeDisposedError,
+  BridgeExecutionError,
+} 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';
+
+// Core types
+export type {
+  PythonModule,
+  PythonFunction,
+  PythonClass,
+  PythonType,
+  PrimitiveType,
+  CollectionType,
+  UnionType,
+  OptionalType,
+  CustomType,
+  GenericType,
+  Parameter,
+  Property,
+  PythonImport,
+  TypescriptType,
+  RuntimeStrategy,
+  TywrapOptions,
+  PythonModuleConfig,
+  OutputConfig,
+  RuntimeConfig,
+  PyodideConfig,
+  NodeConfig,
+  HttpConfig,
+  PerformanceConfig,
+  DevelopmentConfig,
+  TypeMappingConfig,
+  TypePreset,
+  BridgeInfo,
+  AnalysisResult,
+  AnalysisError,
+  AnalysisWarning,
+  AnalysisStatistics,
+  GeneratedCode,
+} from './types/index.js';
+
+// Main API
+export { tywrap } from './tywrap.js';
+export { generate } from './tywrap.js';
+
+// Runtime detection utilities
+export { detectRuntime, isNodejs, isDeno, isBun, isBrowser } from './utils/runtime.js';
+export {
+  decodeValue,
+  decodeValueAsync,
+  registerArrowDecoder,
+  clearArrowDecoder,
+} from './utils/codec.js';
+
+// Version info
+export const VERSION = '0.1.0';
+
+/**
+ * Quick setup function for getting started
+ */
+// Default export for convenience
+export default tywrap;

package/src/runtime/base.ts

@@ -0,0 +1,32 @@
+/**
+ * Base runtime bridge
+ */
+
+import type { RuntimeExecution } from '../types/index.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>;
+
+  abstract dispose(): Promise<void>;
+}

package/src/runtime/errors.ts

@@ -0,0 +1,19 @@
+export class BridgeError extends Error {
+  code?: string;
+  constructor(message: string, options?: { code?: string; cause?: unknown }) {
+    super(message);
+    this.name = new.target.name;
+    this.code = options?.code;
+    if (options?.cause) {
+      (this as Error & { cause?: unknown }).cause = options.cause;
+    }
+  }
+}
+
+export class BridgeProtocolError extends BridgeError {}
+export class BridgeTimeoutError extends BridgeError {}
+export class BridgeDisposedError extends BridgeError {}
+
+export class BridgeExecutionError extends BridgeError {
+  traceback?: string;
+}

package/src/runtime/http.ts

@@ -0,0 +1,132 @@
+/**
+ * HTTP runtime bridge
+ */
+
+import { decodeValueAsync } from '../utils/codec.js';
+
+import { RuntimeBridge } from './base.js';
+
+export interface HttpBridgeOptions {
+  baseURL: string;
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+}
+
+interface HttpCallPayload {
+  module: string;
+  functionName: string;
+  args: unknown[];
+  kwargs?: Record<string, unknown>;
+}
+
+interface HttpInstantiatePayload {
+  module: string;
+  className: string;
+  args: unknown[];
+  kwargs?: Record<string, unknown>;
+}
+
+interface HttpCallMethodPayload {
+  handle: string;
+  methodName: string;
+  args: unknown[];
+  kwargs?: Record<string, unknown>;
+}
+
+interface HttpDisposePayload {
+  handle: string;
+}
+
+export class HttpBridge extends RuntimeBridge {
+  private readonly baseURL: string;
+  private readonly headers: Record<string, string>;
+  private readonly timeoutMs: number;
+
+  constructor(options: HttpBridgeOptions = { baseURL: 'http://localhost:8000' }) {
+    super();
+    this.baseURL = options.baseURL.replace(/\/$/, '');
+    this.headers = { 'content-type': 'application/json', ...(options.headers ?? {}) };
+    this.timeoutMs = options.timeoutMs ?? 30000;
+  }
+
+  async call<T = unknown>(
+    module: string,
+    functionName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    const payload: HttpCallPayload = { module, functionName, args, kwargs };
+    const res = await this.post(`${this.baseURL}/call`, payload);
+    return (await decodeValueAsync(res)) as T;
+  }
+
+  async instantiate<T = unknown>(
+    module: string,
+    className: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    const payload: HttpInstantiatePayload = { module, className, args, kwargs };
+    const res = await this.post(`${this.baseURL}/instantiate`, payload);
+    return (await decodeValueAsync(res)) as T;
+  }
+
+  async callMethod<T = unknown>(
+    handle: string,
+    methodName: string,
+    args: unknown[],
+    kwargs?: Record<string, unknown>
+  ): Promise<T> {
+    const payload: HttpCallMethodPayload = { handle, methodName, args, kwargs };
+    const res = await this.post(`${this.baseURL}/call_method`, payload);
+    return (await decodeValueAsync(res)) as T;
+  }
+
+  async disposeInstance(handle: string): Promise<void> {
+    const payload: HttpDisposePayload = { handle };
+    await this.post(`${this.baseURL}/dispose_instance`, payload);
+  }
+
+  async dispose(): Promise<void> {
+    // stateless
+  }
+
+  private async post(url: string, body: unknown): Promise<unknown> {
+    const controller = typeof AbortController !== 'undefined' ? new AbortController() : undefined;
+    const timer = controller ? setTimeout(() => controller.abort(), this.timeoutMs) : undefined;
+    try {
+      const resp = await fetch(url, {
+        method: 'POST',
+        headers: this.headers,
+        body: JSON.stringify(body),
+        signal: controller?.signal,
+      });
+      if (!resp.ok) {
+        const text = await safeText(resp);
+        throw new Error(`HTTP ${resp.status}: ${text || resp.statusText}`);
+      }
+      const ct = resp.headers.get('content-type') ?? '';
+      if (ct.includes('application/json')) {
+        return (await resp.json()) as unknown;
+      }
+      const text = await resp.text();
+      try {
+        return JSON.parse(text) as unknown;
+      } catch {
+        return text as unknown;
+      }
+    } finally {
+      if (timer) {
+        clearTimeout(timer);
+      }
+    }
+  }
+}
+
+async function safeText(resp: Response): Promise<string> {
+  try {
+    return await resp.text();
+  } catch {
+    return '';
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Runtime bridge registry for generated wrappers.
+ */
+
+import type { RuntimeExecution } from '../types/index.js';
+
+let runtimeBridge: RuntimeExecution | null = null;
+
+export function setRuntimeBridge(bridge: RuntimeExecution): void {
+  runtimeBridge = bridge;
+}
+
+export function getRuntimeBridge(): RuntimeExecution {
+  if (!runtimeBridge) {
+    throw new Error(
+      'No runtime bridge configured. Call setRuntimeBridge(new NodeBridge(...)) or setRuntimeBridge(new PyodideBridge(...)) before using generated modules.'
+    );
+  }
+  return runtimeBridge;
+}
+
+export function clearRuntimeBridge(): void {
+  runtimeBridge = null;
+}