@colyseus/schema 3.0.0-alpha.9 → 3.0.1

package/src/decoder/strategy/StateCallbacks.ts

@@ -4,9 +4,9 @@ import { Ref } from "../../encoder/ChangeTree";
 import { Decoder } from "../Decoder";
 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 { DefinitionType } from "../../annotations";
+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) {
+
+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,28 +236,49 @@ 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).map((index) => metadata[index as any as number].name);
+                    }
+                    return $root.addCallback(
+                        $root.refIds.get(context.instance),
+                        OPERATION.REPLACE,
+                        () => {
+                            properties.forEach((prop) =>
+                                targetObject[prop] = context.instance[prop])
+                        }
+                    );
                 }
             }, {
                 get(target, prop: string) {
-                    if (metadata[prop]) {
+                    const metadataField = metadata[metadata[prop]];
+                    if (metadataField) {
                         const instance = context.instance?.[prop];
                         const onInstanceAvailable: OnInstanceAvailableCallback = (
                             (callback: (ref: Ref, existing: boolean) => void) => {
@@ -233,8 +298,9 @@ export function getStateCallbacks(decoder: Decoder) {
                                 }
                             }
                         );
-                        return getProxy(metadata[prop].type, {
-                            instance,
+                        return getProxy(metadataField.type, {
+                            // 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 +323,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 +345,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 +389,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 $;
 }