pynect 0.0.0 → 0.2.0

package/dist/serialization/NumpyBridge.js.map

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

package/dist/serialization/Serializer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * pynect - Serializer
+ * Central coordinator for Python <-> JavaScript data conversion.
+ * Routes to specialized bridges (MsgPack, NumPy, DataFrame) based on format.
+ */
+import type { SerializedValue } from '../types/python';
+/**
+ * SerializerOptions - controls serialization behavior.
+ */
+export interface SerializerOptions {
+    /** Use SharedArrayBuffer for large NumPy arrays (requires cross-origin isolation) */
+    useSharedArrayBuffer?: boolean;
+    /** Maximum size for inline JSON (bytes). Larger -> binary */
+    maxJsonSize?: number;
+    /** Whether to wrap Python objects in PyProxy */
+    wrapPythonRefs?: boolean;
+}
+/**
+ * Serializer - converts between Python wire format and JavaScript values.
+ *
+ * This is a singleton accessed via `Serializer.getInstance()`.
+ *
+ * @example
+ * ```typescript
+ * const serializer = Serializer.getInstance();
+ *
+ * // JavaScript -> Python wire format
+ * const sv = await serializer.serialize([1, 2, 3, 4, 5]);
+ *
+ * // Python wire format -> JavaScript
+ * const jsValue = await serializer.deserialize(sv);
+ * ```
+ */
+export declare class Serializer {
+    private static _instance;
+    private readonly _options;
+    private readonly _numpyBridge;
+    private readonly _dataframeBridge;
+    private readonly _msgpackSerializer;
+    private constructor();
+    static getInstance(options?: SerializerOptions): Serializer;
+    static resetInstance(): void;
+    /**
+     * Deserialize a Python wire format value to JavaScript.
+     *
+     * Format routing:
+     * - JSON (0) -> JSON.parse
+     * - MsgPack (1) -> MessagePack decode
+     * - NumPy array (2) -> TypedArray
+     * - DataFrame (3) -> DataFrameResult
+     * - Series (4) -> SeriesResult
+     * - PyRef (6) -> PyProxy (via addon)
+     * - Bytes (7) -> Uint8Array
+     * - None (8) -> null
+     */
+    deserialize(sv: SerializedValue): Promise<unknown>;
+    /**
+     * Deserialize synchronously (for non-async contexts).
+     * Limited: only works for simple types.
+     */
+    deserializeSync(sv: SerializedValue): unknown;
+    /**
+     * Serialize a JavaScript value to Python wire format.
+     * Chooses the most efficient encoding automatically.
+     */
+    serialize(value: unknown): Promise<SerializedValue>;
+    /**
+     * Serialize synchronously (for non-async contexts).
+     */
+    serializeSync(value: unknown): SerializedValue;
+    private _deserializeJson;
+    private _deserializeMsgPack;
+    private _deserializePythonRef;
+    private _deserializeBytes;
+    private _serializeValue;
+    private _serializeValueSync;
+}
+//# sourceMappingURL=Serializer.d.ts.map

package/dist/serialization/Serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Serializer.d.ts","sourceRoot":"","sources":["../../src/serialization/Serializer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,iBAAiB,CAAC;AAQzB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkB;IACnD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoB;IAEvD,OAAO;IAWP,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU;IAO3D,MAAM,CAAC,aAAa,IAAI,IAAI;IAM5B;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAkCxD;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO;IAqB7C;;;OAGG;IACG,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC;IAIzD;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe;IAM9C,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,iBAAiB;YAYX,eAAe;IAI7B,OAAO,CAAC,mBAAmB;CAkG5B"}

package/dist/serialization/Serializer.js

