@woosh/meep-engine 2.165.0 → 2.165.2

package/src/engine/ecs/storage/binary/object-v2/BinaryObjectDeSerializer.js

@@ -0,0 +1,315 @@
+import { assert } from "../../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+import { executeBinaryClassUpgraderChain } from "../executeBinaryClassUpgraderChain.js";
+import { readObjectString } from "./objectStringCodec.js";
+import {
+    OBJECT_FORMAT_VERSION,
+    OBJECT_MAGIC,
+    TAG_ADAPTER_OBJECT,
+    TAG_ARRAY,
+    TAG_BIGINT,
+    TAG_FALSE,
+    TAG_FLOAT,
+    TAG_NEG_INT,
+    TAG_NULL,
+    TAG_PLAIN_OBJECT,
+    TAG_POS_INT,
+    TAG_REF,
+    TAG_REFLECT_OBJECT,
+    TAG_STRING,
+    TAG_TRUE,
+    TAG_UNDEFINED
+} from "./ObjectBinaryFormat.js";
+
+/**
+ * A resolved class-table entry. Migration is resolved lazily, on the first adapter-encoded object of the class,
+ * because whether a class was written via an adapter (and therefore whether the stored version needs migrating) is
+ * a property of the object tag in the body, not of the reader's registry.
+ *
+ * @typedef {Object} ResolvedClass
+ * @property {string} typeName
+ * @property {number} version version the data was written with
+ * @property {BinaryClassSerializationAdapter|undefined} adapter registered adapter, or undefined
+ * @property {Function|undefined} Klass constructor to instantiate, or undefined if unresolvable
+ * @property {BinaryClassUpgrader[]|null} migrators cached migrator chain (null = none needed)
+ * @property {boolean} migratorsResolved whether the migrator chain has been computed yet
+ */
+
+/**
+ * Reader half of the general object-graph binary serializer. Consumes documents produced by
+ * {@link BinaryObjectSerializer}.
+ *
+ * Needs:
+ *  - a {@link BinarySerializationRegistry} for hand-written adapters and version migrators;
+ *  - a {@link ModuleRegistry} mapping `typeName -> class` so reflective (adapter-less) class instances can be
+ *    reconstructed. It may be omitted if the data contains no reflective class instances (plain objects, arrays and
+ *    adapter-backed classes need no module registry).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BinaryObjectDeSerializer {
+
+    /**
+     * @type {BinarySerializationRegistry|null}
+     */
+    #registry = null;
+
+    /**
+     * @type {ModuleRegistry|null}
+     */
+    #modules = null;
+
+    /**
+     * index -> reconstructed object/array, for resolving back-references and cycles.
+     * @type {Array<Object>}
+     */
+    #refs = [];
+
+    /**
+     * @type {ResolvedClass[]}
+     */
+    #classes = [];
+
+    /**
+     * @type {Array<string[]>}
+     */
+    #shapes = [];
+
+    /**
+     * @param {BinarySerializationRegistry} registry
+     * @param {ModuleRegistry} [modules] required only if the data contains reflective (adapter-less) class instances
+     */
+    constructor(registry, modules) {
+        this.setRegistry(registry);
+        this.setModuleRegistry(modules);
+    }
+
+    /**
+     * @param {BinarySerializationRegistry} registry
+     */
+    setRegistry(registry) {
+        assert.defined(registry, 'registry');
+        assert.ok(registry.isBinarySerializationRegistry, 'registry is not a BinarySerializationRegistry');
+
+        this.#registry = registry;
+    }
+
+    /**
+     * @param {ModuleRegistry} [modules]
+     */
+    setModuleRegistry(modules) {
+        this.#modules = modules === undefined ? null : modules;
+    }
+
+    /**
+     * Deserialize a complete document written by {@link BinaryObjectSerializer.serialize}.
+     *
+     * @template T
+     * @param {BinaryBuffer} buffer source, read at the current {@link BinaryBuffer.position}
+     * @returns {T}
+     */
+    deserialize(buffer) {
+        const magic = buffer.readUint16();
+
+        if (magic !== OBJECT_MAGIC) {
+            throw new Error(`Not an object-graph stream: expected magic 0x${OBJECT_MAGIC.toString(16).toUpperCase()}, read 0x${magic.toString(16).toUpperCase()}`);
+        }
+
+        const formatVersion = buffer.readUint8();
+
+        if (formatVersion !== OBJECT_FORMAT_VERSION) {
+            throw new Error(`Unsupported object-graph format version ${formatVersion}, this build supports ${OBJECT_FORMAT_VERSION}`);
+        }
+
+        this.#refs = [];
+        this.#classes = [];
+        this.#shapes = [];
+
+        // class table
+        const classCount = buffer.readUintVar();
+        for (let i = 0; i < classCount; i++) {
+            const typeName = readObjectString(buffer);
+            const version = buffer.readUintVar();
+            this.#classes.push(this.#resolveClass(typeName, version));
+        }
+
+        // shape table
+        const shapeCount = buffer.readUintVar();
+        for (let i = 0; i < shapeCount; i++) {
+            const fieldCount = buffer.readUintVar();
+            const names = new Array(fieldCount);
+            for (let j = 0; j < fieldCount; j++) {
+                names[j] = readObjectString(buffer);
+            }
+            this.#shapes.push(names);
+        }
+
+        return this.readValue(buffer);
+    }
+
+    /**
+     * Resolve a class name to its adapter and/or constructor. Does not resolve migrators — that is deferred to the
+     * first adapter-encoded object of the class (see {@link ResolvedClass}).
+     *
+     * @param {string} typeName
+     * @param {number} version
+     * @returns {ResolvedClass}
+     */
+    #resolveClass(typeName, version) {
+        const adapter = this.#registry.getAdapter(typeName);
+
+        let Klass;
+
+        if (adapter !== undefined) {
+            Klass = adapter.klass;
+        } else if (this.#modules !== null && this.#modules.has(typeName)) {
+            Klass = this.#modules.get(typeName);
+        } else {
+            Klass = undefined;
+        }
+
+        return { typeName, version, adapter, Klass, migrators: null, migratorsResolved: false };
+    }
+
+    /**
+     * Read a single value. Nesting adapters call this to deserialize a child of any type.
+     *
+     * @template T
+     * @param {BinaryBuffer} buffer
+     * @returns {T}
+     */
+    readValue(buffer) {
+        const tag = buffer.readUint8();
+
+        switch (tag) {
+            case TAG_NULL:
+                return null;
+            case TAG_UNDEFINED:
+                return undefined;
+            case TAG_FALSE:
+                return false;
+            case TAG_TRUE:
+                return true;
+            case TAG_POS_INT:
+                return buffer.readUintVar();
+            case TAG_NEG_INT:
+                return -buffer.readUintVar();
+            case TAG_FLOAT:
+                return buffer.readFloat64();
+            case TAG_STRING:
+                return readObjectString(buffer);
+            case TAG_BIGINT:
+                return BigInt(readObjectString(buffer));
+            case TAG_REF:
+                return this.#refs[buffer.readUintVar()];
+            case TAG_ARRAY:
+                return this.#readArray(buffer);
+            case TAG_PLAIN_OBJECT: {
+                const shapeIdx = buffer.readUintVar();
+                return this.#readReflected(buffer, {}, shapeIdx);
+            }
+            case TAG_REFLECT_OBJECT: {
+                const record = this.#classes[buffer.readUintVar()];
+                const shapeIdx = buffer.readUintVar();
+
+                if (record.Klass === undefined) {
+                    throw new Error(`Cannot reconstruct reflective class '${record.typeName}': it is not in the module registry and has no registered adapter`);
+                }
+
+                return this.#readReflected(buffer, new record.Klass(), shapeIdx);
+            }
+            case TAG_ADAPTER_OBJECT:
+                return this.#readAdapterObject(buffer);
+            default:
+                throw new Error(`Unknown object-graph value tag ${tag}`);
+        }
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @returns {Array<*>}
+     */
+    #readArray(buffer) {
+        const length = buffer.readUintVar();
+
+        const array = [];
+        // register before filling so a cyclic element can refer back to this array
+        this.#refs.push(array);
+
+        for (let i = 0; i < length; i++) {
+            array.push(this.readValue(buffer));
+        }
+
+        return array;
+    }
+
+    /**
+     * @template T
+     * @param {BinaryBuffer} buffer
+     * @param {T} target freshly-constructed instance (or {}) to populate
+     * @param {number} shapeIdx
+     * @returns {T}
+     */
+    #readReflected(buffer, target, shapeIdx) {
+        // register before filling so a cyclic field can refer back to this object
+        this.#refs.push(target);
+
+        const names = this.#shapes[shapeIdx];
+
+        for (let i = 0; i < names.length; i++) {
+            target[names[i]] = this.readValue(buffer);
+        }
+
+        return target;
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @returns {Object}
+     */
+    #readAdapterObject(buffer) {
+        const record = this.#classes[buffer.readUintVar()];
+
+        if (record.adapter === undefined) {
+            throw new Error(`Cannot read adapter-encoded object of class '${record.typeName}': no adapter is registered`);
+        }
+
+        if (!record.migratorsResolved) {
+            if (record.version !== record.adapter.version) {
+                // migrate up OR down to the adapter's current version
+                const chain = this.#registry.getUpgradersChain(record.typeName, record.version, record.adapter.version);
+
+                if (chain === null) {
+                    throw new Error(`No migration path for class '${record.typeName}' from version ${record.version} to ${record.adapter.version}`);
+                }
+
+                record.migrators = chain;
+            }
+
+            record.migratorsResolved = true;
+        }
+
+        const value = new record.Klass();
+        // register before the adapter reads, so a cyclic reference inside the payload resolves to this instance
+        this.#refs.push(value);
+
+        let payloadBuffer = buffer;
+
+        if (record.migrators !== null) {
+            // fresh scratch buffers keep migration re-entrant if the payload itself nests an object needing migration
+            payloadBuffer = executeBinaryClassUpgraderChain(record.migrators, buffer, new BinaryBuffer(), new BinaryBuffer());
+        }
+
+        record.adapter.initialize(this);
+        record.adapter.deserialize(payloadBuffer, value);
+
+        return value;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+BinaryObjectDeSerializer.prototype.isBinaryObjectDeSerializer = true;

