@colyseus/schema 4.0.1 → 4.0.2

package/lib/src/decoder/strategy/Callbacks.d.ts

@@ -0,0 +1,154 @@
+import { Collection, NonFunctionPropNames } from "../../types/HelperTypes";
+import { Ref } from "../../encoder/ChangeTree";
+import { Decoder } from "../Decoder";
+import { DataChange } from "../DecodeOperation";
+import { OPERATION } from "../../encoding/spec";
+import { Schema } from "../../Schema";
+import { $refId } from "../../types/symbols";
+import { MapSchema } from "../../types/custom/MapSchema";
+import { ArraySchema } from "../../types/custom/ArraySchema";
+import { type SchemaCallbackProxy } from "./getDecoderStateCallbacks";
+type PropertyChangeCallback<K> = (currentValue: K, previousValue: K) => void;
+type KeyValueCallback<K, V> = (key: K, value: V) => void;
+type InstanceChangeCallback = () => void;
+type PublicPropNames<T> = Exclude<NonFunctionPropNames<T>, typeof $refId> & string;
+type CollectionPropNames<T> = Exclude<{
+    [K in keyof T]: T[K] extends Collection<any, any> ? K : never;
+}[keyof T] & string, typeof $refId>;
+type CollectionValueType<T, K extends keyof T> = T[K] extends MapSchema<infer V, any> ? V : T[K] extends ArraySchema<infer V> ? V : T[K] extends Collection<any, infer V, any> ? V : never;
+type CollectionKeyType<T, K extends keyof T> = T[K] extends MapSchema<any, infer Key> ? Key : T[K] extends ArraySchema<any> ? number : T[K] extends Collection<infer Key, any, any> ? Key : never;
+/**
+ * State Callbacks handler
+ *
+ * Usage:
+ * ```ts
+ * const $ = Callbacks.get(decoder);
+ *
+ * // Listen to property changes
+ * $.listen("currentTurn", (currentValue, previousValue) => { ... });
+ *
+ * // Listen to collection additions
+ * $.onAdd("entities", (sessionId, entity) => {
+ *     // Nested property listening
+ *     $.listen(entity, "hp", (currentHp, previousHp) => { ... });
+ * });
+ *
+ * // Listen to collection removals
+ * $.onRemove("entities", (sessionId, entity) => { ... });
+ *
+ * // Listen to any property change on an instance
+ * $.onChange(entity, () => { ... });
+ *
+ * // Bind properties to another object
+ * $.bindTo(player, playerVisual);
+ * ```
+ */
+export declare class StateCallbackStrategy<TState extends Schema> {
+    protected decoder: Decoder<TState>;
+    protected uniqueRefIds: Set<number>;
+    protected isTriggering: boolean;
+    constructor(decoder: Decoder<TState>);
+    protected get callbacks(): {
+        [refId: number]: import("../ReferenceTracker").SchemaCallbacks;
+    };
+    protected get state(): TState;
+    protected addCallback(refId: number, operationOrProperty: OPERATION | string, handler: Function): () => void;
+    protected addCallbackOrWaitCollectionAvailable<TInstance extends Schema, TReturn extends Ref>(instance: TInstance, propertyName: string, operation: OPERATION, handler: Function, immediate?: boolean): () => void;
+    /**
+     * Listen to property changes on the root state.
+     */
+    listen<K extends PublicPropNames<TState>>(property: K, handler: PropertyChangeCallback<TState[K]>, immediate?: boolean): () => void;
+    /**
+     * Listen to property changes on a nested instance.
+     */
+    listen<TInstance extends Schema, K extends PublicPropNames<TInstance>>(instance: TInstance, property: K, handler: PropertyChangeCallback<TInstance[K]>, immediate?: boolean): () => void;
+    protected listenInstance<TInstance extends Schema>(instance: TInstance, propertyName: string, handler: PropertyChangeCallback<any>, immediate?: boolean): () => void;
+    /**
+     * Listen to any property change on an instance.
+     */
+    onChange<TInstance extends Schema>(instance: TInstance, handler: InstanceChangeCallback): () => void;
+    /**
+     * Listen to item changes in a collection on root state.
+     */
+    onChange<K extends CollectionPropNames<TState>>(property: K, handler: KeyValueCallback<CollectionKeyType<TState, K>, CollectionValueType<TState, K>>): () => void;
+    /**
+     * Listen to item changes in a nested collection.
+     */
+    onChange<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>): () => void;
+    /**
+     * Listen to items added to a collection on root state.
+     */
+    onAdd<K extends CollectionPropNames<TState>>(property: K, handler: KeyValueCallback<CollectionKeyType<TState, K>, CollectionValueType<TState, K>>, immediate?: boolean): () => void;
+    /**
+     * Listen to items added to a nested collection.
+     */
+    onAdd<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>, immediate?: boolean): () => void;
+    /**
+     * Listen to items removed from a collection on root state.
+     */
+    onRemove<K extends CollectionPropNames<TState>>(property: K, handler: KeyValueCallback<CollectionKeyType<TState, K>, CollectionValueType<TState, K>>): () => void;
+    /**
+     * Listen to items removed from a nested collection.
+     */
+    onRemove<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>): () => void;
+    /**
+     * Bind properties from a Schema instance to a target object.
+     * Changes will be automatically reflected on the target object.
+     */
+    bindTo<TInstance extends Schema, TTarget>(from: TInstance, to: TTarget, properties?: string[], immediate?: boolean): () => void;
+    protected triggerChanges(allChanges: DataChange[]): void;
+}
+/**
+ * Factory class for retrieving the callbacks API.
+ */
+export declare const Callbacks: {
+    /**
+     * Get the new callbacks standard API.
+     *
+     * Usage:
+     * ```ts
+     * const callbacks = Callbacks.get(roomOrDecoder);
+     *
+     * // Listen to property changes
+     * callbacks.listen("currentTurn", (currentValue, previousValue) => { ... });
+     *
+     * // Listen to collection additions
+     * callbacks.onAdd("entities", (sessionId, entity) => {
+     *     // Nested property listening
+     *     callbacks.listen(entity, "hp", (currentHp, previousHp) => { ... });
+     * });
+     *
+     * // Listen to collection removals
+     * callbacks.onRemove("entities", (sessionId, entity) => { ... });
+     *
+     * // Listen to any property change on an instance
+     * callbacks.onChange(entity, () => { ... });
+     *
+     * // Bind properties to another object
+     * callbacks.bindTo(player, playerVisual);
+     * ```
+     *
+     * @param roomOrDecoder - Room or Decoder instance to get the callbacks for.
+     * @returns the new callbacks standard API.
+     */
+    get<T extends Schema>(roomOrDecoder: Decoder<T> | {
+        serializer: {
+            decoder: Decoder<T>;
+        };
+    }): StateCallbackStrategy<T>;
+    /**
+     * Get the legacy callbacks API.
+     *
+     * We aim to deprecate this API on 1.0, and iterate on improving Callbacks.get() API.
+     *
+     * @param roomOrDecoder - Room or Decoder instance to get the legacy callbacks for.
+     * @returns the legacy callbacks API.
+     */
+    getLegacy<T extends Schema>(roomOrDecoder: Decoder<T> | {
+        serializer: {
+            decoder: Decoder<T>;
+        };
+    }): SchemaCallbackProxy<T>;
+    getRawChanges(decoder: Decoder, callback: (changes: DataChange[]) => void): void;
+};
+export {};