@@ -0,0 +1,281 @@
+"use strict";
+/**
+ * pynect - Serializer
+ * Central coordinator for Python <-> JavaScript data conversion.
+ * Routes to specialized bridges (MsgPack, NumPy, DataFrame) based on format.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Serializer = void 0;
+const NumpyBridge_1 = require("./NumpyBridge");
+const DataFrameBridge_1 = require("./DataFrameBridge");
+const MsgPackSerializer_1 = require("./MsgPackSerializer");
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('Serializer');
+/**
+ * Serializer - converts between Python wire format and JavaScript values.
+ *
+ * This is a singleton accessed via `Serializer.getInstance()`.
+ *
+ * @example
+ * ```typescript
+ * const serializer = Serializer.getInstance();
+ *
+ * // JavaScript -> Python wire format
+ * const sv = await serializer.serialize([1, 2, 3, 4, 5]);
+ *
+ * // Python wire format -> JavaScript
+ * const jsValue = await serializer.deserialize(sv);
+ * ```
+ */
+class Serializer {
+    static _instance = null;
+    _options;
+    _numpyBridge;
+    _dataframeBridge;
+    _msgpackSerializer;
+    constructor(options = {}) {
+        this._options = {
+            useSharedArrayBuffer: options.useSharedArrayBuffer ?? false,
+            maxJsonSize: options.maxJsonSize ?? 65536, // 64KB
+            wrapPythonRefs: options.wrapPythonRefs ?? true,
+        };
+        this._numpyBridge = new NumpyBridge_1.NumpyBridge({ useSharedArrayBuffer: this._options.useSharedArrayBuffer });
+        this._dataframeBridge = new DataFrameBridge_1.DataFrameBridge();
+        this._msgpackSerializer = new MsgPackSerializer_1.MsgPackSerializer();
+    }
+    static getInstance(options) {
+        if (!Serializer._instance) {
+            Serializer._instance = new Serializer(options);
+        }
+        return Serializer._instance;
+    }
+    static resetInstance() {
+        Serializer._instance = null;
+    }
+    // Python Wire Format -> JavaScript
+    /**
+     * Deserialize a Python wire format value to JavaScript.
+     *
+     * Format routing:
+     * - JSON (0) -> JSON.parse
+     * - MsgPack (1) -> MessagePack decode
+     * - NumPy array (2) -> TypedArray
+     * - DataFrame (3) -> DataFrameResult
+     * - Series (4) -> SeriesResult
+     * - PyRef (6) -> PyProxy (via addon)
+     * - Bytes (7) -> Uint8Array
+     * - None (8) -> null
+     */
+    async deserialize(sv) {
+        const format = sv.format;
+        switch (format) {
+            case 0: // JSON
+                return this._deserializeJson(sv);
+            case 1: // MSGPACK
+                return this._deserializeMsgPack(sv);
+            case 2: // NUMPY_ARRAY
+                return this._numpyBridge.deserialize(sv);
+            case 3: // PANDAS_DATAFRAME
+                return this._dataframeBridge.deserializeDataFrame(sv);
+            case 4: // PANDAS_SERIES
+                return this._dataframeBridge.deserializeSeries(sv);
+            case 6: // PYTHON_REF
+                return this._deserializePythonRef(sv);
+            case 7: // BYTES
+                return this._deserializeBytes(sv);
+            case 8: // NONE
+                return null;
+            default:
+                logger.warn(`Unknown serialization format: ${format}`);
+                return null;
+        }
+    }
+    /**
+     * Deserialize synchronously (for non-async contexts).
+     * Limited: only works for simple types.
+     */
+    deserializeSync(sv) {
+        const format = sv.format;
+        switch (format) {
+            case 0: // JSON
+                return this._deserializeJson(sv);
+            case 7: // BYTES
+                return sv.data instanceof Uint8Array ? sv.data : null;
+            case 8: // NONE
+                return null;
+            default:
+                // For binary formats, return null in sync mode
+                return null;
+        }
+    }
+    // JavaScript -> Python Wire Format
+    /**
+     * Serialize a JavaScript value to Python wire format.
+     * Chooses the most efficient encoding automatically.
+     */
+    async serialize(value) {
+        return this._serializeValue(value);
+    }
+    /**
+     * Serialize synchronously (for non-async contexts).
+     */
+    serializeSync(value) {
+        return this._serializeValueSync(value);
+    }
+    // Private Deserialization
+    _deserializeJson(sv) {
+        const data = sv.data;
+        if (data === null || data === undefined) {
+            return null;
+        }
+        const jsonStr = typeof data === 'string' ? data : new TextDecoder().decode(data);
+        if (!jsonStr || jsonStr === 'null') {
+            return null;
+        }
+        if (jsonStr === 'true') {
+            return true;
+        }
+        if (jsonStr === 'false') {
+            return false;
+        }
+        try {
+            return JSON.parse(jsonStr);
+        }
+        catch {
+            // If JSON parse fails, return the raw string
+            return jsonStr;
+        }
+    }
+    _deserializeMsgPack(sv) {
+        const data = sv.data;
+        if (!data || !(data instanceof Uint8Array)) {
+            return null;
+        }
+        try {
+            return this._msgpackSerializer.decode(data);
+        }
+        catch (err) {
+            logger.warn('MsgPack deserialization failed', err);
+            return null;
+        }
+    }
+    _deserializePythonRef(sv) {
+        // PyRef deserialization is handled by PyProxy._deserializeAddonResult
+        // which has access to the addon. Here we return the raw ref.
+        const objectId = sv.metadata?.objectId;
+        if (objectId) {
+            return { __pyref__: objectId };
+        }
+        return null;
+    }
+    _deserializeBytes(sv) {
+        const data = sv.data;
+        if (!data) {
+            return null;
+        }
+        if (data instanceof Uint8Array) {
+            return data;
+        }
+        if (typeof data === 'string') {
+            return new TextEncoder().encode(data);
+        }
+        return null;
+    }
+    // Private Serialization
+    async _serializeValue(value) {
+        return this._serializeValueSync(value);
+    }
+    _serializeValueSync(value) {
+        // null / undefined
+        if (value === null || value === undefined) {
+            return { format: 0, data: 'null', metadata: {} };
+        }
+        // Boolean
+        if (typeof value === 'boolean') {
+            return { format: 0, data: String(value), metadata: {} };
+        }
+        // Number
+        if (typeof value === 'number') {
+            if (Number.isNaN(value)) {
+                return { format: 0, data: 'null', metadata: {} };
+            }
+            return { format: 0, data: String(value), metadata: {} };
+        }
+        // BigInt
+        if (typeof value === 'bigint') {
+            return { format: 0, data: `"${value.toString()}"`, metadata: {} };
+        }
+        // String
+        if (typeof value === 'string') {
+            return { format: 0, data: JSON.stringify(value), metadata: {} };
+        }
+        // TypedArrays -> NumPy format
+        if (value instanceof Float32Array) {
+            return this._numpyBridge.serializeTypedArray(value, 'float32');
+        }
+        if (value instanceof Float64Array) {
+            return this._numpyBridge.serializeTypedArray(value, 'float64');
+        }
+        if (value instanceof Int8Array) {
+            return this._numpyBridge.serializeTypedArray(value, 'int8');
+        }
+        if (value instanceof Int16Array) {
+            return this._numpyBridge.serializeTypedArray(value, 'int16');
+        }
+        if (value instanceof Int32Array) {
+            return this._numpyBridge.serializeTypedArray(value, 'int32');
+        }
+        if (value instanceof BigInt64Array) {
+            return this._numpyBridge.serializeTypedArray(value, 'int64');
+        }
+        if (value instanceof Uint8Array) {
+            return this._numpyBridge.serializeTypedArray(value, 'uint8');
+        }
+        if (value instanceof Uint16Array) {
+            return this._numpyBridge.serializeTypedArray(value, 'uint16');
+        }
+        if (value instanceof Uint32Array) {
+            return this._numpyBridge.serializeTypedArray(value, 'uint32');
+        }
+        if (value instanceof BigUint64Array) {
+            return this._numpyBridge.serializeTypedArray(value, 'uint64');
+        }
+        // Raw ArrayBuffer
+        if (value instanceof ArrayBuffer) {
+            return { format: 7, data: new Uint8Array(value), metadata: {} };
+        }
+        // Array - use MsgPack for large, JSON for small
+        if (Array.isArray(value)) {
+            try {
+                const json = JSON.stringify(value);
+                if (json.length <= this._options.maxJsonSize) {
+                    return { format: 0, data: json, metadata: { length: value.length } };
+                }
+                // Large array -> MessagePack
+                const packed = this._msgpackSerializer.encode(value);
+                return { format: 1, data: packed, metadata: { length: value.length } };
+            }
+            catch {
+                return { format: 8, data: null, metadata: {} };
+            }
+        }
+        // Plain object - JSON or MsgPack
+        if (typeof value === 'object') {
+            try {
+                const json = JSON.stringify(value);
+                if (json.length <= this._options.maxJsonSize) {
+                    return { format: 0, data: json, metadata: {} };
+                }
+                const packed = this._msgpackSerializer.encode(value);
+                return { format: 1, data: packed, metadata: {} };
+            }
+            catch {
+                return { format: 8, data: null, metadata: {} };
+            }
+        }
+        // Fallback
+        return { format: 8, data: null, metadata: {} };
+    }
+}
+exports.Serializer = Serializer;
+//# sourceMappingURL=Serializer.js.map

