nodepyx 1.0.0

package/dist/types/config.d.ts

@@ -0,0 +1,175 @@
+/**
+ * nodepyx — Core Configuration Types
+ * Full configuration interface for nodepyx runtime initialization.
+ */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+export interface VirtualenvConfig {
+    /** Path to virtualenv directory (e.g. './.nodepyx/venv') */
+    path: string;
+    /** Python packages to install (e.g. ['pandas', 'numpy', 'scikit-learn']) */
+    packages: string[];
+    /** Automatically install missing packages at startup */
+    autoInstall: boolean;
+    /** pip index URL override */
+    pipIndexUrl?: string;
+    /** Additional pip install args */
+    pipArgs?: string[];
+}
+export interface CondaConfig {
+    /** Name of the conda environment */
+    envName: string;
+    /** Path to conda executable */
+    condaPath?: string;
+    /** Channels to search for packages */
+    channels?: string[];
+    /** Packages to ensure are installed */
+    packages?: string[];
+}
+export interface GILConfig {
+    /**
+     * How often to release the GIL during long Python operations (microseconds).
+     * Lower values improve Node.js responsiveness at cost of Python throughput.
+     * Default: 5000 (5ms)
+     */
+    releaseInterval?: number;
+    /**
+     * Maximum time to wait for GIL acquisition before timing out (milliseconds).
+     * Default: 10000 (10s)
+     */
+    acquireTimeout?: number;
+}
+export interface ThreadPoolConfig {
+    /** Number of worker threads for Python execution. Default: 4 */
+    size?: number;
+    /** Max queue depth before backpressure is applied. Default: 1000 */
+    maxQueueSize?: number;
+    /** Thread idle timeout before shrinking pool (ms). Default: 30000 */
+    idleTimeout?: number;
+}
+export interface MemoryConfig {
+    /** Maximum Python heap size (e.g. '2GB', '512MB'). Default: '2GB' */
+    limit?: string;
+    /** Trigger Python GC when heap exceeds this threshold. Default: '1GB' */
+    gcThreshold?: string;
+    /** Enable leak detection in debug builds. Default: false */
+    leakDetection?: boolean;
+}
+export interface ProfilingConfig {
+    /** Enable CPU profiling. Default: false */
+    enabled?: boolean;
+    /** Output file for profile data */
+    outputFile?: string;
+    /** Sampling interval (microseconds). Default: 1000 */
+    samplingInterval?: number;
+}
+export interface nodepyxConfig {
+    /**
+     * Path to Python executable or virtualenv root.
+     * If not specified, auto-detects system Python.
+     * Examples: '/usr/bin/python3', './.venv', '/opt/conda/envs/myenv'
+     */
+    pythonPath?: string;
+    /**
+     * Virtualenv configuration — creates and manages a dedicated virtualenv.
+     * Takes precedence over pythonPath if specified.
+     */
+    virtualenv?: VirtualenvConfig;
+    /**
+     * Conda environment configuration.
+     * Takes precedence over virtualenv and pythonPath if specified.
+     */
+    conda?: CondaConfig;
+    /**
+     * Thread pool configuration for Python execution.
+     */
+    threadPool?: ThreadPoolConfig;
+    /**
+     * Legacy shorthand for threadPool.size.
+     * @deprecated Use threadPool.size instead.
+     */
+    threadPoolSize?: number;
+    /**
+     * Memory configuration for Python heap.
+     */
+    memory?: MemoryConfig;
+    /**
+     * Legacy shorthand for memory.limit.
+     * @deprecated Use memory.limit instead.
+     */
+    memoryLimit?: string;
+    /**
+     * Directory for TypeScript type stubs generated from Python modules.
+     * Default: './.nodepyx/stubs'
+     */
+    stubsDir?: string;
+    /**
+     * Log level for nodepyx internal logging.
+     * Default: 'warn'
+     */
+    logLevel?: LogLevel;
+    /**
+     * Profiling configuration.
+     */
+    profiling?: ProfilingConfig;
+    /**
+     * Legacy shorthand for profiling.enabled.
+     * @deprecated Use profiling.enabled instead.
+     */
+    enableProfiling?: boolean;
+    /**
+     * Timeout for individual Python calls (milliseconds).
+     * Default: 30000 (30s)
+     */
+    callTimeout?: number;
+    /**
+     * GIL (Global Interpreter Lock) management configuration.
+     */
+    gil?: GILConfig;
+    /**
+     * Additional Python sys.path entries.
+     * Inserted at sys.path[0] in order.
+     */
+    pythonPath_extra?: string[];
+    /**
+     * Environment variables to set for the Python interpreter.
+     */
+    env?: Record<string, string>;
+    /**
+     * Enable experimental features. Use with caution.
+     */
+    experimental?: {
+        /** Use SharedArrayBuffer for NumPy transfers. Default: true */
+        sharedArrayBuffer?: boolean;
+        /** Cache Proxy chain resolutions. Default: true */
+        proxyCache?: boolean;
+        /** Lazy attribute resolution. Default: true */
+        lazyResolution?: boolean;
+    };
+}
+/**
+ * Resolved and normalized configuration (all fields filled with defaults).
+ */
+export interface ResolvednodepyxConfig {
+    pythonExecutable: string;
+    pythonHome: string;
+    threadPoolSize: number;
+    maxQueueSize: number;
+    idleTimeout: number;
+    memoryLimit: string;
+    gcThreshold: string;
+    leakDetection: boolean;
+    stubsDir: string;
+    logLevel: LogLevel;
+    callTimeout: number;
+    gil: Required<GILConfig>;
+    profilingEnabled: boolean;
+    profilingFile?: string;
+    profilingSamplingInterval: number;
+    sharedArrayBuffer: boolean;
+    proxyCache: boolean;
+    lazyResolution: boolean;
+    env: Record<string, string>;
+    pythonPathExtra: string[];
+}
+export declare function resolveConfig(config?: nodepyxConfig): ResolvednodepyxConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

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