package/lib/src/decoder/strategy/Callbacks.js

@@ -0,0 +1,336 @@
+import { Decoder } from "../Decoder";
+import { OPERATION } from "../../encoding/spec";
+import { Schema } from "../../Schema";
+import { $refId } from "../../types/symbols";
+import { getDecoderStateCallbacks } from "./getDecoderStateCallbacks";
+import { getRawChangesCallback } from "./RawChanges";
+/**
+ * State Callbacks handler
+ *
+ * Usage:
+ * ```ts
+ * const $ = Callbacks.get(decoder);
+ *
+ * // Listen to property changes
+ * $.listen("currentTurn", (currentValue, previousValue) => { ... });
+ *
+ * // Listen to collection additions
+ * $.onAdd("entities", (sessionId, entity) => {
+ *     // Nested property listening
+ *     $.listen(entity, "hp", (currentHp, previousHp) => { ... });
+ * });
+ *
+ * // Listen to collection removals
+ * $.onRemove("entities", (sessionId, entity) => { ... });
+ *
+ * // Listen to any property change on an instance
+ * $.onChange(entity, () => { ... });
+ *
+ * // Bind properties to another object
+ * $.bindTo(player, playerVisual);
+ * ```
+ */
+export class StateCallbackStrategy {
+    constructor(decoder) {
+        this.uniqueRefIds = new Set();
+        this.isTriggering = false;
+        this.decoder = decoder;
+        this.decoder.triggerChanges = this.triggerChanges.bind(this);
+    }
+    get callbacks() {
+        return this.decoder.root.callbacks;
+    }
+    get state() {
+        return this.decoder.state;
+    }
+    addCallback(refId, operationOrProperty, handler) {
+        const $root = this.decoder.root;
+        return $root.addCallback(refId, operationOrProperty, handler);
+    }
+    addCallbackOrWaitCollectionAvailable(instance, propertyName, operation, handler, immediate = true) {
+        let removeHandler = () => { };
+        const removeOnAdd = () => removeHandler();
+        const collection = instance[propertyName];
+        // Collection not available yet. Listen for its availability before attaching the handler.
+        if (collection === null || collection === undefined) {
+            removeHandler = this.addCallback(instance[$refId], propertyName, (value, _) => {
+                if (value !== null && value !== undefined) {
+                    removeHandler = this.addCallback(value[$refId], operation, handler);
+                }
+            });
+            return removeOnAdd;
+        }
+        else {
+            //
+            // Call immediately if collection is already available, if it's an ADD operation.
+            //
+            immediate = immediate && this.isTriggering === false;
+            if (operation === OPERATION.ADD && immediate) {
+                collection.forEach((value, key) => {
+                    handler(key, value);
+                });
+            }
+            return this.addCallback(collection[$refId], operation, handler);
+        }
+    }
+    listen(...args) {
+        if (typeof args[0] === 'string') {
+            // listen(property, handler, immediate?)
+            return this.listenInstance(this.state, args[0], args[1], args[2]);
+        }
+        else {
+            // listen(instance, property, handler, immediate?)
+            return this.listenInstance(args[0], args[1], args[2], args[3]);
+        }
+    }
+    listenInstance(instance, propertyName, handler, immediate = true) {
+        immediate = immediate && this.isTriggering === false;
+        //
+        // Call handler immediately if property is already available.
+        //
+        const currentValue = instance[propertyName];
+        if (immediate && currentValue !== null && currentValue !== undefined) {
+            handler(currentValue, undefined);
+        }
+        return this.addCallback(instance[$refId], propertyName, handler);
+    }
+    onChange(...args) {
+        if (args.length === 2 && typeof args[0] !== 'string') {
+            // onChange(instance, handler) - instance change
+            const instance = args[0];
+            const handler = args[1];
+            return this.addCallback(instance[$refId], OPERATION.REPLACE, handler);
+        }
+        if (typeof args[0] === 'string') {
+            // onChange(property, handler) - collection on root state
+            return this.addCallbackOrWaitCollectionAvailable(this.state, args[0], OPERATION.REPLACE, args[1]);
+        }
+        else {
+            // onChange(instance, property, handler) - nested collection
+            return this.addCallbackOrWaitCollectionAvailable(args[0], args[1], OPERATION.REPLACE, args[2]);
+        }
+    }
+    onAdd(...args) {
+        if (typeof args[0] === 'string') {
+            // onAdd(property, handler, immediate?) - collection on root state
+            return this.addCallbackOrWaitCollectionAvailable(this.state, args[0], OPERATION.ADD, args[1], args[2] !== false);
+        }
+        else {
+            // onAdd(instance, property, handler, immediate?) - nested collection
+            return this.addCallbackOrWaitCollectionAvailable(args[0], args[1], OPERATION.ADD, args[2], args[3] !== false);
+        }
+    }
+    onRemove(...args) {
+        if (typeof args[0] === 'string') {
+            // onRemove(property, handler) - collection on root state
+            return this.addCallbackOrWaitCollectionAvailable(this.state, args[0], OPERATION.DELETE, args[1]);
+        }
+        else {
+            // onRemove(instance, property, handler) - nested collection
+            return this.addCallbackOrWaitCollectionAvailable(args[0], args[1], OPERATION.DELETE, args[2]);
+        }
+    }
+    /**
+     * Bind properties from a Schema instance to a target object.
+     * Changes will be automatically reflected on the target object.
+     */
+    bindTo(from, to, properties, immediate = true) {
+        const metadata = from.constructor[Symbol.metadata];
+        // If no properties specified, bind all properties
+        if (!properties) {
+            properties = Object.keys(metadata)
+                .filter(key => !isNaN(Number(key)))
+                .map((index) => metadata[index].name);
+        }
+        const action = () => {
+            for (const prop of properties) {
+                const fromValue = from[prop];
+                if (fromValue !== undefined) {
+                    to[prop] = fromValue;
+                }
+            }
+        };
+        if (immediate) {
+            action();
+        }
+        return this.addCallback(from[$refId], OPERATION.REPLACE, action);
+    }
+    triggerChanges(allChanges) {
+        this.uniqueRefIds.clear();
+        for (let i = 0, l = allChanges.length; i < l; i++) {
+            const change = allChanges[i];
+            const refId = change.refId;
+            const ref = change.ref;
+            const $callbacks = this.callbacks[refId];
+            if (!$callbacks) {
+                continue;
+            }
+            //
+            // trigger onRemove on child structure.
+            //
+            if ((change.op & OPERATION.DELETE) === OPERATION.DELETE &&
+                change.previousValue instanceof Schema) {
+                const childRefId = change.previousValue[$refId];
+                const deleteCallbacks = this.callbacks[childRefId]?.[OPERATION.DELETE];
+                if (deleteCallbacks) {
+                    for (let j = deleteCallbacks.length - 1; j >= 0; j--) {
+                        deleteCallbacks[j]();
+                    }
+                }
+            }
+            if (ref instanceof Schema) {
+                //
+                // Handle Schema instance
+                //
+                if (!this.uniqueRefIds.has(refId)) {
+                    // trigger onChange
+                    const replaceCallbacks = $callbacks[OPERATION.REPLACE];
+                    if (replaceCallbacks) {
+                        for (let j = replaceCallbacks.length - 1; j >= 0; j--) {
+                            try {
+                                replaceCallbacks[j]();
+                            }
+                            catch (e) {
+                                console.error(e);
+                            }
+                        }
+                    }
+                }
+                // trigger field callbacks
+                const fieldCallbacks = $callbacks[change.field];
+                if (fieldCallbacks) {
+                    for (let j = fieldCallbacks.length - 1; j >= 0; j--) {
+                        try {
+                            this.isTriggering = true;
+                            fieldCallbacks[j](change.value, change.previousValue);
+                        }
+                        catch (e) {
+                            console.error(e);
+                        }
+                        finally {
+                            this.isTriggering = false;
+                        }
+                    }
+                }
+            }
+            else {
+                //
+                // Handle collection of items
+                //
+                const dynamicIndex = change.dynamicIndex ?? change.field;
+                if ((change.op & OPERATION.DELETE) === OPERATION.DELETE) {
+                    //
+                    // FIXME: `previousValue` should always be available.
+                    //
+                    if (change.previousValue !== undefined) {
+                        // trigger onRemove (key, value)
+                        const deleteCallbacks = $callbacks[OPERATION.DELETE];
+                        if (deleteCallbacks) {
+                            for (let j = deleteCallbacks.length - 1; j >= 0; j--) {
+                                deleteCallbacks[j](dynamicIndex, change.previousValue);
+                            }
+                        }
+                    }
+                    // Handle DELETE_AND_ADD operation
+                    if ((change.op & OPERATION.ADD) === OPERATION.ADD) {
+                        const addCallbacks = $callbacks[OPERATION.ADD];
+                        if (addCallbacks) {
+                            this.isTriggering = true;
+                            for (let j = addCallbacks.length - 1; j >= 0; j--) {
+                                addCallbacks[j](dynamicIndex, change.value);
+                            }
+                            this.isTriggering = false;
+                        }
+                    }
+                }
+                else if ((change.op & OPERATION.ADD) === OPERATION.ADD &&
+                    change.previousValue !== change.value) {
+                    // trigger onAdd (key, value)
+                    const addCallbacks = $callbacks[OPERATION.ADD];
+                    if (addCallbacks) {
+                        this.isTriggering = true;
+                        for (let j = addCallbacks.length - 1; j >= 0; j--) {
+                            addCallbacks[j](dynamicIndex, change.value);
+                        }
+                        this.isTriggering = false;
+                    }
+                }
+                // trigger onChange (key, value)
+                if (change.value !== change.previousValue) {
+                    const replaceCallbacks = $callbacks[OPERATION.REPLACE];
+                    if (replaceCallbacks) {
+                        for (let j = replaceCallbacks.length - 1; j >= 0; j--) {
+                            replaceCallbacks[j](dynamicIndex, change.value);
+                        }
+                    }
+                }
+            }
+            this.uniqueRefIds.add(refId);
+        }
+    }
+}
+/**
+ * Factory class for retrieving the callbacks API.
+ */
+export const Callbacks = {
+    /**
+     * Get the new callbacks standard API.
+     *
+     * Usage:
+     * ```ts
+     * const callbacks = Callbacks.get(roomOrDecoder);
+     *
+     * // Listen to property changes
+     * callbacks.listen("currentTurn", (currentValue, previousValue) => { ... });
+     *
+     * // Listen to collection additions
+     * callbacks.onAdd("entities", (sessionId, entity) => {
+     *     // Nested property listening
+     *     callbacks.listen(entity, "hp", (currentHp, previousHp) => { ... });
+     * });
+     *
+     * // Listen to collection removals
+     * callbacks.onRemove("entities", (sessionId, entity) => { ... });
+     *
+     * // Listen to any property change on an instance
+     * callbacks.onChange(entity, () => { ... });
+     *
+     * // Bind properties to another object
+     * callbacks.bindTo(player, playerVisual);
+     * ```
+     *
+     * @param roomOrDecoder - Room or Decoder instance to get the callbacks for.
+     * @returns the new callbacks standard API.
+     */
+    get(roomOrDecoder) {
+        if (roomOrDecoder instanceof Decoder) {
+            return new StateCallbackStrategy(roomOrDecoder);
+        }
+        else if (roomOrDecoder.serializer.decoder) {
+            return new StateCallbackStrategy(roomOrDecoder.serializer.decoder);
+        }
+        else {
+            throw new Error('Invalid room or decoder');
+        }
+    },
+    /**
+     * Get the legacy callbacks API.
+     *
+     * We aim to deprecate this API on 1.0, and iterate on improving Callbacks.get() API.
+     *
+     * @param roomOrDecoder - Room or Decoder instance to get the legacy callbacks for.
+     * @returns the legacy callbacks API.
+     */
+    getLegacy(roomOrDecoder) {
+        if (roomOrDecoder instanceof Decoder) {
+            return getDecoderStateCallbacks(roomOrDecoder);
+        }
+        else if (roomOrDecoder.serializer.decoder) {
+            return getDecoderStateCallbacks(roomOrDecoder.serializer.decoder);
+        }
+    },
+    getRawChanges(decoder, callback) {
+        return getRawChangesCallback(decoder, callback);
+    }
+};
+//# sourceMappingURL=Callbacks.js.map