package/dist/serialization/Serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Serializer.js","sourceRoot":"","sources":["../../src/serialization/Serializer.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAMH,+CAA4C;AAC5C,uDAAoD;AACpD,2DAAwD;AACxD,4CAAyC;AAEzC,MAAM,MAAM,GAAG,IAAI,eAAM,CAAC,YAAY,CAAC,CAAC;AAcxC;;;;;;;;;;;;;;;GAeG;AACH,MAAa,UAAU;IACb,MAAM,CAAC,SAAS,GAAsB,IAAI,CAAC;IAClC,QAAQ,CAA8B;IACtC,YAAY,CAAc;IAC1B,gBAAgB,CAAkB;IAClC,kBAAkB,CAAoB;IAEvD,YAAoB,UAA6B,EAAE;QACjD,IAAI,CAAC,QAAQ,GAAG;YACd,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,IAAI,KAAK;YAC3D,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,KAAK,EAAG,OAAO;YACnD,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,IAAI;SAC/C,CAAC;QACF,IAAI,CAAC,YAAY,GAAG,IAAI,yBAAW,CAAC,EAAE,oBAAoB,EAAE,IAAI,CAAC,QAAQ,CAAC,oBAAoB,EAAE,CAAC,CAAC;QAClG,IAAI,CAAC,gBAAgB,GAAG,IAAI,iCAAe,EAAE,CAAC;QAC9C,IAAI,CAAC,kBAAkB,GAAG,IAAI,qCAAiB,EAAE,CAAC;IACpD,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,OAA2B;QAC5C,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;YAC1B,UAAU,CAAC,SAAS,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,UAAU,CAAC,SAAS,CAAC;IAC9B,CAAC;IAED,MAAM,CAAC,aAAa;QAClB,UAAU,CAAC,SAAS,GAAG,IAAI,CAAC;IAC9B,CAAC;IAED,mCAAmC;IAEnC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,WAAW,CAAC,EAAmB;QACnC,MAAM,MAAM,GAAG,EAAE,CAAC,MAAgB,CAAC;QAEnC,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,CAAC,EAAE,OAAO;gBACb,OAAO,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;YAEnC,KAAK,CAAC,EAAE,UAAU;gBAChB,OAAO,IAAI,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC;YAEtC,KAAK,CAAC,EAAE,cAAc;gBACpB,OAAO,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;YAE3C,KAAK,CAAC,EAAE,mBAAmB;gBACzB,OAAO,IAAI,CAAC,gBAAgB,CAAC,oBAAoB,CAAC,EAAE,CAAC,CAAC;YAExD,KAAK,CAAC,EAAE,gBAAgB;gBACtB,OAAO,IAAI,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC;YAErD,KAAK,CAAC,EAAE,aAAa;gBACnB,OAAO,IAAI,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC;YAExC,KAAK,CAAC,EAAE,QAAQ;gBACd,OAAO,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC;YAEpC,KAAK,CAAC,EAAE,OAAO;gBACb,OAAO,IAAI,CAAC;YAEd;gBACE,MAAM,CAAC,IAAI,CAAC,iCAAiC,MAAM,EAAE,CAAC,CAAC;gBACvD,OAAO,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,EAAmB;QACjC,MAAM,MAAM,GAAG,EAAE,CAAC,MAAgB,CAAC;QAEnC,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,CAAC,EAAE,OAAO;gBACb,OAAO,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;YAEnC,KAAK,CAAC,EAAE,QAAQ;gBACd,OAAO,EAAE,CAAC,IAAI,YAAY,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YAExD,KAAK,CAAC,EAAE,OAAO;gBACb,OAAO,IAAI,CAAC;YAEd;gBACE,+CAA+C;gBAC/C,OAAO,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAED,mCAAmC;IAEnC;;;OAGG;IACH,KAAK,CAAC,SAAS,CAAC,KAAc;QAC5B,OAAO,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,KAAc;QAC1B,OAAO,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,0BAA0B;IAElB,gBAAgB,CAAC,EAAmB;QAC1C,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;QACrB,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YAAA,OAAO,IAAI,CAAC;QAAA,CAAC;QAEvD,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAkB,CAAC,CAAC;QAE/F,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;YAAA,OAAO,IAAI,CAAC;QAAA,CAAC;QAClD,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;YAAA,OAAO,IAAI,CAAC;QAAA,CAAC;QACtC,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;YAAA,OAAO,KAAK,CAAC;QAAA,CAAC;QAExC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,6CAA6C;YAC7C,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAEO,mBAAmB,CAAC,EAAmB;QAC7C,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;QACrB,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,YAAY,UAAU,CAAC,EAAE,CAAC;YAAA,OAAO,IAAI,CAAC;QAAA,CAAC;QAC1D,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE,GAAG,CAAC,CAAC;YACnD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAEO,qBAAqB,CAAC,EAAmB;QAC/C,sEAAsE;QACtE,6DAA6D;QAC7D,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC;QACvC,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;QACjC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,iBAAiB,CAAC,EAAmB;QAC3C,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;QACrB,IAAI,CAAC,IAAI,EAAE,CAAC;YAAA,OAAO,IAAI,CAAC;QAAA,CAAC;QACzB,IAAI,IAAI,YAAY,UAAU,EAAE,CAAC;YAAA,OAAO,IAAI,CAAC;QAAA,CAAC;QAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wBAAwB;IAEhB,KAAK,CAAC,eAAe,CAAC,KAAc;QAC1C,OAAO,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAEO,mBAAmB,CAAC,KAAc;QACxC,mBAAmB;QACnB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC1C,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QAClF,CAAC;QAED,UAAU;QACV,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACzF,CAAC;QAED,SAAS;QACT,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxB,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;YAClF,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACzF,CAAC;QAED,SAAS;QACT,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,IAAI,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACnG,CAAC;QAED,SAAS;QACT,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACjG,CAAC;QAED,8BAA8B;QAC9B,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAChE,CAAC;QACD,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAChE,CAAC;QAED,kBAAkB;QAClB,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACjG,CAAC;QAED,gDAAgD;QAChD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;oBAC7C,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBACtG,CAAC;gBACD,6BAA6B;gBAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACrD,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACxG,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;YAChF,CAAC;QACH,CAAC;QAED,iCAAiC;QACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;oBAC7C,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;gBAChF,CAAC;gBACD,MAAM,MAAM,GAAG,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACrD,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;YAClF,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;YAChF,CAAC;QACH,CAAC;QAED,WAAW;QACX,OAAO,EAAE,MAAM,EAAE,CAAgC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAChF,CAAC;;AAhRH,gCAiRC"}

