@colyseus/schema 3.0.0-alpha.3 → 3.0.0-alpha.30

package/src/decoder/strategy/StateCallbacks.ts

@@ -6,7 +6,7 @@ import { DataChange } from "../DecodeOperation";
 import { OPERATION } from "../../encoding/spec";
 import { DefinitionType } from "../../annotations";
 import { Schema } from "../../Schema";
-import type { ArraySchema } from "../../types/custom/ArraySchema";
+import type { CollectionSchema } from "../../types/custom/CollectionSchema";
 
 //
 // Discussion: https://github.com/colyseus/schema/issues/155
@@ -17,27 +17,74 @@ import type { ArraySchema } from "../../types/custom/ArraySchema";
 // - Avoid closures by allowing to pass a context. (https://github.com/colyseus/schema/issues/155#issuecomment-1804694081)
 //
 
-type GetProxyType<T> = unknown extends T // is "any"?
+export type GetCallbackProxy = (<T extends Schema>(instance: T) => CallbackProxy<T>);
+
+export type CallbackProxy<T> = unknown extends T // is "any"?
     ? InstanceCallback<T> & CollectionCallback<any, any>
     : T extends Collection<infer K, infer V, infer _>
         ? CollectionCallback<K, V>
-        : InstanceCallback<T>
+        : InstanceCallback<T>;
 
 type InstanceCallback<T> = {
+    /**
+     * Trigger callback when value of a property changes.
+     *
+     * @param prop name of the property
+     * @param callback callback to be triggered on property change
+     * @param immediate trigger immediatelly if property has been already set.
+     * @return callback to detach the listener
+     */
     listen<K extends NonFunctionPropNames<T>>(
         prop: K,
         callback: (value: T[K], previousValue: T[K]) => void,
         immediate?: boolean,
-    )
-    onChange(callback: () => void): void;
+    ): () => void;
+
+    /**
+     * Trigger callback whenever any property changed within this instance.
+     *
+     * @param prop name of the property
+     * @param callback callback to be triggered on property change
+     * @param immediate trigger immediatelly if property has been already set.
+     * @return callback to detach the listener
+     */
+    onChange(callback: () => void): () => void;
+
+    /**
+     * Bind properties to another object. Changes on the properties will be reflected on the target object.
+     *
+     * @param targetObject object to bind properties to
+     * @param properties list of properties to bind. If not provided, all properties will be bound.
+     */
     bindTo(targetObject: any, properties?: Array<NonFunctionPropNames<T>>): void;
 } & {
-    [K in NonFunctionNonPrimitivePropNames<T>]: GetProxyType<T[K]>;
+    [K in NonFunctionNonPrimitivePropNames<T>]: CallbackProxy<T[K]>;
 }
 
 type CollectionCallback<K, V> = {
-    onAdd(callback: (item: V, index: K) => void, immediate?: boolean): void;
-    onRemove(callback: (item: V, index: K) => void): void;
+    /**
+     * Trigger callback when an item has been added to the collection.
+     *
+     * @param callback
+     * @param immediate
+     * @return callback to detach the onAdd listener
+     */
+    onAdd(callback: (item: V, index: K) => void, immediate?: boolean): () => void;
+
+    /**
+     * Trigger callback when an item has been removed to the collection.
+     *
+     * @param callback
+     * @return callback to detach the onRemove listener
+     */
+    onRemove(callback: (item: V, index: K) => void): () => void;
+
+    // /**
+    //  * Trigger callback when an item has been removed to the collection.
+    //  *
+    //  * @param callback
+    //  */
+    // onChange(callback: (item: V, index: K) => void): void;
 };
 
 type OnInstanceAvailableCallback = (callback: (ref: Ref, existing: boolean) => void) => void;
@@ -48,11 +95,13 @@ type CallContext = {
     onInstanceAvailable?: OnInstanceAvailableCallback,
 }
 