package/lib/src/decoder/strategy/Callbacks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Callbacks.js","sourceRoot":"","sources":["../../../../src/decoder/strategy/Callbacks.ts"],"names":[],"mappings":"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","sourcesContent":["import { Metadata } from \"../../Metadata\";\nimport { Collection, NonFunctionPropNames } from \"../../types/HelperTypes\";\nimport { Ref } from \"../../encoder/ChangeTree\";\nimport { Decoder } from \"../Decoder\";\nimport { DataChange } from \"../DecodeOperation\";\nimport { OPERATION } from \"../../encoding/spec\";\nimport { Schema } from \"../../Schema\";\nimport { $refId } from \"../../types/symbols\";\nimport { MapSchema } from \"../../types/custom/MapSchema\";\nimport { ArraySchema } from \"../../types/custom/ArraySchema\";\nimport { getDecoderStateCallbacks, type SchemaCallbackProxy } from \"./getDecoderStateCallbacks\";\nimport { getRawChangesCallback } from \"./RawChanges\";\n\n//\n// C#-style Callbacks API\n// Matches the API from: https://docs.colyseus.io/state/callbacks\n//\n// Key features:\n// - Uses string property names with TypeScript auto-completion\n// - Consistent parameter order (key, value) for collection callbacks\n// - Overloaded methods for nested instance callbacks\n//\n\ntype PropertyChangeCallback<K> = (currentValue: K, previousValue: K) => void;\ntype KeyValueCallback<K, V> = (key: K, value: V) => void;\ntype InstanceChangeCallback = () => void;\n\n// Exclude internal properties from valid property names\ntype PublicPropNames<T> = Exclude<NonFunctionPropNames<T>, typeof $refId> & string;\n\n// Extract only properties that extend Collection\ntype CollectionPropNames<T> = Exclude<{\n    [K in keyof T]: T[K] extends Collection<any, any> ? K : never\n}[keyof T] & string, typeof $refId>;\n\n// Infer the value type of a collection property\ntype CollectionValueType<T, K extends keyof T> =\n    T[K] extends MapSchema<infer V, any> ? V :\n    T[K] extends ArraySchema<infer V> ? V :\n    T[K] extends Collection<any, infer V, any> ? V : never;\n\n// Infer the key type of a collection property\ntype CollectionKeyType<T, K extends keyof T> =\n    T[K] extends MapSchema<any, infer Key> ? Key :\n    T[K] extends ArraySchema<any> ? number :\n    T[K] extends Collection<infer Key, any, any> ? Key : never;\n\n/**\n * State Callbacks handler\n *\n * Usage:\n * ```ts\n * const $ = Callbacks.get(decoder);\n *\n * // Listen to property changes\n * $.listen(\"currentTurn\", (currentValue, previousValue) => { ... });\n *\n * // Listen to collection additions\n * $.onAdd(\"entities\", (sessionId, entity) => {\n *     // Nested property listening\n *     $.listen(entity, \"hp\", (currentHp, previousHp) => { ... });\n * });\n *\n * // Listen to collection removals\n * $.onRemove(\"entities\", (sessionId, entity) => { ... });\n *\n * // Listen to any property change on an instance\n * $.onChange(entity, () => { ... });\n *\n * // Bind properties to another object\n * $.bindTo(player, playerVisual);\n * ```\n */\nexport class StateCallbackStrategy<TState extends Schema> {\n    protected decoder: Decoder<TState>;\n    protected uniqueRefIds: Set<number> = new Set();\n    protected isTriggering: boolean = false;\n\n    constructor(decoder: Decoder<TState>) {\n        this.decoder = decoder;\n        this.decoder.triggerChanges = this.triggerChanges.bind(this);\n    }\n\n    protected get callbacks() {\n        return this.decoder.root.callbacks;\n    }\n\n    protected get state() {\n        return this.decoder.state;\n    }\n\n    protected addCallback(\n        refId: number,\n        operationOrProperty: OPERATION | string,\n        handler: Function\n    ): () => void {\n        const $root = this.decoder.root;\n        return $root.addCallback(refId, operationOrProperty, handler);\n    }\n\n    protected addCallbackOrWaitCollectionAvailable<TInstance extends Schema, TReturn extends Ref>(\n        instance: TInstance,\n        propertyName: string,\n        operation: OPERATION,\n        handler: Function,\n        immediate: boolean = true\n    ): () => void {\n        let removeHandler: () => void = () => {};\n        const removeOnAdd = () => removeHandler();\n\n        const collection = (instance as any)[propertyName] as TReturn;\n\n        // Collection not available yet. Listen for its availability before attaching the handler.\n        if (collection === null || collection === undefined) {\n            removeHandler = this.addCallback(\n                instance[$refId],\n                propertyName,\n                (value: TReturn, _: TReturn) => {\n                    if (value !== null && value !== undefined) {\n                        removeHandler = this.addCallback(value[$refId], operation, handler);\n                    }\n                }\n            );\n            return removeOnAdd;\n\n        } else {\n            //\n            // Call immediately if collection is already available, if it's an ADD operation.\n            //\n            immediate = immediate && this.isTriggering === false;\n\n            if (operation === OPERATION.ADD && immediate) {\n                (collection as Collection<any, any>).forEach((value: any, key: any) => {\n                    handler(key, value);\n                });\n            }\n\n            return this.addCallback(collection[$refId], operation, handler);\n        }\n    }\n\n    /**\n     * Listen to property changes on the root state.\n     */\n    listen<K extends PublicPropNames<TState>>(\n        property: K,\n        handler: PropertyChangeCallback<TState[K]>,\n        immediate?: boolean\n    ): () => void;\n\n    /**\n     * Listen to property changes on a nested instance.\n     */\n    listen<TInstance extends Schema, K extends PublicPropNames<TInstance>>(\n        instance: TInstance,\n        property: K,\n        handler: PropertyChangeCallback<TInstance[K]>,\n        immediate?: boolean\n    ): () => void;\n\n    listen(...args: any[]): () => void {\n        if (typeof args[0] === 'string') {\n            // listen(property, handler, immediate?)\n            return this.listenInstance(this.state, args[0], args[1], args[2]);\n        } else {\n            // listen(instance, property, handler, immediate?)\n            return this.listenInstance(args[0], args[1], args[2], args[3]);\n        }\n    }\n\n    protected listenInstance<TInstance extends Schema>(\n        instance: TInstance,\n        propertyName: string,\n        handler: PropertyChangeCallback<any>,\n        immediate: boolean = true\n    ): () => void {\n        immediate = immediate && this.isTriggering === false;\n\n        //\n        // Call handler immediately if property is already available.\n        //\n        const currentValue = (instance as any)[propertyName];\n        if (immediate && currentValue !== null && currentValue !== undefined) {\n            handler(currentValue, undefined as any);\n        }\n\n        return this.addCallback(instance[$refId], propertyName, handler);\n    }\n\n    /**\n     * Listen to any property change on an instance.\n     */\n    onChange<TInstance extends Schema>(\n        instance: TInstance,\n        handler: InstanceChangeCallback\n    ): () => void;\n\n    /**\n     * Listen to item changes in a collection on root state.\n     */\n    onChange<K extends CollectionPropNames<TState>>(\n        property: K,\n        handler: KeyValueCallback<CollectionKeyType<TState, K>, CollectionValueType<TState, K>>\n    ): () => void;\n\n    /**\n     * Listen to item changes in a nested collection.\n     */\n    onChange<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(\n        instance: TInstance,\n        property: K,\n        handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>\n    ): () => void;\n\n    onChange(...args: any[]): () => void {\n        if (args.length === 2 && typeof args[0] !== 'string') {\n            // onChange(instance, handler) - instance change\n            const instance = args[0] as Schema;\n            const handler = args[1] as InstanceChangeCallback;\n            return this.addCallback(instance[$refId], OPERATION.REPLACE, handler);\n        }\n\n        if (typeof args[0] === 'string') {\n            // onChange(property, handler) - collection on root state\n            return this.addCallbackOrWaitCollectionAvailable(\n                this.state,\n                args[0],\n                OPERATION.REPLACE,\n                args[1]\n            );\n        } else {\n            // onChange(instance, property, handler) - nested collection\n            return this.addCallbackOrWaitCollectionAvailable(\n                args[0],\n                args[1],\n                OPERATION.REPLACE,\n                args[2]\n            );\n        }\n    }\n\n    /**\n     * Listen to items added to a collection on root state.\n     */\n    onAdd<K extends CollectionPropNames<TState>>(\n        property: K,\n        handler: KeyValueCallback<CollectionKeyType<TState, K>, CollectionValueType<TState, K>>,\n        immediate?: boolean\n    ): () => void;\n\n    /**\n     * Listen to items added to a nested collection.\n     */\n    onAdd<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(\n        instance: TInstance,\n        property: K,\n        handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>,\n        immediate?: boolean\n    ): () => void;\n\n    onAdd(...args: any[]): () => void {\n        if (typeof args[0] === 'string') {\n            // onAdd(property, handler, immediate?) - collection on root state\n            return this.addCallbackOrWaitCollectionAvailable(\n                this.state,\n                args[0],\n                OPERATION.ADD,\n                args[1],\n                args[2] !== false\n            );\n        } else {\n            // onAdd(instance, property, handler, immediate?) - nested collection\n            return this.addCallbackOrWaitCollectionAvailable(\n                args[0],\n                args[1],\n                OPERATION.ADD,\n                args[2],\n                args[3] !== false\n            );\n        }\n    }\n\n    /**\n     * Listen to items removed from a collection on root state.\n     */\n    onRemove<K extends CollectionPropNames<TState>>(\n        property: K,\n        handler: KeyValueCallback<CollectionKeyType<TState, K>, CollectionValueType<TState, K>>\n    ): () => void;\n\n    /**\n     * Listen to items removed from a nested collection.\n     */\n    onRemove<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(\n        instance: TInstance,\n        property: K,\n        handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>\n    ): () => void;\n\n    onRemove(...args: any[]): () => void {\n        if (typeof args[0] === 'string') {\n            // onRemove(property, handler) - collection on root state\n            return this.addCallbackOrWaitCollectionAvailable(\n                this.state,\n                args[0],\n                OPERATION.DELETE,\n                args[1]\n            );\n        } else {\n            // onRemove(instance, property, handler) - nested collection\n            return this.addCallbackOrWaitCollectionAvailable(\n                args[0],\n                args[1],\n                OPERATION.DELETE,\n                args[2]\n            );\n        }\n    }\n\n    /**\n     * Bind properties from a Schema instance to a target object.\n     * Changes will be automatically reflected on the target object.\n     */\n    bindTo<TInstance extends Schema, TTarget>(\n        from: TInstance,\n        to: TTarget,\n        properties?: string[],\n        immediate: boolean = true\n    ): () => void {\n        const metadata: Metadata = (from.constructor as typeof Schema)[Symbol.metadata];\n\n        // If no properties specified, bind all properties\n        if (!properties) {\n            properties = Object.keys(metadata)\n                .filter(key => !isNaN(Number(key)))\n                .map((index) => metadata[index as any as number].name);\n        }\n\n        const action = () => {\n            for (const prop of properties!) {\n                const fromValue = (from as any)[prop];\n                if (fromValue !== undefined) {\n                    (to as any)[prop] = fromValue;\n                }\n            }\n        };\n\n        if (immediate) {\n            action();\n        }\n\n        return this.addCallback(from[$refId], OPERATION.REPLACE, action);\n    }\n\n    protected triggerChanges(allChanges: DataChange[]): void {\n        this.uniqueRefIds.clear();\n\n        for (let i = 0, l = allChanges.length; i < l; i++) {\n            const change = allChanges[i];\n            const refId = change.refId;\n            const ref = change.ref;\n\n            const $callbacks = this.callbacks[refId];\n            if (!$callbacks) {\n                continue;\n            }\n\n            //\n            // trigger onRemove on child structure.\n            //\n            if (\n                (change.op & OPERATION.DELETE) === OPERATION.DELETE &&\n                change.previousValue instanceof Schema\n            ) {\n                const childRefId = (change.previousValue as Ref)[$refId];\n                const deleteCallbacks = this.callbacks[childRefId]?.[OPERATION.DELETE];\n                if (deleteCallbacks) {\n                    for (let j = deleteCallbacks.length - 1; j >= 0; j--) {\n                        deleteCallbacks[j]();\n                    }\n                }\n            }\n\n            if (ref instanceof Schema) {\n                //\n                // Handle Schema instance\n                //\n\n                if (!this.uniqueRefIds.has(refId)) {\n                    // trigger onChange\n                    const replaceCallbacks = $callbacks[OPERATION.REPLACE];\n                    if (replaceCallbacks) {\n                        for (let j = replaceCallbacks.length - 1; j >= 0; j--) {\n                            try {\n                                replaceCallbacks[j]();\n                            } catch (e) {\n                                console.error(e);\n                            }\n                        }\n                    }\n                }\n\n                // trigger field callbacks\n                const fieldCallbacks = $callbacks[change.field];\n                if (fieldCallbacks) {\n                    for (let j = fieldCallbacks.length - 1; j >= 0; j--) {\n                        try {\n                            this.isTriggering = true;\n                            fieldCallbacks[j](change.value, change.previousValue);\n                        } catch (e) {\n                            console.error(e);\n                        } finally {\n                            this.isTriggering = false;\n                        }\n                    }\n                }\n\n            } else {\n                //\n                // Handle collection of items\n                //\n                const dynamicIndex = change.dynamicIndex ?? change.field;\n\n                if ((change.op & OPERATION.DELETE) === OPERATION.DELETE) {\n                    //\n                    // FIXME: `previousValue` should always be available.\n                    //\n                    if (change.previousValue !== undefined) {\n                        // trigger onRemove (key, value)\n                        const deleteCallbacks = $callbacks[OPERATION.DELETE];\n                        if (deleteCallbacks) {\n                            for (let j = deleteCallbacks.length - 1; j >= 0; j--) {\n                                deleteCallbacks[j](dynamicIndex, change.previousValue);\n                            }\n                        }\n                    }\n\n                    // Handle DELETE_AND_ADD operation\n                    if ((change.op & OPERATION.ADD) === OPERATION.ADD) {\n                        const addCallbacks = $callbacks[OPERATION.ADD];\n                        if (addCallbacks) {\n                            this.isTriggering = true;\n                            for (let j = addCallbacks.length - 1; j >= 0; j--) {\n                                addCallbacks[j](dynamicIndex, change.value);\n                            }\n                            this.isTriggering = false;\n                        }\n                    }\n\n                } else if (\n                    (change.op & OPERATION.ADD) === OPERATION.ADD &&\n                    change.previousValue !== change.value\n                ) {\n                    // trigger onAdd (key, value)\n                    const addCallbacks = $callbacks[OPERATION.ADD];\n                    if (addCallbacks) {\n                        this.isTriggering = true;\n                        for (let j = addCallbacks.length - 1; j >= 0; j--) {\n                            addCallbacks[j](dynamicIndex, change.value);\n                        }\n                        this.isTriggering = false;\n                    }\n                }\n\n                // trigger onChange (key, value)\n                if (change.value !== change.previousValue) {\n                    const replaceCallbacks = $callbacks[OPERATION.REPLACE];\n                    if (replaceCallbacks) {\n                        for (let j = replaceCallbacks.length - 1; j >= 0; j--) {\n                            replaceCallbacks[j](dynamicIndex, change.value);\n                        }\n                    }\n                }\n            }\n\n            this.uniqueRefIds.add(refId);\n        }\n    }\n}\n\n/**\n * Factory class for retrieving the callbacks API.\n */\nexport const Callbacks = {\n    /**\n     * Get the new callbacks standard API.\n     *\n     * Usage:\n     * ```ts\n     * const callbacks = Callbacks.get(roomOrDecoder);\n     *\n     * // Listen to property changes\n     * callbacks.listen(\"currentTurn\", (currentValue, previousValue) => { ... });\n     *\n     * // Listen to collection additions\n     * callbacks.onAdd(\"entities\", (sessionId, entity) => {\n     *     // Nested property listening\n     *     callbacks.listen(entity, \"hp\", (currentHp, previousHp) => { ... });\n     * });\n     *\n     * // Listen to collection removals\n     * callbacks.onRemove(\"entities\", (sessionId, entity) => { ... });\n     *\n     * // Listen to any property change on an instance\n     * callbacks.onChange(entity, () => { ... });\n     *\n     * // Bind properties to another object\n     * callbacks.bindTo(player, playerVisual);\n     * ```\n     *\n     * @param roomOrDecoder - Room or Decoder instance to get the callbacks for.\n     * @returns the new callbacks standard API.\n     */\n    get<T extends Schema>(roomOrDecoder: Decoder<T> | { serializer: { decoder: Decoder<T> } }): StateCallbackStrategy<T> {\n        if (roomOrDecoder instanceof Decoder) {\n            return new StateCallbackStrategy<T>(roomOrDecoder);\n\n        } else if (roomOrDecoder.serializer.decoder) {\n            return new StateCallbackStrategy<T>(roomOrDecoder.serializer.decoder);\n\n        } else {\n            throw new Error('Invalid room or decoder');\n        }\n    },\n\n    /**\n     * Get the legacy callbacks API.\n     *\n     * We aim to deprecate this API on 1.0, and iterate on improving Callbacks.get() API.\n     *\n     * @param roomOrDecoder - Room or Decoder instance to get the legacy callbacks for.\n     * @returns the legacy callbacks API.\n     */\n    getLegacy<T extends Schema>(roomOrDecoder: Decoder<T> | { serializer: { decoder: Decoder<T> } }): SchemaCallbackProxy<T> {\n        if (roomOrDecoder instanceof Decoder) {\n            return getDecoderStateCallbacks(roomOrDecoder);\n\n        } else if (roomOrDecoder.serializer.decoder) {\n            return getDecoderStateCallbacks(roomOrDecoder.serializer.decoder);\n        }\n    },\n\n    getRawChanges(decoder: Decoder, callback: (changes: DataChange[]) => void) {\n        return getRawChangesCallback(decoder, callback);\n    }\n};\n\n"]}

