tywrap 0.1.0

package/src/utils/codec.ts

@@ -0,0 +1,275 @@
+/**
+ * Codec utilities for transporting rich Python values over JSON
+ *
+ * Python bridge emits envelopes like:
+ * { "__tywrap__": "dataframe", "encoding": "arrow", "b64": "..." }
+ * Optionally with ndarray fallback: { "__tywrap__": "ndarray", "encoding": "json", ... }
+ * SciPy sparse: { "__tywrap__": "scipy.sparse", "encoding": "json", "format": "csr", ... }
+ * Torch tensors: { "__tywrap__": "torch.tensor", "encoding": "ndarray", "value": { ... } }
+ * Sklearn estimators: { "__tywrap__": "sklearn.estimator", "encoding": "json", ... }
+ */
+
+// Avoid hard dependency on apache-arrow types at compile time to keep install optional.
+export type ArrowTable = { readonly numCols?: number; readonly numRows?: number } & Record<
+  string,
+  unknown
+>;
+
+export interface SparseMatrix {
+  format: 'csr' | 'csc' | 'coo';
+  shape: readonly number[];
+  data: readonly unknown[];
+  indices?: readonly number[];
+  indptr?: readonly number[];
+  row?: readonly number[];
+  col?: readonly number[];
+  dtype?: string;
+}
+
+export interface TorchTensor {
+  data: unknown;
+  shape?: readonly number[];
+  dtype?: string;
+  device?: string;
+}
+
+export interface SklearnEstimator {
+  className: string;
+  module: string;
+  version?: string;
+  params: Record<string, unknown>;
+}
+
+export type CodecEnvelope =
+  | {
+      readonly __tywrap__: 'dataframe';
+      readonly encoding: 'arrow';
+      readonly b64: string;
+    }
+  | {
+      readonly __tywrap__: 'series';
+      readonly encoding: 'arrow' | 'json';
+      readonly b64?: string;
+      readonly data?: unknown;
+      readonly name?: string | null;
+    }
+  | {
+      readonly __tywrap__: 'ndarray';
+      readonly encoding: 'arrow' | 'json';
+      readonly b64?: string; // when encoding=arrow
+      readonly data?: unknown; // when encoding=json
+      readonly shape?: readonly number[];
+    }
+  | {
+      readonly __tywrap__: 'scipy.sparse';
+      readonly encoding: 'json';
+      readonly format: 'csr' | 'csc' | 'coo';
+      readonly shape: readonly number[];
+      readonly data: readonly unknown[];
+      readonly indices?: readonly number[];
+      readonly indptr?: readonly number[];
+      readonly row?: readonly number[];
+      readonly col?: readonly number[];
+      readonly dtype?: string;
+    }
+  | {
+      readonly __tywrap__: 'torch.tensor';
+      readonly encoding: 'ndarray';
+      readonly value: unknown;
+      readonly shape?: readonly number[];
+      readonly dtype?: string;
+      readonly device?: string;
+    }
+  | {
+      readonly __tywrap__: 'sklearn.estimator';
+      readonly encoding: 'json';
+      readonly className: string;
+      readonly module: string;
+      readonly version?: string;
+      readonly params: Record<string, unknown>;
+    };
+
+export type DecodedValue = ArrowTable | Uint8Array | SparseMatrix | TorchTensor | SklearnEstimator | unknown;
+
+let arrowTableFrom: ((bytes: Uint8Array) => ArrowTable | Uint8Array) | undefined;
+
+export function registerArrowDecoder(
+  decoder: (bytes: Uint8Array) => ArrowTable | Uint8Array
+): void {
+  arrowTableFrom = decoder;
+}
+
+export function clearArrowDecoder(): void {
+  arrowTableFrom = undefined;
+}
+
+/**
+ * Whether an Arrow decoder has been registered for this process.
+ */
+export function hasArrowDecoder(): boolean {
+  return typeof arrowTableFrom === 'function';
+}
+
+function isObject(value: unknown): value is { [k: string]: unknown } {
+  return typeof value === 'object' && value !== null;
+}
+
+function fromBase64(b64: string): Uint8Array {
+  if (typeof Buffer !== 'undefined') {
+    const buf = Buffer.from(b64, 'base64');
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.length);
+  }
+  if (globalThis.atob) {
+    const bin = globalThis.atob(b64);
+    const arr = Array.from(bin, c => c.charCodeAt(0));
+    return new Uint8Array(arr);
+  }
+  throw new Error('Base64 decoding is not available in this runtime');
+}
+
+function requireArrowDecoder(): (bytes: Uint8Array) => ArrowTable | Uint8Array {
+  if (!arrowTableFrom) {
+    throw new Error(
+      'Arrow decoder not registered. Call registerArrowDecoder(...) or set TYWRAP_CODEC_FALLBACK=json in Python.'
+    );
+  }
+  return arrowTableFrom;
+}
+
+async function tryDecodeArrowTable(bytes: Uint8Array): Promise<ArrowTable | Uint8Array> {
+  const decoder = requireArrowDecoder();
+  try {
+    return decoder(bytes);
+  } catch (err) {
+    throw new Error(`Arrow decode failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function decodeEnvelope<T>(value: unknown, decodeArrow: (bytes: Uint8Array) => T): T | unknown {
+  if (!isObject(value)) {
+    return value;
+  }
+  const marker = (value as { __tywrap__?: unknown }).__tywrap__;
+  if (
+    (marker === 'dataframe' || marker === 'series') &&
+    (value as { encoding?: unknown }).encoding === 'arrow' &&
+    typeof (value as { b64?: unknown }).b64 === 'string'
+  ) {
+    const bytes = fromBase64(String((value as { b64: string }).b64));
+    return decodeArrow(bytes);
+  }
+  if (
+    marker === 'dataframe' &&
+    (value as { encoding?: unknown }).encoding === 'json' &&
+    'data' in (value as object)
+  ) {
+    return (value as { data: unknown }).data;
+  }
+  if (
+    marker === 'series' &&
+    (value as { encoding?: unknown }).encoding === 'json' &&
+    'data' in (value as object)
+  ) {
+    return (value as { data: unknown }).data;
+  }
+  if (marker === 'ndarray') {
+    if (
+      (value as { encoding?: unknown }).encoding === 'arrow' &&
+      typeof (value as { b64?: unknown }).b64 === 'string'
+    ) {
+      const bytes = fromBase64(String((value as { b64: string }).b64));
+      return decodeArrow(bytes);
+    }
+    if ((value as { encoding?: unknown }).encoding === 'json' && 'data' in (value as object)) {
+      return (value as { data: unknown }).data;
+    }
+  }
+  if (
+    marker === 'scipy.sparse' &&
+    (value as { encoding?: unknown }).encoding === 'json' &&
+    typeof (value as { format?: unknown }).format === 'string' &&
+    Array.isArray((value as { shape?: unknown }).shape) &&
+    Array.isArray((value as { data?: unknown }).data)
+  ) {
+    const sparse = value as {
+      format: 'csr' | 'csc' | 'coo';
+      shape: readonly number[];
+      data: readonly unknown[];
+      indices?: readonly number[];
+      indptr?: readonly number[];
+      row?: readonly number[];
+      col?: readonly number[];
+      dtype?: string;
+    };
+    return {
+      format: sparse.format,
+      shape: sparse.shape,
+      data: sparse.data,
+      indices: sparse.indices,
+      indptr: sparse.indptr,
+      row: sparse.row,
+      col: sparse.col,
+      dtype: sparse.dtype,
+    } satisfies SparseMatrix;
+  }
+  if (marker === 'torch.tensor' && (value as { encoding?: unknown }).encoding === 'ndarray') {
+    const torchValue = value as {
+      value?: unknown;
+      shape?: readonly number[];
+      dtype?: string;
+      device?: string;
+    };
+    if ('value' in (torchValue as object)) {
+      const decoded = decodeEnvelope(torchValue.value, decodeArrow);
+      return {
+        data: decoded,
+        shape: torchValue.shape,
+        dtype: torchValue.dtype,
+        device: torchValue.device,
+      } satisfies TorchTensor;
+    }
+  }
+  if (
+    marker === 'sklearn.estimator' &&
+    (value as { encoding?: unknown }).encoding === 'json' &&
+    typeof (value as { className?: unknown }).className === 'string' &&
+    typeof (value as { module?: unknown }).module === 'string' &&
+    isObject((value as { params?: unknown }).params)
+  ) {
+    const estimator = value as {
+      className: string;
+      module: string;
+      version?: string;
+      params: Record<string, unknown>;
+    };
+    return {
+      className: estimator.className,
+      module: estimator.module,
+      version: estimator.version,
+      params: estimator.params,
+    } satisfies SklearnEstimator;
+  }
+  return value as unknown;
+}
+
+/**
+ * Decode values produced by the Python bridge.
+ */
+export async function decodeValueAsync(value: unknown): Promise<DecodedValue> {
+  return await decodeEnvelope(value, tryDecodeArrowTable);
+}
+
+/**
+ * Synchronous decode. Arrow decoding requires a registered decoder.
+ */
+export function decodeValue(value: unknown): DecodedValue {
+  const decodeArrow = (bytes: Uint8Array): DecodedValue => {
+    const decoder = requireArrowDecoder();
+    try {
+      return decoder(bytes);
+    } catch (err) {
+      throw new Error(`Arrow decode failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  };
+  return decodeEnvelope(value, decodeArrow);
+}

package/src/utils/logger.ts

@@ -0,0 +1,201 @@
+/**
+ * Structured Logger for tywrap
+ * Provides log levels, optional JSON output, and component context
+ */
+
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'SILENT';
+
+const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+  SILENT: 4,
+};
+
+export interface LogContext {
+  [key: string]: unknown;
+}
+
+export interface LoggerOptions {
+  /** Minimum log level to output. Default: 'WARN' */
+  level?: LogLevel;
+  /** Component name for context (e.g., 'Cache', 'Worker'). */
+  component?: string;
+  /** Output logs as JSON. Default: false */
+  jsonOutput?: boolean;
+  /** Enable/disable logging. Default: true */
+  enabled?: boolean;
+  /** Output stream. Default: process.stderr */
+  output?: NodeJS.WritableStream;
+}
+
+export interface Logger {
+  debug(message: string, context?: LogContext): void;
+  info(message: string, context?: LogContext): void;
+  warn(message: string, context?: LogContext): void;
+  error(message: string, context?: LogContext): void;
+  /** Create a child logger with a component prefix */
+  child(component: string): Logger;
+  /** Check if a log level is enabled */
+  isLevelEnabled(level: LogLevel): boolean;
+  /** Update logger options */
+  configure(options: Partial<LoggerOptions>): void;
+}
+
+interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  component?: string;
+  message: string;
+  context?: LogContext;
+}
+
+function getEnvLogLevel(): LogLevel | undefined {
+  if (typeof process === 'undefined' || !process.env) {
+    return undefined;
+  }
+  const envLevel = process.env.TYWRAP_LOG_LEVEL?.toUpperCase();
+  if (envLevel && envLevel in LOG_LEVEL_PRIORITY) {
+    return envLevel as LogLevel;
+  }
+  return undefined;
+}
+
+function getEnvJsonOutput(): boolean {
+  if (typeof process === 'undefined' || !process.env) {
+    return false;
+  }
+  return process.env.TYWRAP_LOG_JSON === 'true' || process.env.TYWRAP_LOG_JSON === '1';
+}
+
+function formatHumanReadable(entry: LogEntry): string {
+  const componentPart = entry.component ? ` [${entry.component}]` : '';
+  const contextPart = entry.context && Object.keys(entry.context).length > 0
+    ? ` ${JSON.stringify(entry.context)}`
+    : '';
+  return `${entry.timestamp} [${entry.level}]${componentPart} ${entry.message}${contextPart}`;
+}
+
+function formatJson(entry: LogEntry): string {
+  const output: Record<string, unknown> = {
+    ts: entry.timestamp,
+    level: entry.level,
+  };
+  if (entry.component) {
+    output.component = entry.component;
+  }
+  output.msg = entry.message;
+  if (entry.context && Object.keys(entry.context).length > 0) {
+    Object.assign(output, entry.context);
+  }
+  return JSON.stringify(output);
+}
+
+class LoggerImpl implements Logger {
+  private level: LogLevel;
+  private component?: string;
+  private jsonOutput: boolean;
+  private enabled: boolean;
+  private output: NodeJS.WritableStream;
+
+  constructor(options: LoggerOptions = {}) {
+    this.level = options.level ?? getEnvLogLevel() ?? 'WARN';
+    this.component = options.component;
+    this.jsonOutput = options.jsonOutput ?? getEnvJsonOutput();
+    this.enabled = options.enabled ?? true;
+    this.output = options.output ?? (typeof process !== 'undefined' ? process.stderr : undefined as unknown as NodeJS.WritableStream);
+  }
+
+  configure(options: Partial<LoggerOptions>): void {
+    if (options.level !== undefined) {
+      this.level = options.level;
+    }
+    if (options.component !== undefined) {
+      this.component = options.component;
+    }
+    if (options.jsonOutput !== undefined) {
+      this.jsonOutput = options.jsonOutput;
+    }
+    if (options.enabled !== undefined) {
+      this.enabled = options.enabled;
+    }
+    if (options.output !== undefined) {
+      this.output = options.output;
+    }
+  }
+
+  isLevelEnabled(level: LogLevel): boolean {
+    if (!this.enabled) {
+      return false;
+    }
+    return LOG_LEVEL_PRIORITY[level] >= LOG_LEVEL_PRIORITY[this.level];
+  }
+
+  private log(level: LogLevel, message: string, context?: LogContext): void {
+    // Early exit for performance - avoid string operations when disabled
+    if (!this.isLevelEnabled(level)) {
+      return;
+    }
+
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      component: this.component,
+      message,
+      context,
+    };
+
+    const formatted = this.jsonOutput ? formatJson(entry) : formatHumanReadable(entry);
+
+    if (this.output) {
+      this.output.write(`${formatted}\n`);
+    }
+  }
+
+  debug(message: string, context?: LogContext): void {
+    this.log('DEBUG', message, context);
+  }
+
+  info(message: string, context?: LogContext): void {
+    this.log('INFO', message, context);
+  }
+
+  warn(message: string, context?: LogContext): void {
+    this.log('WARN', message, context);
+  }
+
+  error(message: string, context?: LogContext): void {
+    this.log('ERROR', message, context);
+  }
+
+  child(component: string): Logger {
+    const childComponent = this.component
+      ? `${this.component}:${component}`
+      : component;
+
+    return new LoggerImpl({
+      level: this.level,
+      component: childComponent,
+      jsonOutput: this.jsonOutput,
+      enabled: this.enabled,
+      output: this.output,
+    });
+  }
+}
+
+/** Global logger instance */
+export const logger: Logger = new LoggerImpl();
+
+/** Create a new logger with custom options */
+export function createLogger(options: LoggerOptions = {}): Logger {
+  return new LoggerImpl(options);
+}
+
+/**
+ * Create component-specific loggers
+ * Usage: const log = getComponentLogger('Cache');
+ */
+export function getComponentLogger(component: string): Logger {
+  return logger.child(component);
+}