package/src/engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Writer half of the general object-graph binary serializer. See {@link BinaryObjectDeSerializer} for the reader
+ * and `DESIGN.md` for the wire format and rationale.
+ *
+ * Serializes an arbitrary value — primitives, arrays, plain objects and class instances — with **no per-class
+ * setup required**. Class instances are serialized by reflection over their own enumerable fields by default; if a
+ * class has a hand-written adapter registered in the {@link BinarySerializationRegistry}, that adapter is used
+ * instead (compact, custom, versioned). Shared references and cycles are preserved via first-seen object indices.
+ *
+ * Class names and reflective field-name sets are interned into two tables that are written ahead of the body, so
+ * repeated types cost their name once. The body is built into a scratch buffer first and copied in after the
+ * tables — the only extra work versus single-pass is that final byte copy.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BinaryObjectSerializer {
+    /**
+     * @param {BinarySerializationRegistry} registry
+     */
+    constructor(registry: BinarySerializationRegistry);
+    /**
+     * @param {BinarySerializationRegistry} registry
+     */
+    setRegistry(registry: BinarySerializationRegistry): void;
+    /**
+     * Serialize `value` and its whole object graph into `buffer` as a complete document (header + tables + body).
+     *
+     * @param {BinaryBuffer} buffer target, written at the current {@link BinaryBuffer.position}
+     * @param {*} value any value; objects may be plain, class instances (reflective or adapter-backed) or arrays
+     */
+    serialize(buffer: BinaryBuffer, value: any): void;
+    /**
+     * Write a single value. Nesting adapters call this to serialize a child of any type (including `null`).
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {*} value
+     */
+    writeValue(buffer: BinaryBuffer, value: any): void;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isBinaryObjectSerializer: boolean;
+    #private;
+}
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+//# sourceMappingURL=BinaryObjectSerializer.d.ts.map