package/lib/src/decoder/strategy/RawChanges.d.ts

@@ -0,0 +1,3 @@
+import { DataChange } from "../DecodeOperation";
+import { Decoder } from "../Decoder";
+export declare function getRawChangesCallback(decoder: Decoder, callback: (changes: DataChange[]) => void): void;

package/lib/src/decoder/strategy/RawChanges.js

@@ -0,0 +1,4 @@
+export function getRawChangesCallback(decoder, callback) {
+    decoder.triggerChanges = callback;
+}
+//# sourceMappingURL=RawChanges.js.map

package/lib/src/decoder/strategy/RawChanges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RawChanges.js","sourceRoot":"","sources":["../../../../src/decoder/strategy/RawChanges.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,qBAAqB,CACjC,OAAgB,EAChB,QAAyC;IAEzC,OAAO,CAAC,cAAc,GAAG,QAAQ,CAAC;AACtC,CAAC","sourcesContent":["import { DataChange } from \"../DecodeOperation\";\nimport { Decoder } from \"../Decoder\";\n\nexport function getRawChangesCallback(\n    decoder: Decoder,\n    callback: (changes: DataChange[]) => void\n) {\n    decoder.triggerChanges = callback;\n}"]}

package/lib/src/decoder/strategy/getDecoderStateCallbacks.d.ts

