@colyseus/schema 5.0.9 → 5.0.11

package/build/index.js

@@ -2598,7 +2598,6 @@
         // per-view WeakSet lookups with direct bitwise ops.
         // Lazy: undefined until the tree participates in any view.
         visibleViews;
-        invisibleViews;
         // Per-(view, tag) bitmap, indexed by tag. Custom tags only —
         // DEFAULT_VIEW_TAG visibility lives in `visibleViews`.
         tagViews;
@@ -2950,18 +2949,34 @@
             // per-view visibility lives on the tree (NOT keyed by refId), so a
             // recycled tree must not inherit its previous life's view membership.
             this.visibleViews = undefined;
-            this.invisibleViews = undefined;
             this.tagViews = undefined;
             this.subscribedViews = undefined;
         }
-        shift(shiftIndex) {
+        /**
+         * ArraySchema#unshift(): re-key pending ops on both channels by
+         * `+count`, then record ADDs for the new items at indexes 0..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.
+         */
+        unshift(count) {
             if (this._isSchema)
-                throw new Error("ChangeTree (Schema): shift is not supported");
+                throw new Error("ChangeTree (Schema): unshift is not supported");
             const src = this.collDirty;
             const dst = new Map();
+            const track = !this.paused && !this.isStatic;
+            if (track) {
+                for (let i = 0; i < count; i++)
+                    dst.set(i, exports.OPERATION.ADD);
+            }
             for (const [idx, val] of src)
-                dst.set(idx + shiftIndex, val);
+                dst.set(idx + count, val);
             this.collDirty = dst;
+            this.unreliableRecorder?.shift(count);
+            if (track)
+                this.root?.enqueueChangeTree(this);
         }
         // Tree attachment + child iteration — see ./changeTree/treeAttachment.ts.
         setRoot(root) { setRoot(this, root); }
@@ -3030,12 +3045,6 @@
         indexedOperation(index, operation) {
             this._routeAndRecord(index, operation, true);
         }
-        // ArraySchema#unshift(): apply shift to both channels.
-        // Unreliable recorder on an array is always a CollectionChangeRecorder.
-        shiftChangeIndexes(shiftIndex) {
-            this.shift(shiftIndex);
-            this.unreliableRecorder?.shift(shiftIndex);
-        }
         getChange(index) {
             return this.operationAt(index);
         }
@@ -3376,7 +3385,8 @@
         // ArraySchema stores its per-instance child type at `$childType`.
         // This encoder is array-only — there's no Schema fallback to consider.
         const type = ref[$childType];
-        const useOperationByRefId = hasView && changeTree.isFiltered && typeof type !== "string";
+        const isSchemaChild = typeof type !== "string";
+        const useOperationByRefId = hasView && changeTree.isFiltered && isSchemaChild;
         let refOrIndex;
         if (useOperationByRefId) {
             const item = ref.tmpItems[field];
@@ -3392,6 +3402,20 @@
                 operation = exports.OPERATION.ADD_BY_REFID;
             }
         }
+        else if (operation === exports.OPERATION.DELETE && isSchemaChild) {
+            //
+            // DELETE by identity: idempotent, so a stale positional DELETE
+            // (pending in the shared queue when a client bootstraps via
+            // encodeAll) can't corrupt that client — its snapshot no longer
+            // holds the item, the refId is unknown, and the decoder skips.
+            //
+            const item = ref.tmpItems[field];
+            if (!item) {
+                return;
+            }
+            refOrIndex = item[$refId];
+            operation = exports.OPERATION.DELETE_BY_REFID;
+        }
         else {
             refOrIndex = field;
         }
@@ -3783,7 +3807,10 @@
                     tgt.$items.set(dynamicIndex, value);
                     break;
                 case CollectionKind.Array:
-                    tgt.$setAt(index, value, operation);
+                    // resync snapshot ADDs are positional overwrites, not inserts
+                    tgt.$setAt(index, value, (decoder.resyncVisited !== null && operation === exports.OPERATION.ADD)
+                        ? exports.OPERATION.REPLACE
+                        : operation);
                     break;
                 // SetSchema / CollectionSchema / StreamSchema — use the wire-
                 // index we decoded above so server/client `$items` stay in sync
