@colyseus/schema 4.0.21 → 4.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "4.0.21",
+  "version": "4.0.22",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {

package/src/encoder/Encoder.ts

@@ -190,8 +190,26 @@ export class Encoder<T extends Schema = any> {
     ) {
         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: Iterable<number> = view.changesOutOfOrder
+            ? this.topoOrderViewChanges(view)
+            : view.changes.keys();
+
+        for (const refId of orderedRefIds) {
+            const changes = view.changes.get(refId);
             const changeTree: ChangeTree = this.root.changeTrees[refId];
 
             if (changeTree === undefined) {
@@ -235,6 +253,7 @@ export class Encoder<T extends Schema = any> {
         //
         // clear "view" changes after encoding
         view.changes.clear();
+        view.changesOutOfOrder = false;
 
         // try to encode "filtered" changes
         this.encode(it, view, bytes, "filteredChanges", false, viewOffset);
@@ -245,6 +264,52 @@ export class Encoder<T extends Schema = any> {
         );
     }
 
+    /**
+     * 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.
+     */
+    protected topoOrderViewChanges(view: StateView): number[] {
+        const result: number[] = [];
+        const visited = new Set<number>();
+
+        const visit = (refId: number) => {
+            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;

package/src/encoder/StateView.ts

@@ -35,12 +35,47 @@ export class StateView {
      */
     changes = new Map<number, IndexedOperations>();
 
+    /**
+     * 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: boolean = false;
+
     constructor(public iterable: boolean = false) {
         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`.
+     */
+    protected touchChanges(refId: number): IndexedOperations {
+        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: Ref, tag: number = DEFAULT_VIEW_TAG, checkIncludeParent: boolean = true) {
         const changeTree: ChangeTree = obj?.[$changes];
@@ -82,12 +117,8 @@ export class StateView {
             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;
 
@@ -182,11 +213,7 @@ export 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<ChangeTree, Set<number>>();
@@ -214,6 +241,10 @@ export class StateView {
             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
@@ -229,23 +260,13 @@ export class StateView {
 
         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);
+                const parentChanges = this.touchChanges(parent[$refId]);
 
-                } else if (changes[changeTree.parentIndex] === OPERATION.ADD) {
+                if (parentChanges[changeTree.parentIndex] === OPERATION.ADD) {
                     //
                     // SAME PATCH ADD + REMOVE:
                     // The 'changes' of deleted structure should be ignored.
@@ -254,13 +275,14 @@ export class StateView {
                 }
 
                 // 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;
 
@@ -276,6 +298,7 @@ export class StateView {
 
         } else {
             // delete only tagged properties
+            const changes = this.touchChanges(refId);
             metadata?.[$fieldIndexesByViewTag][tag].forEach((index) => {
                 changes[index] = OPERATION.DELETE;