StateView: allow to opt-in for tracking items. add .clear() method.

Author: endel

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "3.0.22",
+  "version": "3.0.23",
   "description": "Binary state serializer with delta encoding for games",
   "bin": {
     "schema-codegen": "./bin/schema-codegen",

src/Schema.ts

@@ -69,7 +69,7 @@ export class Schema {
 
         } else if (tag === DEFAULT_VIEW_TAG) {
             // view pass: default tag
-            return view.items.has(ref[$changes]);
+            return view.visible.has(ref[$changes]);
 
         } else {
             // view pass: custom tag

src/encoder/Encoder.ts

@@ -62,7 +62,7 @@ export class Encoder<T extends Schema = any> {
             const changeTree = changeTrees[i];
 
             if (hasView) {
-                if (!view.items.has(changeTree)) {
+                if (!view.visible.has(changeTree)) {
                     view.invisible.add(changeTree);
                     continue; // skip this change tree
 

src/encoder/StateView.ts

@@ -3,16 +3,23 @@ import { $changes, $fieldIndexesByViewTag, $viewFieldIndexes } from "../types/sy
 import { DEFAULT_VIEW_TAG } from "../annotations";
 import { OPERATION } from "../encoding/spec";
 import { Metadata } from "../Metadata";
+import { spliceOne } from "../types/utils";
 
-export function createView() {
-    return new StateView();
+export function createView(iterable: boolean = false) {
+    return new StateView(iterable);
 }
 
 export class StateView {
+    /**
+     * Iterable list of items that are visible to this view
+     * (Available only if constructed with `iterable: true`)
+     */
+    items: Ref[];
+
     /**
      * List of ChangeTree's that are visible to this view
      */
-    items: WeakSet<ChangeTree> = new WeakSet<ChangeTree>();
+    visible: WeakSet<ChangeTree> = new WeakSet<ChangeTree>();
 
     /**
      * List of ChangeTree's that are invisible to this view
@@ -27,6 +34,12 @@ export class StateView {
      */
     changes = new Map<number, IndexedOperations>();
 
+    constructor(public iterable: boolean = false) {
+        if (iterable) {
+            this.items = [];
+        }
+    }
+
     // TODO: allow to set multiple tags at once
     add(obj: Ref, tag: number = DEFAULT_VIEW_TAG, checkIncludeParent: boolean = true) {
         if (!obj?.[$changes]) {
@@ -37,7 +50,12 @@ export class StateView {
         // FIXME: ArraySchema/MapSchema do not have metadata
         const metadata: Metadata = obj.constructor[Symbol.metadata];
         const changeTree: ChangeTree = obj[$changes];
-        this.items.add(changeTree);
+        this.visible.add(changeTree);
+
+        // add to iterable list (only the explicitly added items)
+        if (this.iterable && checkIncludeParent) {
+            this.items.push(obj);
+        }
 
         // add parent ChangeTree's
         // - if it was invisible to this view
@@ -123,9 +141,9 @@ export class StateView {
         const changeTree = childChangeTree.parent[$changes];
         const parentIndex = childChangeTree.parentIndex;
 
-        if (!this.items.has(changeTree)) {
+        if (!this.visible.has(changeTree)) {
             // view must have all "changeTree" parent tree
-            this.items.add(changeTree);
+            this.visible.add(changeTree);
 
             // add parent's parent
             const parentChangeTree: ChangeTree = changeTree.parent?.[$changes];
@@ -162,14 +180,24 @@ export class StateView {
         }
     }
 
-    remove(obj: Ref, tag: number = DEFAULT_VIEW_TAG) {
+    remove(obj: Ref, tag?: number): this; // hide _isClear parameter from public API
+    remove(obj: Ref, tag?: number, _isClear?: boolean): this;
+    remove(obj: Ref, tag: number = DEFAULT_VIEW_TAG, _isClear: boolean = false): this {
         const changeTree: ChangeTree = obj[$changes];
         if (!changeTree) {
             console.warn("StateView#remove(), invalid object:", obj);
             return this;
         }
 
-        this.items.delete(changeTree);
+        this.visible.delete(changeTree);
+
+        // remove from iterable list
+        if (
+            this.iterable &&
+            !_isClear // no need to remove during clear(), as it will be cleared entirely
+        ) {
+            spliceOne(this.items, this.items.indexOf(obj));
+        }
 
         const ref = changeTree.ref;
         const metadata: Metadata = ref.constructor[Symbol.metadata]; // ArraySchema/MapSchema do not have metadata
@@ -227,11 +255,24 @@ export class StateView {
     }
 
     has(obj: Ref) {
-        return this.items.has(obj[$changes]);
+        return this.visible.has(obj[$changes]);
     }
 
     hasTag(ob: Ref, tag: number = DEFAULT_VIEW_TAG) {
         const tags = this.tags?.get(ob[$changes]);
         return tags?.has(tag) ?? false;
     }
-}
+
+    clear() {
+        if (!this.iterable) {
+            throw new Error("StateView#clear() is only available for iterable StateView's. Use StateView(iterable: true) constructor.");
+        }
+
+        for (let i = 0, l = this.items.length; i < l; i++) {
+            this.remove(this.items[i], DEFAULT_VIEW_TAG, true);
+        }
+
+        // clear items array
+        this.items.length = 0;
+    }
+}

src/types/custom/ArraySchema.ts

@@ -42,7 +42,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V> {
             !view ||
             typeof (ref[$childType]) === "string" ||
             // view.items.has(ref[$getByIndex](index)[$changes])
-            view.items.has(ref['tmpItems'][index]?.[$changes])
+            view.visible.has(ref['tmpItems'][index]?.[$changes])
         );
     }
 

src/types/custom/CollectionSchema.ts

@@ -33,7 +33,7 @@ export class CollectionSchema<V=any> implements Collection<K, V>{
         return (
             !view ||
             typeof (ref[$childType]) === "string" ||
-            view.items.has((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes])
+            view.visible.has((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes])
         );
     }
 

src/types/custom/MapSchema.ts

@@ -34,7 +34,7 @@ export class MapSchema<V=any, K extends string = string> implements Map<K, V>, C
         return (
             !view ||
             typeof (ref[$childType]) === "string" ||
-            view.items.has((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes])
+            view.visible.has((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes])
         );
     }
 

src/types/custom/SetSchema.ts

@@ -31,7 +31,7 @@ export class SetSchema<V=any> implements Collection<number, V> {
         return (
             !view ||
             typeof (ref[$childType]) === "string" ||
-            view.items.has((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes])
+            view.visible.has((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes])
         );
     }
 

test/StateView.test.ts

@@ -771,6 +771,94 @@ describe("StateView", () => {
             assert.strictEqual(1, client1.state.entities.size);
             assert.strictEqual(3, client1.state.entities.get("one").components.length);
 
+            assert.strictEqual(1, client2.state.entities.size);
+            assert.strictEqual(3, client2.state.entities.get("two").components.length);
+        });
+
+        it("should allow to .clear() the view", () => {
+            class Component extends Schema {
+                @type("string") name: string;
+                @type("number") value: number;
+            }
+
+            class ListComponent extends Component {
+                @type(["string"]) list = new ArraySchema<string>();
+            }
+
+            class TagComponent extends Component {
+                @type("string") tag: string;
+            }
+
+            class Entity extends Schema {
+                @type("string") id: string = nanoid(9);
+                @type([Component]) components = new ArraySchema<Component>();
+            }
+
+            class MyRoomState extends Schema {
+                @view() @type({ map: Entity }) entities = new Map<string, Entity>();
+            }
+
+            const state = new MyRoomState();
+            const encoder = getEncoder(state);
+
+            const client1 = createClientWithView(state, new StateView(true));
+            const client2 = createClientWithView(state, new StateView(true));
+
+            state.entities.set("one", new Entity().assign({
+                id: "one",
+                components: [
+                    new Component().assign({ name: "Health", value: 100 }),
+                    new ListComponent().assign({ name: "List", value: 200, list: ["one", "two"] }),
+                    new TagComponent().assign({ name: "Tag", value: 300, tag: "tag" }),
+                ]
+            }));
+
+            state.entities.set("two", new Entity().assign({
+                id: "two",
+                components: [
+                    new Component().assign({ name: "Health", value: 100 }),
+                    new ListComponent().assign({ name: "List", value: 200, list: ["one", "two"] }),
+                    new TagComponent().assign({ name: "Tag", value: 300, tag: "tag" }),
+                ]
+            }));
+
+            encodeMultiple(encoder, state, [client1, client2]);
+
+            // add entities for the first time
+            client1.view.add(state.entities.get("one"));
+            client2.view.add(state.entities.get("two"));
+
+            assert.strictEqual(1, client1.view.items.length);
+            assert.strictEqual(1, client2.view.items.length);
+
+            encodeMultiple(encoder, state, [client1, client2]);
+
+            assert.strictEqual(1, client1.state.entities.size);
+            assert.strictEqual(3, client1.state.entities.get("one").components.length);
+
+            assert.strictEqual(1, client2.state.entities.size);
+            assert.strictEqual(3, client2.state.entities.get("two").components.length);
+
+            client1.view.clear();
+            client2.view.clear();
+
+            assert.strictEqual(0, client1.view.items.length);
+            assert.strictEqual(0, client2.view.items.length);
+
+            encodeMultiple(encoder, state, [client1, client2]);
+
+            assert.strictEqual(0, client1.state.entities.size);
+            assert.strictEqual(0, client2.state.entities.size);
+
+            // re-add entities!
+            client1.view.add(state.entities.get("one"));
+            client2.view.add(state.entities.get("two"));
+
+            encodeMultiple(encoder, state, [client1, client2]);
+
+            assert.strictEqual(1, client1.state.entities.size);
+            assert.strictEqual(3, client1.state.entities.get("one").components.length);
+
             assert.strictEqual(1, client2.state.entities.size);
             assert.strictEqual(3, client2.state.entities.get("two").components.length);