@@ -0,0 +1,76 @@
+import { Collection, NonFunctionNonPrimitivePropNames, NonFunctionPropNames } from "../../types/HelperTypes";
+import { Decoder } from "../Decoder";
+import { Schema } from "../../Schema";
+/**
+ * TODO: define a schema interface, which even having duplicate definitions, it could be used to get the callback proxy.
+ *
+ * ```ts
+ *     export type SchemaCallbackProxy<RoomState> = (<T extends Schema>(instance: T) => CallbackProxy<T>);
+ * ```
+ */
+export type SchemaCallbackProxy<RoomState> = (<T>(instance: T) => CallbackProxy<T>);
+export type GetCallbackProxy = SchemaCallbackProxy<any>;
+export type CallbackProxy<T> = unknown extends T ? SchemaCallback<T> & CollectionCallback<any, any> : T extends Collection<infer K, infer V, infer _> ? CollectionCallback<K, V> : SchemaCallback<T>;
+export type SchemaCallback<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): () => 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>]: CallbackProxy<T[K]>;
+};
+export type CollectionCallback<K, V> = {
+    /**
+     * 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 the value on a key has changed.
+     *
+     * THIS METHOD IS NOT RECURSIVE!
+     * If you want to listen to changes on individual items, you need to attach callbacks to the them directly inside the `onAdd` callback.
+     *
+     * @param callback
+     * @return callback to detach the onChange listener
+     */
+    onChange(callback: (item: V, index: K) => void): () => void;
+};
+/**
+ * Legacy callback system
+ *
+ * @param decoder
+ * @returns
+ */
+export declare function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>): SchemaCallbackProxy<T>;