@woosh/meep-engine 2.164.0 → 2.165.1

package/src/engine/ecs/storage/binary/BinarySerializationRegistry.d.ts

@@ -36,6 +36,15 @@ export class BinarySerializationRegistry {
      * @returns {BinaryClassSerializationAdapter|undefined}
      */
     removeAdapter(className: string): BinaryClassSerializationAdapter | undefined;
+    /**
+     * Reverse of {@link registerAdapter}: resolve the registered class name for a given class (constructor).
+     * Useful when serializing a value whose class name is not known up-front — obtain the constructor via
+     * `Object.getPrototypeOf(value).constructor` and look it up here. Does not read or mutate any instance.
+     *
+     * @param {Function} klass class/constructor to look up
+     * @returns {string|undefined} the class name under which an adapter is registered, or `undefined` if none
+     */
+    getClassName(klass: Function): string | undefined;
     /**
      *
      * @param {string} className
@@ -62,5 +71,6 @@ export class BinarySerializationRegistry {
      * @type {boolean}
      */
     readonly isBinarySerializationRegistry: boolean;
+    #private;
 }
 //# sourceMappingURL=BinarySerializationRegistry.d.ts.map

package/src/engine/ecs/storage/binary/BinarySerializationRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BinarySerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/storage/binary/BinarySerializationRegistry.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH;IAEI;;;;OAIG;IACH,2BAAsB;IACtB;;;;OAIG;IACH,6BAAwB;IAExB;;;OAGG;IACH,2BAFW,iCAAiC,QAM3C;IAED;;;;;;OAMG;IACH,sEAJW,MAAM,GACJ,OAAO,CAkCnB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,kCAAgC,SAAS,CAYrD;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACJ,kCAAgC,SAAS,CAMrD;IAED;;;;;OAKG;IACH,4BAJW,MAAM,kCAEJ,OAAO,CA6CnB;IAED;;;;;;OAMG;IACH,6BALW,MAAM,gBACN,MAAM,eACN,MAAM,GACJ,qBAAqB,GAAC,IAAI,CA0DtC;IAIL;;;OAGG;IACH,wCAFU,OAAO,CAEkD;CANlE"}
+{"version":3,"file":"BinarySerializationRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/storage/binary/BinarySerializationRegistry.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH;IAEI;;;;OAIG;IACH,2BAAsB;IACtB;;;;OAIG;IACH,6BAAwB;IAWxB;;;OAGG;IACH,2BAFW,iCAAiC,QAM3C;IAED;;;;;;OAMG;IACH,sEAJW,MAAM,GACJ,OAAO,CAyCnB;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACJ,kCAAgC,SAAS,CA2BrD;IAED;;;;;;;OAOG;IACH,+BAFa,MAAM,GAAC,SAAS,CAI5B;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACJ,kCAAgC,SAAS,CAMrD;IAED;;;;;OAKG;IACH,4BAJW,MAAM,kCAEJ,OAAO,CA6CnB;IAED;;;;;;OAMG;IACH,6BALW,MAAM,gBACN,MAAM,eACN,MAAM,GACJ,qBAAqB,GAAC,IAAI,CA0DtC;IAIL;;;OAGG;IACH,wCAFU,OAAO,CAEkD;;CANlE"}

package/src/engine/ecs/storage/binary/BinarySerializationRegistry.js

