nodepyx 1.0.0

package/src/utils/ErrorTranslator.ts

@@ -0,0 +1,220 @@
+/**
+ * nodepyx — Error Translator
+ * Converts Python exceptions into proper JavaScript Error subclasses.
+ * Preserves full traceback, exception type, and chained causes.
+ */
+
+import type { PyErrorInfo } from '../types/python';
+
+/**
+ * Base class for all Python-originating errors.
+ * Provides access to Python-specific error metadata.
+ */
+export class PythonError extends Error {
+  /** Python exception class name (e.g. 'ValueError', 'FileNotFoundError') */
+  readonly pythonType: string;
+  /** Python module where the exception originated */
+  readonly pythonModule: string;
+  /** Full Python traceback string */
+  readonly traceback: string;
+  /** Original PyErrorInfo object */
+  readonly pyErrorInfo: PyErrorInfo;
+
+  constructor(info: PyErrorInfo) {
+    super(`[Python ${info.type}] ${info.message}`);
+    this.name = 'PythonError';
+    this.pythonType = info.type;
+    this.pythonModule = info.module ?? 'builtins';
+    this.traceback = info.traceback;
+    this.pyErrorInfo = info;
+
+    // Maintain proper prototype chain
+    Object.setPrototypeOf(this, new.target.prototype);
+
+    // Capture stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, PythonError);
+    }
+  }
+
+  /** Format error with Python traceback for display */
+  format(): string {
+    return [
+      `PythonError: ${this.pythonType}: ${this.pyErrorInfo.message}`,
+      '',
+      '--- Python Traceback ---',
+      this.traceback,
+      '--- Node.js Stack ---',
+      this.stack ?? '',
+    ].join('\n');
+  }
+}
+
+// ─── Specific Python Exception Subclasses ──────────────────────────────────
+
+export class PythonValueError extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonValueError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonTypeError extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonTypeError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonKeyError extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonKeyError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonIndexError extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonIndexError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonAttributeError extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonAttributeError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonImportError extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonImportError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonModuleNotFoundError extends PythonImportError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonModuleNotFoundError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonFileNotFoundError extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonFileNotFoundError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonPermissionError extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonPermissionError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonRuntimeError extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonRuntimeError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonMemoryError extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonMemoryError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonStopIteration extends PythonError {
+  constructor(info: PyErrorInfo) {
+    super(info);
+    this.name = 'PythonStopIteration';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class PythonTimeoutError extends Error {
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number, operation: string) {
+    super(`Python operation timed out after ${timeoutMs}ms: ${operation}`);
+    this.name = 'PythonTimeoutError';
+    this.timeoutMs = timeoutMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class nodepyxNotInitializedError extends Error {
+  constructor(message = 'nodepyx is not initialized. Call nodepyx.init() first.') {
+    super(message);
+    this.name = 'nodepyxNotInitializedError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class nodepyxShutdownError extends Error {
+  constructor(message = 'nodepyx runtime has been shut down.') {
+    super(message);
+    this.name = 'nodepyxShutdownError';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+// ─── Error Translation Map ──────────────────────────────────────────────────
+
+type PythonErrorConstructor = new (info: PyErrorInfo) => PythonError;
+
+const EXCEPTION_MAP: Record<string, PythonErrorConstructor> = {
+  ValueError: PythonValueError,
+  TypeError: PythonTypeError,
+  KeyError: PythonKeyError,
+  IndexError: PythonIndexError,
+  AttributeError: PythonAttributeError,
+  ImportError: PythonImportError,
+  ModuleNotFoundError: PythonModuleNotFoundError,
+  FileNotFoundError: PythonFileNotFoundError,
+  PermissionError: PythonPermissionError,
+  RuntimeError: PythonRuntimeError,
+  MemoryError: PythonMemoryError,
+  StopIteration: PythonStopIteration,
+  StopAsyncIteration: PythonStopIteration,
+};
+
+/**
+ * Translates a PyErrorInfo (from the C++ addon) into the appropriate
+ * JavaScript Error subclass. Falls back to generic PythonError.
+ */
+export function translatePythonError(info: PyErrorInfo): PythonError {
+  const Ctor = EXCEPTION_MAP[info.type] ?? PythonError;
+  return new Ctor(info);
+}
+
+/**
+ * Type guard: checks whether a value is a PythonError.
+ */
+export function isPythonError(value: unknown): value is PythonError {
+  return value instanceof PythonError;
+}
+
+/**
+ * Type guard: checks whether a value is a specific Python exception type.
+ */
+export function isPythonErrorOfType(value: unknown, pythonType: string): value is PythonError {
+  return value instanceof PythonError && value.pythonType === pythonType;
+}
+

package/src/utils/Logger.ts

@@ -0,0 +1,119 @@
+/**
+ * nodepyx — Logger
+ * Structured logger with level filtering and colorized output.
+ */
+
+import type { LogLevel } from '../types/config';
+
+const LEVELS: Record<LogLevel, number> = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+};
+
+const COLORS = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+};
+
+function colorize(color: keyof typeof COLORS, text: string): string {
+  if (!process.stdout.isTTY) {return text;}
+  return `${COLORS[color]}${text}${COLORS.reset}`;
+}
+
+function formatTimestamp(): string {
+  return new Date().toISOString().replace('T', ' ').replace('Z', '');
+}
+
+export class Logger {
+  private _level: LogLevel;
+  private _prefix: string;
+  private static _globalLevel: LogLevel = 'warn';
+
+  constructor(prefix: string, level?: LogLevel) {
+    this._prefix = prefix;
+    this._level = level ?? Logger._globalLevel;
+  }
+
+  static setGlobalLevel(level: LogLevel): void {
+    Logger._globalLevel = level;
+  }
+
+  setLevel(level: LogLevel): void {
+    this._level = level;
+  }
+
+  private _shouldLog(level: LogLevel): boolean {
+    return LEVELS[level] <= LEVELS[this._level];
+  }
+
+  private _format(level: string, message: string, data?: unknown): string {
+    const ts = colorize('gray', formatTimestamp());
+    const lvl = level;
+    const prefix = colorize('blue', `[${this._prefix}]`);
+    let line = `${ts} ${lvl} ${prefix} ${message}`;
+    if (data !== undefined) {
+      const dataStr = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+      line += `\n${colorize('gray', dataStr)}`;
+    }
+    return line;
+  }
+
+  error(message: string, data?: unknown): void {
+    if (!this._shouldLog('error')) {return;}
+    const lvl = colorize('red', 'ERROR');
+    console.error(this._format(lvl, message, data));
+  }
+
+  warn(message: string, data?: unknown): void {
+    if (!this._shouldLog('warn')) {return;}
+    const lvl = colorize('yellow', 'WARN ');
+    console.warn(this._format(lvl, message, data));
+  }
+
+  info(message: string, data?: unknown): void {
+    if (!this._shouldLog('info')) {return;}
+    const lvl = colorize('cyan', 'INFO ');
+    console.info(this._format(lvl, message, data));
+  }
+
+  debug(message: string, data?: unknown): void {
+    if (!this._shouldLog('debug')) {return;}
+    const lvl = colorize('gray', 'DEBUG');
+    console.debug(this._format(lvl, message, data));
+  }
+
+  success(message: string, data?: unknown): void {
+    if (!this._shouldLog('info')) {return;}
+    const lvl = colorize('green', 'OK   ');
+    console.info(this._format(lvl, message, data));
+  }
+
+  time(label: string): () => void {
+    const start = performance.now();
+    return () => {
+      const elapsed = (performance.now() - start).toFixed(2);
+      this.debug(`${label} completed in ${elapsed}ms`);
+    };
+  }
+
+  child(subPrefix: string): Logger {
+    return new Logger(`${this._prefix}:${subPrefix}`, this._level);
+  }
+}
+
+/** Global logger factory */
+export function createLogger(prefix: string, level?: LogLevel): Logger {
+  return new Logger(prefix, level);
+}
+
+/** Default nodepyx logger */
+export const logger = createLogger('nodepyx');
+

package/src/utils/MemoryMonitor.ts

@@ -0,0 +1,175 @@
+/**
+ * nodepyx — Memory Monitor
+ * Tracks Python object references, heap usage, and triggers GC when needed.
+ */
+
+import { Logger } from './Logger';
+import type { NativeAddon } from '../types/addon';
+
+export interface MemorySnapshot {
+  timestamp: number;
+  pythonHeapBytes: number;
+  pythonHeapPeakBytes: number;
+  trackedObjects: number;
+  pendingCallbacks: number;
+  nodeHeapUsed: number;
+  nodeHeapTotal: number;
+  nodeExternal: number;
+}
+
+export interface MemoryThresholds {
+  /** Trigger GC when Python heap exceeds this (bytes). Default: 1GB */
+  gcThreshold: number;
+  /** Emit warning when tracked objects exceed this. Default: 10000 */
+  objectWarningCount: number;
+  /** Emit warning when pending callbacks exceed this. Default: 500 */
+  callbackWarningCount: number;
+}
+
+export class MemoryMonitor {
+  private readonly _logger: Logger;
+  private _addon: NativeAddon | null = null;
+  private _snapshots: MemorySnapshot[] = [];
+  private _maxSnapshots = 100;
+  private _monitorInterval: NodeJS.Timeout | null = null;
+  private _thresholds: MemoryThresholds;
+  private _gcRunning = false;
+
+  constructor(thresholds?: Partial<MemoryThresholds>) {
+    this._logger = new Logger('MemoryMonitor');
+    this._thresholds = {
+      gcThreshold: this._parseBytes('1GB'),
+      objectWarningCount: 10000,
+      callbackWarningCount: 500,
+      ...thresholds,
+    };
+  }
+
+  attach(addon: NativeAddon): void {
+    this._addon = addon;
+  }
+
+  startMonitoring(intervalMs = 5000): void {
+    if (this._monitorInterval) {return;}
+    this._monitorInterval = setInterval(() => {
+      this._checkMemory().catch(err => {
+        this._logger.error('Memory check failed', err);
+      });
+    }, intervalMs);
+
+    // Don't keep event loop alive
+    if (this._monitorInterval.unref) {
+      this._monitorInterval.unref();
+    }
+
+    this._logger.debug(`Memory monitoring started (interval: ${intervalMs}ms)`);
+  }
+
+  stopMonitoring(): void {
+    if (this._monitorInterval) {
+      clearInterval(this._monitorInterval);
+      this._monitorInterval = null;
+      this._logger.debug('Memory monitoring stopped');
+    }
+  }
+
+  async takeSnapshot(): Promise<MemorySnapshot> {
+    const nodeHeap = process.memoryUsage();
+    let pythonStats = { pythonHeapBytes: 0, pythonHeapPeakBytes: 0, trackedObjects: 0, pendingCallbacks: 0 };
+
+    if (this._addon) {
+      const stats = this._addon.getMemoryStats();
+      pythonStats = {
+        pythonHeapBytes: stats.pythonHeapBytes,
+        pythonHeapPeakBytes: stats.pythonHeapPeakBytes,
+        trackedObjects: stats.trackedObjects,
+        pendingCallbacks: stats.pendingCallbacks,
+      };
+    }
+
+    const snapshot: MemorySnapshot = {
+      timestamp: Date.now(),
+      ...pythonStats,
+      nodeHeapUsed: nodeHeap.heapUsed,
+      nodeHeapTotal: nodeHeap.heapTotal,
+      nodeExternal: nodeHeap.external,
+    };
+
+    this._snapshots.push(snapshot);
+    if (this._snapshots.length > this._maxSnapshots) {
+      this._snapshots.shift();
+    }
+
+    return snapshot;
+  }
+
+  getSnapshots(): MemorySnapshot[] {
+    return [...this._snapshots];
+  }
+
+  getLatestSnapshot(): MemorySnapshot | null {
+    return this._snapshots[this._snapshots.length - 1] ?? null;
+  }
+
+  async forceGC(): Promise<void> {
+    if (this._gcRunning || !this._addon) {return;}
+    this._gcRunning = true;
+    try {
+      this._logger.debug('Running Python garbage collection...');
+      await this._addon.collectGarbage();
+      this._logger.debug('Python GC completed');
+    } finally {
+      this._gcRunning = false;
+    }
+  }
+
+  private async _checkMemory(): Promise<void> {
+    const snapshot = await this.takeSnapshot();
+
+    // Check Python heap threshold
+    if (snapshot.pythonHeapBytes > this._thresholds.gcThreshold) {
+      this._logger.warn(
+        `Python heap (${this._formatBytes(snapshot.pythonHeapBytes)}) exceeded GC threshold ` +
+        `(${this._formatBytes(this._thresholds.gcThreshold)}). Running GC...`
+      );
+      await this.forceGC();
+    }
+
+    // Check tracked objects
+    if (snapshot.trackedObjects > this._thresholds.objectWarningCount) {
+      this._logger.warn(
+        `High Python object count: ${snapshot.trackedObjects} tracked objects`
+      );
+    }
+
+    // Check pending callbacks
+    if (snapshot.pendingCallbacks > this._thresholds.callbackWarningCount) {
+      this._logger.warn(
+        `High pending callback count: ${snapshot.pendingCallbacks}`
+      );
+    }
+  }
+
+  private _parseBytes(str: string): number {
+    const match = str.match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB|TB)?$/i);
+    if (!match) {return 1_073_741_824;} // 1GB default
+    const value = parseFloat(match[1]);
+    const unit = (match[2] ?? 'B').toUpperCase();
+    const units: Record<string, number> = {
+      B: 1,
+      KB: 1024,
+      MB: 1024 ** 2,
+      GB: 1024 ** 3,
+      TB: 1024 ** 4,
+    };
+    return Math.floor(value * (units[unit] ?? 1));
+  }
+
+  private _formatBytes(bytes: number): string {
+    if (bytes < 1024) {return `${bytes}B`;}
+    if (bytes < 1024 ** 2) {return `${(bytes / 1024).toFixed(1)}KB`;}
+    if (bytes < 1024 ** 3) {return `${(bytes / 1024 ** 2).toFixed(1)}MB`;}
+    return `${(bytes / 1024 ** 3).toFixed(2)}GB`;
+  }
+}
+