pynect 0.0.0-stage → 0.2.0

package/dist/utils/ErrorTranslator.d.ts

@@ -0,0 +1,83 @@
+/**
+ * pynect - 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 declare 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);
+    /** Format error with Python traceback for display */
+    format(): string;
+}
+export declare class PythonValueError extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonTypeError extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonKeyError extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonIndexError extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonAttributeError extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonImportError extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonModuleNotFoundError extends PythonImportError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonFileNotFoundError extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonPermissionError extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonRuntimeError extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonMemoryError extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonStopIteration extends PythonError {
+    constructor(info: PyErrorInfo);
+}
+export declare class PythonTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, operation: string);
+}
+export declare class PynectNotInitializedError extends Error {
+    constructor(message?: string);
+}
+export declare class PynectShutdownError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Translates a PyErrorInfo (from the C++ addon) into the appropriate
+ * JavaScript Error subclass. Falls back to generic PythonError.
+ */
+export declare function translatePythonError(info: PyErrorInfo): PythonError;
+/**
+ * Type guard: checks whether a value is a PythonError.
+ */
+export declare function isPythonError(value: unknown): value is PythonError;
+/**
+ * Type guard: checks whether a value is a specific Python exception type.
+ */
+export declare function isPythonErrorOfType(value: unknown, pythonType: string): value is PythonError;
+//# sourceMappingURL=ErrorTranslator.d.ts.map

package/dist/utils/ErrorTranslator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorTranslator.d.ts","sourceRoot":"","sources":["../../src/utils/ErrorTranslator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;gBAEtB,IAAI,EAAE,WAAW;IAiB7B,qDAAqD;IACrD,MAAM,IAAI,MAAM;CAUjB;AAID,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,cAAe,SAAQ,WAAW;gBACjC,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,gBAAiB,SAAQ,WAAW;gBACnC,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,oBAAqB,SAAQ,WAAW;gBACvC,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,iBAAkB,SAAQ,WAAW;gBACpC,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,yBAA0B,SAAQ,iBAAiB;gBAClD,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,uBAAwB,SAAQ,WAAW;gBAC1C,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,qBAAsB,SAAQ,WAAW;gBACxC,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,iBAAkB,SAAQ,WAAW;gBACpC,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,mBAAoB,SAAQ,WAAW;gBACtC,IAAI,EAAE,WAAW;CAK9B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAMjD;AAED,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,SAAyD;CAK7E;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,SAAuC;CAK3D;AAsBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAGnE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,IAAI,WAAW,CAE5F"}

