@colyseus/schema 4.0.19 → 5.0.0

package/src/types/custom/ArraySchema.ts

@@ -1,12 +1,12 @@
-import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $onDecodeEnd, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $onDecodeEnd, $proxyTarget, $refId } from "../symbols.js";
 import type { Schema } from "../../Schema.js";
-import { type IRef, ChangeTree, setOperationAtIndex } from "../../encoder/ChangeTree.js";
+import { type IRef, ChangeTree, installUntrackedChangeTree } from "../../encoder/ChangeTree.js";
 import { OPERATION } from "../../encoding/spec.js";
 import { registerType } from "../registry.js";
 import { Collection } from "../HelperTypes.js";
 
 import { encodeArray } from "../../encoder/EncodeOperation.js";
-import { decodeArray } from "../../decoder/DecodeOperation.js";
+import { CollectionKind, decodeArray } from "../../decoder/DecodeOperation.js";
 import type { StateView } from "../../encoder/StateView.js";
 import { assertInstanceType } from "../../encoding/assert.js";
 
@@ -18,20 +18,113 @@ const DEFAULT_SORT = (a: any, b: any) => {
     else return 0
 }
 
+/**
+ * Module-level Proxy handler shared by every `ArraySchema` instance. Hoisted
+ * out of the ctor so per-instance Proxy setup stops allocating ~6 arrow
+ * closures (the `__name` wrappers around those closures dominated one slice
+ * of the decoder profile). The handlers reference the target via the trap's
+ * `obj` arg — they don't need a captured `this`. Both `new ArraySchema()`
+ * and `ArraySchema.initializeForDecoder()` plug into it.
+ */
+const ARRAY_PROXY_HANDLER: ProxyHandler<any> = {
+    get: (obj, prop) => {
+        if (
+            typeof (prop) !== "symbol" &&
+            // FIXME: d8 accuses this as low performance
+            !isNaN(prop as any) // https://stackoverflow.com/a/175787/892698
+        ) {
+            return obj.items[prop as unknown as number];
+        }
+        return Reflect.get(obj, prop);
+    },
+
+    set: (obj, key, setValue) => {
+        if (typeof (key) !== "symbol" && !isNaN(key as any)) {
+            if (setValue === undefined || setValue === null) {
+                obj.$deleteAt(key as unknown as number);
+
+            } else {
+                if (setValue[$changes]) {
+                    assertInstanceType(setValue, obj[$childType] as typeof Schema, obj, key);
+
+                    const previousValue = obj.items[key as unknown as number];
+
+                    if (!obj.isMovingItems) {
+                        obj.$changeAt(Number(key), setValue);
+
+                    } else {
+                        if (previousValue !== undefined) {
+                            if (setValue[$changes].isNew) {
+                                obj[$changes].indexedOperation(Number(key), OPERATION.MOVE_AND_ADD);
+
+                            } else {
+                                if ((obj[$changes].getChange(Number(key)) & OPERATION.DELETE) === OPERATION.DELETE) {
+                                    obj[$changes].indexedOperation(Number(key), OPERATION.DELETE_AND_MOVE);
+
+                                } else {
+                                    obj[$changes].indexedOperation(Number(key), OPERATION.MOVE);
+                                }
+                            }
+
+                        } else if (setValue[$changes].isNew) {
+                            obj[$changes].indexedOperation(Number(key), OPERATION.ADD);
+                        }
+
+                        setValue[$changes].setParent(obj, obj[$changes].root, key);
+                    }
+
+                    if (previousValue !== undefined) {
+                        // remove root reference from previous value
+                        previousValue[$changes].root?.remove(previousValue[$changes]);
+                    }
+
+                } else {
+                    obj.$changeAt(Number(key), setValue);
+                }
+
+                obj.items[key as unknown as number] = setValue;
+                obj.tmpItems[key as unknown as number] = setValue;
+            }
+
+            return true;
+        }
+        return Reflect.set(obj, key, setValue);
+    },
+
+    deleteProperty: (obj, prop) => {
+        if (typeof (prop) === "number") {
+            obj.$deleteAt(prop);
+        } else {
+            delete obj[prop as unknown as number];
+        }
+        return true;
+    },
+
+    has: (obj, key) => {
+        if (typeof (key) !== "symbol" && !isNaN(Number(key))) {
+            return Reflect.has(obj.items, key);
+        }
+        return Reflect.has(obj, key);
+    },
+};
+
 export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IRef {
     [n: number]: V;
     [$changes]: ChangeTree;
     [$refId]?: number;
+    [$proxyTarget]: this;
 
     protected [$childType]: string | typeof Schema;
 
     protected items: V[] = [];
     protected tmpItems: V[] = [];
-    protected deletedIndexes: {[index: number]: boolean} = {};
+    protected deletedIndexes: boolean[] = [];
     protected isMovingItems = false;
 
     static [$encoder] = encodeArray;
     static [$decoder] = decodeArray;
+    /** Integer tag read by `decodeKeyValueOperation` — see `CollectionKind`. */
+    static readonly COLLECTION_KIND = CollectionKind.Array;
 
     /**
      * Determine if a property must be filtered.
@@ -65,99 +158,12 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
     }
 
     constructor (...items: V[]) {
-        Object.defineProperty(this, $childType, {
-            value: undefined,
-            enumerable: false,
-            writable: true,
-            configurable: true,
-        });
-
-        const proxy = new Proxy(this, {
-            get: (obj, prop) => {
-                if (
-                    typeof (prop) !== "symbol" &&
-                    // FIXME: d8 accuses this as low performance
-                    !isNaN(prop as any) // https://stackoverflow.com/a/175787/892698
-                ) {
-                    return this.items[prop as unknown as number];
-
-                } else {
-                    return Reflect.get(obj, prop);
-                }
-            },
-
-            set: (obj, key, setValue) => {
-                if (typeof (key) !== "symbol" && !isNaN(key as any)) {
-                    if (setValue === undefined || setValue === null) {
-                        obj.$deleteAt(key as unknown as number);
-
-                    } else {
-                        if (setValue[$changes]) {
-                            assertInstanceType(setValue, obj[$childType] as typeof Schema, obj, key);
-
-                            const previousValue = obj.items[key as unknown as number];
-
-                            if (!obj.isMovingItems) {
-                                obj.$changeAt(Number(key), setValue);
-
-                            } else {
-                                if (previousValue !== undefined) {
-                                    if (setValue[$changes].isNew) {
-                                        obj[$changes].indexedOperation(Number(key), OPERATION.MOVE_AND_ADD);
-
-                                    } else {
-                                        if ((obj[$changes].getChange(Number(key)) & OPERATION.DELETE) === OPERATION.DELETE) {
-                                            obj[$changes].indexedOperation(Number(key), OPERATION.DELETE_AND_MOVE);
-
-                                        } else {
-                                            obj[$changes].indexedOperation(Number(key), OPERATION.MOVE);
-                                        }
-                                    }
-
-                                } else if (setValue[$changes].isNew) {
-                                    obj[$changes].indexedOperation(Number(key), OPERATION.ADD);
-                                }
-
-                                setValue[$changes].setParent(this, obj[$changes].root, key);
-                            }
-
-                            if (previousValue !== undefined) {
-                                // remove root reference from previous value
-                                previousValue[$changes].root?.remove(previousValue[$changes]);
-                            }
-
-                        } else {
-                            obj.$changeAt(Number(key), setValue);
-                        }
-
-                        obj.items[key as unknown as number] = setValue;
-                        obj.tmpItems[key as unknown as number] = setValue;
-                    }
-
-                    return true;
-                } else {
-                    return Reflect.set(obj, key, setValue);
-                }
-            },
-
-            deleteProperty: (obj, prop) => {
-                if (typeof (prop) === "number") {
-                    obj.$deleteAt(prop);
-
-                } else {
-                    delete obj[prop as unknown as number];
-                }
+        this[$childType] = undefined as any;
+        // Self-reference so methods called via the Proxy can recover the
+        // underlying instance and access fields directly. See $proxyTarget.
+        this[$proxyTarget] = this;
 
-                return true;
-            },
-
-            has: (obj, key) => {
-                if (typeof (key) !== "symbol" && !isNaN(Number(key))) {
-                    return Reflect.has(this.items, key);
-                }
-                return Reflect.has(obj, key)
-            }
-        });
+        const proxy = new Proxy(this, ARRAY_PROXY_HANDLER);
 
         Object.defineProperty(this, $changes, {
             value: new ChangeTree(proxy),
@@ -172,6 +178,30 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         return proxy;
     }
 
+    /**
+     * Decoder-side factory. Skips the `ChangeTree` allocation and
+     * replicates the class-field initializers by hand (since `Object.create`
+     * bypasses them). Must stay in sync with the class-field declarations
+     * and the constructor body above.
+     *
+     * Pass the Proxy to `installUntrackedChangeTree` as the public identity
+     * so children set their parent to the Proxy, not the raw target.
+     */
+    static initializeForDecoder<V = any>(): ArraySchema<V> {
+        const self: any = Object.create(ArraySchema.prototype);
+        self.items = [];
+        // `tmpItems` / `deletedIndexes` are encoder-only (consulted by the
+        // staged-snapshot path in `$getByIndex`, `$onEncodeEnd`, etc.). The
+        // decoder reads from `items` directly and never maintains them.
+        self.isMovingItems = false;
+        self[$childType] = undefined;
+        self[$proxyTarget] = self;
+
+        const proxy = new Proxy(self, ARRAY_PROXY_HANDLER);
+        installUntrackedChangeTree(self, proxy);
+        return proxy;
+    }
+
     set length (newLength: number) {
         if (newLength === 0) {
             this.clear();
@@ -186,10 +216,22 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         return this.items.length;
     }
 
-    push(...values: V[]) {
-        let length = this.tmpItems.length;
+    // ────── Change tracking control (same API as Schema) ──────
+    pauseTracking(): void { this[$changes].pause(); }
+    resumeTracking(): void { this[$changes].resume(); }
+    untracked<T>(fn: () => T): T { return this[$changes].untracked(fn); }
+    get isTrackingPaused(): boolean { return this[$changes].paused; }
 
-        const changeTree = this[$changes];
+    push(...values: V[]) {
+        // `this` is the Proxy when called from user code. Grab the underlying
+        // instance once so the body's field reads (items, tmpItems, $changes,
+        // $childType) skip the Proxy.get trap on every iteration.
+        const self = this[$proxyTarget];
+        const items = self.items;
+        const tmpItems = self.tmpItems;
+        const changeTree = self[$changes];
+        const childType = self[$childType];
+        let length = tmpItems.length;
 
         for (let i = 0, l = values.length; i < l; i++, length++) {
             const value = values[i];
@@ -198,19 +240,21 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
                 // skip null values
                 return;
 
-            } else if (typeof (value) === "object" && this[$childType]) {
-                assertInstanceType(value as any, this[$childType] as typeof Schema, this, i);
+            } else if (typeof (value) === "object" && childType) {
+                assertInstanceType(value as any, childType as typeof Schema, self, i);
                 // TODO: move value[$changes]?.setParent() to this block.
             }
 
-            changeTree.indexedOperation(length, OPERATION.ADD, this.items.length);
+            changeTree.indexedOperation(length, OPERATION.ADD);
 
-            this.items.push(value);
-            this.tmpItems.push(value);
+            items.push(value);
+            tmpItems.push(value);
 
             //
             // set value's parent after the value is set
             // (to avoid encoding "refId" operations before parent's "ADD" operation)
+            // Pass `this` (the Proxy) as parent — the Proxy is the public
+            // identity of the array; ChangeTree.parentRef compares by identity.
             //
             value[$changes]?.setParent(this, changeTree.root, length);
         }
@@ -222,12 +266,15 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
      * Removes the last element from an array and returns it.
      */
     pop(): V | undefined {
+        // Unwrap Proxy once — see push() for rationale.
+        const self = this[$proxyTarget];
+        const tmpItems = self.tmpItems;
+        const deletedIndexes = self.deletedIndexes;
         let index: number = -1;
 
         // find last non-undefined index
-        for (let i = this.tmpItems.length - 1; i >= 0; i--) {
-            // if (this.tmpItems[i] !== undefined) {
-            if (this.deletedIndexes[i] !== true) {
+        for (let i = tmpItems.length - 1; i >= 0; i--) {
+            if (deletedIndexes[i] !== true) {
                 index = i;
                 break;
             }
@@ -237,11 +284,10 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
             return undefined;
         }
 
-        this[$changes].delete(index, undefined, this.items.length - 1);
-
-        this.deletedIndexes[index] = true;
+        self[$changes].delete(index);
+        deletedIndexes[index] = true;
 
-        return this.items.pop();
+        return self.items.pop();
     }
 
     at(index: number) {
@@ -303,24 +349,25 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
     }
 
     clear() {
+        const self = this[$proxyTarget];
         // skip if already clear
-        if (this.items.length === 0) {
+        if (self.items.length === 0) {
             return;
         }
 
         // discard previous operations.
-        const changeTree = this[$changes];
+        const changeTree = self[$changes];
 
         // remove children references
         changeTree.forEachChild((childChangeTree, _) => {
             changeTree.root?.remove(childChangeTree);
         });
 
-        changeTree.discard(true);
+        changeTree.discard();
         changeTree.operation(OPERATION.CLEAR);
 
-        this.items.length = 0;
-        this.tmpItems.length = 0;
+        self.items.length = 0;
+        self.tmpItems.length = 0;
     }
 
     /**
@@ -345,9 +392,10 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
      */
     // @ts-ignore
     reverse(): ArraySchema<V> {
-        this[$changes].operation(OPERATION.REVERSE);
-        this.items.reverse();
-        this.tmpItems.reverse();
+        const self = this[$proxyTarget];
+        self[$changes].operation(OPERATION.REVERSE);
+        self.items.reverse();
+        self.tmpItems.reverse();
         return this;
     }
 
@@ -355,19 +403,17 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
      * Removes the first element from an array and returns it.
      */
     shift(): V | undefined {
-        if (this.items.length === 0) { return undefined; }
+        const self = this[$proxyTarget];
+        const items = self.items;
+        if (items.length === 0) { return undefined; }
 
-        const changeTree = this[$changes];
-
-        const index = this.tmpItems.findIndex(item => item === this.items[0]);
-        const allChangesIndex = this.items.findIndex(item => item === this.items[0]);
-
-        changeTree.delete(index, OPERATION.DELETE, allChangesIndex);
-        changeTree.shiftAllChangeIndexes(-1, allChangesIndex);
-
-        this.deletedIndexes[index] = true;
+        const changeTree = self[$changes];
+        const first = items[0];
+        const index = self.tmpItems.findIndex(item => item === first);
+        changeTree.delete(index, OPERATION.DELETE);
+        self.deletedIndexes[index] = true;
 
-        return this.items.shift();
+        return items.shift();
     }
 
     /**
@@ -391,17 +437,18 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
      * ```
      */
     sort(compareFn: (a: V, b: V) => number = DEFAULT_SORT): this {
-        this.isMovingItems = true;
+        const self = this[$proxyTarget];
+        self.isMovingItems = true;
 
-        const changeTree = this[$changes];
-        const sortedItems = this.items.sort(compareFn);
+        const changeTree = self[$changes];
+        const sortedItems = self.items.sort(compareFn);
 
         // wouldn't OPERATION.MOVE make more sense here?
         sortedItems.forEach((_, i) => changeTree.change(i, OPERATION.REPLACE));
 
-        this.tmpItems.sort(compareFn);
+        self.tmpItems.sort(compareFn);
 
-        this.isMovingItems = false;
+        self.isMovingItems = false;
         return this;
     }
 
@@ -416,16 +463,20 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         deleteCount?: number,
         ...insertItems: V[]
     ): V[] {
-        const changeTree = this[$changes];
-
-        const itemsLength = this.items.length;
-        const tmpItemsLength = this.tmpItems.length;
+        const self = this[$proxyTarget];
+        const changeTree = self[$changes];
+        const items = self.items;
+        const tmpItems = self.tmpItems;
+        const deletedIndexes = self.deletedIndexes;
+
+        const itemsLength = items.length;
+        const tmpItemsLength = tmpItems.length;
         const insertCount = insertItems.length;
 
         // build up-to-date list of indexes, excluding removed values.
         const indexes: number[] = [];
         for (let i = 0; i < tmpItemsLength; i++) {
-            if (this.deletedIndexes[i] !== true) {
+            if (deletedIndexes[i] !== true) {
                 indexes.push(i);
             }
         }
@@ -442,7 +493,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
             for (let i = start; i < start + deleteCount; i++) {
                 const index = indexes[i];
                 changeTree.delete(index, OPERATION.DELETE);
-                this.deletedIndexes[index] = true;
+                deletedIndexes[index] = true;
             }
 
         } else {
@@ -462,36 +513,19 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
 
                 changeTree.indexedOperation(
                     addIndex,
-                    (this.deletedIndexes[addIndex])
+                    (deletedIndexes[addIndex])
                         ? OPERATION.DELETE_AND_ADD
                         : OPERATION.ADD
                 );
 
-                // set value's parent/root
+                // set value's parent/root — use `this` (Proxy) as parent.
                 insertItems[i][$changes]?.setParent(this, changeTree.root, addIndex);
             }
         }
 
-        //
-        // delete exceeding indexes from "allChanges"
-        // (prevent .encodeAll() from encoding non-existing items)
-        //
-        if (deleteCount > insertCount) {
-            changeTree.shiftAllChangeIndexes(-(deleteCount - insertCount), indexes[start + insertCount]);
-            // debugChangeSet("AFTER SHIFT indexes", changeTree.allChanges);
-        }
-
-        //
-        // FIXME: this code block is duplicated on ChangeTree
-        //
-        if (changeTree.filteredChanges !== undefined) {
-            changeTree.root?.enqueueChangeTree(changeTree, 'filteredChanges');
+        changeTree.root?.enqueueChangeTree(changeTree);
 
-        } else {
-            changeTree.root?.enqueueChangeTree(changeTree, 'changes');
-        }
-
-        return this.items.splice(start, deleteCount, ...insertItems);
+        return items.splice(start, deleteCount, ...insertItems);
     }
 
     /**
@@ -499,28 +533,20 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
      * @param items  Elements to insert at the start of the Array.
      */
     unshift(...items: V[]): number {
-        const changeTree = this[$changes];
+        const self = this[$proxyTarget];
+        const changeTree = self[$changes];
 
-        // shift indexes
+        // 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);
-
-        // new index
-        if (changeTree.isFiltered) {
-            setOperationAtIndex(changeTree.filteredChanges, this.items.length);
-            // changeTree.filteredChanges[this.items.length] = OPERATION.ADD;
-        } else {
-            setOperationAtIndex(changeTree.allChanges, this.items.length);
-            // changeTree.allChanges[this.items.length] = OPERATION.ADD;
-        }
-
-        // FIXME: should we use OPERATION.MOVE here instead?
         items.forEach((_, index) => {
             changeTree.change(index, OPERATION.ADD)
         });
 
-        this.tmpItems.unshift(...items);
+        self.tmpItems.unshift(...items);
 
-        return this.items.unshift(...items);
+        return self.items.unshift(...items);
     }
 
     /**
@@ -648,13 +674,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
      * length+end.
      */
     fill(value: V, start?: number, end?: number): this {
-        //
-        // TODO
-        //
         throw new Error("ArraySchema#fill() not implemented");
-        // this.$items.fill(value, start, end);
-
-        return this;
     }
 
     /**
@@ -667,11 +687,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
      * @param end If not specified, length of the this object is used as its default value.
      */
     copyWithin(target: number, start: number, end?: number): this {
-        //
-        // TODO
-        //
         throw new Error("ArraySchema#copyWithin() not implemented");
-        return this;
     }
 
     /**
@@ -824,14 +840,13 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         return this;
     }
 
+    /**
+     * Encoder-only. Reads the staged-snapshot (`tmpItems`) so the encoder can
+     * resolve a wire-index even after the user has mutated `items` mid-tick.
+     * The decoder reads `items[index]` directly — see `decodeArray` and
+     * `$deleteByIndex` below.
+     */
     [$getByIndex](index: number, isEncodeAll: boolean = false): any {
-        //
-        // TODO: avoid unecessary `this.tmpItems` check during decoding.
-        //
-        //    ENCODING uses `this.tmpItems` (or `this.items` if `isEncodeAll` is true)
-        //    DECODING uses `this.items`
-        //
-
         return (isEncodeAll)
             ? this.items[index]
             : this.deletedIndexes[index]
@@ -841,17 +856,15 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
 
     [$deleteByIndex](index: number): void {
         this.items[index] = undefined;
-        this.tmpItems[index] = undefined; // TODO: do not try to get "tmpItems" at decoding time.
     }
 
     protected [$onEncodeEnd]() {
         this.tmpItems = this.items.slice();
-        this.deletedIndexes = {};
+        this.deletedIndexes.length = 0;
     }
 
     protected [$onDecodeEnd]() {
         this.items = this.items.filter((item) => item !== undefined);
-        this.tmpItems = this.items.slice(); // TODO: do no use "tmpItems" at decoding time.
     }
 
     toArray() {