nodepyx 1.0.0

package/dist/serialization/Serializer.js

@@ -0,0 +1,281 @@
+"use strict";
+/**
+ * nodepyx — 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":"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"}

package/dist/types/PythonTypeMapper.d.ts

@@ -0,0 +1,87 @@
+/**
+ * nodepyx — PythonTypeMapper
+ * Maps Python type annotation strings → TypeScript type strings.
+ *
+ * Handles:
+ *  - Python built-in types (str, int, float, bool, …)
+ *  - typing module generics (List[X], Dict[K,V], Optional[X], Union[A,B], …)
+ *  - numpy / pandas / torch special types
+ *  - Forward references (strings in quotes)
+ *  - PEP 604 union syntax (X | Y)
+ */
+export type TsType = string;
+/**
+ * Mapping entry — maps a Python canonical name to a TS type.
+ */
+export interface TypeMapEntry {
+    /** TypeScript type string */
+    tsType: TsType;
+    /** Whether this type needs an import statement */
+    needsImport?: boolean;
+    /** The import path (e.g. './DataFrameBridge') */
+    importFrom?: string;
+}
+/** Context passed to mapType for resolving generic parameters */
+export interface TypeMapContext {
+    /** Known class names from the current module */
+    knownClasses?: Set<string>;
+    /** Module name being inspected */
+    moduleName?: string;
+    /** Whether to emit strict types (never use `unknown`) */
+    strict?: boolean;
+}
+/**
+ * Map a Python type annotation string to a TypeScript type string.
+ *
+ * @example
+ * ```typescript
+ * mapType('List[int]')               // → 'Array<number>'
+ * mapType('Dict[str, float]')        // → 'Record<string, number>'
+ * mapType('Optional[DataFrame]')     // → 'DataFrameResult | null'
+ * mapType('Union[str, int, None]')   // → 'string | number | null'
+ * mapType('Tuple[int, str, bool]')   // → '[number, string, boolean]'
+ * ```
+ */
+export declare function mapType(pythonType: string, ctx?: TypeMapContext): TsType;
+/**
+ * Map a Python return type annotation.
+ * Automatically wraps the result in `Promise<>` since all Python calls
+ * are asynchronous from the JavaScript side.
+ *
+ * Generator / Iterator returns are mapped to `AsyncGenerator`.
+ * None → Promise<void>
+ */
+export declare function mapReturnType(pythonReturnType: string, ctx?: TypeMapContext): TsType;
+/**
+ * Convert a Python default value representation to a TypeScript literal.
+ */
+export declare function mapDefaultValue(pythonDefault: string): string;
+/**
+ * Split generic parameters at the top level (respects nested brackets).
+ * e.g. "str, Dict[str, int], bool" → ["str", "Dict[str, int]", "bool"]
+ */
+export declare function splitGenericParams(params: string): string[];
+/**
+ * Stateful type mapper that accumulates required imports
+ * and knows which class names belong to the current module.
+ *
+ * @example
+ * ```typescript
+ * const mapper = new PythonTypeMapper({ moduleName: 'sklearn.linear_model' });
+ * mapper.registerClass('LinearRegression');
+ *
+ * mapper.map('LinearRegression')  // → 'LinearRegression' (local class ref)
+ * mapper.map('DataFrame')         // → 'DataFrameResult'
+ * ```
+ */
+export declare class PythonTypeMapper {
+    private readonly _ctx;
+    private readonly _imports;
+    constructor(ctx?: TypeMapContext);
+    registerClass(name: string): void;
+    map(pyType: string): TsType;
+    mapReturn(pyType: string): TsType;
+    addImport(symbol: string, from: string): void;
+    generateImportBlock(): string;
+}
+//# sourceMappingURL=PythonTypeMapper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PythonTypeMapper.d.ts","sourceRoot":"","sources":["../../src/types/PythonTypeMapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAoOD;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CACrB,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,cAAmB,GACvB,MAAM,CA0CR;AAID;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,gBAAgB,EAAE,MAAM,EACxB,GAAG,GAAE,cAAmB,GACvB,MAAM,CAwBR;AAID;;GAEG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAS7D;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB3D;AA2BD;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;gBAE/C,GAAG,GAAE,cAAmB;IAOpC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAa3B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAIjC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAO7C,mBAAmB,IAAI,MAAM;CAO9B"}