@colyseus/schema 4.0.21 → 4.0.23

package/build/decoder/strategy/Callbacks.d.ts

@@ -41,7 +41,7 @@ export declare class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to any property change on an instance.
      */
-    onChange<TInstance extends Schema>(instance: TInstance, handler: InstanceChangeCallback): () => void;
+    onChange<TInstance extends object>(instance: TInstance, handler: InstanceChangeCallback): () => void;
     /**
      * Listen to item changes in a collection on root state.
      */
@@ -49,7 +49,7 @@ export declare class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to item changes in a nested collection.
      */
-    onChange<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>): () => void;
+    onChange<TInstance extends object, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>): () => void;
     /**
      * Listen to items added to a collection on root state.
      */
@@ -57,7 +57,7 @@ export declare class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to items added to a nested collection.
      */
-    onAdd<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>, immediate?: boolean): () => void;
+    onAdd<TInstance, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>, immediate?: boolean): () => void;
     /**
      * Listen to items removed from a collection on root state.
      */
@@ -65,12 +65,12 @@ export declare class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to items removed from a nested collection.
      */
-    onRemove<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>): () => void;
+    onRemove<TInstance, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>): () => void;
     /**
      * Bind properties from a Schema instance to a target object.
      * Changes will be automatically reflected on the target object.
      */
-    bindTo<TInstance extends Schema, TTarget>(from: TInstance, to: TTarget, properties?: string[], immediate?: boolean): () => void;
+    bindTo<TInstance, TTarget>(from: TInstance, to: TTarget, properties?: string[], immediate?: boolean): () => void;
     protected triggerChanges(allChanges: DataChange[]): void;
 }
 /**

package/build/encoder/Encoder.d.ts

@@ -16,6 +16,23 @@ export declare class Encoder<T extends Schema = any> {
     encodeAll(it?: Iterator, buffer?: Uint8Array): Uint8Array<ArrayBufferLike>;
     encodeAllView(view: StateView, sharedOffset: number, it: Iterator, bytes?: Uint8Array): Uint8Array<ArrayBufferLike>;
     encodeView(view: StateView, sharedOffset: number, it: Iterator, bytes?: Uint8Array): Uint8Array<ArrayBufferLike>;
+    /**
+     * 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[];
     discardChanges(): void;
     tryEncodeTypeId(bytes: Uint8Array, baseType: typeof Schema, targetType: typeof Schema, it: Iterator): void;
     get hasChanges(): boolean;

package/build/encoder/StateView.d.ts

@@ -21,7 +21,33 @@ export declare class StateView {
      * (This is used to force encoding a property, even if it was not changed)
      */
     changes: 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;
     constructor(iterable?: boolean);
+    /**
+     * 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;
     add(obj: Ref, tag?: number, checkIncludeParent?: boolean): boolean;
     protected addParentOf(childChangeTree: ChangeTree, tag: number): void;
     remove(obj: Ref, tag?: number): this;

package/build/index.cjs

@@ -4389,8 +4389,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.
@@ -4426,10 +4443,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;
@@ -5474,6 +5534,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);
@@ -5501,12 +5562,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];
@@ -5540,12 +5634,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.
@@ -5624,11 +5714,7 @@ class StateView {
         }
         // 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();
             }
@@ -5650,6 +5736,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 &&
@@ -5660,22 +5749,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] === 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.
@@ -5683,12 +5762,13 @@ class StateView {
                     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.
@@ -5703,6 +5783,7 @@ class StateView {
         }
         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