-export function getStateCallbacks(decoder: Decoder) {
-    const $root = decoder.$root;
+
+export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>): GetCallbackProxy {
+    const $root = decoder.root;
     const callbacks = $root.callbacks;
 
-    let isTriggeringOnAdd = false;
+    const onAddCalls: WeakMap<Function, boolean> = new WeakMap();
+    let currentOnAddCallback: Function | undefined;
 
     decoder.triggerChanges = function (allChanges: DataChange[]) {
         const uniqueRefIds = new Set<number>();
@@ -76,8 +125,6 @@ export function getStateCallbacks(decoder: Decoder) {
                 for (let i = deleteCallbacks?.length - 1; i >= 0; i--) {
                     deleteCallbacks[i]();
                 }
-                // callbacks[$root.refIds.get(change.previousValue)]?.[OPERATION.DELETE]?.forEach(callback =>
-                //     callback());
             }
 
             if (ref instanceof Schema) {
@@ -86,47 +133,35 @@ export function getStateCallbacks(decoder: Decoder) {
                 //
 
                 if (!uniqueRefIds.has(refId)) {
-                    try {
-                        // trigger onChange
-                        const replaceCallbacks = $callbacks?.[OPERATION.REPLACE];
-                        for (let i = replaceCallbacks?.length - 1; i >= 0; i--) {
-                            replaceCallbacks[i]();
-                        }
-
-                    } catch (e) {
-                        console.error(e);
+                    // trigger onChange
+                    const replaceCallbacks = $callbacks?.[OPERATION.REPLACE];
+                    for (let i = replaceCallbacks?.length - 1; i >= 0; i--) {
+                        replaceCallbacks[i]();
+                        // try {
+                        // } catch (e) {
+                        //     console.error(e);
+                        // }
                     }
                 }
 
-                try {
-                    if ($callbacks.hasOwnProperty(change.field)) {
-                        const fieldCallbacks = $callbacks[change.field];
-                        for (let i = fieldCallbacks?.length - 1; i >= 0; i--) {
-                            fieldCallbacks[i](change.value, change.previousValue);
-                        }
+                if ($callbacks.hasOwnProperty(change.field)) {
+                    const fieldCallbacks = $callbacks[change.field];
+                    for (let i = fieldCallbacks?.length - 1; i >= 0; i--) {
+                        fieldCallbacks[i](change.value, change.previousValue);
+                        // try {
+                        // } catch (e) {
+                        //     console.error(e);
+                        // }
                     }
-
-                } catch (e) {
-                    //
-                    console.error(e);
                 }
 
+
             } else {
                 //
                 // Handle collection of items
                 //
 
-                if (change.op === OPERATION.ADD && change.previousValue === undefined) {
-                    // triger onAdd
-
-                    isTriggeringOnAdd = true;
-                    const addCallbacks = $callbacks[OPERATION.ADD];
-                    for (let i = addCallbacks?.length - 1; i >= 0; i--) {
-                        addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
-                    }
-                    isTriggeringOnAdd = false;
-
-                } else if ((change.op & OPERATION.DELETE) === OPERATION.DELETE) {
+                if ((change.op & OPERATION.DELETE) === OPERATION.DELETE) {
                     //
                     // FIXME: `previousValue` should always be available.
                     //
@@ -139,13 +174,19 @@ export function getStateCallbacks(decoder: Decoder) {
                     }
 
                     // Handle DELETE_AND_ADD operations
-                    // FIXME: should we set "isTriggeringOnAdd" here?
                     if ((change.op & OPERATION.ADD) === OPERATION.ADD) {
                         const addCallbacks = $callbacks[OPERATION.ADD];
                         for (let i = addCallbacks?.length - 1; i >= 0; i--) {
                             addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
                         }
                     }
+
+                } else if ((change.op & OPERATION.ADD) === OPERATION.ADD && change.previousValue === undefined) {
+                    // triger onAdd
+                    const addCallbacks = $callbacks[OPERATION.ADD];
+                    for (let i = addCallbacks?.length - 1; i >= 0; i--) {
+                        addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
+                    }
                 }
 
                 // trigger onChange
@@ -161,7 +202,10 @@ export function getStateCallbacks(decoder: Decoder) {
         }
     };
 
-    function getProxy(metadataOrType: Metadata | DefinitionType, context: CallContext) {
+    function getProxy(
+        metadataOrType: Metadata | DefinitionType,
+        context: CallContext
+    ) {
         let metadata: Metadata = context.instance?.constructor[Symbol.metadata] || metadataOrType;
         let isCollection = (
             (context.instance && typeof (context.instance['forEach']) === "function") ||
@@ -170,7 +214,7 @@ export function getStateCallbacks(decoder: Decoder) {
 
         if (metadata && !isCollection) {
 
-            const onAdd = function (
+            const onAddListen = function (
                 ref: Ref,
                 prop: string,
                 callback: (value: any, previousValue: any) => void, immediate: boolean
@@ -179,7 +223,7 @@ export function getStateCallbacks(decoder: Decoder) {
                 if (
                     immediate &&
                     context.instance[prop] !== undefined &&
-                    !isTriggeringOnAdd // FIXME: This is a workaround (https://github.com/colyseus/schema/issues/147)
+                    !onAddCalls.has(currentOnAddCallback) // Workaround for https://github.com/colyseus/schema/issues/147
                 ) {
                     callback(context.instance[prop], undefined);
                 }
@@ -192,24 +236,44 @@ export function getStateCallbacks(decoder: Decoder) {
             return new Proxy({
                 listen: function listen(prop: string, callback: (value: any, previousValue: any) => void, immediate: boolean = true) {
                     if (context.instance) {
-                        return onAdd(context.instance, prop, callback, immediate);
+                        return onAddListen(context.instance, prop, callback, immediate);
 
                     } else {
                         // collection instance not received yet
-                        context.onInstanceAvailable((ref: Ref, existing: boolean) =>
-                            onAdd(ref, prop, callback, immediate && existing));
+                        let detachCallback = () => {};
+
+                        context.onInstanceAvailable((ref: Ref, existing: boolean) => {
+                            detachCallback = onAddListen(ref, prop, callback, immediate && existing && !onAddCalls.has(currentOnAddCallback))
+                        });
+
+                        return () => detachCallback();
                     }
                 },
+
                 onChange: function onChange(callback: () => void) {
                     return $root.addCallback(
                         $root.refIds.get(context.instance),
                         OPERATION.REPLACE,
                         callback
                     );
-
                 },
+
+                //
+                // TODO: refactor `bindTo()` implementation.
+                // There is room for improvement.
+                //
                 bindTo: function bindTo(targetObject: any, properties?: string[]) {
-                    console.log("bindTo", targetObject, properties);
+                    if (!properties) {
+                        properties = Object.keys(metadata);
+                    }
+                    return $root.addCallback(
+                        $root.refIds.get(context.instance),
+                        OPERATION.REPLACE,
+                        () => {
+                            properties.forEach((prop) =>
+                                targetObject[prop] = context.instance[prop])
+                        }
+                    );
                 }
             }, {
                 get(target, prop: string) {
@@ -234,7 +298,8 @@ export function getStateCallbacks(decoder: Decoder) {
                             }
                         );
                         return getProxy(metadata[prop].type, {
-                            instance,
+                            // make sure refId is available, otherwise need to wait for the instance to be available.
+                            instance: ($root.refIds.get(instance) && instance),
                             parentInstance: context.instance,
                             onInstanceAvailable,
                         });
@@ -257,9 +322,16 @@ export function getStateCallbacks(decoder: Decoder) {
             const onAdd = function (ref: Ref, callback: (value: any, key: any) => void, immediate: boolean) {
                 // Trigger callback on existing items
                 if (immediate) {
-                    (ref as ArraySchema).forEach((v, k) => callback(v, k));
+                    (ref as CollectionSchema).forEach((v, k) => callback(v, k));
                 }
-                return $root.addCallback($root.refIds.get(ref), OPERATION.ADD, callback);
+
+                return $root.addCallback($root.refIds.get(ref), OPERATION.ADD, (value, key) => {
+                    onAddCalls.set(callback, true);
+                    currentOnAddCallback = callback;
+                    callback(value, key);
+                    onAddCalls.delete(callback)
+                    currentOnAddCallback = undefined;
+                });
             };
 
             const onRemove = function (ref: Ref, callback: (value: any, key: any) => void) {
@@ -272,25 +344,34 @@ export function getStateCallbacks(decoder: Decoder) {
                     // https://github.com/colyseus/schema/issues/147
                     // If parent instance has "onAdd" registered, avoid triggering immediate callback.
                     //
-                    // FIXME: "isTriggeringOnAdd" is a workaround. We should find a better way to handle this.
-                    //
-                    if (context.onInstanceAvailable) {
+
+                    if (context.instance) {
+                        return onAdd(context.instance, callback, immediate && !onAddCalls.has(currentOnAddCallback));
+
+                    } else if (context.onInstanceAvailable) {
                         // collection instance not received yet
-                        context.onInstanceAvailable((ref: Ref, existing: boolean) =>
-                            onAdd(ref, callback, immediate && existing && !isTriggeringOnAdd));
+                        let detachCallback = () => {};
 
-                    } else if (context.instance) {
-                        onAdd(context.instance, callback, immediate && !isTriggeringOnAdd);
+                        context.onInstanceAvailable((ref: Ref, existing: boolean) => {
+                            detachCallback = onAdd(ref, callback, immediate && existing && !onAddCalls.has(currentOnAddCallback));
+                        });
+
+                        return () => detachCallback();
                     }
                 },
                 onRemove: function(callback: (value, key) => void) {
                     if (context.onInstanceAvailable) {
                         // collection instance not received yet
-                        context.onInstanceAvailable((ref: Ref) =>
-                            onRemove(ref, callback));
+                        let detachCallback = () => {};
+
+                        context.onInstanceAvailable((ref: Ref) => {
+                            detachCallback = onRemove(ref, callback)
+                        });
+
+                        return () => detachCallback();
 
                     } else if (context.instance) {
-                        onRemove(context.instance, callback);
+                        return onRemove(context.instance, callback);
                     }
                 },
             }, {
@@ -307,20 +388,9 @@ export function getStateCallbacks(decoder: Decoder) {
         }
     }
 
-    function $<T>(instance: T): GetProxyType<T> {
-        return getProxy(undefined, { instance }) as GetProxyType<T>;
-    }
-
-    return {
-        $,
-        trigger: function trigger(changes: DataChange[]) {
-            for (let i = 0, l = changes.length; i < l; i++) {
-                const change = changes[i];
-
-                change.op
-                change.ref
-            }
-        }
+    function $<T>(instance: T): CallbackProxy<T> {
+        return getProxy(undefined, { instance }) as CallbackProxy<T>;
     }
 
+    return $;
 }

package/src/encoder/ChangeTree.ts

@@ -7,10 +7,10 @@ import type { ArraySchema } from "../types/custom/ArraySchema";
 import type { CollectionSchema } from "../types/custom/CollectionSchema";
 import type { SetSchema } from "../types/custom/SetSchema";
 
+import { Root } from "./Root";
 import { Metadata } from "../Metadata";
 import type { EncodeOperation } from "./EncodeOperation";
 import type { DecodeOperation } from "../decoder/DecodeOperation";
-import type { StateView } from "./StateView";
 
 declare global {
     interface Object {
@@ -27,53 +27,6 @@ export type Ref = Schema
     | CollectionSchema
     | SetSchema;
 
-export class Root {
-    protected nextUniqueId: number = 0;
-    refCount = new WeakMap<ChangeTree, number>();
-
-    // all changes
-    allChanges = new Map<ChangeTree, Map<number, OPERATION>>();
-    allFilteredChanges = new Map<ChangeTree, Map<number, OPERATION>>();
-
-    // pending changes to be encoded
-    changes = new Map<ChangeTree, Map<number, OPERATION>>();
-    filteredChanges = new Map<ChangeTree, Map<number, OPERATION>>();
-
-    getNextUniqueId() {
-        return this.nextUniqueId++;
-    }
-
-    add (changeTree: ChangeTree) {
-        const refCount = this.refCount.get(changeTree) || 0;
-        this.refCount.set(changeTree, refCount + 1);
-    }
-
-    remove(changeTree: ChangeTree) {
-        const refCount = this.refCount.get(changeTree);
-        if (refCount <= 1) {
-            this.allChanges.delete(changeTree);
-            this.changes.delete(changeTree);
-
-            if (changeTree.isFiltered || changeTree.isPartiallyFiltered) {
-                this.allFilteredChanges.delete(changeTree);
-                this.filteredChanges.delete(changeTree);
-            }
-
-            this.refCount.delete(changeTree);
-
-        } else {
-            this.refCount.set(changeTree, refCount - 1);
-        }
-
-        changeTree.forEachChild((child, _) =>
-            this.remove(child));
-    }
-
-    clear() {
-        this.changes.clear();
-    }
-}
-
 export class ChangeTree<T extends Ref=any> {
     ref: T;
     refId: number;
@@ -123,9 +76,6 @@ export class ChangeTree<T extends Ref=any> {
         if (this.isFiltered || this.isPartiallyFiltered) {
             this.root.allFilteredChanges.set(this, this.allFilteredChanges);
             this.root.filteredChanges.set(this, this.filteredChanges);
-
-        // } else {
-        //     this.root.allChanges.set(this, this.allChanges);
         }
 
         if (!this.isFiltered) {
@@ -170,13 +120,12 @@ export class ChangeTree<T extends Ref=any> {
 
         if (!this.isFiltered) {
             this.root.changes.set(this, this.changes);
+            this.root.allChanges.set(this, this.allChanges);
         }
 
         if (this.isFiltered || this.isPartiallyFiltered) {
             this.root.filteredChanges.set(this, this.filteredChanges);
             this.root.allFilteredChanges.set(this, this.filteredChanges);
-        } else {
-            this.root.allChanges.set(this, this.allChanges);
         }
 
         this.ensureRefId();
@@ -206,7 +155,7 @@ export class ChangeTree<T extends Ref=any> {
             // MapSchema / ArraySchema, etc.
             (this.ref as MapSchema).forEach((value, key) => {
                 if (Metadata.isValidInstance(value)) {
-                    callback(value[$changes], this.ref[$changes].indexes[key]);
+                    callback(value[$changes], this.ref[$changes].indexes[key] ?? key);
                 }
             });
         }
@@ -240,9 +189,11 @@ export class ChangeTree<T extends Ref=any> {
         //
 
         if (isFiltered) {
-            this.allFilteredChanges.set(index, OPERATION.ADD);
             this.root?.filteredChanges.set(this, this.filteredChanges);
 
+            this.allFilteredChanges.set(index, OPERATION.ADD);
+            this.root?.allFilteredChanges.set(this, this.allFilteredChanges);
+
         } else {
             this.allChanges.set(index, OPERATION.ADD);
             this.root?.changes.set(this, this.changes);
@@ -285,7 +236,6 @@ export class ChangeTree<T extends Ref=any> {
 
     private _shiftAllChangeIndexes(shiftIndex: number, startIndex: number = 0, allChangeSet: Map<number, OPERATION>) {
         Array.from(allChangeSet.entries()).forEach(([index, op]) => {
-            // console.log('shiftAllChangeIndexes', index >= startIndex, { index, op, shiftIndex, startIndex })
             if (index >= startIndex) {
                 allChangeSet.delete(index);
                 allChangeSet.set(index + shiftIndex, op);
@@ -452,21 +402,41 @@ export class ChangeTree<T extends Ref=any> {
 
     protected checkIsFiltered(parent: Ref, parentIndex: number) {
         // Detect if current structure has "filters" declared
-        this.isPartiallyFiltered = this.ref['constructor']?.[Symbol.metadata]?.[-2];
+        this.isPartiallyFiltered = (this.ref['constructor']?.[Symbol.metadata]?.[-2] !== undefined);
+
+        if (parent && !Metadata.isValidInstance(parent)) {
+            const parentChangeTree = parent[$changes];
+            parent = parentChangeTree.parent;
+            parentIndex = parentChangeTree.parentIndex;
+        }
+
+        const parentMetadata = parent?.['constructor']?.[Symbol.metadata];
 
-        // TODO: support "partially filtered", where the instance is visible, but only a field is not.
+        this.isFiltered = (
+            parent &&
+            parentMetadata?.[-2]?.includes(parentIndex)
+        );
 
-        // Detect if parent has "filters" declared
-        while (parent && !this.isFiltered) {
-            const metadata: Metadata = parent['constructor'][Symbol.metadata];
+        // this.isFiltered = this.ref['constructor']?.[Symbol.metadata]?.[-4];
 
-            const fieldName = metadata?.[parentIndex];
-            const isParentOwned = metadata?.[fieldName]?.tag !== undefined;
+        // // Detect if parent has "filters" declared
+        // while (parent && !this.isFiltered) {
+        //     const metadata: Metadata = parent['constructor'][Symbol.metadata];
+        //     // this.isFiltered = metadata?.[-4];
 
-            this.isFiltered = isParentOwned || parent[$changes].isFiltered; // metadata?.[-2]
+        //     const fieldName = metadata?.[parentIndex];
+        //     const isParentOwned = metadata?.[fieldName]?.tag !== undefined;
+        //     this.isFiltered = isParentOwned || parent[$changes].isFiltered; // metadata?.[-2]
 
-            parent = parent[$changes].parent;
-        };
+        //     parent = parent[$changes].parent;
+        // };
+
+        // console.log("ChangeTree.checkIsFiltered", {
+        //     parent: parent?.constructor.name,
+        //     ref: this.ref.constructor.name,
+        //     isFiltered: this.isFiltered,
+        //     isPartiallyFiltered: this.isPartiallyFiltered,
+        // });
 
         //
         // TODO: refactor this!

package/src/encoder/EncodeOperation.ts

@@ -172,6 +172,19 @@ export const encodeKeyValueOperation: EncodeOperation = function (
     const type = changeTree.getType(field);
     const value = changeTree.getValue(field);
 
+    // try { throw new Error(); } catch (e) {
+    //     // only print if not coming from Reflection.ts
+    //     if (!e.stack.includes("src/Reflection.ts")) {
+    //         console.log("encodeKeyValueOperation -> ", {
+    //             ref: changeTree.ref.constructor.name,
+    //             field,
+    //             operation: OPERATION[operation],
+    //             value: value?.toJSON(),
+    //             items: ref.toJSON(),
+    //         });
+    //     }
+    // }
+
     // TODO: inline this function call small performance gain
     encodeValue(encoder, bytes, ref, type, value, field, operation, it);
 }
@@ -191,18 +204,22 @@ export const encodeArray: EncodeOperation = function (
     hasView: boolean,
 ) {
     const ref = changeTree.ref;
+    const useOperationByRefId = hasView && changeTree.isFiltered && (typeof (changeTree.getType(field)) !== "string");
 
-    if (
-        hasView &&
-        operation === OPERATION.DELETE &&
-        typeof (changeTree.getType(field)) !== "string"
-    ) {
-        // encode delete by refId (array of schemas)
-        bytes[it.offset++] = OPERATION.DELETE_BY_REFID;
-        const value =  ref['tmpItems'][field];
-        const refId = value[$changes].refId;
-        encode.number(bytes, refId, it);
-        return;
+    let refOrIndex: number;
+
+    if (useOperationByRefId) {
+        refOrIndex = ref['tmpItems'][field][$changes].refId;
+
+        if (operation === OPERATION.DELETE) {
+            operation = OPERATION.DELETE_BY_REFID;
+
+        } else if (operation === OPERATION.ADD) {
+            operation = OPERATION.ADD_BY_REFID;
+        }
+
+    } else {
+        refOrIndex = field;
     }
 
     // encode operation
@@ -214,7 +231,7 @@ export const encodeArray: EncodeOperation = function (
     }
 
     // encode index
-    encode.number(bytes, field, it);
+    encode.number(bytes, refOrIndex, it);
 
     // Do not encode value for DELETE operations
     if (operation === OPERATION.DELETE) {