@colyseus/schema 3.0.51 → 3.0.53

package/build/umd/index.js

@@ -967,27 +967,13 @@
         }
     };
 
-    function createChangeSet() {
-        return { indexes: {}, operations: [] };
+    function createChangeSet(queueRootNode) {
+        return { indexes: {}, operations: [], queueRootNode };
     }
     // Linked list helper functions
     function createChangeTreeList() {
         return { next: undefined, tail: undefined, length: 0 };
     }
-    function addToChangeTreeList(list, changeTree) {
-        const node = { changeTree, next: undefined, prev: undefined };
-        if (!list.next) {
-            list.next = node;
-            list.tail = node;
-        }
-        else {
-            node.prev = list.tail;
-            list.tail.next = node;
-            list.tail = node;
-        }
-        list.length++;
-        return node;
-    }
     function setOperationAtIndex(changeSet, index) {
         const operationsIndex = changeSet.indexes[index];
         if (operationsIndex === undefined) {
@@ -1012,17 +998,6 @@
         changeSet.operations[operationsIndex] = undefined;
         delete changeSet.indexes[index];
     }
-    function enqueueChangeTree(root, changeTree, changeSet, queueRootNode = changeTree[changeSet].queueRootNode) {
-        // skip
-        if (!root) {
-            return;
-        }
-        if (queueRootNode) ;
-        else {
-            // Add to linked list if not already present
-            changeTree[changeSet].queueRootNode = addToChangeTreeList(root[changeSet], changeTree);
-        }
-    }
     class ChangeTree {
         constructor(ref) {
             /**
@@ -1128,11 +1103,11 @@
             // this is checked during .encode() time.
             if (this.filteredChanges !== undefined) {
                 this.filteredChanges.operations.push(-op);
-                enqueueChangeTree(this.root, this, 'filteredChanges');
+                this.root?.enqueueChangeTree(this, 'filteredChanges');
             }
             else {
                 this.changes.operations.push(-op);
-                enqueueChangeTree(this.root, this, 'changes');
+                this.root?.enqueueChangeTree(this, 'changes');
             }
         }
         change(index, operation = exports.OPERATION.ADD) {
@@ -1156,13 +1131,13 @@
             if (isFiltered) {
                 setOperationAtIndex(this.allFilteredChanges, index);
                 if (this.root) {
-                    enqueueChangeTree(this.root, this, 'filteredChanges');
-                    enqueueChangeTree(this.root, this, 'allFilteredChanges');
+                    this.root.enqueueChangeTree(this, 'filteredChanges');
+                    this.root.enqueueChangeTree(this, 'allFilteredChanges');
                 }
             }
             else {
                 setOperationAtIndex(this.allChanges, index);
-                enqueueChangeTree(this.root, this, 'changes');
+                this.root?.enqueueChangeTree(this, 'changes');
             }
         }
         shiftChangeIndexes(shiftIndex) {
@@ -1217,12 +1192,12 @@
             if (this.filteredChanges !== undefined) {
                 setOperationAtIndex(this.allFilteredChanges, allChangesIndex);
                 setOperationAtIndex(this.filteredChanges, index);
-                enqueueChangeTree(this.root, this, 'filteredChanges');
+                this.root?.enqueueChangeTree(this, 'filteredChanges');
             }
             else {
                 setOperationAtIndex(this.allChanges, allChangesIndex);
                 setOperationAtIndex(this.changes, index);
-                enqueueChangeTree(this.root, this, 'changes');
+                this.root?.enqueueChangeTree(this, 'changes');
             }
         }
         getType(index) {
@@ -1285,10 +1260,10 @@
             //
             if (this.filteredChanges !== undefined) {
                 deleteOperationAtIndex(this.allFilteredChanges, allChangesIndex);
-                enqueueChangeTree(this.root, this, 'filteredChanges');
+                this.root?.enqueueChangeTree(this, 'filteredChanges');
             }
             else {
-                enqueueChangeTree(this.root, this, 'changes');
+                this.root?.enqueueChangeTree(this, 'changes');
             }
             return previousValue;
         }
@@ -1314,9 +1289,10 @@
                 this.filteredChanges = createChangeSet();
             }
             if (discardAll) {
-                this.allChanges = createChangeSet();
+                // preserve queueRootNode references
+                this.allChanges = createChangeSet(this.allChanges.queueRootNode);
                 if (this.allFilteredChanges !== undefined) {
-                    this.allFilteredChanges = createChangeSet();
+                    this.allFilteredChanges = createChangeSet(this.allFilteredChanges.queueRootNode);
                 }
             }
         }
@@ -1347,16 +1323,16 @@
                 //
                 this._checkFilteredByParent(parent, parentIndex);
                 if (this.filteredChanges !== undefined) {
-                    enqueueChangeTree(this.root, this, 'filteredChanges');
+                    this.root?.enqueueChangeTree(this, 'filteredChanges');
                     if (isNewChangeTree) {
-                        enqueueChangeTree(this.root, this, 'allFilteredChanges');
+                        this.root?.enqueueChangeTree(this, 'allFilteredChanges');
                     }
                 }
             }
             if (!this.isFiltered) {
-                enqueueChangeTree(this.root, this, 'changes');
+                this.root?.enqueueChangeTree(this, 'changes');
                 if (isNewChangeTree) {
-                    enqueueChangeTree(this.root, this, 'allChanges');
+                    this.root?.enqueueChangeTree(this, 'allChanges');
                 }
             }
         }
@@ -2213,7 +2189,7 @@
             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();
         }
         /**
@@ -2308,10 +2284,10 @@
             // FIXME: this code block is duplicated on ChangeTree
             //
             if (changeTree.filteredChanges !== undefined) {
-                enqueueChangeTree(changeTree.root, changeTree, 'filteredChanges');
+                changeTree.root?.enqueueChangeTree(changeTree, 'filteredChanges');
             }
             else {
-                enqueueChangeTree(changeTree.root, changeTree, 'changes');
+                changeTree.root?.enqueueChangeTree(changeTree, 'changes');
             }
             return this.items.splice(start, deleteCount, ...insertItems);
         }
@@ -2726,6 +2702,9 @@
                         previousValue[$changes].root?.remove(previousValue[$changes]);
                     }
                 }
+                if (this.deletedItems[index]) {
+                    delete this.deletedItems[index];
+                }
             }
             else {
                 index = changeTree.indexes[$numFields] ?? 0;
@@ -2845,448 +2824,174 @@
     }
     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.`);
+    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));
             }
-            // 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}`);
-                    }
-                }
+            Object.defineProperty(this, $childType, {
+                value: undefined,
+                enumerable: false,
+                writable: true,
+                configurable: true,
+            });
+        }
+        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);
             }
-            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,
-                });
-            }
-            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],
-                enumerable: false,
-                configurable: true
-            });
-        };
-    }
-    function defineTypes(target, fields, options) {
-        for (let field in fields) {
-            type(fields[field], options)(target.prototype, field);
+            this[$changes].indexes[index] = index;
+            this.$indexes.set(index, index);
+            this.$items.set(index, value);
+            this[$changes].change(index);
+            return index;
         }
-        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'];
+        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;
                 }
-                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] = value;
-            }
-            else if (typeof (value) === "function") {
-                methods[fieldName] = value;
             }
-            else {
-                fields[fieldName] = value;
+            if (index === undefined) {
+                return false;
             }
+            this.deletedItems[index] = this[$changes].delete(index);
+            this.$indexes.delete(index);
+            return this.$items.delete(index);
         }
-        const klass = Metadata.setFields(class extends inherits {
-            constructor(...args) {
-                args[0] = Object.assign({}, defaultValues, args[0]);
-                super(...args);
-            }
-        }, fields);
-        for (let fieldName in viewTagFields) {
-            view(viewTagFields[fieldName])(klass.prototype, fieldName);
+        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);
         }
-        for (let methodName in methods) {
-            klass.prototype[methodName] = methods[methodName];
+        has(value) {
+            return Array.from(this.$items.values()).some((v) => v === value);
         }
-        if (name) {
-            Object.defineProperty(klass, "name", { value: name });
+        forEach(callbackfn) {
+            this.$items.forEach((value, key, _) => callbackfn(value, key, 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;
-            }
-            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]]++;
-            }
-            current = current.next;
+        values() {
+            return this.$items.values();
         }
-        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
-            });
-            Object.defineProperties(instance, instance.constructor[Symbol.metadata]?.[$descriptors] || {});
+        get size() {
+            return this.$items.size;
         }
-        static is(type) {
-            return typeof (type[Symbol.metadata]) === "object";
-            // const metadata = type[Symbol.metadata];
-            // return metadata && Object.prototype.hasOwnProperty.call(metadata, -1);
+        /** Iterator */
+        [Symbol.iterator]() {
+            return this.$items.values();
         }
-        /**
-         * Track property changes
-         */
-        static [(_a$2 = $encoder, _b$2 = $decoder, $track)](changeTree, index, operation = exports.OPERATION.ADD) {
-            changeTree.change(index, operation);
+        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.
@@ -3296,418 +3001,652 @@
          * - 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;
+            const key = this.$indexes.get(index);
+            this.$items.delete(key);
+            this.$indexes.delete(index);
         }
-        /**
-         * 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;
+        [$onEncodeEnd]() {
+            this.deletedItems = {};
         }
-        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;
+        toArray() {
+            return Array.from(this.$items.values());
         }
-        static debugRefIdsFromDecoder(decoder) {
-            return this.debugRefIds(decoder.state, false, 0, decoder);
+        toJSON() {
+            const values = [];
+            this.forEach((value, key) => {
+                values.push((typeof (value['toJSON']) === "function")
+                    ? value['toJSON']()
+                    : value);
+            });
+            return 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`;
+        //
+        // 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.`);
             }
-            // 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);
+            // 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,
+                });
+            }
+            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));
             }
-            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);
+        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'];
+                }
+                fields[fieldName] = value;
+                // If no explicit default provided, handle automatic instantiation for collection types
+                if (!Object.prototype.hasOwnProperty.call(value, 'default')) {
+                    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'];
+                }
             }
-            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;
+            else if (typeof (value) === "function") {
+                if (Schema.is(value)) {
+                    // Direct Schema type: Type → new Type()
+                    defaultValues[fieldName] = new value();
+                    fields[fieldName] = value;
+                }
+                else {
+                    methods[fieldName] = value;
+                }
+            }
+            else {
+                fields[fieldName] = value;
+            }
+        }
+        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();
                 }
-                if (item === entry.value[1]) {
-                    index = entry.value[0];
-                    break;
+                else {
+                    // Otherwise, use the value as-is (for primitives and non-cloneable objects)
+                    defaults[fieldName] = defaultValue;
                 }
             }
-            if (index === undefined) {
-                return false;
+            return defaults;
+        };
+        const klass = Metadata.setFields(class extends inherits {
+            constructor(...args) {
+                args[0] = Object.assign({}, getDefaultValues(), args[0]);
+                super(...args);
             }
-            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 = {};
+        }, 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.
@@ -3717,164 +3656,248 @@
          * - 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));
+        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;
             }
-            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;
+            else if (tag === undefined) {
+                // view pass: no tag
+                return true;
             }
-            // set "index" for reference.
-            const index = this.$refId++;
-            if ((value[$changes]) !== undefined) {
-                value[$changes].setParent(this, this[$changes].root, index);
+            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);
             }
-            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();
+        // 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]);
+            }
         }
-        delete(item) {
-            const entries = this.$items.entries();
-            let index;
-            let entry;
-            while (entry = entries.next()) {
-                if (entry.done) {
-                    break;
+        assign(props) {
+            Object.assign(this, props);
+            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() {
+            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();
                 }
-                if (item === entry.value[1]) {
-                    index = entry.value[0];
-                    break;
+                else {
+                    // primitive values
+                    cloned[field] = this[field];
                 }
             }
-            if (index === undefined) {
-                return false;
-            }
-            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);
+            return cloned;
         }
-        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;
+        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 has;
-        }
-        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);
+            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.
@@ -3944,11 +3967,12 @@
                 }
             }
             this.refCount[changeTree.refId] = (previousRefCount || 0) + 1;
-            // console.log("ADD", { refId: changeTree.refId, refCount: this.refCount[changeTree.refId] });
+            // console.log("ADD", { refId: changeTree.refId, ref: changeTree.ref.constructor.name, refCount: this.refCount[changeTree.refId], isNewChangeTree });
             return isNewChangeTree;
         }
         remove(changeTree) {
             const refCount = (this.refCount[changeTree.refId]) - 1;
+            // console.log("REMOVE", { refId: changeTree.refId, ref: changeTree.ref.constructor.name, refCount, needRemove: refCount <= 0 });
             if (refCount <= 0) {
                 //
                 // Only remove "root" reference if it's the last reference
@@ -4031,6 +4055,28 @@
             }
             changeSet.tail = node;
         }
+        enqueueChangeTree(changeTree, changeSet, queueRootNode = changeTree[changeSet].queueRootNode) {
+            // skip
+            if (queueRootNode) {
+                return;
+            }
+            // Add to linked list if not already present
+            changeTree[changeSet].queueRootNode = this.addToChangeTreeList(this[changeSet], changeTree);
+        }
+        addToChangeTreeList(list, changeTree) {
+            const node = { changeTree, next: undefined, prev: undefined };
+            if (!list.next) {
+                list.next = node;
+                list.tail = node;
+            }
+            else {
+                node.prev = list.tail;
+                list.tail.next = node;
+                list.tail = node;
+            }
+            list.length++;
+            return node;
+        }
         removeChangeFromChangeSet(changeSetName, changeTree) {
             const changeSet = this[changeSetName];
             const node = changeTree[changeSetName].queueRootNode;