@colyseus/schema 4.0.1 → 4.0.2

package/lib/src/Reflection.js

@@ -0,0 +1,179 @@
+import { schema } from "./annotations";
+import { TypeContext } from "./types/TypeContext";
+import { Metadata } from "./Metadata";
+import { Encoder } from "./encoder/Encoder";
+import { Decoder } from "./decoder/Decoder";
+import { Schema } from "./Schema";
+/**
+ * Reflection
+ */
+export const ReflectionField = schema({
+    name: "string",
+    type: "string",
+    referencedType: "number",
+});
+export const ReflectionType = schema({
+    id: "number",
+    extendsId: "number",
+    fields: [ReflectionField],
+});
+export const Reflection = schema({
+    types: [ReflectionType],
+    rootType: "number",
+});
+Reflection.encode = function (encoder, it = { offset: 0 }) {
+    const context = encoder.context;
+    const reflection = new Reflection();
+    const reflectionEncoder = new Encoder(reflection);
+    // rootType is usually the first schema passed to the Encoder
+    // (unless it inherits from another schema)
+    const rootType = context.schemas.get(encoder.state.constructor);
+    if (rootType > 0) {
+        reflection.rootType = rootType;
+    }
+    const includedTypeIds = new Set();
+    const pendingReflectionTypes = {};
+    // add type to reflection in a way that respects inheritance
+    // (parent types should be added before their children)
+    const addType = (type) => {
+        if (type.extendsId === undefined || includedTypeIds.has(type.extendsId)) {
+            includedTypeIds.add(type.id);
+            reflection.types.push(type);
+            const deps = pendingReflectionTypes[type.id];
+            if (deps !== undefined) {
+                delete pendingReflectionTypes[type.id];
+                deps.forEach((childType) => addType(childType));
+            }
+        }
+        else {
+            if (pendingReflectionTypes[type.extendsId] === undefined) {
+                pendingReflectionTypes[type.extendsId] = [];
+            }
+            pendingReflectionTypes[type.extendsId].push(type);
+        }
+    };
+    context.schemas.forEach((typeid, klass) => {
+        const type = new ReflectionType();
+        type.id = Number(typeid);
+        // support inheritance
+        const inheritFrom = Object.getPrototypeOf(klass);
+        if (inheritFrom !== Schema) {
+            type.extendsId = context.schemas.get(inheritFrom);
+        }
+        const metadata = klass[Symbol.metadata];
+        //
+        // FIXME: this is a workaround for inherited types without additional fields
+        // if metadata is the same reference as the parent class - it means the class has no own metadata
+        //
+        if (metadata !== inheritFrom[Symbol.metadata]) {
+            for (const fieldIndex in metadata) {
+                const index = Number(fieldIndex);
+                const fieldName = metadata[index].name;
+                // skip fields from parent classes
+                if (!Object.prototype.hasOwnProperty.call(metadata, fieldName)) {
+                    continue;
+                }
+                const reflectionField = new ReflectionField();
+                reflectionField.name = fieldName;
+                let fieldType;
+                const field = metadata[index];
+                if (typeof (field.type) === "string") {
+                    fieldType = field.type;
+                }
+                else {
+                    let childTypeSchema;
+                    //
+                    // TODO: refactor below.
+                    //
+                    if (Schema.is(field.type)) {
+                        fieldType = "ref";
+                        childTypeSchema = field.type;
+                    }
+                    else {
+                        fieldType = Object.keys(field.type)[0];
+                        if (typeof (field.type[fieldType]) === "string") {
+                            fieldType += ":" + field.type[fieldType]; // array:string
+                        }
+                        else {
+                            childTypeSchema = field.type[fieldType];
+                        }
+                    }
+                    reflectionField.referencedType = (childTypeSchema)
+                        ? context.getTypeId(childTypeSchema)
+                        : -1;
+                }
+                reflectionField.type = fieldType;
+                type.fields.push(reflectionField);
+            }
+        }
+        addType(type);
+    });
+    // in case there are types that were not added due to inheritance
+    for (const typeid in pendingReflectionTypes) {
+        pendingReflectionTypes[typeid].forEach((type) => reflection.types.push(type));
+    }
+    const buf = reflectionEncoder.encodeAll(it);
+    return buf.slice(0, it.offset);
+};
+Reflection.decode = function (bytes, it) {
+    const reflection = new Reflection();
+    const reflectionDecoder = new Decoder(reflection);
+    reflectionDecoder.decode(bytes, it);
+    const typeContext = new TypeContext();
+    // 1st pass, initialize metadata + inheritance
+    reflection.types.forEach((reflectionType) => {
+        const parentClass = typeContext.get(reflectionType.extendsId) ?? Schema;
+        const schema = class _ extends parentClass {
+        };
+        // register for inheritance support
+        TypeContext.register(schema);
+        typeContext.add(schema, reflectionType.id);
+    }, {});
+    // define fields
+    const addFields = (metadata, reflectionType, parentFieldIndex) => {
+        reflectionType.fields.forEach((field, i) => {
+            const fieldIndex = parentFieldIndex + i;
+            if (field.referencedType !== undefined) {
+                let fieldType = field.type;
+                let refType = typeContext.get(field.referencedType);
+                // map or array of primitive type (-1)
+                if (!refType) {
+                    const typeInfo = field.type.split(":");
+                    fieldType = typeInfo[0];
+                    refType = typeInfo[1]; // string
+                }
+                if (fieldType === "ref") {
+                    Metadata.addField(metadata, fieldIndex, field.name, refType);
+                }
+                else {
+                    Metadata.addField(metadata, fieldIndex, field.name, { [fieldType]: refType });
+                }
+            }
+            else {
+                Metadata.addField(metadata, fieldIndex, field.name, field.type);
+            }
+        });
+    };
+    // 2nd pass, set fields
+    reflection.types.forEach((reflectionType) => {
+        const schema = typeContext.get(reflectionType.id);
+        // for inheritance support
+        const metadata = Metadata.initialize(schema);
+        const inheritedTypes = [];
+        let parentType = reflectionType;
+        do {
+            inheritedTypes.push(parentType);
+            parentType = reflection.types.find((t) => t.id === parentType.extendsId);
+        } while (parentType);
+        let parentFieldIndex = 0;
+        inheritedTypes.reverse().forEach((reflectionType) => {
+            // add fields from all inherited classes
+            // TODO: refactor this to avoid adding fields from parent classes
+            addFields(metadata, reflectionType, parentFieldIndex);
+            parentFieldIndex += reflectionType.fields.length;
+        });
+    });
+    const state = new (typeContext.get(reflection.rootType || 0))();
+    return new Decoder(state, typeContext);
+};
+//# sourceMappingURL=Reflection.js.map