@@ -3850,9 +3877,13 @@
             return;
         }
         else if (operation === exports.OPERATION.DELETE_BY_REFID) {
-            // TODO: refactor here, try to follow same flow as below
             const refId = decode.number(bytes, it);
             const previousValue = decoder.root.refs.get(refId);
+            // Stale DELETE — refId unknown to this decoder (e.g. it
+            // bootstrapped via encodeAll after the item was already removed).
+            if (previousValue === undefined) {
+                return;
+            }
             // Decrement the removed child's ref-count so it can be garbage
             // collected — this refId-based branch returns early and never reaches
             // decodeValue(), so it must do the same DELETE bookkeeping itself.
@@ -3860,10 +3891,13 @@
             // different type → "field not defined" / "definition mismatch"
             // (surfaces under StateView when a filtered ArraySchema element is
             // spliced while its parent moves through view membership churn).
-            if (previousValue !== undefined) {
-                decoder.root.removeRef(refId);
-            }
+            // Must run even when the item is absent from THIS array (view churn).
+            decoder.root.removeRef(refId);
             index = tgt.findIndex((value) => value === previousValue);
+            // Item not present in this decoder's array — nothing to remove locally.
+            if (index === -1) {
+                return;
+            }
             tgt[$deleteByIndex](index);
             allChanges?.push({
                 ref,
@@ -3904,9 +3938,12 @@
             resyncTouchEntry(decoder, ref, operation, index, previousValue, value, allChanges);
         }
         if (value !== null && value !== undefined &&
-            value !== previousValue // avoid setting same value twice (if index === 0 it will result in a "unshift" for ArraySchema)
+            value !== previousValue // avoid setting same value twice (an ADD at an occupied index would splice-insert)
         ) {
-            tgt.$setAt(index, value, operation);
+            // resync snapshot ADDs are positional overwrites, not inserts
+            tgt.$setAt(index, value, (decoder.resyncVisited !== null && operation === exports.OPERATION.ADD)
+                ? exports.OPERATION.REPLACE
+                : operation);
         }
         // add change
         if (previousValue !== value) {
@@ -3963,30 +4000,35 @@
                     obj.$deleteAt(key);
                 }
                 else {
+                    // wire slot the write was recorded at; undefined = nothing
+                    // recorded (same value / skipped) — must NOT touch tmpItems
+                    // then, or a same-tick shifted layout gets clobbered.
+                    let wireIndex;
                     if (setValue[$changes]) {
                         assertInstanceType(setValue, obj[$childType], obj, key);
                         const previousValue = obj.items[key];
                         if (!obj.isMovingItems) {
-                            obj.$changeAt(Number(key), setValue);
+                            wireIndex = obj.$changeAt(Number(key), setValue);
                         }
                         else {
+                            wireIndex = obj.$wireIndex(Number(key));
                             if (previousValue !== undefined) {
                                 if (setValue[$changes].isNew) {
-                                    obj[$changes].indexedOperation(Number(key), exports.OPERATION.MOVE_AND_ADD);
+                                    obj[$changes].indexedOperation(wireIndex, exports.OPERATION.MOVE_AND_ADD);
                                 }
                                 else {
-                                    if ((obj[$changes].getChange(Number(key)) & exports.OPERATION.DELETE) === exports.OPERATION.DELETE) {
-                                        obj[$changes].indexedOperation(Number(key), exports.OPERATION.DELETE_AND_MOVE);
+                                    if ((obj[$changes].getChange(wireIndex) & exports.OPERATION.DELETE) === exports.OPERATION.DELETE) {
+                                        obj[$changes].indexedOperation(wireIndex, exports.OPERATION.DELETE_AND_MOVE);
                                     }
                                     else {
-                                        obj[$changes].indexedOperation(Number(key), exports.OPERATION.MOVE);
+                                        obj[$changes].indexedOperation(wireIndex, exports.OPERATION.MOVE);
                                     }
                                 }
                             }
                             else if (setValue[$changes].isNew) {
-                                obj[$changes].indexedOperation(Number(key), exports.OPERATION.ADD);
+                                obj[$changes].indexedOperation(wireIndex, exports.OPERATION.ADD);
                             }
-                            setValue[$changes].setParent(obj, obj[$changes].root, key);
+                            setValue[$changes].setParent(obj, obj[$changes].root, wireIndex);
                         }
                         if (previousValue !== undefined) {
                             // remove root reference from previous value
@@ -3994,10 +4036,12 @@
                         }
                     }
                     else {
-                        obj.$changeAt(Number(key), setValue);
+                        wireIndex = obj.$changeAt(Number(key), setValue);
                     }
                     obj.items[key] = setValue;
-                    obj.tmpItems[key] = setValue;
+                    if (wireIndex !== undefined) {
+                        obj.tmpItems[wireIndex] = setValue;
+                    }
                 }
                 return true;
             }
@@ -4180,40 +4224,68 @@
                 index += this.length;
             return this.items[index];
         }
-        // encoding only
+        /**
+         * items-index → wire (tmpItems) index. Identity while no deletions are
+         * staged this tick; otherwise maps to the index-th live (non-deleted)
+         * tmpItems slot — the same live-index walk `splice()` uses. Without the
+         * translation, index writes recorded after a same-tick `shift()`/`splice()`
+         * land on the wrong wire slots.
+         */
+        $wireIndex(index) {
+            const deletedIndexes = this.deletedIndexes;
+            if (deletedIndexes.length === 0) {
+                return index;
+            }
+            const tmpItems = this.tmpItems;
+            let live = 0;
+            for (let i = 0; i < tmpItems.length; i++) {
+                if (deletedIndexes[i] !== true) {
+                    if (live === index) {
+                        return i;
+                    }
+                    live++;
+                }
+            }
+            // beyond the live range: appends land after the staged tmpItems tail
+            return tmpItems.length + (index - live);
+        }
+        // encoding only. Returns the wire index the change was recorded at
+        // (undefined when nothing was recorded).
         $changeAt(index, value) {
             if (value === undefined || value === null) {
-                console.error("ArraySchema items cannot be null nor undefined; Use `deleteAt(index)` instead.");
-                return;
+                console.error("ArraySchema items cannot be null nor undefined; Use `splice(index, 1)` instead.");
+                return undefined;
             }
             // skip if the value is the same as cached.
             if (this.items[index] === value) {
-                return;
+                return undefined;
             }
             const operation = (this.items[index] !== undefined)
                 ? typeof (value) === "object"
                     ? exports.OPERATION.DELETE_AND_ADD // schema child
                     : exports.OPERATION.REPLACE // primitive
                 : exports.OPERATION.ADD;
+            const wireIndex = this.$wireIndex(index);
             const changeTree = this[$changes];
-            changeTree.change(index, operation);
+            changeTree.change(wireIndex, operation);
             //
             // set value's parent after the value is set
             // (to avoid encoding "refId" operations before parent's "ADD" operation)
             //
-            value[$changes]?.setParent(this, changeTree.root, index);
+            value[$changes]?.setParent(this, changeTree.root, wireIndex);
+            return wireIndex;
         }
         // encoding only
         $deleteAt(index, operation) {
-            this[$changes].delete(index, operation);
+            this[$changes].delete(this.$wireIndex(index), operation);
         }
         // decoding only
         $setAt(index, value, operation) {
-            if (index === 0 &&
-                operation === exports.OPERATION.ADD &&
+            if (operation === exports.OPERATION.ADD &&
                 this.items[index] !== undefined) {
-                // handle decoding unshift
-                this.items.unshift(value);
+                // ADD at an occupied index = insert (unshift / splice-insert):
+                // shift existing items up instead of overwriting.
+                this.items.splice(index, 0, value);
             }
             else if (operation === exports.OPERATION.DELETE_AND_MOVE) {
                 this.items.splice(index, 1);
@@ -4300,10 +4372,16 @@
                 return undefined;
             }
             const changeTree = self[$changes];
-            const first = items[0];
-            const index = self.tmpItems.findIndex(item => item === first);
+            // items[0] ≡ first live (non-deleted) tmpItems slot. Value-based
+            // findIndex is unsafe here: same-tick index writes can duplicate a
+            // value across tmp slots and resolve the wrong one.
+            const deletedIndexes = self.deletedIndexes;
+            let index = 0;
+            while (deletedIndexes[index] === true) {
+                index++;
+            }
             changeTree.delete(index, exports.OPERATION.DELETE);
-            self.deletedIndexes[index] = true;
+            deletedIndexes[index] = true;
             return items.shift();
         }
         /**
@@ -4401,13 +4479,18 @@
         unshift(...items) {
             const self = this[$proxyTarget];
             const changeTree = self[$changes];
-            // Existing items shift up — `shiftChangeIndexes` handles their
-            // relocation bookkeeping. The prepended `items` are genuinely new
-            // (no prior existence to MOVE), so each records an ADD.
-            changeTree.shiftChangeIndexes(items.length);
-            items.forEach((_, index) => {
-                changeTree.change(index, exports.OPERATION.ADD);
-            });
+            // single recorder op: shifts pending indexes up and records the new
+            // ADDs lowest-first (the decoder splice-inserts in ascending order).
+            changeTree.unshift(items.length);
+            // attach ref-type items — parent set AFTER recording, as in $changeAt
+            for (let i = 0; i < items.length; i++) {
+                items[i]?.[$changes]?.setParent(this, changeTree.root, i);
+            }
+            // keep staged-delete flags aligned with the prepended tmp slots
+            const deletedIndexes = self.deletedIndexes;
+            if (deletedIndexes.length > 0) {
+                deletedIndexes.unshift(...new Array(items.length).fill(false));
+            }
             self.tmpItems.unshift(...items);
             return self.items.unshift(...items);
         }
@@ -5026,6 +5109,37 @@
         get(key) {
             return this.$items.get(key);
         }
+        /**
+         * Returns the value for `key` if present. Otherwise inserts `defaultValue`
+         * (tracked as an ADD change, like `set()`) and returns it.
+         *
+         * Mirrors `Map.prototype.getOrInsert` (TC39 "upsert" proposal, typed in
+         * TypeScript 6's standard library).
+         */
+        getOrInsert(key, defaultValue) {
+            if (this.$items.has(key)) {
+                return this.$items.get(key);
+            }
+            this.set(key, defaultValue);
+            return defaultValue;
+        }
+        /**
+         * Returns the value for `key` if present. Otherwise computes a value via
+         * `callbackfn(key)`, inserts it (tracked as an ADD change, like `set()`)
+         * and returns it. The callback is only invoked when the key is missing.
+         *
+         * Mirrors `Map.prototype.getOrInsertComputed` (TC39 "upsert" proposal,
+         * typed in TypeScript 6's standard library).
+         */
+        getOrInsertComputed(key, callbackfn) {
+            if (this.$items.has(key)) {
+                return this.$items.get(key);
+            }
+            const value = callbackfn(key);
+            // per spec: overwrites even if callbackfn itself inserted `key`
+            this.set(key, value);
+            return value;
+        }
         delete(key) {
             if (!this.$items.has(key)) {
                 return false;
@@ -7894,17 +8008,7 @@
         // Visibility gate: when a view is active, a non-visible tree contributes
         // nothing itself but we still recurse so descendants (possibly added to
         // the view explicitly) are reachable.
-        let visibleHere = true;
-        if (ctx.hasView) {
-            const view = ctx.view;
-            if (!view.isChangeTreeVisible(changeTree)) {
-                view.markInvisible(changeTree);
-                visibleHere = false;
-            }
-            else {
-                view.unmarkInvisible(changeTree);
-            }
-        }
+        const visibleHere = !ctx.hasView || ctx.view.isChangeTreeVisible(changeTree);
         if (visibleHere) {
             const desc = changeTree.encDescriptor;
             ctx.changeTree = changeTree;
@@ -8053,12 +8157,8 @@
             let current = queue;
             while (current = current.next) {
                 const changeTree = current.changeTree;
-                if (hasView) {
-                    if (!view.isChangeTreeVisible(changeTree)) {
-                        view.markInvisible(changeTree);
-                        continue;
-                    }
-                    view.unmarkInvisible(changeTree);
+                if (hasView && !view.isChangeTreeVisible(changeTree)) {
+                    continue;
                 }
                 const recorder = unreliable ? changeTree.unreliableRecorder : changeTree;
                 if (!recorder || !recorder.has()) {
@@ -9750,9 +9850,6 @@
             const v = tree.visibleViews;
             if (v !== undefined && slot < v.length)
                 v[slot] &= clearMask;
-            const i = tree.invisibleViews;
-            if (i !== undefined && slot < i.length)
-                i[slot] &= clearMask;
             const s = tree.subscribedViews;
             if (s !== undefined && slot < s.length)
                 s[slot] &= clearMask;
@@ -9904,32 +10001,6 @@
             if (slot < arr.length)
                 arr[slot] &= ~this._bit;
         }
-        /** True iff this view has previously marked `tree` as invisible. */
-        isInvisible(tree) {
-            const arr = tree.invisibleViews;
-            const slot = this._slot;
-            return arr !== undefined && slot < arr.length && (arr[slot] & this._bit) !== 0;
-        }
-        /** Mark `tree` as invisible to this view (used by encode loop). */
-        markInvisible(tree) {
-            const slot = this._slot;
-            let arr = tree.invisibleViews;
-            if (arr === undefined) {
-                arr = tree.invisibleViews = [];
-            }
-            while (arr.length <= slot)
-                arr.push(0);
-            arr[slot] |= this._bit;
-        }
-        /** Clear invisible bit. */
-        unmarkInvisible(tree) {
-            const arr = tree.invisibleViews;
-            if (arr === undefined)
-                return;
-            const slot = this._slot;
-            if (slot < arr.length)
-                arr[slot] &= ~this._bit;
-        }
         // ──────────────────────────────────────────────────────────────────
         // Per-tag, per-view bitmap. Replaces the legacy
         // `tags: WeakMap<ChangeTree, Set<number>>` storage. Hot read site is
@@ -10073,11 +10144,18 @@
             // below use `metadata?.[...]` null-safe access. Only Schema
             // subclasses yield a real Metadata object.
             const metadata = obj.constructor[Symbol.metadata];
-            this.markVisible(changeTree);
-            // add to iterable list (only the explicitly added items)
-            if (this.iterable && checkIncludeParent) {
+            // Add to iterable list (only the explicitly added items), deduping
+            // re-adds of an already-visible instance. isVisible must be read
+            // BEFORE markVisible; indexOf runs only on the re-add path.
+            // NOTE: dedup applies to `items` only — a re-add still re-queues the
+            // full snapshot on purpose (shared-view bootstrap re-add: a
+            // late-attached client may not have consumed earlier drains).
+            // Callers wanting cheap idempotence can guard with `view.has(obj)`.
+            if (this.iterable && checkIncludeParent
+                && (!this.isVisible(changeTree) || this.items.indexOf(obj) === -1)) {
                 this.items.push(obj);
             }
+            this.markVisible(changeTree);
             // add parent ChangeTree's
             // - if it was invisible to this view
             // - if it were previously filtered out
@@ -10160,18 +10238,20 @@
             }
             else if (!changeTree.isNew || isChildAdded) {
                 // new structures will be added as part of .encode() call, no need to force it to .encodeView()
-                const isInvisible = this.isInvisible(changeTree);
                 // Full-sync snapshot: walk the live ref structurally instead of
                 // iterating a cumulative recorder bucket. Every populated index
                 // is emitted as ADD (matching the op-coercion previously done
                 // at encode time). Per-field tags come from the descriptor's
                 // precomputed `tags[]` array — direct index vs a metadata[i].tag
                 // object hop.
+                //
+                // Non-matching custom-tagged fields are NEVER included here —
+                // `view.changes` is drained without a per-field tag re-check,
+                // so anything added leaks straight to the wire.
                 const tags = changeTree.encDescriptor.tags;
                 changeTree.forEachLive((index) => {
                     const tagAtIndex = tags[index];
-                    if (isInvisible || // if "invisible", include all
-                        tagAtIndex === undefined || // "all change" with no tag
+                    if (tagAtIndex === undefined || // "all change" with no tag
                         tagAtIndex === DEFAULT_VIEW_TAG || // visible to all clients
                         (tag !== DEFAULT_VIEW_TAG && (tagAtIndex & tag) !== 0) // tag bits overlap
                     ) {
@@ -10323,7 +10403,7 @@
             }
             // ── Streamable-collection unsubscribe (the stream itself) ─────
             // Flush DELETE for every sent position and drop pending. After
-            // this, the stream is marked invisible to this view — any future
+            // this, the stream is no longer visible to this view — any future
             // `stream.add()` would still seed broadcast pending (if no views)
             // but would NOT re-seed per-view pending (user must re-subscribe).
             if (changeTree.isStreamCollection) {