package/src/engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BinaryObjectSerializer.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;GAeG;AACH;IA4CI;;OAEG;IACH,mDAEC;IAED;;OAEG;IACH,yDAKC;IAWD;;;;;OAKG;IACH,kBAHW,YAAY,oBAiCtB;IAqCD;;;;;OAKG;IACH,mBAHW,YAAY,oBA2GtB;IA4BL;;;OAGG;IACH,mCAFU,OAAO,CAEwC;;CANxD;6BAnU4B,4CAA4C"}

package/src/engine/ecs/storage/binary/object-v2/BinaryObjectSerializer.js

@@ -0,0 +1,331 @@
+import { assert } from "../../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+import { writeObjectString } from "./objectStringCodec.js";
+import {
+    OBJECT_FORMAT_VERSION,
+    OBJECT_MAGIC,
+    TAG_ADAPTER_OBJECT,
+    TAG_ARRAY,
+    TAG_BIGINT,
+    TAG_FALSE,
+    TAG_FLOAT,
+    TAG_NEG_INT,
+    TAG_NULL,
+    TAG_PLAIN_OBJECT,
+    TAG_POS_INT,
+    TAG_REF,
+    TAG_REFLECT_OBJECT,
+    TAG_STRING,
+    TAG_TRUE,
+    TAG_UNDEFINED
+} from "./ObjectBinaryFormat.js";
+
+/**
+ * Largest integer magnitude that {@link BinaryBuffer.writeUintVar} accepts; larger integers fall back to float64.
+ * @readonly
+ * @type {number}
+ */
+const MAX_VARINT = 2147483647;
+
+/**
+ * Writer half of the general object-graph binary serializer. See {@link BinaryObjectDeSerializer} for the reader
+ * and `DESIGN.md` for the wire format and rationale.
+ *
+ * Serializes an arbitrary value — primitives, arrays, plain objects and class instances — with **no per-class
+ * setup required**. Class instances are serialized by reflection over their own enumerable fields by default; if a
+ * class has a hand-written adapter registered in the {@link BinarySerializationRegistry}, that adapter is used
+ * instead (compact, custom, versioned). Shared references and cycles are preserved via first-seen object indices.
+ *
+ * Class names and reflective field-name sets are interned into two tables that are written ahead of the body, so
+ * repeated types cost their name once. The body is built into a scratch buffer first and copied in after the
+ * tables — the only extra work versus single-pass is that final byte copy.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BinaryObjectSerializer {
+
+    /**
+     * Adapter + migrator + class-name registry.
+     * @type {BinarySerializationRegistry|null}
+     */
+    #registry = null;
+
+    /**
+     * Scratch buffer the value graph (body) is written into before it is copied in after the tables.
+     * @type {BinaryBuffer}
+     */
+    #body = new BinaryBuffer();
+
+    /**
+     * Object/array instance -> its assigned index, for reference de-duplication and cycle detection.
+     * @type {Map<Object, number>}
+     */
+    #refs = new Map();
+
+    /**
+     * typeName -> class-table index.
+     * @type {Map<string, number>}
+     */
+    #classIndex = new Map();
+
+    /**
+     * Ordered class-table records, flushed ahead of the body.
+     * @type {Array<{typeName:string, version:number}>}
+     */
+    #classList = [];
+
+    /**
+     * shape key (JSON of the field-name list) -> shape-table index.
+     * @type {Map<string, number>}
+     */
+    #shapeIndex = new Map();
+
+    /**
+     * Ordered shape-table records (each an ordered field-name list), flushed ahead of the body.
+     * @type {Array<string[]>}
+     */
+    #shapeList = [];
+
+    /**
+     * @param {BinarySerializationRegistry} registry
+     */
+    constructor(registry) {
+        this.setRegistry(registry);
+    }
+
+    /**
+     * @param {BinarySerializationRegistry} registry
+     */
+    setRegistry(registry) {
+        assert.defined(registry, 'registry');
+        assert.ok(registry.isBinarySerializationRegistry, 'registry is not a BinarySerializationRegistry');
+
+        this.#registry = registry;
+    }
+
+    #reset() {
+        this.#body.position = 0;
+        this.#refs.clear();
+        this.#classIndex.clear();
+        this.#classList.length = 0;
+        this.#shapeIndex.clear();
+        this.#shapeList.length = 0;
+    }
+
+    /**
+     * Serialize `value` and its whole object graph into `buffer` as a complete document (header + tables + body).
+     *
+     * @param {BinaryBuffer} buffer target, written at the current {@link BinaryBuffer.position}
+     * @param {*} value any value; objects may be plain, class instances (reflective or adapter-backed) or arrays
+     */
+    serialize(buffer, value) {
+        this.#reset();
+
+        // build the body first so the interning tables are complete before we emit them
+        this.writeValue(this.#body, value);
+
+        // header
+        buffer.writeUint16(OBJECT_MAGIC);
+        buffer.writeUint8(OBJECT_FORMAT_VERSION);
+
+        // class table
+        buffer.writeUintVar(this.#classList.length);
+        for (let i = 0; i < this.#classList.length; i++) {
+            const record = this.#classList[i];
+            writeObjectString(buffer, record.typeName);
+            buffer.writeUintVar(record.version);
+        }
+
+        // shape table
+        buffer.writeUintVar(this.#shapeList.length);
+        for (let i = 0; i < this.#shapeList.length; i++) {
+            const names = this.#shapeList[i];
+            buffer.writeUintVar(names.length);
+            for (let j = 0; j < names.length; j++) {
+                writeObjectString(buffer, names[j]);
+            }
+        }
+
+        // body
+        buffer.writeBytes(this.#body.raw_bytes, 0, this.#body.position);
+    }
+
+    /**
+     * @param {string} typeName
+     * @param {number} version
+     * @returns {number} class-table index
+     */
+    #internClass(typeName, version) {
+        let index = this.#classIndex.get(typeName);
+
+        if (index === undefined) {
+            index = this.#classList.length;
+            this.#classList.push({ typeName, version });
+            this.#classIndex.set(typeName, index);
+        }
+
+        return index;
+    }
+
+    /**
+     * @param {string[]} names ordered field names
+     * @returns {number} shape-table index
+     */
+    #internShape(names) {
+        const key = JSON.stringify(names);
+
+        let index = this.#shapeIndex.get(key);
+
+        if (index === undefined) {
+            index = this.#shapeList.length;
+            this.#shapeList.push(names);
+            this.#shapeIndex.set(key, index);
+        }
+
+        return index;
+    }
+
+    /**
+     * Write a single value. Nesting adapters call this to serialize a child of any type (including `null`).
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {*} value
+     */
+    writeValue(buffer, value) {
+        if (value === null) {
+            buffer.writeUint8(TAG_NULL);
+            return;
+        }
+
+        const type = typeof value;
+
+        switch (type) {
+            case "undefined":
+                buffer.writeUint8(TAG_UNDEFINED);
+                return;
+            case "boolean":
+                buffer.writeUint8(value ? TAG_TRUE : TAG_FALSE);
+                return;
+            case "number":
+                if (Number.isInteger(value) && value >= -MAX_VARINT && value <= MAX_VARINT) {
+                    if (value >= 0) {
+                        buffer.writeUint8(TAG_POS_INT);
+                        buffer.writeUintVar(value);
+                    } else {
+                        buffer.writeUint8(TAG_NEG_INT);
+                        buffer.writeUintVar(-value);
+                    }
+                } else {
+                    buffer.writeUint8(TAG_FLOAT);
+                    buffer.writeFloat64(value);
+                }
+                return;
+            case "string":
+                buffer.writeUint8(TAG_STRING);
+                writeObjectString(buffer, value);
+                return;
+            case "bigint":
+                buffer.writeUint8(TAG_BIGINT);
+                writeObjectString(buffer, value.toString());
+                return;
+            case "function":
+                throw new Error("Cannot serialize a function value");
+            case "symbol":
+                throw new Error("Cannot serialize a symbol value");
+            default:
+            // object, handled below
+        }
+
+        // from here `value` is a non-null object (or array)
+
+        const existingIndex = this.#refs.get(value);
+
+        if (existingIndex !== undefined) {
+            // seen before — emit a back-reference (handles shared references and cycles)
+            buffer.writeUint8(TAG_REF);
+            buffer.writeUintVar(existingIndex);
+            return;
+        }
+
+        // assign this instance its index BEFORE writing contents, so a cyclic child can refer back to it
+        this.#refs.set(value, this.#refs.size);
+
+        if (Array.isArray(value)) {
+            buffer.writeUint8(TAG_ARRAY);
+            buffer.writeUintVar(value.length);
+            for (let i = 0; i < value.length; i++) {
+                this.writeValue(buffer, value[i]);
+            }
+            return;
+        }
+
+        const prototype = Object.getPrototypeOf(value);
+        const ctor = prototype === null ? undefined : prototype.constructor;
+
+        // prefer the adapter-registered name (survives minification, keyed on the constructor), then the class's
+        // own static typeName (the deliberate escape hatch from name mangling). The typeName must be OWN, not
+        // inherited: a subclass without its own typeName would otherwise be misclassified as its ancestor.
+        let typeName = this.#registry.getClassName(ctor);
+        if (typeName === undefined && ctor !== undefined && Object.prototype.hasOwnProperty.call(ctor, "typeName")) {
+            typeName = ctor.typeName;
+        }
+
+        if (typeName !== undefined && typeName !== null) {
+            const adapter = this.#registry.getAdapter(typeName);
+
+            if (adapter !== undefined) {
+                // hand-written adapter takes over the payload layout for this class
+                const classIdx = this.#internClass(typeName, adapter.version);
+                buffer.writeUint8(TAG_ADAPTER_OBJECT);
+                buffer.writeUintVar(classIdx);
+                adapter.initialize(this);
+                adapter.serialize(buffer, value);
+                return;
+            }
+
+            // reflective class instance — reconstructed via the module registry on read
+            this.#writeReflected(buffer, TAG_REFLECT_OBJECT, this.#internClass(typeName, 0), value);
+            return;
+        }
+
+        if (prototype === Object.prototype || prototype === null) {
+            // plain object — reconstructed as {} on read
+            this.#writeReflected(buffer, TAG_PLAIN_OBJECT, -1, value);
+            return;
+        }
+
+        throw new Error(`Cannot serialize instance of '${ctor && ctor.name}': it has no registered adapter and no static 'typeName'. Add a static typeName (so it survives minification) or register an adapter.`);
+    }
+
+    /**
+     * Write a reflective object body: `[classIdx] shapeIdx value*`.
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {number} tag {@link TAG_REFLECT_OBJECT} or {@link TAG_PLAIN_OBJECT}
+     * @param {number} classIdx class-table index, or -1 for a plain object (not written)
+     * @param {Object} value
+     */
+    #writeReflected(buffer, tag, classIdx, value) {
+        const names = Object.keys(value);
+        const shapeIdx = this.#internShape(names);
+
+        buffer.writeUint8(tag);
+
+        if (classIdx >= 0) {
+            buffer.writeUintVar(classIdx);
+        }
+
+        buffer.writeUintVar(shapeIdx);
+
+        for (let i = 0; i < names.length; i++) {
+            this.writeValue(buffer, value[names[i]]);
+        }
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+BinaryObjectSerializer.prototype.isBinaryObjectSerializer = true;