package/dist/types/addon.d.ts

@@ -0,0 +1,131 @@
+/**
+ * pynect - Native Addon TypeScript Interface
+ * Type declarations for the C++ N-API addon.
+ * These map exactly to the exported functions in pynect_addon.cpp.
+ */
+import type { SerializedValue, PyCallResult, PyIteratorNext, PyTypeInfo, AttributePath } from './python';
+export interface AddonInitOptions {
+    /** Path to Python home directory */
+    pythonHome: string;
+    /** Path to Python executable */
+    pythonExecutable: string;
+    /** Exact CPython embedding library selected by Pyfig */
+    pythonLibrary: string;
+    /** Thread pool size */
+    threadPoolSize: number;
+    /** Max thread queue size */
+    maxQueueSize: number;
+    /** GIL release interval (microseconds) */
+    gilReleaseInterval: number;
+    /** Call timeout (milliseconds) */
+    callTimeout: number;
+    /** Additional Python sys.path entries */
+    pythonPathExtra: string[];
+    /** Environment variables */
+    env: Record<string, string>;
+    /** Enable profiling */
+    enableProfiling: boolean;
+    /** Include Python tracebacks in JavaScript errors */
+    includeTracebacks: boolean;
+}
+export interface AddonImportResult {
+    objectId: number;
+    success: boolean;
+    error?: string;
+}
+export interface AddonAttributeResult {
+    success: boolean;
+    value?: SerializedValue;
+    objectId?: number;
+    isCallable: boolean;
+    isObject: boolean;
+    error?: string;
+}
+export interface AddonCallOptions {
+    /** Positional arguments */
+    args: SerializedValue[];
+    /** Keyword arguments */
+    kwargs: Record<string, SerializedValue>;
+    /** Call timeout override (ms) */
+    timeout?: number;
+    /** Cooperative timeout for async Python execution (ms). */
+    executionTimeout?: number;
+    /** Unique key used for cancellation. */
+    requestId?: string;
+}
+export interface PyCallOptions {
+    /** Cancel a queued or asynchronous Python call. */
+    signal?: AbortSignal;
+    /** Override the queue timeout for this call (ms). */
+    queueTimeout?: number;
+    /** Override the cooperative async execution timeout for this call (ms). */
+    executionTimeout?: number;
+}
+export interface AddonIteratorResult {
+    iteratorId: number;
+    success: boolean;
+    error?: string;
+}
+export interface AddonMemoryStats {
+    pythonHeapBytes: number;
+    pythonHeapPeakBytes: number;
+    trackedObjects: number;
+    pendingCallbacks: number;
+    threadPoolActive: number;
+    threadPoolQueued: number;
+}
+export interface AddonProfilingReport {
+    totalCalls: number;
+    totalTimeMs: number;
+    avgCallTimeMs: number;
+    peakCallTimeMs: number;
+    callsByModule: Record<string, number>;
+    callsByFunction: Record<string, number>;
+}
+/**
+ * The full interface of the compiled C++ addon module.
+ * All async methods return Promises (resolved on libuv callback).
+ */
+export interface NativeAddon {
+    initializePython(options: AddonInitOptions): Promise<void>;
+    finalizePython(): Promise<void>;
+    isInitialized(): boolean;
+    importModule(moduleName: string): Promise<AddonImportResult>;
+    reloadModule(objectId: number): Promise<AddonImportResult>;
+    getAttribute(objectId: number, name: string): Promise<AddonAttributeResult>;
+    getAttributePath(objectId: number, path: AttributePath): Promise<AddonAttributeResult>;
+    setAttribute(objectId: number, name: string, value: SerializedValue): Promise<boolean>;
+    hasAttribute(objectId: number, name: string): Promise<boolean>;
+    deleteAttribute(objectId: number, name: string): Promise<boolean>;
+    callFunction(objectId: number, path: AttributePath, options: AddonCallOptions): Promise<PyCallResult>;
+    callMethod(objectId: number, methodName: string, options: AddonCallOptions): Promise<PyCallResult>;
+    cancelCall(requestId: string): Promise<unknown>;
+    getTypeInfo(objectId: number): Promise<PyTypeInfo>;
+    getObjectValue(objectId: number): Promise<SerializedValue>;
+    getObjectRepr(objectId: number): Promise<string>;
+    getObjectLength(objectId: number): Promise<number>;
+    getObjectKeys(objectId: number): Promise<string[]>;
+    createIterator(objectId: number, path: AttributePath): Promise<AddonIteratorResult>;
+    iteratorNext(iteratorId: number): Promise<PyIteratorNext>;
+    destroyIterator(iteratorId: number): Promise<void>;
+    runPythonCode(code: string, globals?: SerializedValue): Promise<SerializedValue>;
+    runPythonFile(filePath: string): Promise<SerializedValue>;
+    evalPython(expression: string): Promise<SerializedValue>;
+    incRef(objectId: number): void;
+    decRef(objectId: number): void;
+    collectGarbage(): Promise<void>;
+    getMemoryStats(): AddonMemoryStats;
+    getProfilingReport(): AddonProfilingReport;
+    resetProfilingStats(): void;
+    setThreadPoolSize(size: number): Promise<void>;
+    getThreadPoolStats(): {
+        active: number;
+        queued: number;
+        total: number;
+    };
+}
+/**
+ * Loads the native addon, trying prebuilds first then build directory.
+ */
+export declare function loadNativeAddon(): NativeAddon;
+//# sourceMappingURL=addon.d.ts.map

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

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