package/dist/utils/ErrorTranslator.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * pynect - Error Translator
+ * Converts Python exceptions into proper JavaScript Error subclasses.
+ * Preserves full traceback, exception type, and chained causes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PynectShutdownError = exports.PynectNotInitializedError = exports.PythonTimeoutError = exports.PythonStopIteration = exports.PythonMemoryError = exports.PythonRuntimeError = exports.PythonPermissionError = exports.PythonFileNotFoundError = exports.PythonModuleNotFoundError = exports.PythonImportError = exports.PythonAttributeError = exports.PythonIndexError = exports.PythonKeyError = exports.PythonTypeError = exports.PythonValueError = exports.PythonError = void 0;
+exports.translatePythonError = translatePythonError;
+exports.isPythonError = isPythonError;
+exports.isPythonErrorOfType = isPythonErrorOfType;
+/**
+ * Base class for all Python-originating errors.
+ * Provides access to Python-specific error metadata.
+ */
+class PythonError extends Error {
+    /** Python exception class name (e.g. 'ValueError', 'FileNotFoundError') */
+    pythonType;
+    /** Python module where the exception originated */
+    pythonModule;
+    /** Full Python traceback string */
+    traceback;
+    /** Original PyErrorInfo object */
+    pyErrorInfo;
+    constructor(info) {
+        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() {
+        return [
+            `PythonError: ${this.pythonType}: ${this.pyErrorInfo.message}`,
+            '',
+            '--- Python Traceback ---',
+            this.traceback,
+            '--- Node.js Stack ---',
+            this.stack ?? '',
+        ].join('\n');
+    }
+}
+exports.PythonError = PythonError;
+// Specific Python Exception Subclasses
+class PythonValueError extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonValueError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonValueError = PythonValueError;
+class PythonTypeError extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonTypeError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonTypeError = PythonTypeError;
+class PythonKeyError extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonKeyError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonKeyError = PythonKeyError;
+class PythonIndexError extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonIndexError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonIndexError = PythonIndexError;
+class PythonAttributeError extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonAttributeError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonAttributeError = PythonAttributeError;
+class PythonImportError extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonImportError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonImportError = PythonImportError;
+class PythonModuleNotFoundError extends PythonImportError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonModuleNotFoundError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonModuleNotFoundError = PythonModuleNotFoundError;
+class PythonFileNotFoundError extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonFileNotFoundError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonFileNotFoundError = PythonFileNotFoundError;
+class PythonPermissionError extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonPermissionError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonPermissionError = PythonPermissionError;
+class PythonRuntimeError extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonRuntimeError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonRuntimeError = PythonRuntimeError;
+class PythonMemoryError extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonMemoryError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonMemoryError = PythonMemoryError;
+class PythonStopIteration extends PythonError {
+    constructor(info) {
+        super(info);
+        this.name = 'PythonStopIteration';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonStopIteration = PythonStopIteration;
+class PythonTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs, operation) {
+        super(`Python operation timed out after ${timeoutMs}ms: ${operation}`);
+        this.name = 'PythonTimeoutError';
+        this.timeoutMs = timeoutMs;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PythonTimeoutError = PythonTimeoutError;
+class PynectNotInitializedError extends Error {
+    constructor(message = 'pynect is not initialized. Call pynect.init() first.') {
+        super(message);
+        this.name = 'PynectNotInitializedError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PynectNotInitializedError = PynectNotInitializedError;
+class PynectShutdownError extends Error {
+    constructor(message = 'pynect runtime has been shut down.') {
+        super(message);
+        this.name = 'PynectShutdownError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PynectShutdownError = PynectShutdownError;
+const EXCEPTION_MAP = {
+    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.
+ */
+function translatePythonError(info) {
+    const Ctor = EXCEPTION_MAP[info.type] ?? PythonError;
+    return new Ctor(info);
+}
+/**
+ * Type guard: checks whether a value is a PythonError.
+ */
+function isPythonError(value) {
+    return value instanceof PythonError;
+}
+/**
+ * Type guard: checks whether a value is a specific Python exception type.
+ */
+function isPythonErrorOfType(value, pythonType) {
+    return value instanceof PythonError && value.pythonType === pythonType;
+}
+//# sourceMappingURL=ErrorTranslator.js.map

package/dist/utils/ErrorTranslator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorTranslator.js","sourceRoot":"","sources":["../../src/utils/ErrorTranslator.ts"],"names":[],"mappings":"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"}

package/dist/utils/Locking.d.ts

@@ -0,0 +1,3 @@
+import { type LockAction, type LockOptions, type LockPredicate, type LockResult } from 'loqkit';
+export declare function withPynectLock<TContext extends object, TResult>(context: TContext, action: LockAction<TContext, TResult>, predicate?: LockPredicate<TContext>, options?: LockOptions<TContext>): Promise<LockResult<TContext, TResult>>;
+//# sourceMappingURL=Locking.d.ts.map

package/dist/utils/Locking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Locking.d.ts","sourceRoot":"","sources":["../../src/utils/Locking.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,QAAQ,CAAC;AAEhB,wBAAsB,cAAc,CAAC,QAAQ,SAAS,MAAM,EAAE,OAAO,EACnE,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,EACrC,SAAS,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,EACnC,OAAO,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,GAC9B,OAAO,CAAC,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAIxC"}

package/dist/utils/Locking.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withPynectLock = withPynectLock;
+const loqkit_1 = require("loqkit");
+async function withPynectLock(context, action, predicate, options) {
+    return predicate
+        ? (0, loqkit_1.withLock)(context, action, predicate, options)
+        : (0, loqkit_1.withLock)(context, action, options);
+}
+//# sourceMappingURL=Locking.js.map

package/dist/utils/Locking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Locking.js","sourceRoot":"","sources":["../../src/utils/Locking.ts"],"names":[],"mappings":";;AAQA,wCASC;AAjBD,mCAMgB;AAET,KAAK,UAAU,cAAc,CAClC,OAAiB,EACjB,MAAqC,EACrC,SAAmC,EACnC,OAA+B;IAE/B,OAAO,SAAS;QACd,CAAC,CAAC,IAAA,iBAAQ,EAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC;QAC/C,CAAC,CAAC,IAAA,iBAAQ,EAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC"}

package/dist/utils/Logger.d.ts

@@ -0,0 +1,27 @@
+/**
+ * pynect - Logger
+ * Structured logger with level filtering and colorized output.
+ */
+import type { LogLevel } from '../types/config';
+export declare class Logger {
+    private _level;
+    private _prefix;
+    private static _globalLevel;
+    constructor(prefix: string, level?: LogLevel);
+    static setGlobalLevel(level: LogLevel): void;
+    setLevel(level: LogLevel): void;
+    private _shouldLog;
+    private _format;
+    error(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    success(message: string, data?: unknown): void;
+    time(label: string): () => void;
+    child(subPrefix: string): Logger;
+}
+/** Global logger factory */
+export declare function createLogger(prefix: string, level?: LogLevel): Logger;
+/** Default Pynect logger */
+export declare const logger: Logger;
+//# sourceMappingURL=Logger.d.ts.map

package/dist/utils/Logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/utils/Logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AA6BhD,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAC,YAAY,CAAoB;gBAEnC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ;IAK5C,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI5C,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,OAAO;IAYf,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM3C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM3C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM5C,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM9C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI;IAQ/B,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAGjC;AAED,4BAA4B;AAC5B,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAErE;AAED,4BAA4B;AAC5B,eAAO,MAAM,MAAM,QAAyB,CAAC"}

package/dist/utils/Logger.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * pynect - Logger
+ * Structured logger with level filtering and colorized output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = exports.Logger = void 0;
+exports.createLogger = createLogger;
+const LEVELS = {
+    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, text) {
+    if (!process.stdout.isTTY) {
+        return text;
+    }
+    return `${COLORS[color]}${text}${COLORS.reset}`;
+}
+function formatTimestamp() {
+    return new Date().toISOString().replace('T', ' ').replace('Z', '');
+}
+class Logger {
+    _level;
+    _prefix;
+    static _globalLevel = 'warn';
+    constructor(prefix, level) {
+        this._prefix = prefix;
+        this._level = level ?? Logger._globalLevel;
+    }
+    static setGlobalLevel(level) {
+        Logger._globalLevel = level;
+    }
+    setLevel(level) {
+        this._level = level;
+    }
+    _shouldLog(level) {
+        return LEVELS[level] <= LEVELS[this._level];
+    }
+    _format(level, message, data) {
+        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, data) {
+        if (!this._shouldLog('error')) {
+            return;
+        }
+        const lvl = colorize('red', 'ERROR');
+        console.error(this._format(lvl, message, data));
+    }
+    warn(message, data) {
+        if (!this._shouldLog('warn')) {
+            return;
+        }
+        const lvl = colorize('yellow', 'WARN ');
+        console.warn(this._format(lvl, message, data));
+    }
+    info(message, data) {
+        if (!this._shouldLog('info')) {
+            return;
+        }
+        const lvl = colorize('cyan', 'INFO ');
+        console.info(this._format(lvl, message, data));
+    }
+    debug(message, data) {
+        if (!this._shouldLog('debug')) {
+            return;
+        }
+        const lvl = colorize('gray', 'DEBUG');
+        console.debug(this._format(lvl, message, data));
+    }
+    success(message, data) {
+        if (!this._shouldLog('info')) {
+            return;
+        }
+        const lvl = colorize('green', 'OK   ');
+        console.info(this._format(lvl, message, data));
+    }
+    time(label) {
+        const start = performance.now();
+        return () => {
+            const elapsed = (performance.now() - start).toFixed(2);
+            this.debug(`${label} completed in ${elapsed}ms`);
+        };
+    }
+    child(subPrefix) {
+        return new Logger(`${this._prefix}:${subPrefix}`, this._level);
+    }
+}
+exports.Logger = Logger;
+/** Global logger factory */
+function createLogger(prefix, level) {
+    return new Logger(prefix, level);
+}
+/** Default Pynect logger */
+exports.logger = createLogger('pynect');
+//# sourceMappingURL=Logger.js.map

package/dist/utils/Logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.js","sourceRoot":"","sources":["../../src/utils/Logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/MemoryMonitor.d.ts

@@ -0,0 +1,43 @@
+/**
+ * pynect - Memory Monitor
+ * Tracks Python object references, heap usage, and triggers GC when needed.
+ */
+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 declare class MemoryMonitor {
+    private readonly _logger;
+    private _addon;
+    private _snapshots;
+    private _maxSnapshots;
+    private _monitorInterval;
+    private _thresholds;
+    constructor(thresholds?: Partial<MemoryThresholds>);
+    attach(addon: NativeAddon): void;
+    startMonitoring(intervalMs?: number): void;
+    stopMonitoring(): void;
+    takeSnapshot(): Promise<MemorySnapshot>;
+    getSnapshots(): MemorySnapshot[];
+    getLatestSnapshot(): MemorySnapshot | null;
+    forceGC(): Promise<void>;
+    private _checkMemory;
+    private _parseBytes;
+    private _formatBytes;
+}
+//# sourceMappingURL=MemoryMonitor.d.ts.map

package/dist/utils/MemoryMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryMonitor.d.ts","sourceRoot":"","sources":["../../src/utils/MemoryMonitor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,aAAa,CAAO;IAC5B,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,WAAW,CAAmB;gBAE1B,UAAU,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAUlD,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAIhC,eAAe,CAAC,UAAU,SAAO,GAAG,IAAI;IAgBxC,cAAc,IAAI,IAAI;IAQhB,YAAY,IAAI,OAAO,CAAC,cAAc,CAAC;IA8B7C,YAAY,IAAI,cAAc,EAAE;IAIhC,iBAAiB,IAAI,cAAc,GAAG,IAAI;IAIpC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAmBhB,YAAY;IA2B1B,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,YAAY;CAMrB"}