package/lib/src/Reflection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Reflection.js","sourceRoot":"","sources":["../../src/Reflection.ts"],"names":[],"mappings":"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","sourcesContent":["import { PrimitiveType, schema, SchemaType } from \"./annotations\";\nimport { TypeContext } from \"./types/TypeContext\";\nimport { Metadata } from \"./Metadata\";\nimport { Iterator } from \"./encoding/decode\";\nimport { Encoder } from \"./encoder/Encoder\";\nimport { Decoder } from \"./decoder/Decoder\";\nimport { Schema } from \"./Schema\";\n\n/**\n * Static methods available on Reflection\n */\ninterface ReflectionStatic {\n    /**\n     * Encodes the TypeContext of an Encoder into a buffer.\n     *\n     * @param encoder Encoder instance\n     * @param it\n     * @returns\n     */\n    encode: (encoder: Encoder, it?: Iterator) => Uint8Array;\n\n    /**\n     * Decodes the TypeContext from a buffer into a Decoder instance.\n     *\n     * @param bytes Reflection.encode() output\n     * @param it\n     * @returns Decoder instance\n     */\n    decode: <T extends Schema = Schema>(bytes: Uint8Array, it?: Iterator) => Decoder<T>;\n}\n\n/**\n * Reflection\n */\nexport const ReflectionField = schema({\n    name: \"string\",\n    type: \"string\",\n    referencedType: \"number\",\n})\nexport type ReflectionField = SchemaType<typeof ReflectionField>;\n\nexport const ReflectionType = schema({\n    id: \"number\",\n    extendsId: \"number\",\n    fields: [ ReflectionField ],\n})\nexport type ReflectionType = SchemaType<typeof ReflectionType>;\n\nexport const Reflection = schema({\n    types: [ ReflectionType ],\n    rootType: \"number\",\n}) as ReturnType<typeof schema<{\n    types: [typeof ReflectionType];\n    rootType: \"number\";\n}>> & ReflectionStatic;\n\nexport type Reflection = SchemaType<typeof Reflection>;\n\nReflection.encode = function (encoder: Encoder, it: Iterator = { offset: 0 }) {\n    const context = encoder.context;\n\n    const reflection = new Reflection();\n    const reflectionEncoder = new Encoder(reflection);\n\n    // rootType is usually the first schema passed to the Encoder\n    // (unless it inherits from another schema)\n    const rootType = context.schemas.get(encoder.state.constructor);\n    if (rootType > 0) { reflection.rootType = rootType; }\n\n    const includedTypeIds = new Set<number>();\n    const pendingReflectionTypes: { [typeid: number]: ReflectionType[] } = {};\n\n    // add type to reflection in a way that respects inheritance\n    // (parent types should be added before their children)\n    const addType = (type: ReflectionType) => {\n        if (type.extendsId === undefined || includedTypeIds.has(type.extendsId)) {\n            includedTypeIds.add(type.id);\n\n            reflection.types.push(type);\n\n            const deps = pendingReflectionTypes[type.id];\n            if (deps !== undefined) {\n                delete pendingReflectionTypes[type.id];\n                deps.forEach((childType) => addType(childType));\n            }\n        } else {\n            if (pendingReflectionTypes[type.extendsId] === undefined) {\n                pendingReflectionTypes[type.extendsId] = [];\n            }\n            pendingReflectionTypes[type.extendsId].push(type);\n        }\n    };\n\n    context.schemas.forEach((typeid, klass) => {\n        const type = new ReflectionType();\n        type.id = Number(typeid);\n\n        // support inheritance\n        const inheritFrom = Object.getPrototypeOf(klass);\n        if (inheritFrom !== Schema) {\n            type.extendsId = context.schemas.get(inheritFrom);\n        }\n\n        const metadata = klass[Symbol.metadata];\n\n        //\n        // FIXME: this is a workaround for inherited types without additional fields\n        // if metadata is the same reference as the parent class - it means the class has no own metadata\n        //\n        if (metadata !== inheritFrom[Symbol.metadata]) {\n            for (const fieldIndex in metadata) {\n                const index = Number(fieldIndex);\n                const fieldName = metadata[index].name;\n\n                // skip fields from parent classes\n                if (!Object.prototype.hasOwnProperty.call(metadata, fieldName)) {\n                    continue;\n                }\n\n                const reflectionField = new ReflectionField();\n                reflectionField.name = fieldName;\n\n                let fieldType: string;\n\n                const field = metadata[index];\n\n                if (typeof (field.type) === \"string\") {\n                    fieldType = field.type;\n\n                } else {\n                    let childTypeSchema: typeof Schema;\n\n                    //\n                    // TODO: refactor below.\n                    //\n                    if (Schema.is(field.type)) {\n                        fieldType = \"ref\";\n                        childTypeSchema = field.type as typeof Schema;\n\n                    } else {\n                        fieldType = Object.keys(field.type)[0];\n\n                        if (typeof (field.type[fieldType as keyof typeof field.type]) === \"string\") {\n                            fieldType += \":\" + field.type[fieldType as keyof typeof field.type]; // array:string\n\n                        } else {\n                            childTypeSchema = field.type[fieldType as keyof typeof field.type];\n                        }\n                    }\n\n                    reflectionField.referencedType = (childTypeSchema)\n                        ? context.getTypeId(childTypeSchema)\n                        : -1;\n                }\n\n                reflectionField.type = fieldType;\n                type.fields.push(reflectionField);\n            }\n        }\n\n        addType(type);\n    });\n\n    // in case there are types that were not added due to inheritance\n    for (const typeid in pendingReflectionTypes) {\n        pendingReflectionTypes[typeid].forEach((type) =>\n            reflection.types.push(type))\n    }\n\n    const buf = reflectionEncoder.encodeAll(it);\n    return buf.slice(0, it.offset);\n};\n\nReflection.decode = function <T extends Schema = Schema>(bytes: Uint8Array, it?: Iterator): Decoder<T> {\n    const reflection = new Reflection();\n\n    const reflectionDecoder = new Decoder(reflection);\n    reflectionDecoder.decode(bytes, it);\n\n    const typeContext = new TypeContext();\n\n    // 1st pass, initialize metadata + inheritance\n    reflection.types.forEach((reflectionType) => {\n        const parentClass: typeof Schema = typeContext.get(reflectionType.extendsId) ?? Schema;\n        const schema: typeof Schema = class _ extends parentClass { };\n\n        // register for inheritance support\n        TypeContext.register(schema);\n\n        typeContext.add(schema, reflectionType.id);\n    }, {});\n\n    // define fields\n    const addFields = (metadata: Metadata, reflectionType: ReflectionType, parentFieldIndex: number) => {\n        reflectionType.fields.forEach((field, i) => {\n            const fieldIndex = parentFieldIndex + i;\n\n            if (field.referencedType !== undefined) {\n                let fieldType = field.type;\n                let refType: PrimitiveType = typeContext.get(field.referencedType);\n\n                // map or array of primitive type (-1)\n                if (!refType) {\n                    const typeInfo = field.type.split(\":\");\n                    fieldType = typeInfo[0];\n                    refType = typeInfo[1] as PrimitiveType; // string\n                }\n\n                if (fieldType === \"ref\") {\n                    Metadata.addField(metadata, fieldIndex, field.name, refType);\n\n                } else {\n                    Metadata.addField(metadata, fieldIndex, field.name, { [fieldType]: refType });\n                }\n\n            } else {\n                Metadata.addField(metadata, fieldIndex, field.name, field.type as PrimitiveType);\n            }\n        });\n    };\n\n    // 2nd pass, set fields\n    reflection.types.forEach((reflectionType) => {\n        const schema = typeContext.get(reflectionType.id);\n\n        // for inheritance support\n        const metadata = Metadata.initialize(schema);\n\n        const inheritedTypes: ReflectionType[] = [];\n\n        let parentType: ReflectionType = reflectionType;\n        do {\n            inheritedTypes.push(parentType);\n            parentType = reflection.types.find((t) => t.id === parentType.extendsId);\n        } while (parentType);\n\n        let parentFieldIndex = 0;\n\n        inheritedTypes.reverse().forEach((reflectionType) => {\n            // add fields from all inherited classes\n            // TODO: refactor this to avoid adding fields from parent classes\n            addFields(metadata, reflectionType, parentFieldIndex);\n            parentFieldIndex += reflectionType.fields.length;\n        });\n    });\n\n    const state: T = new (typeContext.get(reflection.rootType || 0) as unknown as any)();\n\n    return new Decoder<T>(state, typeContext);\n}"]}

