@colyseus/schema 3.0.52 → 3.0.54

package/build/cjs/index.js

@@ -685,15 +685,7 @@ class TypeContext {
             if (typeof (fieldType) === "string") {
                 continue;
             }
-            if (Array.isArray(fieldType)) {
-                const type = fieldType[0];
-                // skip primitive types
-                if (type === "string") {
-                    continue;
-                }
-                this.discoverTypes(type, klass, index, parentHasViewTag || fieldHasViewTag);
-            }
-            else if (typeof (fieldType) === "function") {
+            if (typeof (fieldType) === "function") {
                 this.discoverTypes(fieldType, klass, index, parentHasViewTag || fieldHasViewTag);
             }
             else {
@@ -743,11 +735,43 @@ class TypeContext {
 }
 
 function getNormalizedType(type) {
-    return (Array.isArray(type))
-        ? { array: type[0] }
-        : (typeof (type['type']) !== "undefined")
-            ? type['type']
-            : type;
+    if (Array.isArray(type)) {
+        return { array: getNormalizedType(type[0]) };
+    }
+    else if (typeof (type['type']) !== "undefined") {
+        return type['type'];
+    }
+    else if (isTSEnum(type)) {
+        // Detect TS Enum type (either string or number)
+        return Object.keys(type).every(key => typeof type[key] === "string")
+            ? "string"
+            : "number";
+    }
+    else if (typeof type === "object" && type !== null) {
+        // Handle collection types
+        const collectionType = Object.keys(type).find(k => registeredTypes[k] !== undefined);
+        if (collectionType) {
+            type[collectionType] = getNormalizedType(type[collectionType]);
+            return type;
+        }
+    }
+    return type;
+}
+function isTSEnum(_enum) {
+    if (typeof _enum === 'function' && _enum[Symbol.metadata]) {
+        return false;
+    }
+    const keys = Object.keys(_enum);
+    const numericFields = keys.filter(k => /\d+/.test(k));
+    // Check for number enum (has numeric keys and reverse mapping)
+    if (numericFields.length > 0 && numericFields.length === (keys.length / 2) && _enum[_enum[numericFields[0]]] == numericFields[0]) {
+        return true;
+    }
+    // Check for string enum (all values are strings and keys match values)
+    if (keys.length > 0 && keys.every(key => typeof _enum[key] === 'string' && _enum[key] === key)) {
+        return true;
+    }
+    return false;
 }
 const Metadata = {
     addField(metadata, index, name, type, descriptor) {
@@ -862,14 +886,12 @@ const Metadata = {
             ?? -1; // no fields defined
         fieldIndex++;
         for (const field in fields) {
-            const type = fields[field];
+            const type = getNormalizedType(fields[field]);
             // FIXME: this code is duplicated from @type() annotation
-            const complexTypeKlass = (Array.isArray(type))
-                ? getType("array")
-                : (typeof (Object.keys(type)[0]) === "string") && getType(Object.keys(type)[0]);
+            const complexTypeKlass = typeof (Object.keys(type)[0]) === "string" && getType(Object.keys(type)[0]);
             const childType = (complexTypeKlass)
                 ? Object.values(type)[0]
-                : getNormalizedType(type);
+                : type;
             Metadata.addField(metadata, fieldIndex, field, type, getPropertyDescriptor(`_${field}`, fieldIndex, childType, complexTypeKlass));
             fieldIndex++;
         }
@@ -2185,7 +2207,7 @@ class ArraySchema {
         const allChangesIndex = this.items.findIndex(item => item === this.items[0]);
         changeTree.delete(index, exports.OPERATION.DELETE, allChangesIndex);
         changeTree.shiftAllChangeIndexes(-1, allChangesIndex);
-        // this.deletedIndexes[index] = true;
+        this.deletedIndexes[index] = true;
         return this.items.shift();
     }
     /**
@@ -2820,448 +2842,174 @@ class MapSchema {
 }
 registerType("map", { constructor: MapSchema });
 
-const DEFAULT_VIEW_TAG = -1;
-function entity(constructor) {
-    TypeContext.register(constructor);
-    return constructor;
-}
-/**
- * [See documentation](https://docs.colyseus.io/state/schema/)
- *
- * Annotate a Schema property to be serializeable.
- * \@type()'d fields are automatically flagged as "dirty" for the next patch.
- *
- * @example Standard usage, with automatic change tracking.
- * ```
- * \@type("string") propertyName: string;
- * ```
- *
- * @example You can provide the "manual" option if you'd like to manually control your patches via .setDirty().
- * ```
- * \@type("string", { manual: true })
- * ```
- */
-// export function type(type: DefinitionType, options?: TypeOptions) {
-//     return function ({ get, set }, context: ClassAccessorDecoratorContext): ClassAccessorDecoratorResult<Schema, any> {
-//         if (context.kind !== "accessor") {
-//             throw new Error("@type() is only supported for class accessor properties");
-//         }
-//         const field = context.name.toString();
-//         //
-//         // detect index for this field, considering inheritance
-//         //
-//         const parent = Object.getPrototypeOf(context.metadata);
-//         let fieldIndex: number = context.metadata[$numFields] // current structure already has fields defined
-//             ?? (parent && parent[$numFields]) // parent structure has fields defined
-//             ?? -1; // no fields defined
-//         fieldIndex++;
-//         if (
-//             !parent && // the parent already initializes the `$changes` property
-//             !Metadata.hasFields(context.metadata)
-//         ) {
-//             context.addInitializer(function (this: Ref) {
-//                 Object.defineProperty(this, $changes, {
-//                     value: new ChangeTree(this),
-//                     enumerable: false,
-//                     writable: true
-//                 });
-//             });
-//         }
-//         Metadata.addField(context.metadata, fieldIndex, field, type);
-//         const isArray = ArraySchema.is(type);
-//         const isMap = !isArray && MapSchema.is(type);
-//         // if (options && options.manual) {
-//         //     // do not declare getter/setter descriptor
-//         //     definition.descriptors[field] = {
-//         //         enumerable: true,
-//         //         configurable: true,
-//         //         writable: true,
-//         //     };
-//         //     return;
-//         // }
-//         return {
-//             init(value) {
-//                 // TODO: may need to convert ArraySchema/MapSchema here
-//                 // do not flag change if value is undefined.
-//                 if (value !== undefined) {
-//                     this[$changes].change(fieldIndex);
-//                     // automaticallty transform Array into ArraySchema
-//                     if (isArray) {
-//                         if (!(value instanceof ArraySchema)) {
-//                             value = new ArraySchema(...value);
-//                         }
-//                         value[$childType] = Object.values(type)[0];
-//                     }
-//                     // automaticallty transform Map into MapSchema
-//                     if (isMap) {
-//                         if (!(value instanceof MapSchema)) {
-//                             value = new MapSchema(value);
-//                         }
-//                         value[$childType] = Object.values(type)[0];
-//                     }
-//                     // try to turn provided structure into a Proxy
-//                     if (value['$proxy'] === undefined) {
-//                         if (isMap) {
-//                             value = getMapProxy(value);
-//                         }
-//                     }
-//                 }
-//                 return value;
-//             },
-//             get() {
-//                 return get.call(this);
-//             },
-//             set(value: any) {
-//                 /**
-//                  * Create Proxy for array or map items
-//                  */
-//                 // skip if value is the same as cached.
-//                 if (value === get.call(this)) {
-//                     return;
-//                 }
-//                 if (
-//                     value !== undefined &&
-//                     value !== null
-//                 ) {
-//                     // automaticallty transform Array into ArraySchema
-//                     if (isArray) {
-//                         if (!(value instanceof ArraySchema)) {
-//                             value = new ArraySchema(...value);
-//                         }
-//                         value[$childType] = Object.values(type)[0];
-//                     }
-//                     // automaticallty transform Map into MapSchema
-//                     if (isMap) {
-//                         if (!(value instanceof MapSchema)) {
-//                             value = new MapSchema(value);
-//                         }
-//                         value[$childType] = Object.values(type)[0];
-//                     }
-//                     // try to turn provided structure into a Proxy
-//                     if (value['$proxy'] === undefined) {
-//                         if (isMap) {
-//                             value = getMapProxy(value);
-//                         }
-//                     }
-//                     // flag the change for encoding.
-//                     this[$changes].change(fieldIndex);
-//                     //
-//                     // call setParent() recursively for this and its child
-//                     // structures.
-//                     //
-//                     if (value[$changes]) {
-//                         value[$changes].setParent(
-//                             this,
-//                             this[$changes].root,
-//                             Metadata.getIndex(context.metadata, field),
-//                         );
-//                     }
-//                 } else if (get.call(this)) {
-//                     //
-//                     // Setting a field to `null` or `undefined` will delete it.
-//                     //
-//                     this[$changes].delete(field);
-//                 }
-//                 set.call(this, value);
-//             },
-//         };
-//     }
-// }
-function view(tag = DEFAULT_VIEW_TAG) {
-    return function (target, fieldName) {
-        const constructor = target.constructor;
-        const parentClass = Object.getPrototypeOf(constructor);
-        const parentMetadata = parentClass[Symbol.metadata];
-        // TODO: use Metadata.initialize()
-        const metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
-        // const fieldIndex = metadata[fieldName];
-        // if (!metadata[fieldIndex]) {
-        //     //
-        //     // detect index for this field, considering inheritance
-        //     //
-        //     metadata[fieldIndex] = {
-        //         type: undefined,
-        //         index: (metadata[$numFields] // current structure already has fields defined
-        //             ?? (parentMetadata && parentMetadata[$numFields]) // parent structure has fields defined
-        //             ?? -1) + 1 // no fields defined
-        //     }
-        // }
-        Metadata.setTag(metadata, fieldName, tag);
-    };
-}
-function type(type, options) {
-    return function (target, field) {
-        const constructor = target.constructor;
-        if (!type) {
-            throw new Error(`${constructor.name}: @type() reference provided for "${field}" is undefined. Make sure you don't have any circular dependencies.`);
-        }
-        // for inheritance support
-        TypeContext.register(constructor);
-        const parentClass = Object.getPrototypeOf(constructor);
-        const parentMetadata = parentClass[Symbol.metadata];
-        const metadata = Metadata.initialize(constructor);
-        let fieldIndex = metadata[field];
-        /**
-         * skip if descriptor already exists for this field (`@deprecated()`)
-         */
-        if (metadata[fieldIndex] !== undefined) {
-            if (metadata[fieldIndex].deprecated) {
-                // do not create accessors for deprecated properties.
-                return;
-            }
-            else if (metadata[fieldIndex].type !== undefined) {
-                // trying to define same property multiple times across inheritance.
-                // https://github.com/colyseus/colyseus-unity3d/issues/131#issuecomment-814308572
-                try {
-                    throw new Error(`@colyseus/schema: Duplicate '${field}' definition on '${constructor.name}'.\nCheck @type() annotation`);
-                }
-                catch (e) {
-                    const definitionAtLine = e.stack.split("\n")[4].trim();
-                    throw new Error(`${e.message} ${definitionAtLine}`);
-                }
-            }
-        }
-        else {
-            //
-            // detect index for this field, considering inheritance
-            //
-            fieldIndex = metadata[$numFields] // current structure already has fields defined
-                ?? (parentMetadata && parentMetadata[$numFields]) // parent structure has fields defined
-                ?? -1; // no fields defined
-            fieldIndex++;
+var _a$2, _b$2;
+class CollectionSchema {
+    static { this[_a$2] = encodeKeyValueOperation; }
+    static { this[_b$2] = decodeKeyValueOperation; }
+    /**
+     * 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 [(_a$2 = $encoder, _b$2 = $decoder, $filter)](ref, index, view) {
+        return (!view ||
+            typeof (ref[$childType]) === "string" ||
+            view.isChangeTreeVisible((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes]));
+    }
+    static is(type) {
+        return type['collection'] !== undefined;
+    }
+    constructor(initialValues) {
+        this.$items = new Map();
+        this.$indexes = new Map();
+        this.deletedItems = {};
+        this.$refId = 0;
+        this[$changes] = new ChangeTree(this);
+        this[$changes].indexes = {};
+        if (initialValues) {
+            initialValues.forEach((v) => this.add(v));
         }
-        if (options && options.manual) {
-            Metadata.addField(metadata, fieldIndex, field, type, {
-                // do not declare getter/setter descriptor
-                enumerable: true,
-                configurable: true,
-                writable: true,
-            });
-        }
-        else {
-            const complexTypeKlass = (Array.isArray(type))
-                ? getType("array")
-                : (typeof (Object.keys(type)[0]) === "string") && getType(Object.keys(type)[0]);
-            const childType = (complexTypeKlass)
-                ? Object.values(type)[0]
-                : type;
-            Metadata.addField(metadata, fieldIndex, field, type, getPropertyDescriptor(`_${field}`, fieldIndex, childType, complexTypeKlass));
-        }
-    };
-}
-function getPropertyDescriptor(fieldCached, fieldIndex, type, complexTypeKlass) {
-    return {
-        get: function () { return this[fieldCached]; },
-        set: function (value) {
-            const previousValue = this[fieldCached] ?? undefined;
-            // skip if value is the same as cached.
-            if (value === previousValue) {
-                return;
-            }
-            if (value !== undefined &&
-                value !== null) {
-                if (complexTypeKlass) {
-                    // automaticallty transform Array into ArraySchema
-                    if (complexTypeKlass.constructor === ArraySchema && !(value instanceof ArraySchema)) {
-                        value = new ArraySchema(...value);
-                    }
-                    // automaticallty transform Map into MapSchema
-                    if (complexTypeKlass.constructor === MapSchema && !(value instanceof MapSchema)) {
-                        value = new MapSchema(value);
-                    }
-                    value[$childType] = type;
-                }
-                else if (typeof (type) !== "string") {
-                    assertInstanceType(value, type, this, fieldCached.substring(1));
-                }
-                else {
-                    assertType(value, type, this, fieldCached.substring(1));
-                }
-                const changeTree = this[$changes];
-                //
-                // Replacing existing "ref", remove it from root.
-                //
-                if (previousValue !== undefined && previousValue[$changes]) {
-                    changeTree.root?.remove(previousValue[$changes]);
-                    this.constructor[$track](changeTree, fieldIndex, exports.OPERATION.DELETE_AND_ADD);
-                }
-                else {
-                    this.constructor[$track](changeTree, fieldIndex, exports.OPERATION.ADD);
-                }
-                //
-                // call setParent() recursively for this and its child
-                // structures.
-                //
-                value[$changes]?.setParent(this, changeTree.root, fieldIndex);
-            }
-            else if (previousValue !== undefined) {
-                //
-                // Setting a field to `null` or `undefined` will delete it.
-                //
-                this[$changes].delete(fieldIndex);
-            }
-            this[fieldCached] = value;
-        },
-        enumerable: true,
-        configurable: true
-    };
-}
-/**
- * `@deprecated()` flag a field as deprecated.
- * The previous `@type()` annotation should remain along with this one.
- */
-function deprecated(throws = true) {
-    return function (klass, field) {
-        //
-        // FIXME: the following block of code is repeated across `@type()`, `@deprecated()` and `@unreliable()` decorators.
-        //
-        const constructor = klass.constructor;
-        const parentClass = Object.getPrototypeOf(constructor);
-        const parentMetadata = parentClass[Symbol.metadata];
-        const metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
-        const fieldIndex = metadata[field];
-        // if (!metadata[field]) {
-        //     //
-        //     // detect index for this field, considering inheritance
-        //     //
-        //     metadata[field] = {
-        //         type: undefined,
-        //         index: (metadata[$numFields] // current structure already has fields defined
-        //             ?? (parentMetadata && parentMetadata[$numFields]) // parent structure has fields defined
-        //             ?? -1) + 1 // no fields defined
-        //     }
-        // }
-        metadata[fieldIndex].deprecated = true;
-        if (throws) {
-            metadata[$descriptors] ??= {};
-            metadata[$descriptors][field] = {
-                get: function () { throw new Error(`${field} is deprecated.`); },
-                set: function (value) { },
-                enumerable: false,
-                configurable: true
-            };
-        }
-        // flag metadata[field] as non-enumerable
-        Object.defineProperty(metadata, fieldIndex, {
-            value: metadata[fieldIndex],
+        Object.defineProperty(this, $childType, {
+            value: undefined,
             enumerable: false,
-            configurable: true
+            writable: true,
+            configurable: true,
         });
-    };
-}
-function defineTypes(target, fields, options) {
-    for (let field in fields) {
-        type(fields[field], options)(target.prototype, field);
-    }
-    return target;
-}
-function schema(fieldsAndMethods, name, inherits = Schema) {
-    const fields = {};
-    const methods = {};
-    const defaultValues = {};
-    const viewTagFields = {};
-    for (let fieldName in fieldsAndMethods) {
-        const value = fieldsAndMethods[fieldName];
-        if (typeof (value) === "object") {
-            if (value['default'] !== undefined) {
-                defaultValues[fieldName] = value['default'];
-            }
-            if (value['view'] !== undefined) {
-                viewTagFields[fieldName] = (typeof (value['view']) === "boolean")
-                    ? DEFAULT_VIEW_TAG
-                    : value['view'];
-            }
-            fields[fieldName] = value;
-        }
-        else if (typeof (value) === "function") {
-            methods[fieldName] = value;
-        }
-        else {
-            fields[fieldName] = value;
-        }
     }
-    const klass = Metadata.setFields(class extends inherits {
-        constructor(...args) {
-            args[0] = Object.assign({}, defaultValues, args[0]);
-            super(...args);
+    add(value) {
+        // set "index" for reference.
+        const index = this.$refId++;
+        const isRef = (value[$changes]) !== undefined;
+        if (isRef) {
+            value[$changes].setParent(this, this[$changes].root, index);
         }
-    }, fields);
-    for (let fieldName in viewTagFields) {
-        view(viewTagFields[fieldName])(klass.prototype, fieldName);
+        this[$changes].indexes[index] = index;
+        this.$indexes.set(index, index);
+        this.$items.set(index, value);
+        this[$changes].change(index);
+        return index;
     }
-    for (let methodName in methods) {
-        klass.prototype[methodName] = methods[methodName];
+    at(index) {
+        const key = Array.from(this.$items.keys())[index];
+        return this.$items.get(key);
     }
-    if (name) {
-        Object.defineProperty(klass, "name", { value: name });
+    entries() {
+        return this.$items.entries();
     }
-    klass.extends = (fields, name) => schema(fields, name, klass);
-    return klass;
-}
-
-function getIndent(level) {
-    return (new Array(level).fill(0)).map((_, i) => (i === level - 1) ? `└─ ` : `   `).join("");
-}
-function dumpChanges(schema) {
-    const $root = schema[$changes].root;
-    const dump = {
-        ops: {},
-        refs: []
-    };
-    // for (const refId in $root.changes) {
-    let current = $root.changes.next;
-    while (current) {
-        const changeTree = current.changeTree;
-        // skip if ChangeTree is undefined
-        if (changeTree === undefined) {
-            current = current.next;
-            continue;
-        }
-        const changes = changeTree.indexedOperations;
-        dump.refs.push(`refId#${changeTree.refId}`);
-        for (const index in changes) {
-            const op = changes[index];
-            const opName = exports.OPERATION[op];
-            if (!dump.ops[opName]) {
-                dump.ops[opName] = 0;
+    delete(item) {
+        const entries = this.$items.entries();
+        let index;
+        let entry;
+        while (entry = entries.next()) {
+            if (entry.done) {
+                break;
+            }
+            if (item === entry.value[1]) {
+                index = entry.value[0];
+                break;
             }
-            dump.ops[exports.OPERATION[op]]++;
         }
-        current = current.next;
+        if (index === undefined) {
+            return false;
+        }
+        this.deletedItems[index] = this[$changes].delete(index);
+        this.$indexes.delete(index);
+        return this.$items.delete(index);
     }
-    return dump;
-}
-
-var _a$2, _b$2;
-/**
- * Schema encoder / decoder
- */
-class Schema {
-    static { this[_a$2] = encodeSchemaOperation; }
-    static { this[_b$2] = 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
+    clear() {
+        const changeTree = this[$changes];
+        // discard previous operations.
+        changeTree.discard(true);
+        changeTree.indexes = {};
+        // remove children references
+        changeTree.forEachChild((childChangeTree, _) => {
+            changeTree.root?.remove(childChangeTree);
         });
-        Object.defineProperties(instance, instance.constructor[Symbol.metadata]?.[$descriptors] || {});
+        // clear previous indexes
+        this.$indexes.clear();
+        // clear items
+        this.$items.clear();
+        changeTree.operation(exports.OPERATION.CLEAR);
     }
-    static is(type) {
-        return typeof (type[Symbol.metadata]) === "object";
-        // const metadata = type[Symbol.metadata];
-        // return metadata && Object.prototype.hasOwnProperty.call(metadata, -1);
+    has(value) {
+        return Array.from(this.$items.values()).some((v) => v === value);
     }
-    /**
-     * Track property changes
-     */
-    static [(_a$2 = $encoder, _b$2 = $decoder, $track)](changeTree, index, operation = exports.OPERATION.ADD) {
-        changeTree.change(index, operation);
+    forEach(callbackfn) {
+        this.$items.forEach((value, key, _) => callbackfn(value, key, this));
+    }
+    values() {
+        return this.$items.values();
+    }
+    get size() {
+        return this.$items.size;
+    }
+    /** Iterator */
+    [Symbol.iterator]() {
+        return this.$items.values();
+    }
+    setIndex(index, key) {
+        this.$indexes.set(index, key);
+    }
+    getIndex(index) {
+        return this.$indexes.get(index);
+    }
+    [$getByIndex](index) {
+        return this.$items.get(this.$indexes.get(index));
+    }
+    [$deleteByIndex](index) {
+        const key = this.$indexes.get(index);
+        this.$items.delete(key);
+        this.$indexes.delete(index);
+    }
+    [$onEncodeEnd]() {
+        this.deletedItems = {};
+    }
+    toArray() {
+        return Array.from(this.$items.values());
+    }
+    toJSON() {
+        const values = [];
+        this.forEach((value, key) => {
+            values.push((typeof (value['toJSON']) === "function")
+                ? value['toJSON']()
+                : value);
+        });
+        return values;
+    }
+    //
+    // Decoding utilities
+    //
+    clone(isDecoding) {
+        let cloned;
+        if (isDecoding) {
+            // client-side
+            cloned = Object.assign(new CollectionSchema(), this);
+        }
+        else {
+            // server-side
+            cloned = new CollectionSchema();
+            this.forEach((value) => {
+                if (value[$changes]) {
+                    cloned.add(value['clone']());
+                }
+                else {
+                    cloned.add(value);
+                }
+            });
+        }
+        return cloned;
     }
+}
+registerType("collection", { constructor: CollectionSchema, });
+
+var _a$1, _b$1;
+class SetSchema {
+    static { this[_a$1] = encodeKeyValueOperation; }
+    static { this[_b$1] = decodeKeyValueOperation; }
     /**
      * Determine if a property must be filtered.
      * - If returns false, the property is NOT going to be encoded.
@@ -3271,418 +3019,653 @@ class Schema {
      * - 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);
-        }
+    static [(_a$1 = $encoder, _b$1 = $decoder, $filter)](ref, index, view) {
+        return (!view ||
+            typeof (ref[$childType]) === "string" ||
+            view.visible.has((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes]));
     }
-    // allow inherited classes to have a constructor
-    constructor(...args) {
-        //
-        // inline
-        // Schema.initialize(this);
-        //
-        Schema.initialize(this);
-        //
-        // Assign initial values
-        //
-        if (args[0]) {
-            Object.assign(this, args[0]);
+    static is(type) {
+        return type['set'] !== undefined;
+    }
+    constructor(initialValues) {
+        this.$items = new Map();
+        this.$indexes = new Map();
+        this.deletedItems = {};
+        this.$refId = 0;
+        this[$changes] = new ChangeTree(this);
+        this[$changes].indexes = {};
+        if (initialValues) {
+            initialValues.forEach((v) => this.add(v));
         }
+        Object.defineProperty(this, $childType, {
+            value: undefined,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
     }
-    assign(props) {
-        Object.assign(this, props);
-        return this;
+    add(value) {
+        // immediatelly return false if value already added.
+        if (this.has(value)) {
+            return false;
+        }
+        // set "index" for reference.
+        const index = this.$refId++;
+        if ((value[$changes]) !== undefined) {
+            value[$changes].setParent(this, this[$changes].root, index);
+        }
+        const operation = this[$changes].indexes[index]?.op ?? exports.OPERATION.ADD;
+        this[$changes].indexes[index] = index;
+        this.$indexes.set(index, index);
+        this.$items.set(index, value);
+        this[$changes].change(index, operation);
+        return index;
     }
-    /**
-     * (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);
+    entries() {
+        return this.$items.entries();
     }
-    clone() {
-        const cloned = new (this.constructor);
-        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[metadata[fieldIndex]].name;
-            const field = metadata[fieldIndex].name;
-            if (typeof (this[field]) === "object" &&
-                typeof (this[field]?.clone) === "function") {
-                // deep clone
-                cloned[field] = this[field].clone();
+    delete(item) {
+        const entries = this.$items.entries();
+        let index;
+        let entry;
+        while (entry = entries.next()) {
+            if (entry.done) {
+                break;
             }
-            else {
-                // primitive values
-                cloned[field] = this[field];
+            if (item === entry.value[1]) {
+                index = entry.value[0];
+                break;
             }
         }
-        return cloned;
+        if (index === undefined) {
+            return false;
+        }
+        this.deletedItems[index] = this[$changes].delete(index);
+        this.$indexes.delete(index);
+        return this.$items.delete(index);
     }
-    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];
+    clear() {
+        const changeTree = this[$changes];
+        // discard previous operations.
+        changeTree.discard(true);
+        changeTree.indexes = {};
+        // clear previous indexes
+        this.$indexes.clear();
+        // clear items
+        this.$items.clear();
+        changeTree.operation(exports.OPERATION.CLEAR);
+    }
+    has(value) {
+        const values = this.$items.values();
+        let has = false;
+        let entry;
+        while (entry = values.next()) {
+            if (entry.done) {
+                break;
+            }
+            if (value === entry.value) {
+                has = true;
+                break;
             }
         }
-        return obj;
+        return has;
     }
-    /**
-     * Used in tests only
-     * @internal
-     */
-    discardAllChanges() {
-        this[$changes].discardAll();
+    forEach(callbackfn) {
+        this.$items.forEach((value, key, _) => callbackfn(value, key, this));
+    }
+    values() {
+        return this.$items.values();
+    }
+    get size() {
+        return this.$items.size;
+    }
+    /** Iterator */
+    [Symbol.iterator]() {
+        return this.$items.values();
+    }
+    setIndex(index, key) {
+        this.$indexes.set(index, key);
+    }
+    getIndex(index) {
+        return this.$indexes.get(index);
     }
     [$getByIndex](index) {
-        const metadata = this.constructor[Symbol.metadata];
-        return this[metadata[index].name];
+        return this.$items.get(this.$indexes.get(index));
     }
     [$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 = (decoder) ? decoder.root.refIds.get(ref) : changeTree.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;
+        const key = this.$indexes.get(index);
+        this.$items.delete(key);
+        this.$indexes.delete(index);
     }
-    static debugRefIdEncodingOrder(ref, changeSet = 'allChanges') {
-        let encodeOrder = [];
-        let current = ref[$changes].root[changeSet].next;
-        while (current) {
-            if (current.changeTree) {
-                encodeOrder.push(current.changeTree.refId);
-            }
-            current = current.next;
-        }
-        return encodeOrder;
+    [$onEncodeEnd]() {
+        this.deletedItems = {};
     }
-    static debugRefIdsFromDecoder(decoder) {
-        return this.debugRefIds(decoder.state, false, 0, decoder);
+    toArray() {
+        return Array.from(this.$items.values());
     }
-    /**
-     * 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} (${changeTree.refId}) -> .${changeSetName}:\n`;
-        function dumpChangeSet(changeSet) {
-            changeSet.operations
-                .filter(op => op)
-                .forEach((index) => {
-                const operation = changeTree.indexedOperations[index];
-                console.log({ index, operation });
-                output += `- [${index}]: ${exports.OPERATION[operation]} (${JSON.stringify(changeTree.getValue(Number(index), isEncodeAll))})\n`;
+    toJSON() {
+        const values = [];
+        this.forEach((value, key) => {
+            values.push((typeof (value['toJSON']) === "function")
+                ? value['toJSON']()
+                : value);
+        });
+        return values;
+    }
+    //
+    // Decoding utilities
+    //
+    clone(isDecoding) {
+        let cloned;
+        if (isDecoding) {
+            // client-side
+            cloned = Object.assign(new SetSchema(), this);
+        }
+        else {
+            // server-side
+            cloned = new SetSchema();
+            this.forEach((value) => {
+                if (value[$changes]) {
+                    cloned.add(value['clone']());
+                }
+                else {
+                    cloned.add(value);
+                }
             });
         }
-        dumpChangeSet(changeSet);
-        // display filtered changes
-        if (!isEncodeAll &&
-            changeTree.filteredChanges &&
-            (changeTree.filteredChanges.operations).filter(op => op).length > 0) {
-            output += `${instance.constructor.name} (${changeTree.refId}) -> .filteredChanges:\n`;
-            dumpChangeSet(changeTree.filteredChanges);
+        return cloned;
+    }
+}
+registerType("set", { constructor: SetSchema });
+
+const DEFAULT_VIEW_TAG = -1;
+function entity(constructor) {
+    TypeContext.register(constructor);
+    return constructor;
+}
+/**
+ * [See documentation](https://docs.colyseus.io/state/schema/)
+ *
+ * Annotate a Schema property to be serializeable.
+ * \@type()'d fields are automatically flagged as "dirty" for the next patch.
+ *
+ * @example Standard usage, with automatic change tracking.
+ * ```
+ * \@type("string") propertyName: string;
+ * ```
+ *
+ * @example You can provide the "manual" option if you'd like to manually control your patches via .setDirty().
+ * ```
+ * \@type("string", { manual: true })
+ * ```
+ */
+// export function type(type: DefinitionType, options?: TypeOptions) {
+//     return function ({ get, set }, context: ClassAccessorDecoratorContext): ClassAccessorDecoratorResult<Schema, any> {
+//         if (context.kind !== "accessor") {
+//             throw new Error("@type() is only supported for class accessor properties");
+//         }
+//         const field = context.name.toString();
+//         //
+//         // detect index for this field, considering inheritance
+//         //
+//         const parent = Object.getPrototypeOf(context.metadata);
+//         let fieldIndex: number = context.metadata[$numFields] // current structure already has fields defined
+//             ?? (parent && parent[$numFields]) // parent structure has fields defined
+//             ?? -1; // no fields defined
+//         fieldIndex++;
+//         if (
+//             !parent && // the parent already initializes the `$changes` property
+//             !Metadata.hasFields(context.metadata)
+//         ) {
+//             context.addInitializer(function (this: Ref) {
+//                 Object.defineProperty(this, $changes, {
+//                     value: new ChangeTree(this),
+//                     enumerable: false,
+//                     writable: true
+//                 });
+//             });
+//         }
+//         Metadata.addField(context.metadata, fieldIndex, field, type);
+//         const isArray = ArraySchema.is(type);
+//         const isMap = !isArray && MapSchema.is(type);
+//         // if (options && options.manual) {
+//         //     // do not declare getter/setter descriptor
+//         //     definition.descriptors[field] = {
+//         //         enumerable: true,
+//         //         configurable: true,
+//         //         writable: true,
+//         //     };
+//         //     return;
+//         // }
+//         return {
+//             init(value) {
+//                 // TODO: may need to convert ArraySchema/MapSchema here
+//                 // do not flag change if value is undefined.
+//                 if (value !== undefined) {
+//                     this[$changes].change(fieldIndex);
+//                     // automaticallty transform Array into ArraySchema
+//                     if (isArray) {
+//                         if (!(value instanceof ArraySchema)) {
+//                             value = new ArraySchema(...value);
+//                         }
+//                         value[$childType] = Object.values(type)[0];
+//                     }
+//                     // automaticallty transform Map into MapSchema
+//                     if (isMap) {
+//                         if (!(value instanceof MapSchema)) {
+//                             value = new MapSchema(value);
+//                         }
+//                         value[$childType] = Object.values(type)[0];
+//                     }
+//                     // try to turn provided structure into a Proxy
+//                     if (value['$proxy'] === undefined) {
+//                         if (isMap) {
+//                             value = getMapProxy(value);
+//                         }
+//                     }
+//                 }
+//                 return value;
+//             },
+//             get() {
+//                 return get.call(this);
+//             },
+//             set(value: any) {
+//                 /**
+//                  * Create Proxy for array or map items
+//                  */
+//                 // skip if value is the same as cached.
+//                 if (value === get.call(this)) {
+//                     return;
+//                 }
+//                 if (
+//                     value !== undefined &&
+//                     value !== null
+//                 ) {
+//                     // automaticallty transform Array into ArraySchema
+//                     if (isArray) {
+//                         if (!(value instanceof ArraySchema)) {
+//                             value = new ArraySchema(...value);
+//                         }
+//                         value[$childType] = Object.values(type)[0];
+//                     }
+//                     // automaticallty transform Map into MapSchema
+//                     if (isMap) {
+//                         if (!(value instanceof MapSchema)) {
+//                             value = new MapSchema(value);
+//                         }
+//                         value[$childType] = Object.values(type)[0];
+//                     }
+//                     // try to turn provided structure into a Proxy
+//                     if (value['$proxy'] === undefined) {
+//                         if (isMap) {
+//                             value = getMapProxy(value);
+//                         }
+//                     }
+//                     // flag the change for encoding.
+//                     this[$changes].change(fieldIndex);
+//                     //
+//                     // call setParent() recursively for this and its child
+//                     // structures.
+//                     //
+//                     if (value[$changes]) {
+//                         value[$changes].setParent(
+//                             this,
+//                             this[$changes].root,
+//                             Metadata.getIndex(context.metadata, field),
+//                         );
+//                     }
+//                 } else if (get.call(this)) {
+//                     //
+//                     // Setting a field to `null` or `undefined` will delete it.
+//                     //
+//                     this[$changes].delete(field);
+//                 }
+//                 set.call(this, value);
+//             },
+//         };
+//     }
+// }
+function view(tag = DEFAULT_VIEW_TAG) {
+    return function (target, fieldName) {
+        const constructor = target.constructor;
+        const parentClass = Object.getPrototypeOf(constructor);
+        const parentMetadata = parentClass[Symbol.metadata];
+        // TODO: use Metadata.initialize()
+        const metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
+        // const fieldIndex = metadata[fieldName];
+        // if (!metadata[fieldIndex]) {
+        //     //
+        //     // detect index for this field, considering inheritance
+        //     //
+        //     metadata[fieldIndex] = {
+        //         type: undefined,
+        //         index: (metadata[$numFields] // current structure already has fields defined
+        //             ?? (parentMetadata && parentMetadata[$numFields]) // parent structure has fields defined
+        //             ?? -1) + 1 // no fields defined
+        //     }
+        // }
+        Metadata.setTag(metadata, fieldName, tag);
+    };
+}
+function type(type, options) {
+    return function (target, field) {
+        const constructor = target.constructor;
+        if (!type) {
+            throw new Error(`${constructor.name}: @type() reference provided for "${field}" is undefined. Make sure you don't have any circular dependencies.`);
+        }
+        // Normalize type (enum/collection/etc)
+        type = getNormalizedType(type);
+        // for inheritance support
+        TypeContext.register(constructor);
+        const parentClass = Object.getPrototypeOf(constructor);
+        const parentMetadata = parentClass[Symbol.metadata];
+        const metadata = Metadata.initialize(constructor);
+        let fieldIndex = metadata[field];
+        /**
+         * skip if descriptor already exists for this field (`@deprecated()`)
+         */
+        if (metadata[fieldIndex] !== undefined) {
+            if (metadata[fieldIndex].deprecated) {
+                // do not create accessors for deprecated properties.
+                return;
+            }
+            else if (metadata[fieldIndex].type !== undefined) {
+                // trying to define same property multiple times across inheritance.
+                // https://github.com/colyseus/colyseus-unity3d/issues/131#issuecomment-814308572
+                try {
+                    throw new Error(`@colyseus/schema: Duplicate '${field}' definition on '${constructor.name}'.\nCheck @type() annotation`);
+                }
+                catch (e) {
+                    const definitionAtLine = e.stack.split("\n")[4].trim();
+                    throw new Error(`${e.message} ${definitionAtLine}`);
+                }
+            }
+        }
+        else {
+            //
+            // detect index for this field, considering inheritance
+            //
+            fieldIndex = metadata[$numFields] // current structure already has fields defined
+                ?? (parentMetadata && parentMetadata[$numFields]) // parent structure has fields defined
+                ?? -1; // no fields defined
+            fieldIndex++;
+        }
+        if (options && options.manual) {
+            Metadata.addField(metadata, fieldIndex, field, type, {
+                // do not declare getter/setter descriptor
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
         }
-        // display filtered changes
-        if (isEncodeAll &&
-            changeTree.allFilteredChanges &&
-            (changeTree.allFilteredChanges.operations).filter(op => op).length > 0) {
-            output += `${instance.constructor.name} (${changeTree.refId}) -> .allFilteredChanges:\n`;
-            dumpChangeSet(changeTree.allFilteredChanges);
+        else {
+            const complexTypeKlass = typeof (Object.keys(type)[0]) === "string" && getType(Object.keys(type)[0]);
+            const childType = (complexTypeKlass)
+                ? Object.values(type)[0]
+                : type;
+            Metadata.addField(metadata, fieldIndex, field, type, getPropertyDescriptor(`_${field}`, fieldIndex, childType, complexTypeKlass));
         }
-        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;
+    };
+}
+function getPropertyDescriptor(fieldCached, fieldIndex, type, complexTypeKlass) {
+    return {
+        get: function () { return this[fieldCached]; },
+        set: function (value) {
+            const previousValue = this[fieldCached] ?? undefined;
+            // skip if value is the same as cached.
+            if (value === previousValue) {
+                return;
             }
-            else {
-                while (parentChangeTree !== undefined) {
-                    parentChangeTrees.push(parentChangeTree);
-                    if (parentChangeTree.ref === ref) {
-                        includeChangeTree = true;
-                        break;
+            if (value !== undefined &&
+                value !== null) {
+                if (complexTypeKlass) {
+                    // automaticallty transform Array into ArraySchema
+                    if (complexTypeKlass.constructor === ArraySchema && !(value instanceof ArraySchema)) {
+                        value = new ArraySchema(...value);
                     }
-                    parentChangeTree = parentChangeTree.parent?.[$changes];
+                    // automaticallty transform Map into MapSchema
+                    if (complexTypeKlass.constructor === MapSchema && !(value instanceof MapSchema)) {
+                        value = new MapSchema(value);
+                    }
+                    value[$childType] = type;
                 }
-            }
-            if (includeChangeTree) {
-                instanceRefIds.push(changeTree.refId);
-                totalOperations += Object.keys(changes).length;
-                changeTrees.set(changeTree, parentChangeTrees.reverse());
-            }
-        }
-        output += "---\n";
-        output += `root refId: ${rootChangeTree.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.refId})\n`;
-                    visitedParents.add(parentChangeTree);
+                else if (typeof (type) !== "string") {
+                    assertInstanceType(value, type, this, fieldCached.substring(1));
                 }
-            });
-            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.refId}) - changes: ${Object.keys(changes).length}\n`;
-            for (const index in changes) {
-                const operation = changes[index];
-                output += `${getIndent(level + 1)}${exports.OPERATION[operation]}: ${index}\n`;
+                else {
+                    assertType(value, type, this, fieldCached.substring(1));
+                }
+                const changeTree = this[$changes];
+                //
+                // Replacing existing "ref", remove it from root.
+                //
+                if (previousValue !== undefined && previousValue[$changes]) {
+                    changeTree.root?.remove(previousValue[$changes]);
+                    this.constructor[$track](changeTree, fieldIndex, exports.OPERATION.DELETE_AND_ADD);
+                }
+                else {
+                    this.constructor[$track](changeTree, fieldIndex, exports.OPERATION.ADD);
+                }
+                //
+                // call setParent() recursively for this and its child
+                // structures.
+                //
+                value[$changes]?.setParent(this, changeTree.root, fieldIndex);
             }
-        }
-        return `${output}`;
-    }
+            else if (previousValue !== undefined) {
+                //
+                // Setting a field to `null` or `undefined` will delete it.
+                //
+                this[$changes].delete(fieldIndex);
+            }
+            this[fieldCached] = value;
+        },
+        enumerable: true,
+        configurable: true
+    };
 }
-
-var _a$1, _b$1;
-class CollectionSchema {
-    static { this[_a$1] = encodeKeyValueOperation; }
-    static { this[_b$1] = decodeKeyValueOperation; }
-    /**
-     * 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 [(_a$1 = $encoder, _b$1 = $decoder, $filter)](ref, index, view) {
-        return (!view ||
-            typeof (ref[$childType]) === "string" ||
-            view.isChangeTreeVisible((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes]));
-    }
-    static is(type) {
-        return type['collection'] !== undefined;
-    }
-    constructor(initialValues) {
-        this.$items = new Map();
-        this.$indexes = new Map();
-        this.deletedItems = {};
-        this.$refId = 0;
-        this[$changes] = new ChangeTree(this);
-        this[$changes].indexes = {};
-        if (initialValues) {
-            initialValues.forEach((v) => this.add(v));
+/**
+ * `@deprecated()` flag a field as deprecated.
+ * The previous `@type()` annotation should remain along with this one.
+ */
+function deprecated(throws = true) {
+    return function (klass, field) {
+        //
+        // FIXME: the following block of code is repeated across `@type()`, `@deprecated()` and `@unreliable()` decorators.
+        //
+        const constructor = klass.constructor;
+        const parentClass = Object.getPrototypeOf(constructor);
+        const parentMetadata = parentClass[Symbol.metadata];
+        const metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
+        const fieldIndex = metadata[field];
+        // if (!metadata[field]) {
+        //     //
+        //     // detect index for this field, considering inheritance
+        //     //
+        //     metadata[field] = {
+        //         type: undefined,
+        //         index: (metadata[$numFields] // current structure already has fields defined
+        //             ?? (parentMetadata && parentMetadata[$numFields]) // parent structure has fields defined
+        //             ?? -1) + 1 // no fields defined
+        //     }
+        // }
+        metadata[fieldIndex].deprecated = true;
+        if (throws) {
+            metadata[$descriptors] ??= {};
+            metadata[$descriptors][field] = {
+                get: function () { throw new Error(`${field} is deprecated.`); },
+                set: function (value) { },
+                enumerable: false,
+                configurable: true
+            };
         }
-        Object.defineProperty(this, $childType, {
-            value: undefined,
+        // flag metadata[field] as non-enumerable
+        Object.defineProperty(metadata, fieldIndex, {
+            value: metadata[fieldIndex],
             enumerable: false,
-            writable: true,
-            configurable: true,
+            configurable: true
         });
+    };
+}
+function defineTypes(target, fields, options) {
+    for (let field in fields) {
+        type(fields[field], options)(target.prototype, field);
     }
-    add(value) {
-        // set "index" for reference.
-        const index = this.$refId++;
-        const isRef = (value[$changes]) !== undefined;
-        if (isRef) {
-            value[$changes].setParent(this, this[$changes].root, index);
-        }
-        this[$changes].indexes[index] = index;
-        this.$indexes.set(index, index);
-        this.$items.set(index, value);
-        this[$changes].change(index);
-        return index;
-    }
-    at(index) {
-        const key = Array.from(this.$items.keys())[index];
-        return this.$items.get(key);
-    }
-    entries() {
-        return this.$items.entries();
-    }
-    delete(item) {
-        const entries = this.$items.entries();
-        let index;
-        let entry;
-        while (entry = entries.next()) {
-            if (entry.done) {
-                break;
+    return target;
+}
+function schema(fieldsAndMethods, name, inherits = Schema) {
+    const fields = {};
+    const methods = {};
+    const defaultValues = {};
+    const viewTagFields = {};
+    for (let fieldName in fieldsAndMethods) {
+        const value = fieldsAndMethods[fieldName];
+        if (typeof (value) === "object") {
+            if (value['view'] !== undefined) {
+                viewTagFields[fieldName] = (typeof (value['view']) === "boolean")
+                    ? DEFAULT_VIEW_TAG
+                    : value['view'];
             }
-            if (item === entry.value[1]) {
-                index = entry.value[0];
-                break;
+            fields[fieldName] = getNormalizedType(value);
+            // If no explicit default provided, handle automatic instantiation for collection types
+            if (!Object.prototype.hasOwnProperty.call(value, 'default')) {
+                // TODO: remove Array.isArray() check. Use ['array'] !== undefined only.
+                if (Array.isArray(value) || value['array'] !== undefined) {
+                    // Collection: Array → new ArraySchema()
+                    defaultValues[fieldName] = new ArraySchema();
+                }
+                else if (value['map'] !== undefined) {
+                    // Collection: Map → new MapSchema()
+                    defaultValues[fieldName] = new MapSchema();
+                }
+                else if (value['collection'] !== undefined) {
+                    // Collection: Collection → new CollectionSchema()
+                    defaultValues[fieldName] = new CollectionSchema();
+                }
+                else if (value['set'] !== undefined) {
+                    // Collection: Set → new SetSchema()
+                    defaultValues[fieldName] = new SetSchema();
+                }
+                else if (value['type'] !== undefined && Schema.is(value['type'])) {
+                    // Direct Schema type: Type → new Type()
+                    defaultValues[fieldName] = new value['type']();
+                }
+            }
+            else {
+                defaultValues[fieldName] = value['default'];
+            }
+        }
+        else if (typeof (value) === "function") {
+            if (Schema.is(value)) {
+                // Direct Schema type: Type → new Type()
+                defaultValues[fieldName] = new value();
+                fields[fieldName] = getNormalizedType(value);
+            }
+            else {
+                methods[fieldName] = value;
             }
         }
-        if (index === undefined) {
-            return false;
+        else {
+            fields[fieldName] = getNormalizedType(value);
         }
-        this.deletedItems[index] = this[$changes].delete(index);
-        this.$indexes.delete(index);
-        return this.$items.delete(index);
-    }
-    clear() {
-        const changeTree = this[$changes];
-        // discard previous operations.
-        changeTree.discard(true);
-        changeTree.indexes = {};
-        // remove children references
-        changeTree.forEachChild((childChangeTree, _) => {
-            changeTree.root?.remove(childChangeTree);
-        });
-        // clear previous indexes
-        this.$indexes.clear();
-        // clear items
-        this.$items.clear();
-        changeTree.operation(exports.OPERATION.CLEAR);
-    }
-    has(value) {
-        return Array.from(this.$items.values()).some((v) => v === value);
-    }
-    forEach(callbackfn) {
-        this.$items.forEach((value, key, _) => callbackfn(value, key, this));
-    }
-    values() {
-        return this.$items.values();
     }
-    get size() {
-        return this.$items.size;
-    }
-    /** Iterator */
-    [Symbol.iterator]() {
-        return this.$items.values();
-    }
-    setIndex(index, key) {
-        this.$indexes.set(index, key);
-    }
-    getIndex(index) {
-        return this.$indexes.get(index);
-    }
-    [$getByIndex](index) {
-        return this.$items.get(this.$indexes.get(index));
-    }
-    [$deleteByIndex](index) {
-        const key = this.$indexes.get(index);
-        this.$items.delete(key);
-        this.$indexes.delete(index);
-    }
-    [$onEncodeEnd]() {
-        this.deletedItems = {};
+    const getDefaultValues = () => {
+        const defaults = {};
+        for (const fieldName in defaultValues) {
+            const defaultValue = defaultValues[fieldName];
+            // If the default value has a clone method, use it to get a fresh instance
+            if (defaultValue && typeof defaultValue.clone === 'function') {
+                defaults[fieldName] = defaultValue.clone();
+            }
+            else {
+                // Otherwise, use the value as-is (for primitives and non-cloneable objects)
+                defaults[fieldName] = defaultValue;
+            }
+        }
+        return defaults;
+    };
+    const klass = Metadata.setFields(class extends inherits {
+        constructor(...args) {
+            args[0] = Object.assign({}, getDefaultValues(), args[0]);
+            super(...args);
+        }
+    }, fields);
+    for (let fieldName in viewTagFields) {
+        view(viewTagFields[fieldName])(klass.prototype, fieldName);
     }
-    toArray() {
-        return Array.from(this.$items.values());
+    for (let methodName in methods) {
+        klass.prototype[methodName] = methods[methodName];
     }
-    toJSON() {
-        const values = [];
-        this.forEach((value, key) => {
-            values.push((typeof (value['toJSON']) === "function")
-                ? value['toJSON']()
-                : value);
-        });
-        return values;
+    if (name) {
+        Object.defineProperty(klass, "name", { value: name });
     }
-    //
-    // Decoding utilities
-    //
-    clone(isDecoding) {
-        let cloned;
-        if (isDecoding) {
-            // client-side
-            cloned = Object.assign(new CollectionSchema(), this);
+    klass.extends = (fields, name) => schema(fields, name, klass);
+    return klass;
+}
+
+function getIndent(level) {
+    return (new Array(level).fill(0)).map((_, i) => (i === level - 1) ? `└─ ` : `   `).join("");
+}
+function dumpChanges(schema) {
+    const $root = schema[$changes].root;
+    const dump = {
+        ops: {},
+        refs: []
+    };
+    // for (const refId in $root.changes) {
+    let current = $root.changes.next;
+    while (current) {
+        const changeTree = current.changeTree;
+        // skip if ChangeTree is undefined
+        if (changeTree === undefined) {
+            current = current.next;
+            continue;
         }
-        else {
-            // server-side
-            cloned = new CollectionSchema();
-            this.forEach((value) => {
-                if (value[$changes]) {
-                    cloned.add(value['clone']());
-                }
-                else {
-                    cloned.add(value);
-                }
-            });
+        const changes = changeTree.indexedOperations;
+        dump.refs.push(`refId#${changeTree.refId}`);
+        for (const index in changes) {
+            const op = changes[index];
+            const opName = exports.OPERATION[op];
+            if (!dump.ops[opName]) {
+                dump.ops[opName] = 0;
+            }
+            dump.ops[exports.OPERATION[op]]++;
         }
-        return cloned;
+        current = current.next;
     }
+    return dump;
 }
-registerType("collection", { constructor: CollectionSchema, });
 
 var _a, _b;
-class SetSchema {
-    static { this[_a] = encodeKeyValueOperation; }
-    static { this[_b] = decodeKeyValueOperation; }
+/**
+ * Schema encoder / decoder
+ */
+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";
+        // const metadata = type[Symbol.metadata];
+        // return metadata && Object.prototype.hasOwnProperty.call(metadata, -1);
+    }
+    /**
+     * Track property changes
+     */
+    static [(_a = $encoder, _b = $decoder, $track)](changeTree, index, operation = exports.OPERATION.ADD) {
+        changeTree.change(index, operation);
+    }
     /**
      * Determine if a property must be filtered.
      * - If returns false, the property is NOT going to be encoded.
@@ -3692,164 +3675,248 @@ class SetSchema {
      * - 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 [(_a = $encoder, _b = $decoder, $filter)](ref, index, view) {
-        return (!view ||
-            typeof (ref[$childType]) === "string" ||
-            view.visible.has((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes]));
-    }
-    static is(type) {
-        return type['set'] !== undefined;
-    }
-    constructor(initialValues) {
-        this.$items = new Map();
-        this.$indexes = new Map();
-        this.deletedItems = {};
-        this.$refId = 0;
-        this[$changes] = new ChangeTree(this);
-        this[$changes].indexes = {};
-        if (initialValues) {
-            initialValues.forEach((v) => this.add(v));
-        }
-        Object.defineProperty(this, $childType, {
-            value: undefined,
-            enumerable: false,
-            writable: true,
-            configurable: true,
-        });
-    }
-    add(value) {
-        // immediatelly return false if value already added.
-        if (this.has(value)) {
-            return false;
-        }
-        // set "index" for reference.
-        const index = this.$refId++;
-        if ((value[$changes]) !== undefined) {
-            value[$changes].setParent(this, this[$changes].root, index);
-        }
-        const operation = this[$changes].indexes[index]?.op ?? exports.OPERATION.ADD;
-        this[$changes].indexes[index] = index;
-        this.$indexes.set(index, index);
-        this.$items.set(index, value);
-        this[$changes].change(index, operation);
-        return index;
-    }
-    entries() {
-        return this.$items.entries();
-    }
-    delete(item) {
-        const entries = this.$items.entries();
-        let index;
-        let entry;
-        while (entry = entries.next()) {
-            if (entry.done) {
-                break;
-            }
-            if (item === entry.value[1]) {
-                index = entry.value[0];
-                break;
-            }
+    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;
         }
-        if (index === undefined) {
-            return false;
+        else if (tag === undefined) {
+            // view pass: no tag
+            return true;
         }
-        this.deletedItems[index] = this[$changes].delete(index);
-        this.$indexes.delete(index);
-        return this.$items.delete(index);
-    }
-    clear() {
-        const changeTree = this[$changes];
-        // discard previous operations.
-        changeTree.discard(true);
-        changeTree.indexes = {};
-        // clear previous indexes
-        this.$indexes.clear();
-        // clear items
-        this.$items.clear();
-        changeTree.operation(exports.OPERATION.CLEAR);
-    }
-    has(value) {
-        const values = this.$items.values();
-        let has = false;
-        let entry;
-        while (entry = values.next()) {
-            if (entry.done) {
-                break;
-            }
-            if (value === entry.value) {
-                has = true;
-                break;
-            }
+        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);
         }
-        return has;
     }
-    forEach(callbackfn) {
-        this.$items.forEach((value, key, _) => callbackfn(value, key, this));
+    // allow inherited classes to have a constructor
+    constructor(...args) {
+        //
+        // inline
+        // Schema.initialize(this);
+        //
+        Schema.initialize(this);
+        //
+        // Assign initial values
+        //
+        if (args[0]) {
+            Object.assign(this, args[0]);
+        }
     }
-    values() {
-        return this.$items.values();
+    assign(props) {
+        Object.assign(this, props);
+        return this;
     }
-    get size() {
-        return this.$items.size;
+    /**
+     * (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);
     }
-    /** Iterator */
-    [Symbol.iterator]() {
-        return this.$items.values();
+    clone() {
+        const cloned = new (this.constructor);
+        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[metadata[fieldIndex]].name;
+            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;
     }
-    setIndex(index, key) {
-        this.$indexes.set(index, key);
+    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;
     }
-    getIndex(index) {
-        return this.$indexes.get(index);
+    /**
+     * Used in tests only
+     * @internal
+     */
+    discardAllChanges() {
+        this[$changes].discardAll();
     }
     [$getByIndex](index) {
-        return this.$items.get(this.$indexes.get(index));
+        const metadata = this.constructor[Symbol.metadata];
+        return this[metadata[index].name];
     }
     [$deleteByIndex](index) {
-        const key = this.$indexes.get(index);
-        this.$items.delete(key);
-        this.$indexes.delete(index);
+        const metadata = this.constructor[Symbol.metadata];
+        this[metadata[index].name] = undefined;
     }
-    [$onEncodeEnd]() {
-        this.deletedItems = {};
+    /**
+     * 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 = (decoder) ? decoder.root.refIds.get(ref) : changeTree.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;
     }
-    toArray() {
-        return Array.from(this.$items.values());
+    static debugRefIdEncodingOrder(ref, changeSet = 'allChanges') {
+        let encodeOrder = [];
+        let current = ref[$changes].root[changeSet].next;
+        while (current) {
+            if (current.changeTree) {
+                encodeOrder.push(current.changeTree.refId);
+            }
+            current = current.next;
+        }
+        return encodeOrder;
     }
-    toJSON() {
-        const values = [];
-        this.forEach((value, key) => {
-            values.push((typeof (value['toJSON']) === "function")
-                ? value['toJSON']()
-                : value);
-        });
-        return values;
+    static debugRefIdsFromDecoder(decoder) {
+        return this.debugRefIds(decoder.state, false, 0, decoder);
     }
-    //
-    // Decoding utilities
-    //
-    clone(isDecoding) {
-        let cloned;
-        if (isDecoding) {
-            // client-side
-            cloned = Object.assign(new SetSchema(), this);
+    /**
+     * 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} (${changeTree.refId}) -> .${changeSetName}:\n`;
+        function dumpChangeSet(changeSet) {
+            changeSet.operations
+                .filter(op => op)
+                .forEach((index) => {
+                const operation = changeTree.indexedOperations[index];
+                output += `- [${index}]: ${exports.OPERATION[operation]} (${JSON.stringify(changeTree.getValue(Number(index), isEncodeAll))})\n`;
+            });
         }
-        else {
-            // server-side
-            cloned = new SetSchema();
-            this.forEach((value) => {
-                if (value[$changes]) {
-                    cloned.add(value['clone']());
+        dumpChangeSet(changeSet);
+        // display filtered changes
+        if (!isEncodeAll &&
+            changeTree.filteredChanges &&
+            (changeTree.filteredChanges.operations).filter(op => op).length > 0) {
+            output += `${instance.constructor.name} (${changeTree.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} (${changeTree.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];
                 }
-                else {
-                    cloned.add(value);
+            }
+            if (includeChangeTree) {
+                instanceRefIds.push(changeTree.refId);
+                totalOperations += Object.keys(changes).length;
+                changeTrees.set(changeTree, parentChangeTrees.reverse());
+            }
+        }
+        output += "---\n";
+        output += `root refId: ${rootChangeTree.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.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.refId}) - changes: ${Object.keys(changes).length}\n`;
+            for (const index in changes) {
+                const operation = changes[index];
+                output += `${getIndent(level + 1)}${exports.OPERATION[operation]}: ${index}\n`;
+            }
         }
-        return cloned;
+        return `${output}`;
     }
 }
-registerType("set", { constructor: SetSchema });
 
 /******************************************************************************
 Copyright (c) Microsoft Corporation.