@colyseus/schema 5.0.14 → 5.0.20

package/src/encoder/ChangeTree.ts

@@ -17,7 +17,7 @@
  */
 import { OPERATION } from "../encoding/spec.js";
 import { Schema } from "../Schema.js";
-import { $changes, $childType, $decoder, $onEncodeEnd, $encoder, $getByIndex, $proxyTarget, $refId, $refTypeFieldIndexes, $numFields, type $deleteByIndex } from "../types/symbols.js";
+import { $changes, $childType, $decoder, $onEncodeEnd, $encoder, $getByIndex, $refId, $refTypeFieldIndexes, $numFields, type $deleteByIndex } from "../types/symbols.js";
 
 import type { MapSchema } from "../types/custom/MapSchema.js";
 import type { ArraySchema } from "../types/custom/ArraySchema.js";
@@ -27,7 +27,7 @@ import type { StreamSchema } from "../types/custom/StreamSchema.js";
 
 import { Root } from "./Root.js";
 import { Metadata } from "../Metadata.js";
-import { type ChangeRecorder, type ICollectionChangeRecorder, SchemaChangeRecorder, CollectionChangeRecorder, popcount32 } from "./ChangeRecorder.js";
+import { type ChangeRecorder, SchemaChangeRecorder, CollectionChangeRecorder, popcount32 } from "./ChangeRecorder.js";
 import type { EncodeOperation } from "./EncodeOperation.js";
 import { type EncodeDescriptor, getEncodeDescriptor } from "./EncodeDescriptor.js";
 import type { DecodeOperation } from "../decoder/DecodeOperation.js";
