@colyseus/schema 4.0.21 → 4.0.23

package/build/index.js

@@ -4393,8 +4393,25 @@
         }
         encodeView(view, sharedOffset, it, bytes = this.sharedBuffer) {
             const viewOffset = it.offset;
-            // encode visibility changes (add/remove for this view)
-            for (const [refId, changes] of view.changes) {
+            //
+            // Iterate `view.changes` in topological order so a refId is never
+            // SWITCH_TO_STRUCTURE'd before an earlier op has introduced it on
+            // the decoder. Map insertion order alone isn't sufficient: a
+            // sequence like view.remove(child) → view.add(child) on a child
+            // whose ancestor wasn't yet visible can put the child entry into
+            // the Map before its newly-visible ancestor.
+            //
+            // Hot-path optimization: `view.add` preserves topo order by
+            // construction (addParentOf walks deepest-ancestor-first before
+            // touching the obj's own entry). Only `view.remove` can leave the
+            // Map dirty. `StateView.changesOutOfOrder` tracks this so most
+            // encodes can iterate `view.changes` directly, paying nothing.
+            //
+            const orderedRefIds = view.changesOutOfOrder
+                ? this.topoOrderViewChanges(view)
+                : view.changes.keys();
+            for (const refId of orderedRefIds) {
+                const changes = view.changes.get(refId);
                 const changeTree = this.root.changeTrees[refId];
                 if (changeTree === undefined) {
                     // detached instance, remove from view and skip.
@@ -4430,10 +4447,53 @@
             //
             // clear "view" changes after encoding
             view.changes.clear();
+            view.changesOutOfOrder = false;
             // try to encode "filtered" changes
             this.encode(it, view, bytes, "filteredChanges", false, viewOffset);
             return concatBytes(bytes.subarray(0, sharedOffset), bytes.subarray(viewOffset, it.offset));
         }
+        /**
+         * Produce a topological ordering of `view.changes` keys so each refId
+         * is preceded by any ancestor that's also in the same view's changeset.
+         *
+         * The wire stream uses SWITCH_TO_STRUCTURE pointers; if a child is
+         * encoded before any earlier op has introduced its refId on the
+         * decoder, decode fails with "refId not found". An entry's refId can
+         * only be introduced by an ADD on one of its ancestors — so any
+         * ancestor that itself appears in this view's pending changes must
+         * be encoded first.
+         *
+         * Implementation: DFS post-order over the parent chain. The `visited`
+         * Set guards against duplicates; cycles are not expected in a
+         * well-formed parent chain but the visited check is a cheap safety
+         * net. Cost is O(n × d) for n entries with parent-chain depth d.
+         */
+        topoOrderViewChanges(view) {
+            const result = [];
+            const visited = new Set();
+            const visit = (refId) => {
+                if (visited.has(refId)) {
+                    return;
+                }
+                visited.add(refId);
+                const changeTree = this.root.changeTrees[refId];
+                if (changeTree !== undefined) {
+                    let chain = changeTree.parentChain;
+                    while (chain) {
+                        const parentRefId = chain.ref[$refId];
+                        if (parentRefId !== undefined && view.changes.has(parentRefId)) {
+                            visit(parentRefId);
+                        }
+                        chain = chain.next;
+                    }
+                }
+                result.push(refId);
+            };
+            for (const refId of view.changes.keys()) {
+                visit(refId);
+            }
+            return result;
+        }
         discardChanges() {
             // discard shared changes
             let current = this.root.changes.next;
@@ -5478,6 +5538,7 @@
             else if ('decoder' in roomOrDecoder.serializer) {
                 return getDecoderStateCallbacks(roomOrDecoder.serializer.decoder);
             }
+            throw new Error('Invalid room or decoder');
         },
         getRawChanges(decoder, callback) {
             return getRawChangesCallback(decoder, callback);
@@ -5505,12 +5566,45 @@
          * (This is used to force encoding a property, even if it was not changed)
          */
         changes = new Map();
+        /**
+         * Set when an operation may have left `changes` out of topological
+         * order (a parent that needs to be encoded before its descendants is
+         * positioned after them in the Map). `Encoder.encodeView` consults
+         * this flag and only runs the topo-ordering pass when it's true,
+         * skipping the work in the common case where insertion order already
+         * coincides with topo order.
+         *
+         * Only `remove()` can break the invariant: it writes entries that
+         * bypass `addParentOf`'s deepest-ancestor-first ordering. Everything
+         * else (including multi-parent re-adds) preserves order by
+         * construction. Reset to false at the end of each encodeView pass
+         * (when `changes` is cleared).
+         */
+        changesOutOfOrder = false;
         constructor(iterable = false) {
             this.iterable = iterable;
             if (iterable) {
                 this.items = [];
             }
         }
+        /**
+         * Get the IndexedOperations entry for `refId`, creating one if missing.
+         *
+         * Map insertion order alone doesn't guarantee parent-before-child
+         * iteration in all cases (a `view.remove()` followed by `view.add()`
+         * can put a child entry into the Map before its newly-visible
+         * ancestor). The wire-order invariant (parent SWITCH_TO_STRUCTURE
+         * before any of its children's) is enforced at encode time by
+         * `Encoder.encodeView` via a topological pass over `view.changes`.
+         */
+        touchChanges(refId) {
+            let entry = this.changes.get(refId);
+            if (entry === undefined) {
+                entry = {};
+                this.changes.set(refId, entry);
+            }
+            return entry;
+        }
         // TODO: allow to set multiple tags at once
         add(obj, tag = DEFAULT_VIEW_TAG, checkIncludeParent = true) {
             const changeTree = obj?.[$changes];
@@ -5544,12 +5638,8 @@
             if (checkIncludeParent && parentChangeTree) {
                 this.addParentOf(changeTree, tag);
             }
-            let changes = this.changes.get(obj[$refId]);
-            if (changes === undefined) {
-                changes = {};
-                // FIXME / OPTIMIZE: do not add if no changes are needed
-                this.changes.set(obj[$refId], changes);
-            }
+            // FIXME / OPTIMIZE: do not add if no changes are needed
+            const changes = this.touchChanges(obj[$refId]);
             let isChildAdded = false;
             //
             // Add children of this ChangeTree first.
@@ -5628,11 +5718,7 @@
             }
             // add parent's tag properties
             if (changeTree.getChange(parentIndex) !== exports.OPERATION.DELETE) {
-                let changes = this.changes.get(changeTree.ref[$refId]);
-                if (changes === undefined) {
-                    changes = {};
-                    this.changes.set(changeTree.ref[$refId], changes);
-                }
+                const changes = this.touchChanges(changeTree.ref[$refId]);
                 if (!this.tags) {
                     this.tags = new WeakMap();
                 }
@@ -5654,6 +5740,9 @@
                 console.warn("StateView#remove(), invalid object:", obj);
                 return this;
             }
+            // remove() bypasses addParentOf's ordering guarantee — flag the
+            // changeset as potentially out of topological order.
+            this.changesOutOfOrder = true;
             this.visible.delete(changeTree);
             // remove from iterable list
             if (this.iterable &&
@@ -5664,22 +5753,12 @@
             const ref = changeTree.ref;
             const metadata = ref.constructor[Symbol.metadata]; // ArraySchema/MapSchema do not have metadata
             const refId = ref[$refId];
-            let changes = this.changes.get(refId);
-            if (changes === undefined) {
-                changes = {};
-                this.changes.set(refId, changes);
-            }
             if (tag === DEFAULT_VIEW_TAG) {
                 // parent is collection (Map/Array)
                 const parent = changeTree.parent;
                 if (parent && !Metadata.isValidInstance(parent) && changeTree.isFiltered) {
-                    const parentRefId = parent[$refId];
-                    let changes = this.changes.get(parentRefId);
-                    if (changes === undefined) {
-                        changes = {};
-                        this.changes.set(parentRefId, changes);
-                    }
-                    else if (changes[changeTree.parentIndex] === exports.OPERATION.ADD) {
+                    const parentChanges = this.touchChanges(parent[$refId]);
+                    if (parentChanges[changeTree.parentIndex] === exports.OPERATION.ADD) {
                         //
                         // SAME PATCH ADD + REMOVE:
                         // The 'changes' of deleted structure should be ignored.
@@ -5687,12 +5766,13 @@
                         this.changes.delete(refId);
                     }
                     // DELETE / DELETE BY REF ID
-                    changes[changeTree.parentIndex] = exports.OPERATION.DELETE;
+                    parentChanges[changeTree.parentIndex] = exports.OPERATION.DELETE;
                     // Remove child schema from visible set
                     this._recursiveDeleteVisibleChangeTree(changeTree);
                 }
                 else {
                     // delete all "tagged" properties.
+                    const changes = this.touchChanges(refId);
                     metadata?.[$viewFieldIndexes]?.forEach((index) => {
                         changes[index] = exports.OPERATION.DELETE;
                         // Remove child structures of @view() fields from visible set.
@@ -5707,6 +5787,7 @@
             }
             else {
                 // delete only tagged properties
+                const changes = this.touchChanges(refId);
                 metadata?.[$fieldIndexesByViewTag][tag].forEach((index) => {
                     changes[index] = exports.OPERATION.DELETE;
                     // Remove child structures from visible set

package/build/index.mjs

@@ -4387,8 +4387,25 @@ class Encoder {
     }
     encodeView(view, sharedOffset, it, bytes = this.sharedBuffer) {
         const viewOffset = it.offset;
-        // encode visibility changes (add/remove for this view)
-        for (const [refId, changes] of view.changes) {
+        //
+        // Iterate `view.changes` in topological order so a refId is never
+        // SWITCH_TO_STRUCTURE'd before an earlier op has introduced it on
+        // the decoder. Map insertion order alone isn't sufficient: a
+        // sequence like view.remove(child) → view.add(child) on a child
+        // whose ancestor wasn't yet visible can put the child entry into
+        // the Map before its newly-visible ancestor.
+        //
+        // Hot-path optimization: `view.add` preserves topo order by
+        // construction (addParentOf walks deepest-ancestor-first before
+        // touching the obj's own entry). Only `view.remove` can leave the
+        // Map dirty. `StateView.changesOutOfOrder` tracks this so most
+        // encodes can iterate `view.changes` directly, paying nothing.
+        //
+        const orderedRefIds = view.changesOutOfOrder
+            ? this.topoOrderViewChanges(view)
+            : view.changes.keys();
+        for (const refId of orderedRefIds) {
+            const changes = view.changes.get(refId);
             const changeTree = this.root.changeTrees[refId];
             if (changeTree === undefined) {
                 // detached instance, remove from view and skip.
@@ -4424,10 +4441,53 @@ class Encoder {
         //
         // clear "view" changes after encoding
         view.changes.clear();
+        view.changesOutOfOrder = false;
         // try to encode "filtered" changes
         this.encode(it, view, bytes, "filteredChanges", false, viewOffset);
         return concatBytes(bytes.subarray(0, sharedOffset), bytes.subarray(viewOffset, it.offset));
     }
+    /**
+     * Produce a topological ordering of `view.changes` keys so each refId
+     * is preceded by any ancestor that's also in the same view's changeset.
+     *
+     * The wire stream uses SWITCH_TO_STRUCTURE pointers; if a child is
+     * encoded before any earlier op has introduced its refId on the
+     * decoder, decode fails with "refId not found". An entry's refId can
+     * only be introduced by an ADD on one of its ancestors — so any
+     * ancestor that itself appears in this view's pending changes must
+     * be encoded first.
+     *
+     * Implementation: DFS post-order over the parent chain. The `visited`
+     * Set guards against duplicates; cycles are not expected in a
+     * well-formed parent chain but the visited check is a cheap safety
+     * net. Cost is O(n × d) for n entries with parent-chain depth d.
+     */
+    topoOrderViewChanges(view) {
+        const result = [];
+        const visited = new Set();
+        const visit = (refId) => {
+            if (visited.has(refId)) {
+                return;
+            }
+            visited.add(refId);
+            const changeTree = this.root.changeTrees[refId];
+            if (changeTree !== undefined) {
+                let chain = changeTree.parentChain;
+                while (chain) {
+                    const parentRefId = chain.ref[$refId];
+                    if (parentRefId !== undefined && view.changes.has(parentRefId)) {
+                        visit(parentRefId);
+                    }
+                    chain = chain.next;
+                }
+            }
+            result.push(refId);
+        };
+        for (const refId of view.changes.keys()) {
+            visit(refId);
+        }
+        return result;
+    }
     discardChanges() {
         // discard shared changes
         let current = this.root.changes.next;
@@ -5472,6 +5532,7 @@ const Callbacks = {
         else if ('decoder' in roomOrDecoder.serializer) {
             return getDecoderStateCallbacks(roomOrDecoder.serializer.decoder);
         }
+        throw new Error('Invalid room or decoder');
     },
     getRawChanges(decoder, callback) {
         return getRawChangesCallback(decoder, callback);
@@ -5499,12 +5560,45 @@ class StateView {
      * (This is used to force encoding a property, even if it was not changed)
      */
     changes = new Map();
+    /**
+     * Set when an operation may have left `changes` out of topological
+     * order (a parent that needs to be encoded before its descendants is
+     * positioned after them in the Map). `Encoder.encodeView` consults
+     * this flag and only runs the topo-ordering pass when it's true,
+     * skipping the work in the common case where insertion order already
+     * coincides with topo order.
+     *
+     * Only `remove()` can break the invariant: it writes entries that
+     * bypass `addParentOf`'s deepest-ancestor-first ordering. Everything
+     * else (including multi-parent re-adds) preserves order by
+     * construction. Reset to false at the end of each encodeView pass
+     * (when `changes` is cleared).
+     */
+    changesOutOfOrder = false;
     constructor(iterable = false) {
         this.iterable = iterable;
         if (iterable) {
             this.items = [];
         }
     }
+    /**
+     * Get the IndexedOperations entry for `refId`, creating one if missing.
+     *
+     * Map insertion order alone doesn't guarantee parent-before-child
+     * iteration in all cases (a `view.remove()` followed by `view.add()`
+     * can put a child entry into the Map before its newly-visible
+     * ancestor). The wire-order invariant (parent SWITCH_TO_STRUCTURE
+     * before any of its children's) is enforced at encode time by
+     * `Encoder.encodeView` via a topological pass over `view.changes`.
+     */
+    touchChanges(refId) {
+        let entry = this.changes.get(refId);
+        if (entry === undefined) {
+            entry = {};
+            this.changes.set(refId, entry);
+        }
+        return entry;
+    }
     // TODO: allow to set multiple tags at once
     add(obj, tag = DEFAULT_VIEW_TAG, checkIncludeParent = true) {
         const changeTree = obj?.[$changes];
@@ -5538,12 +5632,8 @@ class StateView {
         if (checkIncludeParent && parentChangeTree) {
             this.addParentOf(changeTree, tag);
         }
-        let changes = this.changes.get(obj[$refId]);
-        if (changes === undefined) {
-            changes = {};
-            // FIXME / OPTIMIZE: do not add if no changes are needed
-            this.changes.set(obj[$refId], changes);
-        }
+        // FIXME / OPTIMIZE: do not add if no changes are needed
+        const changes = this.touchChanges(obj[$refId]);
         let isChildAdded = false;
         //
         // Add children of this ChangeTree first.
@@ -5622,11 +5712,7 @@ class StateView {
         }
         // add parent's tag properties
         if (changeTree.getChange(parentIndex) !== OPERATION.DELETE) {
-            let changes = this.changes.get(changeTree.ref[$refId]);
-            if (changes === undefined) {
-                changes = {};
-                this.changes.set(changeTree.ref[$refId], changes);
-            }
+            const changes = this.touchChanges(changeTree.ref[$refId]);
             if (!this.tags) {
                 this.tags = new WeakMap();
             }
@@ -5648,6 +5734,9 @@ class StateView {
             console.warn("StateView#remove(), invalid object:", obj);
             return this;
         }
+        // remove() bypasses addParentOf's ordering guarantee — flag the
+        // changeset as potentially out of topological order.
+        this.changesOutOfOrder = true;
         this.visible.delete(changeTree);
         // remove from iterable list
         if (this.iterable &&
@@ -5658,22 +5747,12 @@ class StateView {
         const ref = changeTree.ref;
         const metadata = ref.constructor[Symbol.metadata]; // ArraySchema/MapSchema do not have metadata
         const refId = ref[$refId];
-        let changes = this.changes.get(refId);
-        if (changes === undefined) {
-            changes = {};
-            this.changes.set(refId, changes);
-        }
         if (tag === DEFAULT_VIEW_TAG) {
             // parent is collection (Map/Array)
             const parent = changeTree.parent;
             if (parent && !Metadata.isValidInstance(parent) && changeTree.isFiltered) {
-                const parentRefId = parent[$refId];
-                let changes = this.changes.get(parentRefId);
-                if (changes === undefined) {
-                    changes = {};
-                    this.changes.set(parentRefId, changes);
-                }
-                else if (changes[changeTree.parentIndex] === OPERATION.ADD) {
+                const parentChanges = this.touchChanges(parent[$refId]);
+                if (parentChanges[changeTree.parentIndex] === OPERATION.ADD) {
                     //
                     // SAME PATCH ADD + REMOVE:
                     // The 'changes' of deleted structure should be ignored.
@@ -5681,12 +5760,13 @@ class StateView {
                     this.changes.delete(refId);
                 }
                 // DELETE / DELETE BY REF ID
-                changes[changeTree.parentIndex] = OPERATION.DELETE;
+                parentChanges[changeTree.parentIndex] = OPERATION.DELETE;
                 // Remove child schema from visible set
                 this._recursiveDeleteVisibleChangeTree(changeTree);
             }
             else {
                 // delete all "tagged" properties.
+                const changes = this.touchChanges(refId);
                 metadata?.[$viewFieldIndexes]?.forEach((index) => {
                     changes[index] = OPERATION.DELETE;
                     // Remove child structures of @view() fields from visible set.
@@ -5701,6 +5781,7 @@ class StateView {
         }
         else {
             // delete only tagged properties
+            const changes = this.touchChanges(refId);
             metadata?.[$fieldIndexesByViewTag][tag].forEach((index) => {
                 changes[index] = OPERATION.DELETE;
                 // Remove child structures from visible set