package/dist/types/addon.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * pynect - Native Addon TypeScript Interface
+ * Type declarations for the C++ N-API addon.
+ * These map exactly to the exported functions in pynect_addon.cpp.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadNativeAddon = loadNativeAddon;
+/**
+ * Loads the native addon, trying prebuilds first then build directory.
+ */
+function loadNativeAddon() {
+    // Try prebuilt binary first (faster, no build tools needed)
+    try {
+        // node-gyp-build handles platform/arch detection automatically
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const build = require('node-gyp-build');
+        return build(__dirname + '/../../');
+    }
+    catch {
+        // Fall back to explicit build path
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            return require('../../build/Release/pynect_addon.node');
+        }
+        catch {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            return require('../../build/Debug/pynect_addon.node');
+        }
+    }
+}
+//# sourceMappingURL=addon.js.map

package/dist/types/addon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon.js","sourceRoot":"","sources":["../../src/types/addon.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAqKH,0CAiBC;AApBD;;GAEG;AACH,SAAgB,eAAe;IAC7B,4DAA4D;IAC5D,IAAI,CAAC;QACH,+DAA+D;QAC/D,8DAA8D;QAC9D,MAAM,KAAK,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;QACxC,OAAO,KAAK,CAAC,SAAS,GAAG,SAAS,CAAgB,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,mCAAmC;QACnC,IAAI,CAAC;YACH,8DAA8D;YAC9D,OAAO,OAAO,CAAC,uCAAuC,CAAgB,CAAC;QACzE,CAAC;QAAC,MAAM,CAAC;YACP,8DAA8D;YAC9D,OAAO,OAAO,CAAC,qCAAqC,CAAgB,CAAC;QACvE,CAAC;IACH,CAAC;AACH,CAAC"}