nodepyx 1.0.0

package/dist/serialization/NumpyBridge.d.ts

@@ -0,0 +1,96 @@
+/**
+ * nodepyx — NumpyBridge
+ * Converts NumPy arrays to/from JavaScript TypedArrays.
+ *
+ * Wire protocol (binary layout for NUMPY_ARRAY format):
+ *   Bytes 0-3   : uint32 LE  — ndim (number of dimensions)
+ *   Bytes 4-7   : uint32 LE  — dtype code (see NumpyDTypeCode)
+ *   Bytes 8-11  : uint32 LE  — itemsize in bytes
+ *   Bytes 12-15 : uint32 LE  — total element count
+ *   Bytes 16..  : ndim × uint32 LE — shape dimensions
+ *   After shape : raw element bytes (C-contiguous order)
+ *
+ * When SharedArrayBuffer is enabled the element bytes are placed in a
+ * SharedArrayBuffer so the data can be read from Node.js worker threads
+ * without copying.
+ */
+import type { SerializedValue, NumPyArrayResult } from '../types/python';
+export declare enum NumpyDTypeCode {
+    BOOL = 0,
+    INT8 = 1,
+    INT16 = 2,
+    INT32 = 3,
+    INT64 = 4,
+    UINT8 = 5,
+    UINT16 = 6,
+    UINT32 = 7,
+    UINT64 = 8,
+    FLOAT32 = 9,
+    FLOAT64 = 10,
+    COMPLEX64 = 11,
+    COMPLEX128 = 12
+}
+export type NumpyDType = 'bool' | 'int8' | 'int16' | 'int32' | 'int64' | 'uint8' | 'uint16' | 'uint32' | 'uint64' | 'float32' | 'float64' | 'complex64' | 'complex128';
+interface NumpyBridgeOptions {
+    /**
+     * Use SharedArrayBuffer for large arrays.
+     * Requires `Cross-Origin-Opener-Policy: same-origin` and
+     * `Cross-Origin-Embedder-Policy: require-corp` response headers.
+     */
+    useSharedArrayBuffer?: boolean;
+    /** Threshold in bytes above which SharedArrayBuffer is used. Default: 1 MB */
+    sharedArrayBufferThreshold?: number;
+}
+/**
+ * NumpyBridge — converts NumPy arrays ↔ TypedArrays.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new NumpyBridge();
+ *
+ * // Serialize a Float32Array → NumPy wire format
+ * const sv = bridge.serializeTypedArray(new Float32Array([1, 2, 3]), 'float32');
+ *
+ * // Deserialize NumPy wire format → TypedArray
+ * const arr = bridge.deserialize(sv) as Float32Array;
+ * ```
+ */
+export declare class NumpyBridge {
+    private readonly _useShared;
+    private readonly _sharedThreshold;
+    constructor(options?: NumpyBridgeOptions);
+    /**
+     * Deserialize a NUMPY_ARRAY SerializedValue to a TypedArray.
+     */
+    deserialize(sv: SerializedValue): NumPyArrayResult | null;
+    /**
+     * Serialize a TypedArray to a NUMPY_ARRAY SerializedValue.
+     *
+     * @param arr    — the typed array
+     * @param dtype  — NumPy dtype string
+     * @param shape  — optional explicit shape; defaults to [arr.length]
+     */
+    serializeTypedArray(arr: ArrayBufferView, dtype: NumpyDType | {
+        dtype: string;
+        itemsize: number;
+    }, shape?: number[]): SerializedValue;
+    /**
+     * Create an empty NumPy array SerializedValue (used for zero-size results).
+     */
+    serializeEmpty(dtype?: NumpyDType): SerializedValue;
+    private _decodeBuffer;
+    private _buildTypedArray;
+    /**
+     * Detect dtype code from a TypedArray instance.
+     */
+    static detectDType(arr: ArrayBufferView): {
+        dtype: NumpyDType;
+        itemsize: number;
+    };
+    /**
+     * Return the item size in bytes for a dtype string.
+     */
+    static itemSizeOf(dtype: NumpyDType): number;
+}
+export {};
+//# sourceMappingURL=NumpyBridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NumpyBridge.d.ts","sourceRoot":"","sources":["../../src/serialization/NumpyBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAoB,gBAAgB,EAAmB,MAAM,iBAAiB,CAAC;AAO5G,oBAAY,cAAc;IACxB,IAAI,IAAQ;IACZ,IAAI,IAAQ;IACZ,KAAK,IAAO;IACZ,KAAK,IAAO;IACZ,KAAK,IAAO;IACZ,KAAK,IAAO;IACZ,MAAM,IAAM;IACZ,MAAM,IAAM;IACZ,MAAM,IAAM;IACZ,OAAO,IAAK;IACZ,OAAO,KAAK;IACZ,SAAS,KAAM;IACf,UAAU,KAAK;CAChB;AAED,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GACpC,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GACxC,SAAS,GAAG,SAAS,GACrB,WAAW,GAAG,YAAY,CAAC;AAE/B,UAAU,kBAAkB;IAC1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,8EAA8E;IAC9E,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC;AAyCD;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,OAAO,GAAE,kBAAuB;IAO5C;;OAEG;IACH,WAAW,CAAC,EAAE,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI;IAiCzD;;;;;;OAMG;IACH,mBAAmB,CACjB,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,UAAU,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EACvD,KAAK,CAAC,EAAE,MAAM,EAAE,GACf,eAAe;IA8ClB;;OAEG;IACH,cAAc,CAAC,KAAK,GAAE,UAAsB,GAAG,eAAe;IAM9D,OAAO,CAAC,aAAa;IA6BrB,OAAO,CAAC,gBAAgB;IAkDxB;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAiBjF;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM;CAI7C"}