package/dist/types/config.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * nodepyx — Core Configuration Types
+ * Full configuration interface for nodepyx runtime initialization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = resolveConfig;
+function resolveConfig(config = {}) {
+    return {
+        pythonExecutable: config.pythonPath ?? 'python3',
+        pythonHome: config.pythonPath ?? '',
+        threadPoolSize: config.threadPool?.size ?? config.threadPoolSize ?? 4,
+        maxQueueSize: config.threadPool?.maxQueueSize ?? 1000,
+        idleTimeout: config.threadPool?.idleTimeout ?? 30000,
+        memoryLimit: config.memory?.limit ?? config.memoryLimit ?? '2GB',
+        gcThreshold: config.memory?.gcThreshold ?? '1GB',
+        leakDetection: config.memory?.leakDetection ?? false,
+        stubsDir: config.stubsDir ?? './.nodepyx/stubs',
+        logLevel: config.logLevel ?? 'warn',
+        callTimeout: config.callTimeout ?? 30000,
+        gil: {
+            releaseInterval: config.gil?.releaseInterval ?? 5000,
+            acquireTimeout: config.gil?.acquireTimeout ?? 10000,
+        },
+        profilingEnabled: config.profiling?.enabled ?? config.enableProfiling ?? false,
+        profilingFile: config.profiling?.outputFile,
+        profilingSamplingInterval: config.profiling?.samplingInterval ?? 1000,
+        sharedArrayBuffer: config.experimental?.sharedArrayBuffer ?? true,
+        proxyCache: config.experimental?.proxyCache ?? true,
+        lazyResolution: config.experimental?.lazyResolution ?? true,
+        env: config.env ?? {},
+        pythonPathExtra: config.pythonPath_extra ?? [],
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/types/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAmMH,sCA0BC;AA1BD,SAAgB,aAAa,CAAC,SAAwB,EAAE;IACtD,OAAO;QACL,gBAAgB,EAAE,MAAM,CAAC,UAAU,IAAI,SAAS;QAChD,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,EAAE;QACnC,cAAc,EAAE,MAAM,CAAC,UAAU,EAAE,IAAI,IAAI,MAAM,CAAC,cAAc,IAAI,CAAC;QACrE,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,YAAY,IAAI,IAAI;QACrD,WAAW,EAAE,MAAM,CAAC,UAAU,EAAE,WAAW,IAAI,KAAK;QACpD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,MAAM,CAAC,WAAW,IAAI,KAAK;QAChE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,IAAI,KAAK;QAChD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,IAAI,KAAK;QACpD,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,kBAAkB;QAC/C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,MAAM;QACnC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,KAAK;QACxC,GAAG,EAAE;YACH,eAAe,EAAE,MAAM,CAAC,GAAG,EAAE,eAAe,IAAI,IAAI;YACpD,cAAc,EAAE,MAAM,CAAC,GAAG,EAAE,cAAc,IAAI,KAAK;SACpD;QACD,gBAAgB,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,IAAI,MAAM,CAAC,eAAe,IAAI,KAAK;QAC9E,aAAa,EAAE,MAAM,CAAC,SAAS,EAAE,UAAU;QAC3C,yBAAyB,EAAE,MAAM,CAAC,SAAS,EAAE,gBAAgB,IAAI,IAAI;QACrE,iBAAiB,EAAE,MAAM,CAAC,YAAY,EAAE,iBAAiB,IAAI,IAAI;QACjE,UAAU,EAAE,MAAM,CAAC,YAAY,EAAE,UAAU,IAAI,IAAI;QACnD,cAAc,EAAE,MAAM,CAAC,YAAY,EAAE,cAAc,IAAI,IAAI;QAC3D,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE;QACrB,eAAe,EAAE,MAAM,CAAC,gBAAgB,IAAI,EAAE;KAC/C,CAAC;AACJ,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * nodepyx — Types Index
+ * Re-exports all public type definitions.
+ */
+export type { nodepyxConfig, ResolvednodepyxConfig, VirtualenvConfig, CondaConfig, GILConfig, ThreadPoolConfig, MemoryConfig, ProfilingConfig, LogLevel, } from './config';
+export { resolveConfig } from './config';
+export type { PyObjectId, PyTypeName, PyTypeInfo, PyParamInfo, PyMemberInfo, PyCallableInfo, PyClassInfo, PyModuleInspection, SerializedFormat, SerializedValue, SerializedMetadata, PyCallResult, PyErrorInfo, PyIteratorState, PyIteratorNext, DataFrameResult, SeriesResult, NumPyArrayResult, AttributePath, PyProxyInterface, } from './python';
+export type { NativeAddon, AddonInitOptions, AddonImportResult, AddonAttributeResult, AddonCallOptions, AddonIteratorResult, AddonMemoryStats, AddonProfilingReport, } from './addon';
+export { loadNativeAddon } from './addon';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,QAAQ,GACT,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,YAAY,EACV,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * nodepyx — Types Index
+ * Re-exports all public type definitions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadNativeAddon = exports.resolveConfig = void 0;
+var config_1 = require("./config");
+Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_1.resolveConfig; } });
+var addon_1 = require("./addon");
+Object.defineProperty(exports, "loadNativeAddon", { enumerable: true, get: function () { return addon_1.loadNativeAddon; } });
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAcH,mCAAyC;AAAhC,uGAAA,aAAa,OAAA;AAoCtB,iCAA0C;AAAjC,wGAAA,eAAe,OAAA"}

