@colyseus/schema 3.0.22 → 3.0.24

package/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,17 +34,44 @@ 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]) {
+        const changeTree: ChangeTree = obj?.[$changes];
+
+        if (!changeTree) {
             console.warn("StateView#add(), invalid object:", obj);
             return this;
+
+        } else if (
+            !changeTree.parent &&
+            changeTree.refId !== 0 // allow root object
+        ) {
+            /**
+             * TODO: can we avoid this?
+             *
+             * When the "parent" structure has the @view() tag, it is currently
+             * not possible to identify it has to be added to the view as well
+             * (this.addParentOf() is not called).
+             */
+            throw new Error(
+                `Cannot add a detached instance to the StateView. Make sure to assign the "${changeTree.ref.constructor.name}" instance to the state before calling view.add()`
+            );
         }
 
         // 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 +157,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 +196,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 +271,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;
+    }
+}

package/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])
         );
     }
 

package/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])
         );
     }
 

package/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])
         );
     }
 

package/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])
         );
     }