@colyseus/schema 4.0.29 → 4.0.31

package/build/types/custom/ArraySchema.d.ts

@@ -32,6 +32,22 @@ export declare class ArraySchema<V = any> implements Array<V>, Collection<number
     constructor(...items: V[]);
     set length(newLength: number);
     get length(): number;
+    /**
+     * Re-point children at their wire slot. `ChangeTree.parentIndex` caches
+     * the slot a child holds in `tmpItems`, and StateView addresses per-view
+     * ADD/DELETE with it — so a reorder that leaves it behind aims those ops
+     * at whichever element inherited the slot (issue #231).
+     *
+     * The filter check is a correctness boundary, not a tunable: StateView is
+     * the only reader, and an array without `filteredChanges` never has a slot
+     * read back. Everything else stops at that check instead of walking its
+     * children every tick.
+     *
+     * Callers name the lowest slot that moved as `from`. Compaction cannot, so
+     * it hands over the pre-compaction layout as `staged` and the unchanged
+     * prefix is skipped instead. Either way tail churn walks nothing.
+     */
+    protected $reindexChildren(from: number, staged?: V[]): void;
     push(...values: V[]): number;
     /**
      * Removes the last element from an array and returns it.

package/build/types/custom/MapSchema.d.ts

@@ -33,6 +33,23 @@ export declare class MapSchema<V = any, K extends string = string> implements Ma
     static get [Symbol.species](): typeof MapSchema;
     set(key: K, value: V): this;
     get(key: K): V | undefined;
+    /**
+     * 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: K, defaultValue: V): V;
+    /**
+     * 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: K, callbackfn: (key: K) => V): V;
     delete(key: K): boolean;
     clear(): void;
     has(key: K): boolean;

package/package.json

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

package/src/encoder/ChangeTree.ts

@@ -652,6 +652,33 @@ export class ChangeTree<T extends Ref = any> {
         };
     }
 
+    /**
+     * Move `parent`'s existing chain entry to `index`, skipping the work
+     * `addParent` does. `parent` must already be a parent of this tree.
+     *
+     * Called by collections whose wire slots shift (ArraySchema): StateView
+     * addresses per-view ADD/DELETE by that index, so it has to follow the
+     * element it names.
+     */
+    setParentIndex(parent: Ref, index: number) {
+        const chain = this.parentChain;
+        if (chain === undefined) { return; }
+
+        if (chain.next === undefined) {
+            chain.index = index; // sole parent, so it is `parent`
+            return;
+        }
+        // Shared instance — move only the entry `parent` owns. Matching goes
+        // through `$changes` because ArraySchema arrives proxied (see
+        // removeParent below).
+        for (let entry = chain; entry !== undefined; entry = entry.next) {
+            if (entry.ref[$changes] === parent[$changes]) {
+                entry.index = index;
+                return;
+            }
+        }
+    }
+
     /**
      * Remove a parent from the chain
      * @param parent - The parent to remove

package/src/types/custom/ArraySchema.ts

@@ -186,6 +186,34 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         return this.items.length;
     }
 
+    /**
+     * Re-point children at their wire slot. `ChangeTree.parentIndex` caches
+     * the slot a child holds in `tmpItems`, and StateView addresses per-view
+     * ADD/DELETE with it — so a reorder that leaves it behind aims those ops
+     * at whichever element inherited the slot (issue #231).
+     *
+     * The filter check is a correctness boundary, not a tunable: StateView is
+     * the only reader, and an array without `filteredChanges` never has a slot
+     * read back. Everything else stops at that check instead of walking its
+     * children every tick.
+     *
+     * Callers name the lowest slot that moved as `from`. Compaction cannot, so
+     * it hands over the pre-compaction layout as `staged` and the unchanged
+     * prefix is skipped instead. Either way tail churn walks nothing.
+     */
+    protected $reindexChildren(from: number, staged?: V[]) {
+        if (this[$changes].filteredChanges === undefined) { return; } // nothing will read the cache
+        if (typeof this[$childType] === "string") { return; } // primitives have no child tree
+        const tmpItems = this.tmpItems;
+        const length = tmpItems.length;
+        if (staged !== undefined) {
+            while (from < length && tmpItems[from] === staged[from]) { from++; }
+        }
+        for (let i = from; i < length; i++) {
+            tmpItems[i]?.[$changes]?.setParentIndex(this, i);
+        }
+    }
+
     push(...values: V[]) {
         let length = this.tmpItems.length;
 
@@ -348,6 +376,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         this[$changes].operation(OPERATION.REVERSE);
         this.items.reverse();
         this.tmpItems.reverse();
+        this.$reindexChildren(0);
         return this;
     }
 
@@ -400,6 +429,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         sortedItems.forEach((_, i) => changeTree.change(i, OPERATION.REPLACE));
 
         this.tmpItems.sort(compareFn);
+        this.$reindexChildren(0);
 
         this.isMovingItems = false;
         return this;
@@ -519,6 +549,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         });
 
         this.tmpItems.unshift(...items);
+        this.$reindexChildren(0); // from 0: nothing above placed the new items either
 
         return this.items.unshift(...items);
     }
@@ -845,7 +876,15 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
     }
 
     protected [$onEncodeEnd]() {
+        const staged = this.tmpItems;
         this.tmpItems = this.items.slice();
+
+        // Compaction just closed the staged holes — everything above the
+        // lowest one slid down a slot. There is no cheap "were there any"
+        // test to gate this on: `deletedIndexes` is an object here, and a
+        // `for...in` probe measured slower than the prefix scan it skips.
+        this.$reindexChildren(0, staged);
+
         this.deletedIndexes = {};
     }
 

package/src/types/custom/MapSchema.ts

@@ -152,6 +152,39 @@ export class MapSchema<V=any, K extends string = string> implements Map<K, V>, C
         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: K, defaultValue: V): V {
+        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: K, callbackfn: (key: K) => V): V {
+        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: K) {
         if (!this.$items.has(key)) {
             return false;