@colyseus/schema 5.0.8 → 5.0.10

package/build/encoder/ChangeTree.d.ts

@@ -189,7 +189,16 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
      * collection/field, which `Root.remove` does before this runs.
      */
     recycle(): void;
-    shift(shiftIndex: number): void;
+    /**
+     * 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: number): void;
     setRoot(root: Root): void;
     setParent(parent: Ref, root?: Root, parentIndex?: number): void;
     forEachChild(cb: (change: ChangeTree, at: any) => void): void;
@@ -214,7 +223,6 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     private _routeAndRecord;
     change(index: number, operation?: OPERATION): void;
     indexedOperation(index: number, operation: OPERATION): void;
-    shiftChangeIndexes(shiftIndex: number): void;
     getChange(index: number): OPERATION;
     pause(): void;
     resume(): void;

package/build/index.cjs

@@ -2950,14 +2950,31 @@ class ChangeTree {
         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); }
@@ -3026,12 +3043,6 @@ class ChangeTree {
     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);
     }
@@ -3372,7 +3383,8 @@ const encodeArray = function (encoder, bytes, changeTree, field, operation, it,
     // 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];
@@ -3388,6 +3400,20 @@ const encodeArray = function (encoder, bytes, changeTree, field, operation, it,
             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;
     }
@@ -3779,7 +3805,10 @@ const decodeKeyValueOperation = function (decoder, bytes, it, ref, allChanges) {
                 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
@@ -3846,9 +3875,13 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
         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.
@@ -3856,10 +3889,13 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
         // 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,
@@ -3900,9 +3936,12 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
         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) {
@@ -3959,30 +3998,35 @@ const ARRAY_PROXY_HANDLER = {
                 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
@@ -3990,10 +4034,12 @@ const ARRAY_PROXY_HANDLER = {
                     }
                 }
                 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;
         }
@@ -4176,40 +4222,68 @@ class ArraySchema {
             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);
@@ -4296,10 +4370,16 @@ class ArraySchema {
             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();
     }
     /**
@@ -4397,13 +4477,18 @@ class ArraySchema {
     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);
     }
@@ -5022,6 +5107,37 @@ class MapSchema {
     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;
@@ -6747,6 +6863,24 @@ function deprecated(throws = true) {
         });
     };
 }
+let defineTypesWarned = false;
+/**
+ * Adds synchronizable fields to an existing `Schema` subclass — the pre-5.0
+ * helper for plain JavaScript users.
+ *
+ * @deprecated Use `schema()` with `t.*` field builders instead:
+ * https://docs.colyseus.io/state/schema
+ */
+function defineTypes(target, fields, options) {
+    if (!defineTypesWarned) {
+        defineTypesWarned = true;
+        console.warn("@colyseus/schema: defineTypes() is deprecated and will be removed in a future release. Use schema() with t.* field builders instead → https://docs.colyseus.io/state/schema");
+    }
+    for (let field in fields) {
+        type(fields[field], options)(target.prototype, field);
+    }
+    return target;
+}
 /**
  * Build a per-construction factory for a builder type's auto-instantiated
  * default (empty collection or zero-arg Schema ref), or `undefined` when the
@@ -10609,6 +10743,7 @@ exports.decode = decode;
 exports.decodeKeyValueOperation = decodeKeyValueOperation;
 exports.decodeSchemaOperation = decodeSchemaOperation;
 exports.defineCustomTypes = defineCustomTypes;
+exports.defineTypes = defineTypes;
 exports.deprecated = deprecated;
 exports.dumpChanges = dumpChanges;
 exports.encode = encode;