@@ -22,6 +22,15 @@ export class BinarySerializationRegistry {
      */
     serializers = new Map();
 
+    /**
+     * Reverse index of the {@link serializers} map, keyed by the adapter's {@link BinaryClassSerializationAdapter.klass}.
+     * Lets callers resolve the registered class name of a value from its constructor without touching the value itself.
+     * When one class is registered under several names, the first registered name wins (mirrors {@link serializers}).
+     * @readonly
+     * @type {Map<Function, string>}
+     */
+    #klass_to_name = new Map();
+
     /**
      *
      * @param {BinaryClassSerializationAdapter[]} adapters
@@ -69,6 +78,13 @@ export class BinarySerializationRegistry {
 
         this.serializers.set(_className, adapter);
 
+        const klass = adapter.klass;
+
+        if (klass !== null && klass !== undefined && !this.#klass_to_name.has(klass)) {
+            // record reverse mapping, first registered name wins
+            this.#klass_to_name.set(klass, _className);
+        }
+
         return true;
     }
 
@@ -84,11 +100,38 @@ export class BinarySerializationRegistry {
 
         if (adapter !== undefined) {
             this.serializers.delete(className);
+
+            const klass = adapter.klass;
+
+            if (klass !== null && klass !== undefined && this.#klass_to_name.get(klass) === className) {
+                // this name owned the reverse mapping; hand it to another surviving name for the same class if
+                // one exists, so getClassName stays consistent when a class is registered under several names
+                this.#klass_to_name.delete(klass);
+
+                for (const [otherName, otherAdapter] of this.serializers) {
+                    if (otherAdapter.klass === klass) {
+                        this.#klass_to_name.set(klass, otherName);
+                        break;
+                    }
+                }
+            }
         }
 
         return adapter;
     }
 
+    /**
+     * Reverse of {@link registerAdapter}: resolve the registered class name for a given class (constructor).
+     * Useful when serializing a value whose class name is not known up-front — obtain the constructor via
+     * `Object.getPrototypeOf(value).constructor` and look it up here. Does not read or mutate any instance.
+     *
+     * @param {Function} klass class/constructor to look up
+     * @returns {string|undefined} the class name under which an adapter is registered, or `undefined` if none
+     */
+    getClassName(klass) {
+        return this.#klass_to_name.get(klass);
+    }
+
     /**
      *
      * @param {string} className

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

@@ -0,0 +1,93 @@
+/**
+ * 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 {
+    /**
+     * @param {BinarySerializationRegistry} registry
+     * @param {ModuleRegistry} [modules] required only if the data contains reflective (adapter-less) class instances
+     */
+    constructor(registry: BinarySerializationRegistry, modules?: ModuleRegistry);
+    /**
+     * @param {BinarySerializationRegistry} registry
+     */
+    setRegistry(registry: BinarySerializationRegistry): void;
+    /**
+     * @param {ModuleRegistry} [modules]
+     */
+    setModuleRegistry(modules?: ModuleRegistry): void;
+    /**
+     * 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<T>(buffer: BinaryBuffer): T;
+    /**
+     * Read a single value. Nesting adapters call this to deserialize a child of any type.
+     *
+     * @template T
+     * @param {BinaryBuffer} buffer
+     * @returns {T}
+     */
+    readValue<T_1>(buffer: BinaryBuffer): T_1;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isBinaryObjectDeSerializer: boolean;
+    #private;
+}
+/**
+ * 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.
+ */
+export type ResolvedClass = {
+    typeName: string;
+    /**
+     * version the data was written with
+     */
+    version: number;
+    /**
+     * registered adapter, or undefined
+     */
+    adapter: BinaryClassSerializationAdapter | undefined;
+    /**
+     * constructor to instantiate, or undefined if unresolvable
+     */
+    Klass: Function | undefined;
+    /**
+     * cached migrator chain (null = none needed)
+     */
+    migrators: BinaryClassUpgrader[] | null;
+    /**
+     * whether the migrator chain has been computed yet
+     */
+    migratorsResolved: boolean;
+};
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+//# sourceMappingURL=BinaryObjectDeSerializer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BinaryObjectDeSerializer.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/ecs/storage/binary/object-v2/BinaryObjectDeSerializer.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;GAYG;AACH;IA4BI;;;OAGG;IACH,6EAGC;IAED;;OAEG;IACH,yDAKC;IAED;;OAEG;IACH,kDAEC;IAED;;;;;;OAMG;IACH,uBAHW,YAAY,KAwCtB;IA0BD;;;;;;OAMG;IACH,uBAHW,YAAY,OAgDtB;IAoFL;;;OAGG;IACH,qCAFU,OAAO,CAE4C;;CAN5D;;;;;;;cAvRa,MAAM;;;;aACN,MAAM;;;;aACN,kCAAgC,SAAS;;;;WACzC,WAAS,SAAS;;;;eAClB,qBAAqB,GAAC,IAAI;;;;uBAC1B,OAAO;;6BAjCQ,4CAA4C"}

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"}