package/lib/src/Schema.d.ts

@@ -0,0 +1,86 @@
+import { OPERATION } from './encoding/spec';
+import { type DefinitionType } from "./annotations";
+import { AssignableProps, NonFunctionPropNames, ToJSON } from './types/HelperTypes';
+import { ChangeSetName, ChangeTree, IRef, Ref } from './encoder/ChangeTree';
+import { $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $refId, $track } from './types/symbols';
+import { StateView } from './encoder/StateView';
+import type { Decoder } from './decoder/Decoder';
+import type { Metadata } from './Metadata';
+/**
+ * Schema encoder / decoder
+ */
+export declare class Schema<C = any> implements IRef {
+    static [Symbol.metadata]: Metadata;
+    static [$encoder]: import("./encoder/EncodeOperation").EncodeOperation<any>;
+    static [$decoder]: import("./decoder/DecodeOperation").DecodeOperation<any>;
+    [$refId]?: number;
+    /**
+     * Assign the property descriptors required to track changes on this instance.
+     * @param instance
+     */
+    static initialize(instance: any): void;
+    static is(type: DefinitionType): boolean;
+    /**
+     * Track property changes
+     */
+    static [$track](changeTree: ChangeTree, index: number, operation?: OPERATION): void;
+    /**
+     * Determine if a property must be filtered.
+     * - If returns false, the property is NOT going to be encoded.
+     * - If returns true, the property is going to be encoded.
+     *
+     * Encoding with "filters" happens in two steps:
+     * - First, the encoder iterates over all "not owned" properties and encodes them.
+     * - Then, the encoder iterates over all "owned" properties per instance and encodes them.
+     */
+    static [$filter](ref: Schema, index: number, view: StateView): boolean;
+    constructor(arg?: C);
+    /**
+     * Assign properties to the instance.
+     * @param props Properties to assign to the instance
+     * @returns
+     */
+    assign<T extends Partial<this>>(props: AssignableProps<T>): this;
+    /**
+     * Restore the instance from JSON data.
+     * @param jsonData JSON data to restore the instance from
+     * @returns
+     */
+    restore(jsonData: ToJSON<this>): this;
+    /**
+     * (Server-side): Flag a property to be encoded for the next patch.
+     * @param instance Schema instance
+     * @param property string representing the property name, or number representing the index of the property.
+     * @param operation OPERATION to perform (detected automatically)
+     */
+    setDirty<K extends NonFunctionPropNames<this>>(property: K | number, operation?: OPERATION): void;
+    clone(): this;
+    toJSON(this: any): ToJSON<this>;
+    /**
+     * Used in tests only
+     * @internal
+     */
+    discardAllChanges(): void;
+    [$getByIndex](index: number): any;
+    [$deleteByIndex](index: number): void;
+    /**
+     * Inspect the `refId` of all Schema instances in the tree. Optionally display the contents of the instance.
+     *
+     * @param ref Schema instance
+     * @param showContents display JSON contents of the instance
+     * @returns
+     */
+    static debugRefIds<T extends Schema>(ref: T, showContents?: boolean, level?: number, decoder?: Decoder, keyPrefix?: string): string;
+    static debugRefIdEncodingOrder<T extends Ref>(ref: T, changeSet?: ChangeSetName): number[];
+    static debugRefIdsFromDecoder(decoder: Decoder): string;
+    /**
+     * Return a string representation of the changes on a Schema instance.
+     * The list of changes is cleared after each encode.
+     *
+     * @param instance Schema instance
+     * @param isEncodeAll Return "full encode" instead of current change set.
+     * @returns
+     */
+    static debugChanges<T extends Ref>(instance: T, isEncodeAll?: boolean): string;
+    static debugChangesDeep<T extends Schema>(ref: T, changeSetName?: "changes" | "allChanges" | "allFilteredChanges" | "filteredChanges"): string;
+}

