pynect 0.0.0-stage → 0.2.0

package/dist/serialization/MsgPackSerializer.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * pynect - MsgPackSerializer
+ * MessagePack encoder/decoder for high-performance binary serialization.
+ * Used for large arrays, complex objects, and bulk data transfer.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MsgPackSerializer = void 0;
+const msgpack = __importStar(require("@msgpack/msgpack"));
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('MsgPackSerializer');
+/**
+ * Extension type definitions for custom Python types.
+ * Extension type 1 = Python datetime
+ * Extension type 2 = Python complex number
+ * Extension type 3 = Python set
+ * Extension type 4 = Python tuple
+ * Extension type 5 = Python bytes
+ */
+var MsgPackExtType;
+(function (MsgPackExtType) {
+    MsgPackExtType[MsgPackExtType["DATETIME"] = 1] = "DATETIME";
+    MsgPackExtType[MsgPackExtType["COMPLEX"] = 2] = "COMPLEX";
+    MsgPackExtType[MsgPackExtType["SET"] = 3] = "SET";
+    MsgPackExtType[MsgPackExtType["TUPLE"] = 4] = "TUPLE";
+    MsgPackExtType[MsgPackExtType["BYTES"] = 5] = "BYTES";
+    MsgPackExtType[MsgPackExtType["NUMPY_DTYPE"] = 10] = "NUMPY_DTYPE";
+})(MsgPackExtType || (MsgPackExtType = {}));
+/**
+ * MsgPackSerializer - encodes/decodes JavaScript <-> MessagePack binary.
+ *
+ * Handles Python-specific types via extension codecs:
+ * - Python datetime -> JS Date
+ * - Python set -> JS Set
+ * - Python tuple -> JS Array (immutable semantics lost, acceptable)
+ * - Python bytes -> JS Uint8Array
+ * - Python complex -> JS {real, imag}
+ *
+ * @example
+ * ```typescript
+ * const serializer = new MsgPackSerializer();
+ * const encoded = serializer.encode({ key: 'value', nums: [1, 2, 3] });
+ * const decoded = serializer.decode(encoded);
+ * ```
+ */
+class MsgPackSerializer {
+    _encoderOptions;
+    _decoderOptions;
+    constructor() {
+        this._encoderOptions = {
+            extensionCodec: this._createExtensionCodec(),
+            forceIntegerToFloat: false,
+            forceFloat32: false,
+            sortKeys: false,
+            maxDepth: 64,
+        };
+        this._decoderOptions = {
+            extensionCodec: this._createExtensionCodec(),
+            // rawBinaryType: 'Uint8Array',
+            useBigInt64: false,
+        };
+    }
+    /**
+     * Encode a JavaScript value to MessagePack binary.
+     */
+    encode(value) {
+        try {
+            return msgpack.encode(value, this._encoderOptions);
+        }
+        catch (err) {
+            logger.error('MsgPack encoding failed', err);
+            // Fallback: try encoding as JSON string
+            try {
+                const json = JSON.stringify(value);
+                return msgpack.encode(json, this._encoderOptions);
+            }
+            catch {
+                // Last resort: empty bytes
+                return new Uint8Array(0);
+            }
+        }
+    }
+    /**
+     * Decode a MessagePack binary to a JavaScript value.
+     */
+    decode(data) {
+        if (!data || data.length === 0) {
+            return null;
+        }
+        try {
+            return msgpack.decode(data, this._decoderOptions);
+        }
+        catch (err) {
+            logger.error('MsgPack decoding failed', err);
+            return null;
+        }
+    }
+    /**
+     * Encode a stream of values (for streaming large datasets).
+     */
+    encodeStream(values) {
+        const chunks = [];
+        let totalLength = 0;
+        for (const value of values) {
+            const encoded = this.encode(value);
+            chunks.push(encoded);
+            totalLength += encoded.length;
+        }
+        // Concatenate all chunks
+        const result = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return result;
+    }
+    /**
+     * Decode a stream of values from MessagePack binary.
+     */
+    *decodeStream(data) {
+        if (!data || data.length === 0) {
+            return;
+        }
+        try {
+            for (const item of msgpack.decodeMulti(data, this._decoderOptions)) {
+                yield item;
+            }
+        }
+        catch (err) {
+            logger.error('MsgPack stream decoding failed', err);
+        }
+    }
+    // Extension Codec
+    _createExtensionCodec() {
+        const codec = new msgpack.ExtensionCodec();
+        // Python datetime -> JS Date
+        codec.register({
+            type: MsgPackExtType.DATETIME,
+            encode: (value) => {
+                if (value instanceof Date) {
+                    const ms = value.getTime();
+                    const buf = new ArrayBuffer(8);
+                    new DataView(buf).setFloat64(0, ms, false);
+                    return new Uint8Array(buf);
+                }
+                return null;
+            },
+            decode: (data) => {
+                const ms = new DataView(data.buffer, data.byteOffset, data.byteLength).getFloat64(0, false);
+                return new Date(ms);
+            },
+        });
+        // Python complex -> {real, imag}
+        codec.register({
+            type: MsgPackExtType.COMPLEX,
+            encode: (value) => {
+                if (value !== null &&
+                    typeof value === 'object' &&
+                    'real' in value &&
+                    'imag' in value) {
+                    const buf = new ArrayBuffer(16);
+                    const dv = new DataView(buf);
+                    dv.setFloat64(0, value.real, false);
+                    dv.setFloat64(8, value.imag, false);
+                    return new Uint8Array(buf);
+                }
+                return null;
+            },
+            decode: (data) => {
+                const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+                return {
+                    real: dv.getFloat64(0, false),
+                    imag: dv.getFloat64(8, false),
+                };
+            },
+        });
+        // Python set -> JS Set
+        codec.register({
+            type: MsgPackExtType.SET,
+            encode: (value) => {
+                if (value instanceof Set) {
+                    const arr = Array.from(value);
+                    return this.encode(arr);
+                }
+                return null;
+            },
+            decode: (data) => {
+                const arr = this.decode(data);
+                return new Set(arr);
+            },
+        });
+        // Python tuple -> JS Array
+        codec.register({
+            type: MsgPackExtType.TUPLE,
+            encode: (_value) => {
+                // Tuples are encoded as arrays by Python side
+                return null;
+            },
+            decode: (data) => {
+                const decoded = this.decode(data);
+                return Array.isArray(decoded) ? decoded : [decoded];
+            },
+        });
+        return codec;
+    }
+}
+exports.MsgPackSerializer = MsgPackSerializer;
+//# sourceMappingURL=MsgPackSerializer.js.map

package/dist/serialization/MsgPackSerializer.js.map

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

package/dist/serialization/NumpyBridge.d.ts

@@ -0,0 +1,96 @@
+/**
+ * pynect - 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 x 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";
+/**
+ * pynect - 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 x 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 pynect_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