@colyseus/schema 3.0.75 → 4.0.0

package/src/decoder/strategy/Callbacks.ts

@@ -0,0 +1,547 @@
+import { Metadata } from "../../Metadata";
+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 { getDecoderStateCallbacks, type SchemaCallbackProxy } from "./getDecoderStateCallbacks";
+import { getRawChangesCallback } from "./RawChanges";
+
+//
+// C#-style Callbacks API
+// Matches the API from: https://docs.colyseus.io/state/callbacks
+//
+// Key features:
+// - Uses string property names with TypeScript auto-completion
+// - Consistent parameter order (key, value) for collection callbacks
+// - Overloaded methods for nested instance callbacks
+//
+
+type PropertyChangeCallback<K> = (currentValue: K, previousValue: K) => void;
+type KeyValueCallback<K, V> = (key: K, value: V) => void;
+type InstanceChangeCallback = () => void;
+
+// Exclude internal properties from valid property names
+type PublicPropNames<T> = Exclude<NonFunctionPropNames<T>, typeof $refId> & string;
+
+// Extract only properties that extend Collection
+type CollectionPropNames<T> = Exclude<{
+    [K in keyof T]: T[K] extends Collection<any, any> ? K : never
+}[keyof T] & string, typeof $refId>;
+
+// Infer the value type of a collection property
+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;
+
+// Infer the key type of a collection property
+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 class StateCallbackStrategy<TState extends Schema> {
+    protected decoder: Decoder<TState>;
+    protected uniqueRefIds: Set<number> = new Set();
+    protected isTriggering: boolean = false;
+
+    constructor(decoder: Decoder<TState>) {
+        this.decoder = decoder;
+        this.decoder.triggerChanges = this.triggerChanges.bind(this);
+    }
+
+    protected get callbacks() {
+        return this.decoder.root.callbacks;
+    }
+
+    protected get state() {
+        return this.decoder.state;
+    }
+
+    protected addCallback(
+        refId: number,
+        operationOrProperty: OPERATION | string,
+        handler: Function
+    ): () => void {
+        const $root = this.decoder.root;
+        return $root.addCallback(refId, operationOrProperty, handler);
+    }
+
+    protected addCallbackOrWaitCollectionAvailable<TInstance extends Schema, TReturn extends Ref>(
+        instance: TInstance,
+        propertyName: string,
+        operation: OPERATION,
+        handler: Function,
+        immediate: boolean = true
+    ): () => void {
+        let removeHandler: () => void = () => {};
+        const removeOnAdd = () => removeHandler();
+
+        const collection = (instance as any)[propertyName] as TReturn;
+
+        // Collection not available yet. Listen for its availability before attaching the handler.
+        if (collection === null || collection === undefined) {
+            removeHandler = this.addCallback(
+                instance[$refId],
+                propertyName,
+                (value: TReturn, _: TReturn) => {
+                    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 as Collection<any, any>).forEach((value: any, key: any) => {
+                    handler(key, value);
+                });
+            }
+
+            return this.addCallback(collection[$refId], operation, handler);
+        }
+    }
+
+    /**
+     * 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;
+
+    listen(...args: any[]): () => void {
+        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]);
+        }
+    }
+
+    protected listenInstance<TInstance extends Schema>(
+        instance: TInstance,
+        propertyName: string,
+        handler: PropertyChangeCallback<any>,
+        immediate: boolean = true
+    ): () => void {
+        immediate = immediate && this.isTriggering === false;
+
+        //
+        // Call handler immediately if property is already available.
+        //
+        const currentValue = (instance as any)[propertyName];
+        if (immediate && currentValue !== null && currentValue !== undefined) {
+            handler(currentValue, undefined as any);
+        }
+
+        return this.addCallback(instance[$refId], propertyName, handler);
+    }
+
+    /**
+     * 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;
+
+    onChange(...args: any[]): () => void {
+        if (args.length === 2 && typeof args[0] !== 'string') {
+            // onChange(instance, handler) - instance change
+            const instance = args[0] as Schema;
+            const handler = args[1] as InstanceChangeCallback;
+            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]
+            );
+        }
+    }
+
+    /**
+     * 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;
+
+    onAdd(...args: any[]): () => void {
+        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
+            );
+        }
+    }
+
+    /**
+     * 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;
+
+    onRemove(...args: any[]): () => void {
+        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<TInstance extends Schema, TTarget>(
+        from: TInstance,
+        to: TTarget,
+        properties?: string[],
+        immediate: boolean = true
+    ): () => void {
+        const metadata: Metadata = (from.constructor as typeof Schema)[Symbol.metadata];
+
+        // If no properties specified, bind all properties
+        if (!properties) {
+            properties = Object.keys(metadata)
+                .filter(key => !isNaN(Number(key)))
+                .map((index) => metadata[index as any as number].name);
+        }
+
+        const action = () => {
+            for (const prop of properties!) {
+                const fromValue = (from as any)[prop];
+                if (fromValue !== undefined) {
+                    (to as any)[prop] = fromValue;
+                }
+            }
+        };
+
+        if (immediate) {
+            action();
+        }
+
+        return this.addCallback(from[$refId], OPERATION.REPLACE, action);
+    }
+
+    protected triggerChanges(allChanges: DataChange[]): void {
+        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 as Ref)[$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<T extends Schema>(roomOrDecoder: Decoder<T> | { serializer: { decoder: Decoder<T> } }): StateCallbackStrategy<T> {
+        if (roomOrDecoder instanceof Decoder) {
+            return new StateCallbackStrategy<T>(roomOrDecoder);
+
+        } else if (roomOrDecoder.serializer.decoder) {
+            return new StateCallbackStrategy<T>(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<T extends Schema>(roomOrDecoder: Decoder<T> | { serializer: { decoder: Decoder<T> } }): SchemaCallbackProxy<T> {
+        if (roomOrDecoder instanceof Decoder) {
+            return getDecoderStateCallbacks(roomOrDecoder);
+
+        } else if (roomOrDecoder.serializer.decoder) {
+            return getDecoderStateCallbacks(roomOrDecoder.serializer.decoder);
+        }
+    },
+
+    getRawChanges(decoder: Decoder, callback: (changes: DataChange[]) => void) {
+        return getRawChangesCallback(decoder, callback);
+    }
+};
+

package/src/decoder/strategy/{StateCallbacks.ts → getDecoderStateCallbacks.ts}

@@ -1,10 +1,11 @@
 import { Metadata } from "../../Metadata";
 import { Collection, NonFunctionNonPrimitivePropNames, NonFunctionPropNames } from "../../types/HelperTypes";
-import { Ref } from "../../encoder/ChangeTree";
+import { IRef, 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 type { DefinitionType } from "../../annotations";
 import type { CollectionSchema } from "../../types/custom/CollectionSchema";
 
@@ -107,7 +108,12 @@ type CallContext = {
     onInstanceAvailable?: OnInstanceAvailableCallback,
 }
 
-
+/**
+ * Legacy callback system
+ *
+ * @param decoder
+ * @returns
+ */
 export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>): SchemaCallbackProxy<T> {
     const $root = decoder.root;
     const callbacks = $root.callbacks;
@@ -133,7 +139,7 @@ export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>):
                 (change.op & OPERATION.DELETE) === OPERATION.DELETE &&
                 change.previousValue instanceof Schema
             ) {
-                const deleteCallbacks = callbacks[$root.refIds.get(change.previousValue)]?.[OPERATION.DELETE];
+                const deleteCallbacks = callbacks[(change.previousValue as Ref)[$refId]]?.[OPERATION.DELETE];
                 for (let i = deleteCallbacks?.length - 1; i >= 0; i--) {
                     deleteCallbacks[i]();
                 }
@@ -247,7 +253,7 @@ export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>):
                 ) {
                     callback(context.instance[prop], undefined);
                 }