package/lib/src/Schema.js

@@ -0,0 +1,352 @@
+var _a, _b;
+import { OPERATION } from './encoding/spec';
+import { DEFAULT_VIEW_TAG } from "./annotations";
+import { ChangeTree } from './encoder/ChangeTree';
+import { $changes, $decoder, $deleteByIndex, $descriptors, $encoder, $filter, $getByIndex, $refId, $track } from './types/symbols';
+import { encodeSchemaOperation } from './encoder/EncodeOperation';
+import { decodeSchemaOperation } from './decoder/DecodeOperation';
+import { getIndent } from './utils';
+/**
+ * Schema encoder / decoder
+ */
+export class Schema {
+    static { this[_a] = encodeSchemaOperation; }
+    static { this[_b] = decodeSchemaOperation; }
+    /**
+     * Assign the property descriptors required to track changes on this instance.
+     * @param instance
+     */
+    static initialize(instance) {
+        Object.defineProperty(instance, $changes, {
+            value: new ChangeTree(instance),
+            enumerable: false,
+            writable: true
+        });
+        Object.defineProperties(instance, instance.constructor[Symbol.metadata]?.[$descriptors] || {});
+    }
+    static is(type) {
+        return typeof (type[Symbol.metadata]) === "object";
+    }
+    /**
+     * Track property changes
+     */
+    static [(Symbol.metadata, _a = $encoder, _b = $decoder, $track)](changeTree, index, operation = OPERATION.ADD) {
+        changeTree.change(index, operation);
+    }
+    /**
+     * Determine if a property must be filtered.
+     * - If returns false, the property is NOT going to be encoded.
+     * - If returns true, the property is going to be encoded.
+     *
+     * Encoding with "filters" happens in two steps:
+     * - First, the encoder iterates over all "not owned" properties and encodes them.
+     * - Then, the encoder iterates over all "owned" properties per instance and encodes them.
+     */
+    static [$filter](ref, index, view) {
+        const metadata = ref.constructor[Symbol.metadata];
+        const tag = metadata[index]?.tag;
+        if (view === undefined) {
+            // shared pass/encode: encode if doesn't have a tag
+            return tag === undefined;
+        }
+        else if (tag === undefined) {
+            // view pass: no tag
+            return true;
+        }
+        else if (tag === DEFAULT_VIEW_TAG) {
+            // view pass: default tag
+            return view.isChangeTreeVisible(ref[$changes]);
+        }
+        else {
+            // view pass: custom tag
+            const tags = view.tags?.get(ref[$changes]);
+            return tags && tags.has(tag);
+        }
+    }
+    // allow inherited classes to have a constructor
+    constructor(arg) {
+        //
+        // inline
+        // Schema.initialize(this);
+        //
+        Schema.initialize(this);
+        //
+        // Assign initial values
+        //
+        if (arg) {
+            Object.assign(this, arg);
+        }
+    }
+    /**
+     * Assign properties to the instance.
+     * @param props Properties to assign to the instance
+     * @returns
+     */
+    assign(props) {
+        Object.assign(this, props);
+        return this;
+    }
+    /**
+     * Restore the instance from JSON data.
+     * @param jsonData JSON data to restore the instance from
+     * @returns
+     */
+    restore(jsonData) {
+        const metadata = this.constructor[Symbol.metadata];
+        for (const fieldIndex in metadata) {
+            const field = metadata[fieldIndex];
+            const fieldName = field.name;
+            const fieldType = field.type;
+            const value = jsonData[fieldName];
+            if (value === undefined || value === null) {
+                continue;
+            }
+            if (typeof fieldType === "string") {
+                // Primitive type: assign directly
+                this[fieldName] = value;
+            }
+            else if (Schema.is(fieldType)) {
+                // Schema type: create instance and restore
+                const instance = new fieldType();
+                instance.restore(value);
+                this[fieldName] = instance;
+            }
+            else if (typeof fieldType === "object") {
+                // Collection types: { map: ... }, { array: ... }, etc.
+                const collectionType = Object.keys(fieldType)[0];
+                const childType = fieldType[collectionType];
+                if (collectionType === "map") {
+                    const mapSchema = this[fieldName];
+                    for (const key in value) {
+                        if (Schema.is(childType)) {
+                            const childInstance = new childType();
+                            childInstance.restore(value[key]);
+                            mapSchema.set(key, childInstance);
+                        }
+                        else {
+                            mapSchema.set(key, value[key]);
+                        }
+                    }
+                }
+                else if (collectionType === "array") {
+                    const arraySchema = this[fieldName];
+                    for (let i = 0; i < value.length; i++) {
+                        if (Schema.is(childType)) {
+                            const childInstance = new childType();
+                            childInstance.restore(value[i]);
+                            arraySchema.push(childInstance);
+                        }
+                        else {
+                            arraySchema.push(value[i]);
+                        }
+                    }
+                }
+            }
+        }
+        return this;
+    }
+    /**
+     * (Server-side): Flag a property to be encoded for the next patch.
+     * @param instance Schema instance
+     * @param property string representing the property name, or number representing the index of the property.
+     * @param operation OPERATION to perform (detected automatically)
+     */
+    setDirty(property, operation) {
+        const metadata = this.constructor[Symbol.metadata];
+        this[$changes].change(metadata[metadata[property]].index, operation);
+    }
+    clone() {
+        // Create instance without calling custom constructor
+        const cloned = Object.create(this.constructor.prototype);
+        Schema.initialize(cloned);
+        const metadata = this.constructor[Symbol.metadata];
+        //
+        // TODO: clone all properties, not only annotated ones
+        //
+        // for (const field in this) {
+        for (const fieldIndex in metadata) {
+            const field = metadata[fieldIndex].name;
+            if (typeof (this[field]) === "object" &&
+                typeof (this[field]?.clone) === "function") {
+                // deep clone
+                cloned[field] = this[field].clone();
+            }
+            else {
+                // primitive values
+                cloned[field] = this[field];
+            }
+        }
+        return cloned;
+    }
+    toJSON() {
+        const obj = {};
+        const metadata = this.constructor[Symbol.metadata];
+        for (const index in metadata) {
+            const field = metadata[index];
+            const fieldName = field.name;
+            if (!field.deprecated && this[fieldName] !== null && typeof (this[fieldName]) !== "undefined") {
+                obj[fieldName] = (typeof (this[fieldName]['toJSON']) === "function")
+                    ? this[fieldName]['toJSON']()
+                    : this[fieldName];
+            }
+        }
+        return obj;
+    }
+    /**
+     * Used in tests only
+     * @internal
+     */
+    discardAllChanges() {
+        this[$changes].discardAll();
+    }
+    [$getByIndex](index) {
+        const metadata = this.constructor[Symbol.metadata];
+        return this[metadata[index].name];
+    }
+    [$deleteByIndex](index) {
+        const metadata = this.constructor[Symbol.metadata];
+        this[metadata[index].name] = undefined;
+    }
+    /**
+     * Inspect the `refId` of all Schema instances in the tree. Optionally display the contents of the instance.
+     *
+     * @param ref Schema instance
+     * @param showContents display JSON contents of the instance
+     * @returns
+     */
+    static debugRefIds(ref, showContents = false, level = 0, decoder, keyPrefix = "") {
+        const contents = (showContents) ? ` - ${JSON.stringify(ref.toJSON())}` : "";
+        const changeTree = ref[$changes];
+        const refId = ref[$refId];
+        const root = (decoder) ? decoder.root : changeTree.root;
+        // log reference count if > 1
+        const refCount = (root?.refCount?.[refId] > 1)
+            ? ` [×${root.refCount[refId]}]`
+            : '';
+        let output = `${getIndent(level)}${keyPrefix}${ref.constructor.name} (refId: ${refId})${refCount}${contents}\n`;
+        changeTree.forEachChild((childChangeTree, indexOrKey) => {
+            let key = indexOrKey;
+            if (typeof indexOrKey === 'number' && ref['$indexes']) {
+                // MapSchema
+                key = ref['$indexes'].get(indexOrKey) ?? indexOrKey;
+            }
+            const keyPrefix = (ref['forEach'] !== undefined && key !== undefined) ? `["${key}"]: ` : "";
+            output += this.debugRefIds(childChangeTree.ref, showContents, level + 1, decoder, keyPrefix);
+        });
+        return output;
+    }
+    static debugRefIdEncodingOrder(ref, changeSet = 'allChanges') {
+        let encodeOrder = [];
+        let current = ref[$changes].root[changeSet].next;
+        while (current) {
+            if (current.changeTree) {
+                encodeOrder.push(current.changeTree.ref[$refId]);
+            }
+            current = current.next;
+        }
+        return encodeOrder;
+    }
+    static debugRefIdsFromDecoder(decoder) {
+        return this.debugRefIds(decoder.state, false, 0, decoder);
+    }
+    /**
+     * Return a string representation of the changes on a Schema instance.
+     * The list of changes is cleared after each encode.
+     *
+     * @param instance Schema instance
+     * @param isEncodeAll Return "full encode" instead of current change set.
+     * @returns
+     */
+    static debugChanges(instance, isEncodeAll = false) {
+        const changeTree = instance[$changes];
+        const changeSet = (isEncodeAll) ? changeTree.allChanges : changeTree.changes;
+        const changeSetName = (isEncodeAll) ? "allChanges" : "changes";
+        let output = `${instance.constructor.name} (${instance[$refId]}) -> .${changeSetName}:\n`;
+        function dumpChangeSet(changeSet) {
+            changeSet.operations
+                .filter(op => op)
+                .forEach((index) => {
+                const operation = changeTree.indexedOperations[index];
+                output += `- [${index}]: ${OPERATION[operation]} (${JSON.stringify(changeTree.getValue(Number(index), isEncodeAll))})\n`;
+            });
+        }
+        dumpChangeSet(changeSet);
+        // display filtered changes
+        if (!isEncodeAll &&
+            changeTree.filteredChanges &&
+            (changeTree.filteredChanges.operations).filter(op => op).length > 0) {
+            output += `${instance.constructor.name} (${instance[$refId]}) -> .filteredChanges:\n`;
+            dumpChangeSet(changeTree.filteredChanges);
+        }
+        // display filtered changes
+        if (isEncodeAll &&
+            changeTree.allFilteredChanges &&
+            (changeTree.allFilteredChanges.operations).filter(op => op).length > 0) {
+            output += `${instance.constructor.name} (${instance[$refId]}) -> .allFilteredChanges:\n`;
+            dumpChangeSet(changeTree.allFilteredChanges);
+        }
+        return output;
+    }
+    static debugChangesDeep(ref, changeSetName = "changes") {
+        let output = "";
+        const rootChangeTree = ref[$changes];
+        const root = rootChangeTree.root;
+        const changeTrees = new Map();
+        const instanceRefIds = [];
+        let totalOperations = 0;
+        // TODO: FIXME: this method is not working as expected
+        for (const [refId, changes] of Object.entries(root[changeSetName])) {
+            const changeTree = root.changeTrees[refId];
+            if (!changeTree) {
+                continue;
+            }
+            let includeChangeTree = false;
+            let parentChangeTrees = [];
+            let parentChangeTree = changeTree.parent?.[$changes];
+            if (changeTree === rootChangeTree) {
+                includeChangeTree = true;
+            }
+            else {
+                while (parentChangeTree !== undefined) {
+                    parentChangeTrees.push(parentChangeTree);
+                    if (parentChangeTree.ref === ref) {
+                        includeChangeTree = true;
+                        break;
+                    }
+                    parentChangeTree = parentChangeTree.parent?.[$changes];
+                }
+            }
+            if (includeChangeTree) {
+                instanceRefIds.push(changeTree.ref[$refId]);
+                totalOperations += Object.keys(changes).length;
+                changeTrees.set(changeTree, parentChangeTrees.reverse());
+            }
+        }
+        output += "---\n";
+        output += `root refId: ${rootChangeTree.ref[$refId]}\n`;
+        output += `Total instances: ${instanceRefIds.length} (refIds: ${instanceRefIds.join(", ")})\n`;
+        output += `Total changes: ${totalOperations}\n`;
+        output += "---\n";
+        // based on root.changes, display a tree of changes that has the "ref" instance as parent
+        const visitedParents = new WeakSet();
+        for (const [changeTree, parentChangeTrees] of changeTrees.entries()) {
+            parentChangeTrees.forEach((parentChangeTree, level) => {
+                if (!visitedParents.has(parentChangeTree)) {
+                    output += `${getIndent(level)}${parentChangeTree.ref.constructor.name} (refId: ${parentChangeTree.ref[$refId]})\n`;
+                    visitedParents.add(parentChangeTree);
+                }
+            });
+            const changes = changeTree.indexedOperations;
+            const level = parentChangeTrees.length;
+            const indent = getIndent(level);
+            const parentIndex = (level > 0) ? `(${changeTree.parentIndex}) ` : "";
+            output += `${indent}${parentIndex}${changeTree.ref.constructor.name} (refId: ${changeTree.ref[$refId]}) - changes: ${Object.keys(changes).length}\n`;
+            for (const index in changes) {
+                const operation = changes[index];
+                output += `${getIndent(level + 1)}${OPERATION[operation]}: ${index}\n`;
+            }
+        }
+        return `${output}`;
+    }
+}
+//# sourceMappingURL=Schema.js.map