package/dist/serialization/NumpyBridge.js

@@ -0,0 +1,323 @@
+"use strict";
+/**
+ * nodepyx — NumpyBridge
+ * Converts NumPy arrays to/from JavaScript TypedArrays.
+ *
+ * Wire protocol (binary layout for NUMPY_ARRAY format):
+ *   Bytes 0-3   : uint32 LE  — ndim (number of dimensions)
+ *   Bytes 4-7   : uint32 LE  — dtype code (see NumpyDTypeCode)
+ *   Bytes 8-11  : uint32 LE  — itemsize in bytes
+ *   Bytes 12-15 : uint32 LE  — total element count
+ *   Bytes 16..  : ndim × uint32 LE — shape dimensions
+ *   After shape : raw element bytes (C-contiguous order)
+ *
+ * When SharedArrayBuffer is enabled the element bytes are placed in a
+ * SharedArrayBuffer so the data can be read from Node.js worker threads
+ * without copying.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NumpyBridge = exports.NumpyDTypeCode = void 0;
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('NumpyBridge');
+// ─── NumPy dtype codes (must match Python side nodepyx_runtime.py) ───────────
+var NumpyDTypeCode;
+(function (NumpyDTypeCode) {
+    NumpyDTypeCode[NumpyDTypeCode["BOOL"] = 0] = "BOOL";
+    NumpyDTypeCode[NumpyDTypeCode["INT8"] = 1] = "INT8";
+    NumpyDTypeCode[NumpyDTypeCode["INT16"] = 2] = "INT16";
+    NumpyDTypeCode[NumpyDTypeCode["INT32"] = 3] = "INT32";
+    NumpyDTypeCode[NumpyDTypeCode["INT64"] = 4] = "INT64";
+    NumpyDTypeCode[NumpyDTypeCode["UINT8"] = 5] = "UINT8";
+    NumpyDTypeCode[NumpyDTypeCode["UINT16"] = 6] = "UINT16";
+    NumpyDTypeCode[NumpyDTypeCode["UINT32"] = 7] = "UINT32";
+    NumpyDTypeCode[NumpyDTypeCode["UINT64"] = 8] = "UINT64";
+    NumpyDTypeCode[NumpyDTypeCode["FLOAT32"] = 9] = "FLOAT32";
+    NumpyDTypeCode[NumpyDTypeCode["FLOAT64"] = 10] = "FLOAT64";
+    NumpyDTypeCode[NumpyDTypeCode["COMPLEX64"] = 11] = "COMPLEX64";
+    NumpyDTypeCode[NumpyDTypeCode["COMPLEX128"] = 12] = "COMPLEX128";
+})(NumpyDTypeCode || (exports.NumpyDTypeCode = NumpyDTypeCode = {}));
+/** Header size in bytes (see layout above) */
+const HEADER_BYTES = 16;
+// ─── dtype string → NumpyDTypeCode ──────────────────────────────────────────
+const DTYPE_STRING_TO_CODE = {
+    bool: NumpyDTypeCode.BOOL,
+    int8: NumpyDTypeCode.INT8,
+    int16: NumpyDTypeCode.INT16,
+    int32: NumpyDTypeCode.INT32,
+    int64: NumpyDTypeCode.INT64,
+    uint8: NumpyDTypeCode.UINT8,
+    uint16: NumpyDTypeCode.UINT16,
+    uint32: NumpyDTypeCode.UINT32,
+    uint64: NumpyDTypeCode.UINT64,
+    float32: NumpyDTypeCode.FLOAT32,
+    float64: NumpyDTypeCode.FLOAT64,
+    complex64: NumpyDTypeCode.COMPLEX64,
+    complex128: NumpyDTypeCode.COMPLEX128,
+};
+// ─── NumpyDTypeCode → item size in bytes ────────────────────────────────────
+const DTYPE_CODE_TO_ITEMSIZE = {
+    [NumpyDTypeCode.BOOL]: 1,
+    [NumpyDTypeCode.INT8]: 1,
+    [NumpyDTypeCode.INT16]: 2,
+    [NumpyDTypeCode.INT32]: 4,
+    [NumpyDTypeCode.INT64]: 8,
+    [NumpyDTypeCode.UINT8]: 1,
+    [NumpyDTypeCode.UINT16]: 2,
+    [NumpyDTypeCode.UINT32]: 4,
+    [NumpyDTypeCode.UINT64]: 8,
+    [NumpyDTypeCode.FLOAT32]: 4,
+    [NumpyDTypeCode.FLOAT64]: 8,
+    [NumpyDTypeCode.COMPLEX64]: 8,
+    [NumpyDTypeCode.COMPLEX128]: 16,
+};
+/**
+ * NumpyBridge — converts NumPy arrays ↔ TypedArrays.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new NumpyBridge();
+ *
+ * // Serialize a Float32Array → NumPy wire format
+ * const sv = bridge.serializeTypedArray(new Float32Array([1, 2, 3]), 'float32');
+ *
+ * // Deserialize NumPy wire format → TypedArray
+ * const arr = bridge.deserialize(sv) as Float32Array;
+ * ```
+ */
+class NumpyBridge {
+    _useShared;
+    _sharedThreshold;
+    constructor(options = {}) {
+        this._useShared = options.useSharedArrayBuffer ?? false;
+        this._sharedThreshold = options.sharedArrayBufferThreshold ?? 1_048_576; // 1 MB
+    }
+    // ─── Python wire format → TypedArray ─────────────────────────────────────
+    /**
+     * Deserialize a NUMPY_ARRAY SerializedValue to a TypedArray.
+     */
+    deserialize(sv) {
+        if (sv.format !== 'numpy_array') {
+            return null;
+        }
+        const rawData = sv.data;
+        if (!rawData) {
+            logger.warn('NumpyBridge.deserialize: invalid data');
+            return null;
+        }
+        try {
+            let u8;
+            if (typeof rawData === 'string') {
+                // base64-encoded binary
+                const buf = Buffer.from(rawData, 'base64');
+                u8 = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+            }
+            else if (rawData instanceof Uint8Array) {
+                u8 = rawData;
+            }
+            else {
+                logger.warn('NumpyBridge.deserialize: unsupported data type');
+                return null;
+            }
+            if (u8.length < HEADER_BYTES) {
+                logger.warn('NumpyBridge.deserialize: buffer too small');
+                return null;
+            }
+            return this._decodeBuffer(u8);
+        }
+        catch (err) {
+            logger.error('NumpyBridge.deserialize failed', err);
+            return null;
+        }
+    }
+    // ─── TypedArray → Python wire format ─────────────────────────────────────
+    /**
+     * Serialize a TypedArray to a NUMPY_ARRAY SerializedValue.
+     *
+     * @param arr    — the typed array
+     * @param dtype  — NumPy dtype string
+     * @param shape  — optional explicit shape; defaults to [arr.length]
+     */
+    serializeTypedArray(arr, dtype, shape) {
+        const dtypeStr = (typeof dtype === 'string' ? dtype : dtype.dtype);
+        const dtypeCode = DTYPE_STRING_TO_CODE[dtypeStr] ?? NumpyDTypeCode.FLOAT64;
+        const itemSize = DTYPE_CODE_TO_ITEMSIZE[dtypeCode];
+        const dims = shape ?? [arr.byteLength / itemSize];
+        const ndim = dims.length;
+        const count = dims.reduce((a, b) => a * b, 1);
+        const dataBytes = count * itemSize;
+        const totalBytes = HEADER_BYTES + ndim * 4 + dataBytes;
+        const buffer = new ArrayBuffer(totalBytes);
+        const dv = new DataView(buffer);
+        const u8 = new Uint8Array(buffer);
+        // Write header
+        dv.setUint32(0, ndim, true);
+        dv.setUint32(4, dtypeCode, true);
+        dv.setUint32(8, itemSize, true);
+        dv.setUint32(12, count, true);
+        // Write shape
+        for (let i = 0; i < ndim; i++) {
+            dv.setUint32(HEADER_BYTES + i * 4, dims[i], true);
+        }
+        // Write data
+        const srcU8 = new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+        u8.set(srcU8, HEADER_BYTES + ndim * 4);
+        return {
+            format: 'numpy_array',
+            data: u8,
+            metadata: {
+                dtype: dtypeStr,
+                shape: dims,
+                itemSize,
+                size: dataBytes,
+                length: count,
+            },
+        };
+    }
+    /**
+     * Create an empty NumPy array SerializedValue (used for zero-size results).
+     */
+    serializeEmpty(dtype = 'float64') {
+        return this.serializeTypedArray(new Float64Array(0), dtype, [0]);
+    }
+    // ─── Helpers ──────────────────────────────────────────────────────────────
+    _decodeBuffer(u8) {
+        const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+        const ndim = dv.getUint32(0, true);
+        const dtypeCode = dv.getUint32(4, true);
+        const itemSize = dv.getUint32(8, true);
+        const count = dv.getUint32(12, true);
+        // Read shape
+        const shape = [];
+        for (let i = 0; i < ndim; i++) {
+            shape.push(dv.getUint32(HEADER_BYTES + i * 4, true));
+        }
+        const dataOffset = HEADER_BYTES + ndim * 4;
+        const dataLength = count * itemSize;
+        if (u8.length < dataOffset + dataLength) {
+            throw new Error(`NumpyBridge: buffer too small. ` +
+                `Expected ${dataOffset + dataLength} bytes, got ${u8.length}`);
+        }
+        const srcBuffer = u8.buffer;
+        const srcByteOffset = u8.byteOffset + dataOffset;
+        return this._buildTypedArray(dtypeCode, srcBuffer, srcByteOffset, count, shape, ndim);
+    }
+    _buildTypedArray(code, srcBuffer, byteOffset, count, shape = [], ndim = 1) {
+        const useShared = this._useShared &&
+            typeof SharedArrayBuffer !== 'undefined' &&
+            count * DTYPE_CODE_TO_ITEMSIZE[code] >= this._sharedThreshold;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const targetBuffer = (useShared
+            ? new SharedArrayBuffer(count * DTYPE_CODE_TO_ITEMSIZE[code])
+            : new ArrayBuffer(count * DTYPE_CODE_TO_ITEMSIZE[code]));
+        // Copy data
+        const src = new Uint8Array(srcBuffer, byteOffset, count * DTYPE_CODE_TO_ITEMSIZE[code]);
+        const dest = new Uint8Array(targetBuffer);
+        dest.set(src);
+        let data;
+        let dtypeStr;
+        switch (code) {
+            case NumpyDTypeCode.BOOL:
+            case NumpyDTypeCode.UINT8:
+                data = new Uint8Array(targetBuffer);
+                dtypeStr = code === NumpyDTypeCode.BOOL ? 'bool' : 'uint8';
+                break;
+            case NumpyDTypeCode.INT8:
+                data = new Int8Array(targetBuffer);
+                dtypeStr = 'int8';
+                break;
+            case NumpyDTypeCode.INT16:
+                data = new Int16Array(targetBuffer);
+                dtypeStr = 'int16';
+                break;
+            case NumpyDTypeCode.INT32:
+                data = new Int32Array(targetBuffer);
+                dtypeStr = 'int32';
+                break;
+            case NumpyDTypeCode.INT64:
+                data = new BigInt64Array(targetBuffer);
+                dtypeStr = 'int64';
+                break;
+            case NumpyDTypeCode.UINT16:
+                data = new Uint16Array(targetBuffer);
+                dtypeStr = 'uint16';
+                break;
+            case NumpyDTypeCode.UINT32:
+                data = new Uint32Array(targetBuffer);
+                dtypeStr = 'uint32';
+                break;
+            case NumpyDTypeCode.UINT64:
+                data = new BigUint64Array(targetBuffer);
+                dtypeStr = 'uint64';
+                break;
+            case NumpyDTypeCode.FLOAT32:
+                data = new Float32Array(targetBuffer);
+                dtypeStr = 'float32';
+                break;
+            case NumpyDTypeCode.COMPLEX64:
+                data = new Float32Array(targetBuffer);
+                dtypeStr = 'complex64';
+                break;
+            case NumpyDTypeCode.COMPLEX128:
+                data = new Float64Array(targetBuffer);
+                dtypeStr = 'complex128';
+                break;
+            case NumpyDTypeCode.FLOAT64:
+            default:
+                data = new Float64Array(targetBuffer);
+                dtypeStr = 'float64';
+                break;
+        }
+        return { data, dtype: dtypeStr, shape, ndim };
+    }
+    // ─── Static helpers ───────────────────────────────────────────────────────
+    /**
+     * Detect dtype code from a TypedArray instance.
+     */
+    static detectDType(arr) {
+        let dtype;
+        if (arr instanceof Float32Array) {
+            dtype = 'float32';
+        }
+        else if (arr instanceof Float64Array) {
+            dtype = 'float64';
+        }
+        else if (arr instanceof Int8Array) {
+            dtype = 'int8';
+        }
+        else if (arr instanceof Int16Array) {
+            dtype = 'int16';
+        }
+        else if (arr instanceof Int32Array) {
+            dtype = 'int32';
+        }
+        else if (arr instanceof BigInt64Array) {
+            dtype = 'int64';
+        }
+        else if (arr instanceof Uint8Array) {
+            dtype = 'uint8';
+        }
+        else if (arr instanceof Uint16Array) {
+            dtype = 'uint16';
+        }
+        else if (arr instanceof Uint32Array) {
+            dtype = 'uint32';
+        }
+        else if (arr instanceof BigUint64Array) {
+            dtype = 'uint64';
+        }
+        else {
+            dtype = 'float64';
+        }
+        const code = DTYPE_STRING_TO_CODE[dtype] ?? NumpyDTypeCode.FLOAT64;
+        return { dtype, itemsize: DTYPE_CODE_TO_ITEMSIZE[code] };
+    }
+    /**
+     * Return the item size in bytes for a dtype string.
+     */
+    static itemSizeOf(dtype) {
+        const code = DTYPE_STRING_TO_CODE[dtype] ?? NumpyDTypeCode.FLOAT64;
+        return DTYPE_CODE_TO_ITEMSIZE[code];
+    }
+}
+exports.NumpyBridge = NumpyBridge;
+//# sourceMappingURL=NumpyBridge.js.map

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 @@
+/**
+ * nodepyx — 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,8DAA8D;IAC9D,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"}