-                return $root.addCallback($root.refIds.get(ref), prop, callback);
+                return $root.addCallback(ref[$refId], prop, callback);
             }
 
             /**
@@ -272,7 +278,7 @@ export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>):
 
                 onChange: function onChange(callback: () => void) {
                     return $root.addCallback(
-                        $root.refIds.get(context.instance),
+                        context.instance[$refId],
                         OPERATION.REPLACE,
                         callback
                     );
@@ -287,7 +293,7 @@ export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>):
                         properties = Object.keys(metadata).map((index) => metadata[index as any as number].name);
                     }
                     return $root.addCallback(
-                        $root.refIds.get(context.instance),
+                        context.instance[$refId],
                         OPERATION.REPLACE,
                         () => {
                             properties.forEach((prop) =>
@@ -313,7 +319,7 @@ export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>):
                                 }, false);
 
                                 // has existing value
-                                if ($root.refIds.get(instance) !== undefined) {
+                                if (instance?.[$refId] !== undefined) {
                                     callback(instance, true);
                                 }
                             }
@@ -321,7 +327,7 @@ export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>):
 
                         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),
+                            instance: (instance?.[$refId] !== undefined && instance),
                             parentInstance: context.instance,
                             onInstanceAvailable,
                         });
@@ -347,7 +353,7 @@ export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>):
                     (ref as CollectionSchema).forEach((v, k) => callback(v, k));
                 }
 
-                return $root.addCallback($root.refIds.get(ref), OPERATION.ADD, (value: any, key: any) => {
+                return $root.addCallback(ref[$refId], OPERATION.ADD, (value: any, key: any) => {
                     onAddCalls.set(callback, true);
                     currentOnAddCallback = callback;
                     callback(value, key);
@@ -357,11 +363,11 @@ export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>):
             };
 
             const onRemove = function (ref: Ref, callback: (value: any, key: any) => void) {
-                return $root.addCallback($root.refIds.get(ref), OPERATION.DELETE, callback);
+                return $root.addCallback(ref[$refId], OPERATION.DELETE, callback);
             };
 
             const onChange = function (ref: Ref, callback: (value: any, key: any) => void) {
-                return $root.addCallback($root.refIds.get(ref), OPERATION.REPLACE, callback);
+                return $root.addCallback(ref[$refId], OPERATION.REPLACE, callback);
             };
 
             return new Proxy({

package/src/encoder/ChangeTree.ts

@@ -1,6 +1,6 @@
 import { OPERATION } from "../encoding/spec";
 import { Schema } from "../Schema";
-import { $changes, $childType, $decoder, $onEncodeEnd, $encoder, $getByIndex, $refTypeFieldIndexes, $viewFieldIndexes, type $deleteByIndex } from "../types/symbols";
+import { $changes, $childType, $decoder, $onEncodeEnd, $encoder, $getByIndex, $refId, $refTypeFieldIndexes, $viewFieldIndexes, type $deleteByIndex } from "../types/symbols";
 
 import type { MapSchema } from "../types/custom/MapSchema";
 import type { ArraySchema } from "../types/custom/ArraySchema";
@@ -16,6 +16,7 @@ declare global {
     interface Object {
         // FIXME: not a good practice to extend globals here
         [$changes]?: ChangeTree;
+        // [$refId]?: number;
         [$encoder]?: EncodeOperation,
         [$decoder]?: DecodeOperation,
     }
@@ -23,15 +24,12 @@ declare global {
 
 export interface IRef {
     [$changes]?: ChangeTree;
+    [$refId]?: number;
     [$getByIndex]?: (index: number, isEncodeAll?: boolean) => any;
     [$deleteByIndex]?: (index: number) => void;
 }
 
-export type Ref = Schema
-    | ArraySchema
-    | MapSchema
-    | CollectionSchema
-    | SetSchema;
+export type Ref = Schema | ArraySchema | MapSchema | CollectionSchema | SetSchema;
 
 export type ChangeSetName = "changes"
     | "allChanges"
@@ -126,7 +124,6 @@ export interface ParentChain {
 
 export class ChangeTree<T extends Ref = any> {
     ref: T;
-    refId: number;
     metadata: Metadata;
 
     root?: Root;