@@ -37,6 +37,7 @@ import {
     setParentIndex as _setParentIndex,
     findParent as _findParent, hasParent as _hasParent,
     getAllParents as _getAllParents,
+    indexInParent as _indexInParent,
 } from "./changeTree/parentChain.js";
 import { forEachLive as _forEachLive, forEachLiveWithCtx as _forEachLiveWithCtx } from "./changeTree/liveIteration.js";
 import {
@@ -113,12 +114,27 @@ export function createChangeTreeList(): ChangeTreeList {
     return { next: undefined, tail: undefined, nextPosition: 0 };
 }
 
+/**
+ * Live node in a tree's parent chain — mutating one edits the chain. Only
+ * `parentChain.ts` should hold these.
+ */
 export interface ParentChain {
     ref: Ref;
     index: number;
     next?: ParentChain;
 }
 
+/**
+ * Detached copy of one parent link, handed out by the query helpers. Distinct
+ * from `ParentChain` on purpose: it carries no `next`, so it cannot be walked
+ * as if it were the chain, and it is readonly, so it cannot be mistaken for a
+ * way to move a parent's index — `setParentIndex` does that.
+ */
+export interface ParentEntry {
+    readonly ref: Ref;
+    readonly index: number;
+}
+
 // Flags bitfield. *_UNRELIABLE / _PATCH_ONLY / _STATIC mirror the parent
 // field's annotation — inherited at setParent/setRoot time.
 export const IS_FILTERED = 1, IS_VISIBILITY_SHARED = 2, IS_NEW = 4;
@@ -135,6 +151,11 @@ export const IS_STREAM_COLLECTION = 64;
 // only fields assigned after `pool.acquire()` would reach the wire — the
 // retained ones (constructor-initialized children) would never be encoded.
 export const NEEDS_RESTAGE = 128;
+// Queued in `Root.pendingFilterRefresh` — the tree's parent-edge set changed
+// (instance sharing gained/lost an edge) and `isFiltered` /
+// `isVisibilitySharedWithParent` must be re-derived from the LIVE edges
+// before the next encode. See inheritedFlags.refreshFilterState.
+export const PENDING_FILTER_REFRESH = 256;
 /**
  * Flags a child inherits from its parent's own transitive state via
  * `checkInheritedFlags`. Read as a bitwise mask so the inheritance step
@@ -169,6 +190,14 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
      */
     refTarget: T;
 
+    /**
+     * True when `ref` is an ArraySchema — the only proxied type, so its
+     * user-facing identity differs from `refTarget`. Canonical predicate for
+     * "is this tree's ref an array" without probing `ref` (which would hit
+     * the Proxy trap) — two monomorphic loads on the tree itself.
+     */
+    get isArray(): boolean { return this.refTarget !== this.ref; }
+
     metadata: Metadata;
 
     /**
@@ -279,8 +308,7 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
 
     ensureUnreliableRecorder(): ChangeRecorder {
         if (this.unreliableRecorder === undefined) {
-            const isSchema = Metadata.isValidInstance(this.ref);
-            this.unreliableRecorder = isSchema
+            this.unreliableRecorder = this._isSchema
                 ? new SchemaChangeRecorder((this.metadata?.[$numFields] ?? 0) as number)
                 : new CollectionChangeRecorder();
         }
@@ -325,12 +353,13 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
         return Metadata.hasStreamAtIndex(this.metadata, index);
     }
 
-    constructor(ref: T) {
+    constructor(ref: T, refTarget: T = ref) {
         this.ref = ref;
-        // `$proxyTarget` is a self-reference set by ArraySchema on the raw
-        // target; for non-proxied refs it's undefined and we fall back to
-        // `ref`. Cached here so hot-path reads skip the Proxy `get` trap.
-        this.refTarget = ((ref as any)[$proxyTarget] ?? ref) as T;
+        // Raw (non-Proxy) target, passed explicitly by ArraySchema's ctor —
+        // the only proxied type. Defaulting to `ref` for everything else
+        // skips a guaranteed-miss megamorphic `$proxyTarget` probe per
+        // construction. Cached so hot-path reads skip the Proxy `get` trap.
+        this.refTarget = refTarget;
 
         // Single per-class lookup that subsumes Symbol.metadata,
         // isValidInstance, $encoder, $filter, and the filter bitmask.
@@ -592,28 +621,42 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     }
 
     /**
-     * ArraySchema#unshift(): re-key pending ops on both channels by
-     * `+count`, then record ADDs for the new items at indexes 0..count-1.
+     * ArraySchema insert (unshift / splice with more inserts than deletes):
+     * re-key pending ops at or above `at` by `+count`, then record ADDs for
+     * the new items at indexes `at..at+count-1`.
      *
-     * The rebuilt map's insertion order IS the wire order: new ADDs first
-     * (ascending — the decoder splice-inserts each one, which only works
-     * lowest-index-first), then prior ops in their original relative order
-     * at their shifted positions. See ArraySchema#$setAt.
+     * The rebuilt map's insertion order IS the wire order:
+     *   1. ops below `at` — the insert doesn't move them, and an insert of
+     *      their own must still be applied before this one (ascending);
+     *   2. the new ADDs, ascending — the decoder splice-inserts each one,
+     *      which only works lowest-index-first;
+     *   3. the re-keyed ops, in their original relative order — their
+     *      indexes now address the post-insert layout.
+     * See ArraySchema#$setAt.
      */
-    unshift(count: number): void {
-        if (this._isSchema) throw new Error("ChangeTree (Schema): unshift is not supported");
+    insertAt(at: number, count: number): void {
+        if (this._isSchema) throw new Error("ChangeTree (Schema): insertAt is not supported");
         const src = this.collDirty!;
         const dst = new Map<number, OPERATION>();
         const track = !this.paused && !this.isFullStateOnly;
+        if (at > 0) {
+            for (const [idx, val] of src) if (idx < at) dst.set(idx, val);
+        }
         if (track) {
-            for (let i = 0; i < count; i++) dst.set(i, OPERATION.ADD);
+            for (let i = 0; i < count; i++) dst.set(at + i, OPERATION.ADD);
         }
-        for (const [idx, val] of src) dst.set(idx + count, val);
+        for (const [idx, val] of src) if (idx >= at) dst.set(idx + count, val);
         this.collDirty = dst;
-        (this.unreliableRecorder as ICollectionChangeRecorder | undefined)?.shift(count);
+        // no unreliable re-key — collection trees never carry an unreliable
+        // recorder (tree-level @unreliable is disabled, see isFieldUnreliable)
         if (track) this.root?.enqueueChangeTree(this);
     }
 
+    /** ArraySchema#unshift(): insert `count` items at the head. */
+    unshift(count: number): void {
+        this.insertAt(0, count);
+    }
+
     // Tree attachment + child iteration — see ./changeTree/treeAttachment.ts.
     setRoot(root: Root): void { _setRoot(this, root); }
     setParent(parent: Ref, root?: Root, parentIndex?: number): void { _setParent(this, parent, root, parentIndex); }
@@ -762,7 +805,12 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     endEncode() {
         this.reset();
         this.changesNode = undefined;
-        (this.ref as any)[$onEncodeEnd]?.();
+        // Every collection class defines [$onEncodeEnd]; Schema never does —
+        // probing it was a guaranteed megamorphic miss per drained tree.
+        // `?.` stays: a FIELDLESS Schema has no metadata, so its tree is
+        // `_isSchema === false` too. refTarget receiver skips ArraySchema's
+        // proxy hops.
+        if (!this._isSchema) (this.refTarget as any)[$onEncodeEnd]?.();
         this.isNew = false;
     }
 
@@ -770,11 +818,11 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     endEncodeUnreliable() {
         this.unreliableRecorder?.reset();
         this.unreliableChangesNode = undefined;
-        (this.ref as any)[$onEncodeEnd]?.();
+        if (!this._isSchema) (this.refTarget as any)[$onEncodeEnd]?.();
     }
 
     discard() {
-        (this.ref as any)[$onEncodeEnd]?.();
+        if (!this._isSchema) (this.refTarget as any)[$onEncodeEnd]?.();
         this.reset();
         this.unreliableRecorder?.reset();
     }
@@ -811,7 +859,7 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     /** @returns true if parent was found and removed */
     removeParent(parent: Ref = this.parent): boolean { return _removeParent(this, parent); }
 
-    findParent(predicate: (parent: Ref, index: number) => boolean): ParentChain | undefined {
+    findParent(predicate: (parent: Ref, index: number) => boolean): ParentEntry | undefined {
         return _findParent(this, predicate);
     }
 
@@ -819,7 +867,10 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
         return _hasParent(this, predicate);
     }
 
-    getAllParents(): Array<{ ref: Ref, index: number }> { return _getAllParents(this); }
+    /** Wire index this tree holds inside `parent`, or undefined if not a parent. */
+    indexInParent(parent: Ref): number | undefined { return _indexInParent(this, parent); }
+
+    getAllParents(): ParentEntry[] { return _getAllParents(this); }
 
 }
 

package/src/encoder/EncodeOperation.ts

@@ -242,8 +242,17 @@ export const encodeArray: EncodeOperation = function (
         if (operation === OPERATION.DELETE) {
             operation = OPERATION.DELETE_BY_REFID;
 
-        } else if (operation === OPERATION.ADD) {
+        } else if ((operation & OPERATION.ADD) === OPERATION.ADD) {
+            // ADD, DELETE_AND_ADD, MOVE_AND_ADD. The wire index below is a
+            // refId — positional ops would make the decoder misread it as a
+            // slot, so everything must degrade to a BY_REFID op here.
             operation = OPERATION.ADD_BY_REFID;
+
+        } else if ((operation & OPERATION.MOVE) === OPERATION.MOVE) {
+            // Pure reorder (MOVE / DELETE_AND_MOVE). Filtered clients hold
+            // per-view subsets, so element order is not synchronized for
+            // them (ADD_BY_REFID appends) — there is nothing to emit.
+            return;
         }
 
     } else if (operation === OPERATION.DELETE && isSchemaChild) {

package/src/encoder/Encoder.ts

@@ -9,11 +9,12 @@ import type { Iterator } from "../encoding/decode.js";
 import { OPERATION, SWITCH_TO_STRUCTURE, TYPE_ID } from '../encoding/spec.js';
 import { Root } from "./Root.js";
 
-import type { StateView } from "./StateView.js";
+import { ARRAY_SNAPSHOT, type StateView } from "./StateView.js";
 import type { ChangeTree, ChangeTreeList, ChangeTreeNode } from "./ChangeTree.js";
 import type { EncodeOperation } from "./EncodeOperation.js";
 import { forEachLiveWithCtx as _forEachLiveWithCtx } from "./changeTree/liveIteration.js";
 import { forEachChildWithCtx as _forEachChildWithCtx } from "./changeTree/treeAttachment.js";
+import { drainFilterRefresh } from "./changeTree/inheritedFlags.js";
 
 /**
  * Reusable context passed to the recorder's forEachWithCtx to iterate changes
@@ -296,6 +297,10 @@ export class Encoder<T extends Schema = any> {
         initialOffset: number,
         unreliable: boolean,
     ): Uint8Array {
+        // Settle any pending per-edge filter re-derivations before routing
+        // fields to channels (see inheritedFlags.drainFilterRefresh).
+        if (this.root.pendingFilterRefresh.length > 0) drainFilterRefresh(this.root);
+
         const hasView = (view !== undefined);
         const rootChangeTree = this.state[$changes];
 
@@ -379,6 +384,9 @@ export class Encoder<T extends Schema = any> {
         view?: StateView,
         initialOffset: number = it.offset
     ): Uint8Array {
+        // Full-sync splits fields by the same isFiltered classification.
+        if (this.root.pendingFilterRefresh.length > 0) drainFilterRefresh(this.root);
+
         const hasView = (view !== undefined);
         const rootChangeTree = this.state[$changes];
 
@@ -521,7 +529,49 @@ export class Encoder<T extends Schema = any> {
 
             // Iterate entries directly — the inner Map gives us the (index, op)
             // pair without an intermediate keys array or Number() parse.
-            for (const [index, op] of changes) {
+            for (const [key, op] of changes) {
+                // Element-binding entries under a collection parent are keyed
+                // by the child's ChangeTree — resolve its CURRENT wire slot
+                // here (a slot captured at view.add() time goes stale when
+                // the array reindexes later in the same tick).
+                let index: number;
+                if (key === ARRAY_SNAPSHOT) {
+                    // Whole-array snapshot: emit an ADD per live element at
+                    // its CURRENT slot. Structural walk at drain time — a
+                    // reindex after view.add() cannot go stale, and staged
+                    // holes (recorder DELETEs) are skipped by construction.
+                    const tmpItems = refTarget.tmpItems;
+                    const deletedIndexes = refTarget.deletedIndexes;
+                    for (let slot = 0; slot < tmpItems.length; slot++) {
+                        if (tmpItems[slot] === undefined || deletedIndexes[slot] === true) { continue; }
+                        encoder(this, bytes, changeTree, slot, OPERATION.ADD, it, false, true, metadata);
+                    }
+                    continue;
+                }
+                if (typeof key === "number") {
+                    index = key;
+                } else {
+                    const resolved = key.indexInParent(ref);
+                    if (resolved === undefined) { continue; } // detached and re-parented elsewhere
+                    index = resolved;
+
+                    // SAME PATCH view.add + state-removal: the element is
+                    // leaving the array (recorder DELETE at its slot), so the
+                    // binding is moot — and `$getByIndex` on a staged hole
+                    // reads a DIFFERENT element (compacted `items`), which
+                    // would ship a mismatched value payload. Cancel the
+                    // binding AND the child's own pending entry (its refId
+                    // was never introduced to this client). Topological
+                    // drain order guarantees the child entry hasn't been
+                    // visited yet. A recorder ADD at the slot needs no such
+                    // guard — both channels emit ADD_BY_REFID and the
+                    // decoder dedups by identity.
+                    if (op === OPERATION.ADD && changeTree.getChange(index) === OPERATION.DELETE) {
+                        view.changes.delete(key.ref[$refId]);
+                        continue;
+                    }
+                }
+
                 // workaround when using view.add() on item that has been deleted from state
                 // (see test "adding to view item that has been removed from state")
                 const value = refTarget[$getByIndex](index);

package/src/encoder/Root.ts

@@ -1,6 +1,7 @@
 import { OPERATION } from "../encoding/spec.js";
 import { TypeContext } from "../types/TypeContext.js";
-import { ChangeTree, ChangeTreeList, createChangeTreeList, type ChangeTreeNode } from "./ChangeTree.js";
+import { ChangeTree, ChangeTreeList, createChangeTreeList, PENDING_FILTER_REFRESH, type ChangeTreeNode } from "./ChangeTree.js";
+import { restageLiveCb } from "./changeTree/liveIteration.js";
 import { $changes, $refId } from "../types/symbols.js";
 import type { StateView } from "./StateView.js";
 import type { StreamSchema } from "../types/custom/StreamSchema.js";
@@ -53,6 +54,22 @@ export class Root {
      */
     unreliableChanges: ChangeTreeList = createChangeTreeList();
 
+    /**
+     * Trees whose parent-edge set changed this tick (instance sharing
+     * gained or lost an edge). The encoder drains this before emission —
+     * `inheritedFlags.drainFilterRefresh` re-derives each tree's filter
+     * state against the then-settled containers. Only populated when the
+     * TypeContext has any @view/@stream field.
+     */
+    public pendingFilterRefresh: ChangeTree[] = [];
+
+    public enqueueFilterRefresh(tree: ChangeTree): void {
+        if (!this.types.hasFilters) return;
+        if (tree.flags & PENDING_FILTER_REFRESH) return;
+        tree.flags |= PENDING_FILTER_REFRESH;
+        this.pendingFilterRefresh.push(tree);
+    }
+
     /**
      * Free-list of ChangeTreeNode objects. Both queues share this pool —
      * a node carries no queue affinity, only `{ changeTree, prev, next, position }`.
@@ -172,17 +189,16 @@ export class Root {
             //   values would otherwise never be encoded).
             //
             changeTree.needsRestage = false;
-            changeTree.forEachLive((fieldIndex) => {
-                if (changeTree.isFieldUnreliable(fieldIndex)) {
-                    changeTree.ensureUnreliableRecorder().record(fieldIndex, OPERATION.ADD);
-                } else {
-                    changeTree.record(fieldIndex, OPERATION.ADD);
-                }
-            });
+            changeTree.forEachLiveWithCtx(changeTree, restageLiveCb);
         }
 
         this.refCount[refId] = (previousRefCount || 0) + 1;
 
+        // Gained a 2nd+ parent edge (instance sharing / re-assignment) —
+        // re-derive filter state before the next encode. Chokepoint for
+        // every attach path; mirrors the edge-loss enqueue in `remove()`.
+        if (previousRefCount > 0) this.enqueueFilterRefresh(changeTree);
+
         return isNewChangeTree;
     }
 
@@ -229,6 +245,10 @@ export class Root {
         } else {
             this.refCount[refId] = refCount;
 
+            // Lost one of several parent edges — the surviving edge set may
+            // no longer include a public path (or may have gained one).
+            this.enqueueFilterRefresh(changeTree);
+
             //
             // When losing a reference to an instance, it is best to move the
             // ChangeTree next to its parent in the encoding queue.