package/dist/types/python.d.ts

@@ -0,0 +1,235 @@
+/**
+ * nodepyx — Python Object Type Definitions
+ * Core types for representing Python objects in TypeScript.
+ */
+/**
+ * Unique identifier for a Python object in the CPython heap.
+ * Stored as a C-level pointer (opaque to JavaScript).
+ */
+export type PyObjectId = number & {
+    readonly __brand: 'PyObjectId';
+};
+/**
+ * Python built-in type names.
+ */
+export type PyTypeName = 'int' | 'float' | 'complex' | 'bool' | 'str' | 'bytes' | 'bytearray' | 'list' | 'tuple' | 'dict' | 'set' | 'frozenset' | 'NoneType' | 'function' | 'method' | 'builtin_function_or_method' | 'module' | 'type' | 'classmethod' | 'staticmethod' | 'property' | 'generator' | 'coroutine' | 'async_generator' | 'iterator' | 'DataFrame' | 'Series' | 'ndarray' | 'Tensor' | string;
+/**
+ * Metadata about a Python object's type.
+ */
+export interface PyTypeInfo {
+    typeName: PyTypeName;
+    moduleName?: string;
+    qualName?: string;
+    isCallable: boolean;
+    isIterable: boolean;
+    isAsyncIterable: boolean;
+    isAwaitable: boolean;
+    isClass: boolean;
+    isModule: boolean;
+    isNone: boolean;
+    isPrimitive: boolean;
+    isNumeric: boolean;
+    isSequence: boolean;
+    isMapping: boolean;
+}
+/**
+ * Parameter info from Python function introspection.
+ */
+export interface PyParamInfo {
+    name: string;
+    type: string;
+    optional: boolean;
+    hasDefault: boolean;
+    defaultValue?: unknown;
+    kind: 'positional_only' | 'positional_or_keyword' | 'var_positional' | 'keyword_only' | 'var_keyword';
+}
+/**
+ * Member/attribute info for a Python class or module.
+ */
+export interface PyMemberInfo {
+    name: string;
+    type: string;
+    isReadOnly: boolean;
+    docstring?: string;
+}
+/**
+ * Full introspection result for a Python callable.
+ */
+export interface PyCallableInfo {
+    name: string;
+    qualName: string;
+    docstring: string;
+    parameters: PyParamInfo[];
+    returnType: string;
+    isMethod: boolean;
+    isClassMethod: boolean;
+    isStaticMethod: boolean;
+    isCoroutine: boolean;
+    isGenerator: boolean;
+}
+/**
+ * Full introspection result for a Python class.
+ */
+export interface PyClassInfo {
+    name: string;
+    qualName: string;
+    docstring: string;
+    bases: string[];
+    members: PyMemberInfo[];
+    methods: PyCallableInfo[];
+    properties: PyMemberInfo[];
+    classMethods: PyCallableInfo[];
+    staticMethods: PyCallableInfo[];
+}
+/**
+ * Full introspection result for a Python module.
+ */
+export interface PyModuleInspection {
+    name: string;
+    file?: string;
+    docstring: string;
+    version?: string;
+    functions: PyCallableInfo[];
+    classes: PyClassInfo[];
+    constants: PyMemberInfo[];
+    submodules: string[];
+}
+/**
+ * Serialized wire format for Python ↔ JavaScript data transfer.
+ */
+export type SerializedFormat = 'json' | 'msgpack' | 'numpy_array' | 'dataframe' | 'series' | 'pandas_dataframe' | 'pandas_series' | 'torch_tensor' | 'python_ref' | 'bytes' | 'none' | number;
+export interface SerializedValue {
+    format: SerializedFormat;
+    data: Uint8Array | string | null | undefined;
+    metadata?: SerializedMetadata;
+}
+export interface SerializedMetadata {
+    /** For python_ref: the object ID */
+    objectId?: number;
+    /** For numpy_array: dtype, shape, strides */
+    dtype?: string;
+    shape?: number[];
+    strides?: number[];
+    order?: 'C' | 'F';
+    /** For numpy_array: item size in bytes (snake_case variant) */
+    itemsize?: number;
+    /** For pandas objects: column names, dtypes, index */
+    columns?: string[];
+    columnDtypes?: string[];
+    index?: unknown[];
+    indexName?: string;
+    /** For pandas: orient (split/records/index/columns/values) */
+    orient?: string;
+    /** For Series: series name */
+    name?: string;
+    /** For torch tensors */
+    device?: string;
+    requiresGrad?: boolean;
+    /** General */
+    length?: number;
+    size?: number;
+    itemSize?: number;
+}
+/**
+ * Result from a Python function call.
+ */
+export interface PyCallResult {
+    success: boolean;
+    value?: SerializedValue;
+    error?: PyErrorInfo;
+    objectId?: PyObjectId;
+    isObject?: boolean;
+}
+/**
+ * Python exception information.
+ */
+export interface PyErrorInfo {
+    /** Python exception class name, e.g. 'ValueError', 'FileNotFoundError' */
+    type: string;
+    /** Exception message */
+    message: string;
+    /** Full Python traceback */
+    traceback: string;
+    /** Exception module, e.g. 'builtins', 'pandas.errors' */
+    module?: string;
+    /** Chained exception */
+    cause?: PyErrorInfo;
+}
+/**
+ * Iterator state for Python iterators.
+ */
+export interface PyIteratorState {
+    iteratorId: number;
+    objectId: PyObjectId;
+    done: boolean;
+    position: number;
+}
+/**
+ * Result from iterator next() call.
+ */
+export interface PyIteratorNext {
+    done: boolean;
+    value?: SerializedValue;
+    error?: PyErrorInfo;
+}
+/**
+ * DataFrame representation after deserialization.
+ */
+export interface DataFrameResult {
+    columns: string[];
+    /** Row data as array of column-keyed objects */
+    data: Record<string, unknown>[];
+    /** Alias for data — array of records (row objects) */
+    records: Record<string, unknown>[];
+    index: unknown[];
+    dtypes: Record<string, string>;
+    shape: [number, number];
+}
+/**
+ * Series representation after deserialization.
+ */
+export interface SeriesResult {
+    name: string;
+    /** Series values */
+    data: unknown[];
+    /** Alias for data */
+    values: unknown[];
+    index: unknown[];
+    dtype: string;
+    length: number;
+}
+/**
+ * A typed array backed by numpy data.
+ */
+export type NumpyTypedArray = Float32Array | Float64Array | Int8Array | Int16Array | Int32Array | BigInt64Array | Uint8Array | Uint16Array | Uint32Array | BigUint64Array;
+/**
+ * NumPy array representation after deserialization.
+ * Contains the typed array data plus metadata (dtype, shape, ndim).
+ */
+export interface NumPyArrayResult {
+    /** The underlying typed array */
+    data: NumpyTypedArray;
+    /** NumPy dtype string, e.g. 'float64' */
+    dtype: string;
+    /** Array shape */
+    shape: number[];
+    /** Number of dimensions */
+    ndim: number;
+}
+/**
+ * Attribute resolution path for lazy Proxy chains.
+ */
+export type AttributePath = string[];
+/**
+ * The core PyProxy interface — wraps any Python object.
+ * All properties return new PyProxy instances (lazy).
+ * Calling the proxy or awaiting it triggers the Python call.
+ */
+export interface PyProxyInterface {
+    readonly _pyObjectId: PyObjectId;
+    readonly _path: AttributePath;
+    readonly _isResolved: boolean;
+    then(onfulfilled?: (value: unknown) => unknown, onrejected?: (reason: PyErrorInfo) => unknown): Promise<unknown>;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=python.d.ts.map

package/dist/types/python.d.ts.map

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

package/dist/types/python.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * nodepyx — Python Object Type Definitions
+ * Core types for representing Python objects in TypeScript.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=python.js.map

package/dist/types/python.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.js","sourceRoot":"","sources":["../../src/types/python.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

package/dist/utils/ErrorTranslator.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 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 nodepyxNotInitializedError extends Error {
+    constructor(message?: string);
+}
+export declare class nodepyxShutdownError 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,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,SAA2D;CAK/E;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,SAAwC;CAK5D;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"}