@colyseus/schema 3.0.0-alpha.3 → 3.0.0-alpha.31

package/build/cjs/index.js

@@ -1,7 +1,5 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 const SWITCH_TO_STRUCTURE = 255; // (decoding collides with DELETE_AND_ADD + fieldIndex = 63)
 const TYPE_ID = 213;
 /**
@@ -27,6 +25,7 @@ exports.OPERATION = void 0;
     OPERATION[OPERATION["REVERSE"] = 15] = "REVERSE";
     OPERATION[OPERATION["MOVE"] = 32] = "MOVE";
     OPERATION[OPERATION["DELETE_BY_REFID"] = 33] = "DELETE_BY_REFID";
+    OPERATION[OPERATION["ADD_BY_REFID"] = 129] = "ADD_BY_REFID";
 })(exports.OPERATION || (exports.OPERATION = {}));
 
 Symbol.metadata ??= Symbol.for("Symbol.metadata");
@@ -37,6 +36,7 @@ const $decoder = Symbol("$decoder");
 const $filter = Symbol("$filter");
 const $getByIndex = Symbol("$getByIndex");
 const $deleteByIndex = Symbol("$deleteByIndex");
+const $descriptors = Symbol("$descriptors");
 /**
  * Used to hold ChangeTree instances whitin the structures
  */
@@ -72,34 +72,67 @@ function getType(identifier) {
 }
 
 const Metadata = {
-    addField(metadata, index, field, type, descriptor) {
+    addField(metadata, index, name, type, descriptor) {
         if (index > 64) {
-            throw new Error(`Can't define field '${field}'.\nSchema instances may only have up to 64 fields.`);
+            throw new Error(`Can't define field '${name}'.\nSchema instances may only have up to 64 fields.`);
         }
-        metadata[field] = Object.assign(metadata[field] || {}, // avoid overwriting previous field metadata (@owned / @deprecated)
+        metadata[index] = Object.assign(metadata[index] || {}, // avoid overwriting previous field metadata (@owned / @deprecated)
         {
             type: (Array.isArray(type))
                 ? { array: type[0] }
                 : type,
             index,
-            descriptor,
+            name,
         });
+        // create "descriptors" map
+        metadata[$descriptors] ??= {};
+        if (descriptor) {
+            // for encoder
+            metadata[$descriptors][name] = descriptor;
+            metadata[$descriptors][`_${name}`] = {
+                value: undefined,
+                writable: true,
+                enumerable: false,
+                configurable: true,
+            };
+        }
+        else {
+            // for decoder
+            metadata[$descriptors][name] = {
+                value: undefined,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            };
+        }
         // map -1 as last field index
         Object.defineProperty(metadata, -1, {
             value: index,
             enumerable: false,
             configurable: true
         });
-        // map index => field name (non enumerable)
-        Object.defineProperty(metadata, index, {
-            value: field,
+        // map field name => index (non enumerable)
+        Object.defineProperty(metadata, name, {
+            value: index,
             enumerable: false,
             configurable: true,
         });
+        // if child Ref/complex type, add to -4
+        if (typeof (metadata[index].type) !== "string") {
+            if (metadata[-4] === undefined) {
+                Object.defineProperty(metadata, -4, {
+                    value: [],
+                    enumerable: false,
+                    configurable: true,
+                });
+            }
+            metadata[-4].push(index);
+        }
     },
     setTag(metadata, fieldName, tag) {
+        const index = metadata[fieldName];
+        const field = metadata[index];
         // add 'tag' to the field
-        const field = metadata[fieldName];
         field.tag = tag;
         if (!metadata[-2]) {
             // -2: all field indexes with "view" tag
@@ -115,20 +148,14 @@ const Metadata = {
                 configurable: true
             });
         }
-        metadata[-2].push(field.index);
+        metadata[-2].push(index);
         if (!metadata[-3][tag]) {
             metadata[-3][tag] = [];
         }
-        metadata[-3][tag].push(field.index);
+        metadata[-3][tag].push(index);
     },
     setFields(target, fields) {
         const metadata = (target.prototype.constructor[Symbol.metadata] ??= {});
-        // target[$track] = function (changeTree, index: number, operation: OPERATION = OPERATION.ADD) {
-        //     changeTree.change(index, operation, encodeSchemaOperation);
-        // };
-        // target[$encoder] = encodeSchemaOperation;
-        // target[$decoder] = decodeSchemaOperation;
-        // if (!target.prototype.toJSON) { target.prototype.toJSON = Schema.prototype.toJSON; }
         let index = 0;
         for (const field in fields) {
             const type = fields[field];
@@ -136,13 +163,53 @@ const Metadata = {
             const complexTypeKlass = (Array.isArray(type))
                 ? getType("array")
                 : (typeof (Object.keys(type)[0]) === "string") && getType(Object.keys(type)[0]);
-            Metadata.addField(metadata, index, field, type, getPropertyDescriptor(`_${field}`, index, type, complexTypeKlass, metadata, field));
+            Metadata.addField(metadata, index, field, type, getPropertyDescriptor(`_${field}`, index, type, complexTypeKlass));
             index++;
         }
     },
     isDeprecated(metadata, field) {
         return metadata[field].deprecated === true;
     },
+    init(klass) {
+        //
+        // Used only to initialize an empty Schema (Encoder#constructor)
+        // TODO: remove/refactor this...
+        //
+        const metadata = {};
+        klass[Symbol.metadata] = metadata;
+        Object.defineProperty(metadata, -1, {
+            value: 0,
+            enumerable: false,
+            configurable: true,
+        });
+    },
+    initialize(constructor, parentMetadata) {
+        let metadata = constructor[Symbol.metadata] ?? Object.create(null);
+        // make sure inherited classes have their own metadata object.
+        if (constructor[Symbol.metadata] === parentMetadata) {
+            metadata = Object.create(null);
+            if (parentMetadata) {
+                // assign parent metadata to current
+                Object.assign(metadata, parentMetadata);
+                for (let i = 0; i <= parentMetadata[-1]; i++) {
+                    const fieldName = parentMetadata[i].name;
+                    Object.defineProperty(metadata, fieldName, {
+                        value: parentMetadata[fieldName],
+                        enumerable: false,
+                        configurable: true,
+                    });
+                }
+                Object.defineProperty(metadata, -1, {
+                    value: parentMetadata[-1],
+                    enumerable: false,
+                    configurable: true,
+                    writable: true,
+                });
+            }
+        }
+        constructor[Symbol.metadata] = metadata;
+        return metadata;
+    },
     isValidInstance(klass) {
         return (klass.constructor[Symbol.metadata] &&
             Object.prototype.hasOwnProperty.call(klass.constructor[Symbol.metadata], -1));
@@ -151,97 +218,68 @@ const Metadata = {
         const metadata = klass[Symbol.metadata];
         const fields = {};
         for (let i = 0; i <= metadata[-1]; i++) {
-            fields[metadata[i]] = metadata[metadata[i]].type;
+            fields[metadata[i].name] = metadata[i].type;
         }
         return fields;
     }
 };
 
 var _a$5;
-class Root {
-    constructor() {
-        this.nextUniqueId = 0;
-        this.refCount = new WeakMap();
-        // all changes
-        this.allChanges = new Map();
-        this.allFilteredChanges = new Map();
-        // pending changes to be encoded
-        this.changes = new Map();
-        this.filteredChanges = new Map();
-    }
-    getNextUniqueId() {
-        return this.nextUniqueId++;
-    }
-    add(changeTree) {
-        const refCount = this.refCount.get(changeTree) || 0;
-        this.refCount.set(changeTree, refCount + 1);
-    }
-    remove(changeTree) {
-        const refCount = this.refCount.get(changeTree);
-        if (refCount <= 1) {
-            this.allChanges.delete(changeTree);
-            this.changes.delete(changeTree);
-            if (changeTree.isFiltered || changeTree.isPartiallyFiltered) {
-                this.allFilteredChanges.delete(changeTree);
-                this.filteredChanges.delete(changeTree);
-            }
-            this.refCount.delete(changeTree);
-        }
-        else {
-            this.refCount.set(changeTree, refCount - 1);
-        }
-        changeTree.forEachChild((child, _) => this.remove(child));
-    }
-    clear() {
-        this.changes.clear();
-    }
-}
 class ChangeTree {
     static { _a$5 = $isNew; }
-    ;
     constructor(ref) {
-        this.indexes = {}; // TODO: remove this, only used by MapSchema/SetSchema/CollectionSchema (`encodeKeyValueOperation`)
+        this.isFiltered = false;
+        this.isPartiallyFiltered = false;
         this.currentOperationIndex = 0;
-        this.allChanges = new Map();
-        this.allFilteredChanges = new Map();
         this.changes = new Map();
-        this.filteredChanges = new Map();
+        this.allChanges = new Map();
         this[_a$5] = true;
         this.ref = ref;
+        //
+        // Does this structure have "filters" declared?
+        //
+        if (ref.constructor[Symbol.metadata]?.[-2]) {
+            this.allFilteredChanges = new Map();
+            this.filteredChanges = new Map();
+        }
     }
     setRoot(root) {
         this.root = root;
         this.root.add(this);
-        //
-        // At Schema initialization, the "root" structure might not be available
-        // yet, as it only does once the "Encoder" has been set up.
-        //
-        // So the "parent" may be already set without a "root".
-        //
-        this.checkIsFiltered(this.parent, this.parentIndex);
-        // unique refId for the ChangeTree.
-        this.ensureRefId();
+        const metadata = this.ref.constructor[Symbol.metadata];
+        if (this.root.types.hasFilters) {
+            //
+            // At Schema initialization, the "root" structure might not be available
+            // yet, as it only does once the "Encoder" has been set up.
+            //
+            // So the "parent" may be already set without a "root".
+            //
+            this.checkIsFiltered(metadata, this.parent, this.parentIndex);
+            if (this.isFiltered || this.isPartiallyFiltered) {
+                this.root.allFilteredChanges.set(this, this.allFilteredChanges);
+                this.root.filteredChanges.set(this, this.filteredChanges);
+            }
+        }
         if (!this.isFiltered) {
             this.root.changes.set(this, this.changes);
+            this.root.allChanges.set(this, this.allChanges);
         }
-        if (this.isFiltered || this.isPartiallyFiltered) {
-            this.root.allFilteredChanges.set(this, this.allFilteredChanges);
-            this.root.filteredChanges.set(this, this.filteredChanges);
-            // } else {
-            //     this.root.allChanges.set(this, this.allChanges);
+        this.ensureRefId();
+        if (metadata) {
+            metadata[-4]?.forEach((index) => {
+                const field = metadata[index];
+                const value = this.ref[field.name];
+                if (value) {
+                    value[$changes].setRoot(root);
+                }
+            });
         }
-        if (!this.isFiltered) {
-            this.root.allChanges.set(this, this.allChanges);
+        else if (this.ref[$childType] && typeof (this.ref[$childType]) !== "string") {
+            // MapSchema / ArraySchema, etc.
+            this.ref.forEach((value, key) => {
+                value[$changes].setRoot(root);
+            });
         }
-        this.forEachChild((changeTree, _) => {
-            changeTree.setRoot(root);
-        });
-        // this.allChanges.forEach((_, index) => {
-        //     const childRef = this.ref[$getByIndex](index);
-        //     if (childRef && childRef[$changes]) {
-        //         childRef[$changes].setRoot(root);
-        //     }
-        // });
     }
     setParent(parent, root, parentIndex) {
         this.parent = parent;
@@ -251,50 +289,60 @@ class ChangeTree {
             return;
         }
         root.add(this);
+        const metadata = this.ref.constructor[Symbol.metadata];
         // skip if parent is already set
-        if (root === this.root) {
-            this.forEachChild((changeTree, atIndex) => {
-                changeTree.setParent(this.ref, root, atIndex);
-            });
-            return;
-        }
-        this.root = root;
-        this.checkIsFiltered(parent, parentIndex);
-        if (!this.isFiltered) {
-            this.root.changes.set(this, this.changes);
+        if (root !== this.root) {
+            this.root = root;
+            if (root.types.hasFilters) {
+                this.checkIsFiltered(metadata, parent, parentIndex);
+                if (this.isFiltered || this.isPartiallyFiltered) {
+                    this.root.filteredChanges.set(this, this.filteredChanges);
+                    this.root.allFilteredChanges.set(this, this.filteredChanges);
+                }
+            }
+            if (!this.isFiltered) {
+                this.root.changes.set(this, this.changes);
+                this.root.allChanges.set(this, this.allChanges);
+            }
+            this.ensureRefId();
         }
-        if (this.isFiltered || this.isPartiallyFiltered) {
-            this.root.filteredChanges.set(this, this.filteredChanges);
-            this.root.allFilteredChanges.set(this, this.filteredChanges);
+        // assign same parent on child structures
+        if (metadata) {
+            metadata[-4]?.forEach((index) => {
+                const field = metadata[index];
+                const value = this.ref[field.name];
+                value?.[$changes].setParent(this.ref, root, index);
+                // console.log(this.ref.constructor.name, field.name, value);
+                // try { throw new Error(); } catch (e) {
+                //     console.log(e.stack);
+                // }
+            });
         }
-        else {
-            this.root.allChanges.set(this, this.allChanges);
+        else if (this.ref[$childType] && typeof (this.ref[$childType]) !== "string") {
+            // MapSchema / ArraySchema, etc.
+            this.ref.forEach((value, key) => {
+                value[$changes].setParent(this.ref, root, this.indexes[key] ?? key);
+            });
         }
-        this.ensureRefId();
-        this.forEachChild((changeTree, atIndex) => {
-            changeTree.setParent(this.ref, root, atIndex);
-        });
     }
     forEachChild(callback) {
         //
         // assign same parent on child structures
         //
-        if (Metadata.isValidInstance(this.ref)) {
-            const metadata = this.ref['constructor'][Symbol.metadata];
-            // FIXME: need to iterate over parent metadata instead.
-            for (const field in metadata) {
-                const value = this.ref[field];
-                if (value && value[$changes]) {
-                    callback(value[$changes], metadata[field].index);
+        const metadata = this.ref.constructor[Symbol.metadata];
+        if (metadata) {
+            metadata[-4]?.forEach((index) => {
+                const field = metadata[index];
+                const value = this.ref[field.name];
+                if (value) {
+                    callback(value[$changes], index);
                 }
-            }
+            });
         }
-        else if (typeof (this.ref) === "object") {
+        else if (this.ref[$childType] && typeof (this.ref[$childType]) !== "string") {
             // MapSchema / ArraySchema, etc.
             this.ref.forEach((value, key) => {
-                if (Metadata.isValidInstance(value)) {
-                    callback(value[$changes], this.ref[$changes].indexes[key]);
-                }
+                callback(value[$changes], this.indexes[key] ?? key);
             });
         }
     }
@@ -303,8 +351,8 @@ class ChangeTree {
         this.root?.changes.set(this, this.changes);
     }
     change(index, operation = exports.OPERATION.ADD) {
-        const metadata = this.ref['constructor'][Symbol.metadata];
-        const isFiltered = this.isFiltered || (metadata && metadata[metadata[index]].tag !== undefined);
+        const metadata = this.ref.constructor[Symbol.metadata];
+        const isFiltered = this.isFiltered || (metadata?.[index]?.tag !== undefined);
         const changeSet = (isFiltered)
             ? this.filteredChanges
             : this.changes;
@@ -315,14 +363,15 @@ class ChangeTree {
                 : (previousOperation === exports.OPERATION.DELETE)
                     ? exports.OPERATION.DELETE_AND_ADD
                     : operation;
+            //
+            // TODO: are DELETE operations being encoded as ADD here ??
+            //
             changeSet.set(index, op);
         }
-        //
-        // TODO: are DELETE operations being encoded as ADD here ??
-        //
         if (isFiltered) {
             this.allFilteredChanges.set(index, exports.OPERATION.ADD);
             this.root?.filteredChanges.set(this, this.filteredChanges);
+            this.root?.allFilteredChanges.set(this, this.allFilteredChanges);
         }
         else {
             this.allChanges.set(index, exports.OPERATION.ADD);
@@ -361,7 +410,6 @@ class ChangeTree {
     }
     _shiftAllChangeIndexes(shiftIndex, startIndex = 0, allChangeSet) {
         Array.from(allChangeSet.entries()).forEach(([index, op]) => {
-            // console.log('shiftAllChangeIndexes', index >= startIndex, { index, op, shiftIndex, startIndex })
             if (index >= startIndex) {
                 allChangeSet.delete(index);
                 allChangeSet.set(index + shiftIndex, op);
@@ -369,9 +417,7 @@ class ChangeTree {
         });
     }
     indexedOperation(index, operation, allChangesIndex = index) {
-        const metadata = this.ref['constructor'][Symbol.metadata];
-        const isFiltered = this.isFiltered || (metadata && metadata[metadata[index]].tag !== undefined);
-        if (isFiltered) {
+        if (this.filteredChanges !== undefined) {
             this.allFilteredChanges.set(allChangesIndex, exports.OPERATION.ADD);
             this.filteredChanges.set(index, operation);
             this.root?.filteredChanges.set(this, this.filteredChanges);
@@ -384,8 +430,8 @@ class ChangeTree {
     }
     getType(index) {
         if (Metadata.isValidInstance(this.ref)) {
-            const metadata = this.ref['constructor'][Symbol.metadata];
-            return metadata[metadata[index]].type;
+            const metadata = this.ref.constructor[Symbol.metadata];
+            return metadata[index].type;
         }
         else {
             //
@@ -399,7 +445,7 @@ class ChangeTree {
     }
     getChange(index) {
         // TODO: optimize this. avoid checking against multiple instances
-        return this.changes.get(index) ?? this.filteredChanges.get(index);
+        return this.changes.get(index) ?? this.filteredChanges?.get(index);
     }
     //
     // used during `.encode()`
@@ -420,9 +466,7 @@ class ChangeTree {
             }
             return;
         }
-        const metadata = this.ref['constructor'][Symbol.metadata];
-        const isFiltered = this.isFiltered || (metadata && metadata[metadata[index]].tag !== undefined);
-        const changeSet = (isFiltered)
+        const changeSet = (this.filteredChanges)
             ? this.filteredChanges
             : this.changes;
         const previousValue = this.getValue(index);
@@ -445,7 +489,7 @@ class ChangeTree {
         //
         // FIXME: this is looking a bit ugly (and repeated from `.change()`)
         //
-        if (isFiltered) {
+        if (this.filteredChanges) {
             this.root?.filteredChanges.set(this, this.filteredChanges);
             this.allFilteredChanges.delete(allChangesIndex);
         }
@@ -456,6 +500,7 @@ class ChangeTree {
     }
     endEncode() {
         this.changes.clear();
+        // ArraySchema and MapSchema have a custom "encode end" method
         this.ref[$onEncodeEnd]?.();
         // Not a new instance anymore
         delete this[$isNew];
@@ -468,12 +513,12 @@ class ChangeTree {
         //
         this.ref[$onEncodeEnd]?.();
         this.changes.clear();
-        this.filteredChanges.clear();
+        this.filteredChanges?.clear();
         // reset operation index
         this.currentOperationIndex = 0;
         if (discardAll) {
             this.allChanges.clear();
-            this.allFilteredChanges.clear();
+            this.allFilteredChanges?.clear();
             // remove children references
             this.forEachChild((changeTree, _) => this.root?.remove(changeTree));
         }
@@ -500,33 +545,41 @@ class ChangeTree {
     get changed() {
         return this.changes.size > 0;
     }
-    checkIsFiltered(parent, parentIndex) {
+    checkIsFiltered(metadata, parent, parentIndex) {
         // Detect if current structure has "filters" declared
-        this.isPartiallyFiltered = this.ref['constructor']?.[Symbol.metadata]?.[-2];
-        // TODO: support "partially filtered", where the instance is visible, but only a field is not.
-        // Detect if parent has "filters" declared
-        while (parent && !this.isFiltered) {
-            const metadata = parent['constructor'][Symbol.metadata];
-            const fieldName = metadata?.[parentIndex];
-            const isParentOwned = metadata?.[fieldName]?.tag !== undefined;
-            this.isFiltered = isParentOwned || parent[$changes].isFiltered; // metadata?.[-2]
-            parent = parent[$changes].parent;
+        this.isPartiallyFiltered = metadata?.[-2] !== undefined;
+        if (this.isPartiallyFiltered) {
+            this.filteredChanges = this.filteredChanges || new Map();
+            this.allFilteredChanges = this.allFilteredChanges || new Map();
         }
-        //
-        // TODO: refactor this!
-        //
-        //      swapping `changes` and `filteredChanges` is required here
-        //      because "isFiltered" may not be imedialely available on `change()`
-        //
-        if (this.isFiltered && this.changes.size > 0) {
-            // swap changes reference
-            const changes = this.changes;
-            this.changes = this.filteredChanges;
-            this.filteredChanges = changes;
-            // swap "all changes" reference
-            const allFilteredChanges = this.allFilteredChanges;
-            this.allFilteredChanges = this.allChanges;
-            this.allChanges = allFilteredChanges;
+        if (parent) {
+            if (!Metadata.isValidInstance(parent)) {
+                const parentChangeTree = parent[$changes];
+                parent = parentChangeTree.parent;
+                parentIndex = parentChangeTree.parentIndex;
+            }
+            const parentMetadata = parent?.constructor?.[Symbol.metadata];
+            this.isFiltered = (parent && parentMetadata?.[-2]?.includes(parentIndex));
+            //
+            // TODO: refactor this!
+            //
+            //      swapping `changes` and `filteredChanges` is required here
+            //      because "isFiltered" may not be imedialely available on `change()`
+            //
+            if (this.isFiltered) {
+                this.filteredChanges = new Map();
+                this.allFilteredChanges = new Map();
+                if (this.changes.size > 0) {
+                    // swap changes reference
+                    const changes = this.changes;
+                    this.changes = this.filteredChanges;
+                    this.filteredChanges = changes;
+                    // swap "all changes" reference
+                    const allFilteredChanges = this.allFilteredChanges;
+                    this.allFilteredChanges = this.allChanges;
+                    this.allChanges = allFilteredChanges;
+                }
+            }
         }
     }
 }
@@ -563,26 +616,29 @@ try {
     textEncoder = new TextEncoder();
 }
 catch (e) { }
-function utf8Length(str) {
-    var c = 0, length = 0;
-    for (var i = 0, l = str.length; i < l; i++) {
-        c = str.charCodeAt(i);
-        if (c < 0x80) {
-            length += 1;
-        }
-        else if (c < 0x800) {
-            length += 2;
-        }
-        else if (c < 0xd800 || c >= 0xe000) {
-            length += 3;
-        }
-        else {
-            i++;
-            length += 4;
+const hasBufferByteLength = (typeof Buffer !== 'undefined' && Buffer.byteLength);
+const utf8Length = (hasBufferByteLength)
+    ? Buffer.byteLength // node
+    : function (str, _) {
+        var c = 0, length = 0;
+        for (var i = 0, l = str.length; i < l; i++) {
+            c = str.charCodeAt(i);
+            if (c < 0x80) {
+                length += 1;
+            }
+            else if (c < 0x800) {
+                length += 2;
+            }
+            else if (c < 0xd800 || c >= 0xe000) {
+                length += 3;
+            }
+            else {
+                i++;
+                length += 4;
+            }
         }
-    }
-    return length;
-}
+        return length;
+    };
 function utf8Write(view, str, it) {
     var c = 0;
     for (var i = 0, l = str.length; i < l; i++) {
@@ -677,8 +733,7 @@ function string$1(bytes, value, it) {
     if (!value) {
         value = "";
     }
-    // let length = utf8Length(value);
-    let length = Buffer.byteLength(value, "utf8");
+    let length = utf8Length(value, "utf8");
     let size = 0;
     // fixstr
     if (length < 0x20) {
@@ -789,81 +844,40 @@ function number$1(bytes, value, it) {
 
 var encode = /*#__PURE__*/Object.freeze({
     __proto__: null,
-    utf8Length: utf8Length,
-    utf8Write: utf8Write,
-    int8: int8$1,
-    uint8: uint8$1,
+    boolean: boolean$1,
+    float32: float32$1,
+    float64: float64$1,
     int16: int16$1,
-    uint16: uint16$1,
     int32: int32$1,
-    uint32: uint32$1,
     int64: int64$1,
+    int8: int8$1,
+    number: number$1,
+    string: string$1,
+    uint16: uint16$1,
+    uint32: uint32$1,
     uint64: uint64$1,
-    float32: float32$1,
-    float64: float64$1,
+    uint8: uint8$1,
+    utf8Length: utf8Length,
+    utf8Write: utf8Write,
     writeFloat32: writeFloat32,
-    writeFloat64: writeFloat64,
-    boolean: boolean$1,
-    string: string$1,
-    number: number$1
+    writeFloat64: writeFloat64
 });
 
-class EncodeSchemaError extends Error {
-}
-function assertType(value, type, klass, field) {
-    let typeofTarget;
-    let allowNull = false;
-    switch (type) {
-        case "number":
-        case "int8":
-        case "uint8":
-        case "int16":
-        case "uint16":
-        case "int32":
-        case "uint32":
-        case "int64":
-        case "uint64":
-        case "float32":
-        case "float64":
-            typeofTarget = "number";
-            if (isNaN(value)) {
-                console.log(`trying to encode "NaN" in ${klass.constructor.name}#${field}`);
-            }
-            break;
-        case "string":
-            typeofTarget = "string";
-            allowNull = true;
-            break;
-        case "boolean":
-            // boolean is always encoded as true/false based on truthiness
-            return;
-    }
-    if (typeof (value) !== typeofTarget && (!allowNull || (allowNull && value !== null))) {
-        let foundValue = `'${JSON.stringify(value)}'${(value && value.constructor && ` (${value.constructor.name})`) || ''}`;
-        throw new EncodeSchemaError(`a '${typeofTarget}' was expected, but ${foundValue} was provided in ${klass.constructor.name}#${field}`);
-    }
-}
-function assertInstanceType(value, type, klass, field) {
-    if (!(value instanceof type)) {
-        throw new EncodeSchemaError(`a '${type.name}' was expected, but '${value && value.constructor.name}' was provided in ${klass.constructor.name}#${field}`);
-    }
-}
-
-function encodePrimitiveType(type, bytes, value, klass, field, it) {
-    assertType(value, type, klass, field);
-    const encodeFunc = encode[type];
-    if (encodeFunc) {
-        encodeFunc(bytes, value, it);
-        // encodeFunc(bytes, value);
-    }
-    else {
-        throw new EncodeSchemaError(`a '${type}' was expected, but ${value} was provided in ${klass.constructor.name}#${field}`);
+function encodeValue(encoder, bytes, 
+// ref: Ref,
+type, value, 
+// field: string | number,
+operation, it) {
+    if (typeof (type) === "string") {
+        //
+        // Primitive values
+        //
+        // assertType(value, type as string, ref as Schema, field);
+        encode[type]?.(bytes, value, it);
     }
-}
-function encodeValue(encoder, bytes, ref, type, value, field, operation, it) {
-    if (type[Symbol.metadata] !== undefined) {
-        // TODO: move this to the `@type()` annotation
-        assertInstanceType(value, type, ref, field);
+    else if (type[Symbol.metadata] !== undefined) {
+        // // TODO: move this to the `@type()` annotation
+        // assertInstanceType(value, type as typeof Schema, ref as Schema, field);
         //
         // Encode refId for this instance.
         // The actual instance is going to be encoded on next `changeTree` iteration.
@@ -874,21 +888,15 @@ function encodeValue(encoder, bytes, ref, type, value, field, operation, it) {
             encoder.tryEncodeTypeId(bytes, type, value.constructor, it);
         }
     }
-    else if (typeof (type) === "string") {
-        //
-        // Primitive values
-        //
-        encodePrimitiveType(type, bytes, value, ref, field, it);
-    }
     else {
-        //
-        // Custom type (MapSchema, ArraySchema, etc)
-        //
-        const definition = getType(Object.keys(type)[0]);
-        //
-        // ensure a ArraySchema has been provided
-        //
-        assertInstanceType(ref[field], definition.constructor, ref, field);
+        // //
+        // // Custom type (MapSchema, ArraySchema, etc)
+        // //
+        // const definition = getType(Object.keys(type)[0]);
+        // //
+        // // ensure a ArraySchema has been provided
+        // //
+        // assertInstanceType(ref[field], definition.constructor, ref as Schema, field);
         //
         // Encode refId for this instance.
         // The actual instance is going to be encoded on next `changeTree` iteration.
@@ -901,26 +909,27 @@ function encodeValue(encoder, bytes, ref, type, value, field, operation, it) {
  * @private
  */
 const encodeSchemaOperation = function (encoder, bytes, changeTree, index, operation, it) {
-    const ref = changeTree.ref;
-    const metadata = ref['constructor'][Symbol.metadata];
-    const field = metadata[index];
-    const type = metadata[field].type;
-    const value = ref[field];
     // "compress" field index + operation
     bytes[it.offset++] = (index | operation) & 255;
     // Do not encode value for DELETE operations
     if (operation === exports.OPERATION.DELETE) {
         return;
     }
+    const ref = changeTree.ref;
+    const metadata = ref['constructor'][Symbol.metadata];
+    const field = metadata[index];
     // TODO: inline this function call small performance gain
-    encodeValue(encoder, bytes, ref, type, value, field, operation, it);
+    encodeValue(encoder, bytes, 
+    // ref,
+    metadata[index].type, ref[field.name], 
+    // index,
+    operation, it);
 };
 /**
  * Used for collections (MapSchema, CollectionSchema, SetSchema)
  * @private
  */
-const encodeKeyValueOperation = function (encoder, bytes, changeTree, field, operation, it) {
-    const ref = changeTree.ref;
+const encodeKeyValueOperation = function (encoder, bytes, changeTree, index, operation, it) {
     // encode operation
     bytes[it.offset++] = operation & 255;
     // custom operations
@@ -928,11 +937,12 @@ const encodeKeyValueOperation = function (encoder, bytes, changeTree, field, ope
         return;
     }
     // encode index
-    number$1(bytes, field, it);
+    number$1(bytes, index, it);
     // Do not encode value for DELETE operations
     if (operation === exports.OPERATION.DELETE) {
         return;
     }
+    const ref = changeTree.ref;
     //
     // encode "alias" for dynamic fields (maps)
     //
@@ -941,14 +951,30 @@ const encodeKeyValueOperation = function (encoder, bytes, changeTree, field, ope
             //
             // MapSchema dynamic key
             //
-            const dynamicIndex = changeTree.ref['$indexes'].get(field);
+            const dynamicIndex = changeTree.ref['$indexes'].get(index);
             string$1(bytes, dynamicIndex, it);
         }
     }
-    const type = changeTree.getType(field);
-    const value = changeTree.getValue(field);
+    const type = changeTree.getType(index);
+    const value = changeTree.getValue(index);
+    // try { throw new Error(); } catch (e) {
+    //     // only print if not coming from Reflection.ts
+    //     if (!e.stack.includes("src/Reflection.ts")) {
+    //         console.log("encodeKeyValueOperation -> ", {
+    //             ref: changeTree.ref.constructor.name,
+    //             field,
+    //             operation: OPERATION[operation],
+    //             value: value?.toJSON(),
+    //             items: ref.toJSON(),
+    //         });
+    //     }
+    // }
     // TODO: inline this function call small performance gain
-    encodeValue(encoder, bytes, ref, type, value, field, operation, it);
+    encodeValue(encoder, bytes, 
+    // ref,
+    type, value, 
+    // index,
+    operation, it);
 };
 /**
  * Used for collections (MapSchema, ArraySchema, etc.)
@@ -956,15 +982,19 @@ const encodeKeyValueOperation = function (encoder, bytes, changeTree, field, ope
  */
 const encodeArray = function (encoder, bytes, changeTree, field, operation, it, isEncodeAll, hasView) {
     const ref = changeTree.ref;
-    if (hasView &&
-        operation === exports.OPERATION.DELETE &&
-        typeof (changeTree.getType(field)) !== "string") {
-        // encode delete by refId (array of schemas)
-        bytes[it.offset++] = exports.OPERATION.DELETE_BY_REFID;
-        const value = ref['tmpItems'][field];
-        const refId = value[$changes].refId;
-        number$1(bytes, refId, it);
-        return;
+    const useOperationByRefId = hasView && changeTree.isFiltered && (typeof (changeTree.getType(field)) !== "string");
+    let refOrIndex;
+    if (useOperationByRefId) {
+        refOrIndex = ref['tmpItems'][field][$changes].refId;
+        if (operation === exports.OPERATION.DELETE) {
+            operation = exports.OPERATION.DELETE_BY_REFID;
+        }
+        else if (operation === exports.OPERATION.ADD) {
+            operation = exports.OPERATION.ADD_BY_REFID;
+        }
+    }
+    else {
+        refOrIndex = field;
     }
     // encode operation
     bytes[it.offset++] = operation & 255;
@@ -973,7 +1003,7 @@ const encodeArray = function (encoder, bytes, changeTree, field, operation, it,
         return;
     }
     // encode index
-    number$1(bytes, field, it);
+    number$1(bytes, refOrIndex, it);
     // Do not encode value for DELETE operations
     if (operation === exports.OPERATION.DELETE) {
         return;
@@ -988,7 +1018,11 @@ const encodeArray = function (encoder, bytes, changeTree, field, operation, it,
     //     items: ref.toJSON(),
     // });
     // TODO: inline this function call small performance gain
-    encodeValue(encoder, bytes, ref, type, value, field, operation, it);
+    encodeValue(encoder, bytes, 
+    // ref,
+    type, value, 
+    // field,
+    operation, it);
 };
 
 /**
@@ -1014,7 +1048,6 @@ const encodeArray = function (encoder, bytes, changeTree, field, operation, it,
  * SOFTWARE
  */
 function utf8Read(bytes, it, length) {
-    it.offset += length;
     var string = '', chr = 0;
     for (var i = it.offset, end = it.offset + length; i < end; i++) {
         var byte = bytes[i];
@@ -1051,6 +1084,7 @@ function utf8Read(bytes, it, length) {
         // (do not throw error to avoid server/client from crashing due to hack attemps)
         // throw new Error('Invalid byte ' + byte.toString(16));
     }
+    it.offset += length;
     return string;
 }
 function int8(bytes, it) {
@@ -1222,31 +1256,31 @@ function switchStructureCheck(bytes, it) {
 
 var decode = /*#__PURE__*/Object.freeze({
     __proto__: null,
-    utf8Read: utf8Read,
-    int8: int8,
-    uint8: uint8,
-    int16: int16,
-    uint16: uint16,
-    int32: int32,
-    uint32: uint32,
+    arrayCheck: arrayCheck,
+    boolean: boolean,
     float32: float32,
     float64: float64,
+    int16: int16,
+    int32: int32,
     int64: int64,
-    uint64: uint64,
+    int8: int8,
+    number: number,
+    numberCheck: numberCheck,
     readFloat32: readFloat32,
     readFloat64: readFloat64,
-    boolean: boolean,
     string: string,
     stringCheck: stringCheck,
-    number: number,
-    numberCheck: numberCheck,
-    arrayCheck: arrayCheck,
-    switchStructureCheck: switchStructureCheck
+    switchStructureCheck: switchStructureCheck,
+    uint16: uint16,
+    uint32: uint32,
+    uint64: uint64,
+    uint8: uint8,
+    utf8Read: utf8Read
 });
 
 const DEFINITION_MISMATCH = -1;
 function decodeValue(decoder, operation, ref, index, type, bytes, it, allChanges) {
-    const $root = decoder.$root;
+    const $root = decoder.root;
     const previousValue = ref[$getByIndex](index);
     let value;
     if ((operation & exports.OPERATION.DELETE) === exports.OPERATION.DELETE) {
@@ -1345,18 +1379,19 @@ function decodeValue(decoder, operation, ref, index, type, bytes, it, allChanges
 }
 const decodeSchemaOperation = function (decoder, bytes, it, ref, allChanges) {
     const first_byte = bytes[it.offset++];
-    const metadata = ref['constructor'][Symbol.metadata];
+    const metadata = ref.constructor[Symbol.metadata];
     // "compressed" index + operation
     const operation = (first_byte >> 6) << 6;
     const index = first_byte % (operation || 255);
     // skip early if field is not defined
     const field = metadata[index];
     if (field === undefined) {
+        console.warn("@colyseus/schema: field not defined at", { index, ref: ref.constructor.name, metadata });
         return DEFINITION_MISMATCH;
     }
-    const { value, previousValue } = decodeValue(decoder, operation, ref, index, metadata[field].type, bytes, it, allChanges);
+    const { value, previousValue } = decodeValue(decoder, operation, ref, index, field.type, bytes, it, allChanges);
     if (value !== null && value !== undefined) {
-        ref[field] = value;
+        ref[field.name] = value;
     }
     // add change
     if (previousValue !== value) {
@@ -1364,7 +1399,7 @@ const decodeSchemaOperation = function (decoder, bytes, it, ref, allChanges) {
             ref,
             refId: decoder.currentRefId,
             op: operation,
-            field: field,
+            field: field.name,
             value,
             previousValue,
         });
@@ -1432,7 +1467,8 @@ const decodeKeyValueOperation = function (decoder, bytes, it, ref, allChanges) {
 };
 const decodeArray = function (decoder, bytes, it, ref, allChanges) {
     // "uncompressed" index + operation (array/map items)
-    const operation = bytes[it.offset++];
+    let operation = bytes[it.offset++];
+    let index;
     if (operation === exports.OPERATION.CLEAR) {
         //
         // When decoding:
@@ -1446,8 +1482,8 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
     else if (operation === exports.OPERATION.DELETE_BY_REFID) {
         // TODO: refactor here, try to follow same flow as below
         const refId = number(bytes, it);
-        const previousValue = decoder.$root.refs.get(refId);
-        const index = ref.findIndex((value) => value === previousValue);
+        const previousValue = decoder.root.refs.get(refId);
+        index = ref.findIndex((value) => value === previousValue);
         ref[$deleteByIndex](index);
         allChanges.push({
             ref,
@@ -1460,7 +1496,17 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
         });
         return;
     }
-    const index = number(bytes, it);
+    else if (operation === exports.OPERATION.ADD_BY_REFID) {
+        const refId = number(bytes, it);
+        const itemByRefId = decoder.root.refs.get(refId);
+        // use existing index, or push new value
+        index = (itemByRefId)
+            ? ref.findIndex((value) => value === itemByRefId)
+            : ref.length;
+    }
+    else {
+        index = number(bytes, it);
+    }
     const type = ref[$childType];
     let dynamicIndex = index;
     const { value, previousValue } = decodeValue(decoder, operation, ref, index, type, bytes, it, allChanges);
@@ -1484,6 +1530,47 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
     }
 };
 
+class EncodeSchemaError extends Error {
+}
+function assertType(value, type, klass, field) {
+    let typeofTarget;
+    let allowNull = false;
+    switch (type) {
+        case "number":
+        case "int8":
+        case "uint8":
+        case "int16":
+        case "uint16":
+        case "int32":
+        case "uint32":
+        case "int64":
+        case "uint64":
+        case "float32":
+        case "float64":
+            typeofTarget = "number";
+            if (isNaN(value)) {
+                console.log(`trying to encode "NaN" in ${klass.constructor.name}#${field}`);
+            }
+            break;
+        case "string":
+            typeofTarget = "string";
+            allowNull = true;
+            break;
+        case "boolean":
+            // boolean is always encoded as true/false based on truthiness
+            return;
+    }
+    if (typeof (value) !== typeofTarget && (!allowNull || (allowNull && value !== null))) {
+        let foundValue = `'${JSON.stringify(value)}'${(value && value.constructor && ` (${value.constructor.name})`) || ''}`;
+        throw new EncodeSchemaError(`a '${typeofTarget}' was expected, but ${foundValue} was provided in ${klass.constructor.name}#${field}`);
+    }
+}
+function assertInstanceType(value, type, instance, field) {
+    if (!(value instanceof type)) {
+        throw new EncodeSchemaError(`a '${type.name}' was expected, but '${value && value.constructor.name}' was provided in ${instance.constructor.name}#${field}`);
+    }
+}
+
 var _a$4, _b$4;
 const DEFAULT_SORT = (a, b) => {
     const A = a.toString();
@@ -1549,6 +1636,7 @@ class ArraySchema {
                     }
                     else {
                         if (setValue[$changes]) {
+                            assertInstanceType(setValue, obj[$childType], obj, key);
                             if (obj.items[key] !== undefined) {
                                 if (setValue[$changes][$isNew]) {
                                     this[$changes].indexedOperation(Number(key), exports.OPERATION.MOVE_AND_ADD);
@@ -1595,6 +1683,7 @@ class ArraySchema {
             }
         });
         this[$changes] = new ChangeTree(proxy);
+        this[$changes].indexes = {};
         this.push.apply(this, items);
         return proxy;
     }
@@ -1619,9 +1708,11 @@ class ArraySchema {
             if (value === undefined || value === null) {
                 return;
             }
+            else if (typeof (value) === "object" && this[$childType]) {
+                assertInstanceType(value, this[$childType], this, i);
+            }
             const changeTree = this[$changes];
             changeTree.indexedOperation(length, exports.OPERATION.ADD, this.items.length);
-            // changeTree.indexes[length] = length;
             this.items.push(value);
             this.tmpItems.push(value);
             //
@@ -1869,14 +1960,6 @@ class ArraySchema {
     lastIndexOf(searchElement, fromIndex = this.length - 1) {
         return this.items.lastIndexOf(searchElement, fromIndex);
     }
-    /**
-     * Determines whether all the members of an array satisfy the specified test.
-     * @param callbackfn A function that accepts up to three arguments. The every method calls
-     * the callbackfn function for each element in the array until the callbackfn returns a value
-     * which is coercible to the Boolean value false, or until the end of the array.
-     * @param thisArg An object to which the this keyword can refer in the callbackfn function.
-     * If thisArg is omitted, undefined is used as the this value.
-     */
     every(callbackfn, thisArg) {
         return this.items.every(callbackfn, thisArg);
     }
@@ -2155,6 +2238,7 @@ class MapSchema {
         this.$items = new Map();
         this.$indexes = new Map();
         this[$changes] = new ChangeTree(this);
+        this[$changes].indexes = {};
         if (initialValues) {
             if (initialValues instanceof Map ||
                 initialValues instanceof MapSchema) {
@@ -2181,6 +2265,9 @@ class MapSchema {
         if (value === undefined || value === null) {
             throw new Error(`MapSchema#set('${key}', ${value}): trying to set ${value} value on '${key}'.`);
         }
+        else if (typeof (value) === "object" && this[$childType]) {
+            assertInstanceType(value, this[$childType], this, key);
+        }
         // Force "key" as string
         // See: https://github.com/colyseus/colyseus/issues/561#issuecomment-1646733468
         key = key.toString();
@@ -2320,7 +2407,6 @@ class MapSchema {
 }
 registerType("map", { constructor: MapSchema });
 
-const DEFAULT_VIEW_TAG = -1;
 class TypeContext {
     /**
      * For inheritance support
@@ -2342,6 +2428,7 @@ class TypeContext {
         this.types = {};
         this.schemas = new Map();
         this.hasFilters = false;
+        this.parentFiltered = {};
         if (rootClass) {
             this.discoverTypes(rootClass);
         }
@@ -2358,44 +2445,51 @@ class TypeContext {
             return false;
         }
         this.types[typeid] = schema;
+        //
+        // Workaround to allow using an empty Schema (with no `@type()` fields)
+        //
+        if (schema[Symbol.metadata] === undefined) {
+            Metadata.init(schema);
+        }
         this.schemas.set(schema, typeid);
         return true;
     }
     getTypeId(klass) {
         return this.schemas.get(klass);
     }
-    discoverTypes(klass) {
+    discoverTypes(klass, parentIndex, parentFieldViewTag) {
         if (!this.add(klass)) {
             return;
         }
         // add classes inherited from this base class
         TypeContext.inheritedTypes.get(klass)?.forEach((child) => {
-            this.discoverTypes(child);
+            this.discoverTypes(child, parentIndex, parentFieldViewTag);
         });
-        // skip if no fields are defined for this class.
-        if (klass[Symbol.metadata] === undefined) {
-            klass[Symbol.metadata] = {};
-        }
-        // const metadata = Metadata.getFor(klass);
-        const metadata = klass[Symbol.metadata];
+        const metadata = (klass[Symbol.metadata] ??= {});
         // if any schema/field has filters, mark "context" as having filters.
         if (metadata[-2]) {
             this.hasFilters = true;
         }
-        for (const field in metadata) {
-            const fieldType = metadata[field].type;
+        if (parentFieldViewTag !== undefined) {
+            this.parentFiltered[`${this.schemas.get(klass)}-${parentIndex}`] = true;
+        }
+        for (const fieldIndex in metadata) {
+            const index = fieldIndex;
+            const fieldType = metadata[index].type;
+            const viewTag = metadata[index].tag;
             if (typeof (fieldType) === "string") {
                 continue;
             }
             if (Array.isArray(fieldType)) {
                 const type = fieldType[0];
+                // skip primitive types
                 if (type === "string") {
                     continue;
                 }
-                this.discoverTypes(type);
+                this.discoverTypes(type, index, viewTag);
             }
             else if (typeof (fieldType) === "function") {
-                this.discoverTypes(fieldType);
+                this.discoverTypes(fieldType, viewTag);
             }
             else {
                 const type = Object.values(fieldType)[0];
@@ -2403,11 +2497,13 @@ class TypeContext {
                 if (typeof (type) === "string") {
                     continue;
                 }
-                this.discoverTypes(type);
+                this.discoverTypes(type, index, viewTag);
             }
         }
     }
 }
+
+const DEFAULT_VIEW_TAG = -1;
 /**
  * [See documentation](https://docs.colyseus.io/state/schema/)
  *
@@ -2555,18 +2651,20 @@ function view(tag = DEFAULT_VIEW_TAG) {
         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)));
-        if (!metadata[fieldName]) {
-            //
-            // detect index for this field, considering inheritance
-            //
-            metadata[fieldName] = {
-                type: undefined,
-                index: (metadata[-1] // current structure already has fields defined
-                    ?? (parentMetadata && parentMetadata[-1]) // parent structure has fields defined
-                    ?? -1) + 1 // no fields defined
-            };
-        }
+        // const fieldIndex = metadata[fieldName];
+        // if (!metadata[fieldIndex]) {
+        //     //
+        //     // detect index for this field, considering inheritance
+        //     //
+        //     metadata[fieldIndex] = {
+        //         type: undefined,
+        //         index: (metadata[-1] // current structure already has fields defined
+        //             ?? (parentMetadata && parentMetadata[-1]) // parent structure has fields defined
+        //             ?? -1) + 1 // no fields defined
+        //     }
+        // }
         Metadata.setTag(metadata, fieldName, tag);
     };
 }
@@ -2579,18 +2677,18 @@ function type(type, options) {
         // for inheritance support
         TypeContext.register(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)));
-        let fieldIndex;
+        const parentMetadata = parentClass && parentClass[Symbol.metadata];
+        const metadata = Metadata.initialize(constructor, parentMetadata);
+        let fieldIndex = metadata[field];
         /**
          * skip if descriptor already exists for this field (`@deprecated()`)
          */
-        if (metadata[field]) {
-            if (metadata[field].deprecated) {
+        if (metadata[fieldIndex]) {
+            if (metadata[fieldIndex].deprecated) {
                 // do not create accessors for deprecated properties.
                 return;
             }
-            else if (metadata[field].descriptor !== undefined) {
+            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 {
@@ -2601,9 +2699,6 @@ function type(type, options) {
                     throw new Error(`${e.message} ${definitionAtLine}`);
                 }
             }
-            else {
-                fieldIndex = metadata[field].index;
-            }
         }
         else {
             //
@@ -2629,11 +2724,11 @@ function type(type, options) {
             const childType = (complexTypeKlass)
                 ? Object.values(type)[0]
                 : type;
-            Metadata.addField(metadata, fieldIndex, field, type, getPropertyDescriptor(`_${field}`, fieldIndex, childType, complexTypeKlass, metadata, field));
+            Metadata.addField(metadata, fieldIndex, field, type, getPropertyDescriptor(`_${field}`, fieldIndex, childType, complexTypeKlass));
         }
     };
 }
-function getPropertyDescriptor(fieldCached, fieldIndex, type, complexTypeKlass, metadata, field) {
+function getPropertyDescriptor(fieldCached, fieldIndex, type, complexTypeKlass) {
     return {
         get: function () { return this[fieldCached]; },
         set: function (value) {
@@ -2655,22 +2750,27 @@ function getPropertyDescriptor(fieldCached, fieldIndex, type, complexTypeKlass,
                     }
                     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.
                 // TODO: if there are other references to this instance, we should not remove it from root.
                 //
                 if (previousValue !== undefined && previousValue[$changes]) {
-                    this[$changes].root?.remove(previousValue[$changes]);
+                    changeTree.root?.remove(previousValue[$changes]);
                 }
                 // flag the change for encoding.
-                this.constructor[$track](this[$changes], fieldIndex, exports.OPERATION.ADD);
+                this.constructor[$track](changeTree, fieldIndex, exports.OPERATION.ADD);
                 //
                 // call setParent() recursively for this and its child
                 // structures.
                 //
-                if (value[$changes]) {
-                    value[$changes].setParent(this, this[$changes].root, metadata[field].index);
-                }
+                value[$changes]?.setParent(this, changeTree.root, fieldIndex);
             }
             else if (previousValue !== undefined) {
                 //
@@ -2697,20 +2797,22 @@ function deprecated(throws = true) {
         const parentClass = Object.getPrototypeOf(constructor);
         const parentMetadata = parentClass[Symbol.metadata];
         const metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
-        if (!metadata[field]) {
-            //
-            // detect index for this field, considering inheritance
-            //
-            metadata[field] = {
-                type: undefined,
-                index: (metadata[-1] // current structure already has fields defined
-                    ?? (parentMetadata && parentMetadata[-1]) // parent structure has fields defined
-                    ?? -1) + 1 // no fields defined
-            };
-        }
-        metadata[field].deprecated = true;
+        const fieldIndex = metadata[field];
+        // if (!metadata[field]) {
+        //     //
+        //     // detect index for this field, considering inheritance
+        //     //
+        //     metadata[field] = {
+        //         type: undefined,
+        //         index: (metadata[-1] // current structure already has fields defined
+        //             ?? (parentMetadata && parentMetadata[-1]) // parent structure has fields defined
+        //             ?? -1) + 1 // no fields defined
+        //     }
+        // }
+        metadata[fieldIndex].deprecated = true;
         if (throws) {
-            metadata[field].descriptor = {
+            metadata[$descriptors] ??= {};
+            metadata[$descriptors][field] = {
                 get: function () { throw new Error(`${field} is deprecated.`); },
                 set: function (value) { },
                 enumerable: false,
@@ -2718,8 +2820,8 @@ function deprecated(throws = true) {
             };
         }
         // flag metadata[field] as non-enumerable
-        Object.defineProperty(metadata, field, {
-            value: metadata[field],
+        Object.defineProperty(metadata, fieldIndex, {
+            value: metadata[fieldIndex],
             enumerable: false,
             configurable: true
         });
@@ -2785,35 +2887,7 @@ class Schema {
             enumerable: false,
             writable: true
         });
-        const metadata = instance.constructor[Symbol.metadata];
-        // Define property descriptors
-        for (const field in metadata) {
-            if (metadata[field].descriptor) {
-                // for encoder
-                Object.defineProperty(instance, `_${field}`, {
-                    value: undefined,
-                    writable: true,
-                    enumerable: false,
-                    configurable: true,
-                });
-                Object.defineProperty(instance, field, metadata[field].descriptor);
-            }
-            else {
-                // for decoder
-                Object.defineProperty(instance, field, {
-                    value: undefined,
-                    writable: true,
-                    enumerable: true,
-                    configurable: true,
-                });
-            }
-            // Object.defineProperty(instance, field, {
-            //     ...instance.constructor[Symbol.metadata][field].descriptor
-            // });
-            // if (args[0]?.hasOwnProperty(field)) {
-            //     instance[field] = args[0][field];
-            // }
-        }
+        Object.defineProperties(instance, instance.constructor[Symbol.metadata]?.[$descriptors] || {});
     }
     static is(type) {
         return typeof (type[Symbol.metadata]) === "object";
@@ -2837,7 +2911,7 @@ class Schema {
      */
     static [$filter](ref, index, view) {
         const metadata = ref.constructor[Symbol.metadata];
-        const tag = metadata[metadata[index]].tag;
+        const tag = metadata[index]?.tag;
         if (view === undefined) {
             // shared pass/encode: encode if doesn't have a tag
             return tag === undefined;
@@ -2858,12 +2932,21 @@ class Schema {
     }
     // allow inherited classes to have a constructor
     constructor(...args) {
-        Schema.initialize(this);
+        //
+        // inline
+        // Schema.initialize(this);
+        //
+        Object.defineProperty(this, $changes, {
+            value: new ChangeTree(this),
+            enumerable: false,
+            writable: true
+        });
+        Object.defineProperties(this, this.constructor[Symbol.metadata]?.[$descriptors] || {});
         //
         // Assign initial values
         //
         if (args[0]) {
-            this.assign(args[0]);
+            Object.assign(this, args[0]);
         }
     }
     assign(props) {
@@ -2877,7 +2960,8 @@ class Schema {
      * @param operation OPERATION to perform (detected automatically)
      */
     setDirty(property, operation) {
-        this[$changes].change(this.constructor[Symbol.metadata][property].index, operation);
+        const metadata = this.constructor[Symbol.metadata];
+        this[$changes].change(metadata[metadata[property]].index, operation);
     }
     clone() {
         const cloned = new (this.constructor);
@@ -2886,7 +2970,9 @@ class Schema {
         // TODO: clone all properties, not only annotated ones
         //
         // for (const field in this) {
-        for (const field in metadata) {
+        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
@@ -2900,10 +2986,11 @@ class Schema {
         return cloned;
     }
     toJSON() {
-        const metadata = this.constructor[Symbol.metadata];
         const obj = {};
-        for (const fieldName in metadata) {
-            const field = metadata[fieldName];
+        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']()
@@ -2916,10 +3003,12 @@ class Schema {
         this[$changes].discardAll();
     }
     [$getByIndex](index) {
-        return this[this.constructor[Symbol.metadata][index]];
+        const metadata = this.constructor[Symbol.metadata];
+        return this[metadata[index].name];
     }
     [$deleteByIndex](index) {
-        this[this.constructor[Symbol.metadata][index]] = undefined;
+        const metadata = this.constructor[Symbol.metadata];
+        this[metadata[index].name] = undefined;
     }
     static debugRefIds(instance, jsonContents = true, level = 0) {
         const ref = instance;
@@ -2961,13 +3050,13 @@ class Schema {
         }
         return output;
     }
-    static debugChangesDeep(ref) {
+    static debugChangesDeep(ref, changeSetName = "changes") {
         let output = "";
         const rootChangeTree = ref[$changes];
         const changeTrees = new Map();
         let totalInstances = 0;
         let totalOperations = 0;
-        for (const [changeTree, changes] of (rootChangeTree.root.changes.entries())) {
+        for (const [changeTree, changes] of (rootChangeTree.root[changeSetName].entries())) {
             let includeChangeTree = false;
             let parentChangeTrees = [];
             let parentChangeTree = changeTree.parent?.[$changes];
@@ -3043,6 +3132,7 @@ class CollectionSchema {
         this.$indexes = new Map();
         this.$refId = 0;
         this[$changes] = new ChangeTree(this);
+        this[$changes].indexes = {};
         if (initialValues) {
             initialValues.forEach((v) => this.add(v));
         }
@@ -3198,6 +3288,7 @@ class SetSchema {
         this.$indexes = new Map();
         this.$refId = 0;
         this[$changes] = new ChangeTree(this);
+        this[$changes].indexes = {};
         if (initialValues) {
             initialValues.forEach((v) => this.add(v));
         }
@@ -3353,6 +3444,8 @@ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 PERFORMANCE OF THIS SOFTWARE.
 ***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol */
+
 
 function __decorate(decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -3366,37 +3459,82 @@ typeof SuppressedError === "function" ? SuppressedError : function (error, suppr
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 };
 
+class Root {
+    constructor(types) {
+        this.types = types;
+        this.nextUniqueId = 0;
+        this.refCount = new WeakMap();
+        // all changes
+        this.allChanges = new Map();
+        this.allFilteredChanges = new Map();
+        // pending changes to be encoded
+        this.changes = new Map();
+        this.filteredChanges = new Map();
+    }
+    getNextUniqueId() {
+        return this.nextUniqueId++;
+    }
+    add(changeTree) {
+        const refCount = this.refCount.get(changeTree) || 0;
+        this.refCount.set(changeTree, refCount + 1);
+    }
+    remove(changeTree) {
+        const refCount = this.refCount.get(changeTree);
+        if (refCount <= 1) {
+            this.allChanges.delete(changeTree);
+            this.changes.delete(changeTree);
+            if (changeTree.isFiltered || changeTree.isPartiallyFiltered) {
+                this.allFilteredChanges.delete(changeTree);
+                this.filteredChanges.delete(changeTree);
+            }
+            this.refCount.delete(changeTree);
+        }
+        else {
+            this.refCount.set(changeTree, refCount - 1);
+        }
+        changeTree.forEachChild((child, _) => this.remove(child));
+    }
+    clear() {
+        this.changes.clear();
+    }
+}
+
 class Encoder {
     static { this.BUFFER_SIZE = 8 * 1024; } // 8KB
-    constructor(root) {
+    constructor(state) {
         this.sharedBuffer = Buffer.allocUnsafeSlow(Encoder.BUFFER_SIZE);
-        this.setRoot(root);
         //
         // TODO: cache and restore "Context" based on root schema
         // (to avoid creating a new context for every new room)
         //
-        this.context = new TypeContext(root.constructor);
+        this.context = new TypeContext(state.constructor);
+        this.root = new Root(this.context);
+        this.setState(state);
         // console.log(">>>>>>>>>>>>>>>> Encoder types");
         // this.context.schemas.forEach((id, schema) => {
         //     console.log("type:", id, schema.name, Object.keys(schema[Symbol.metadata]));
         // });
     }
-    setRoot(state) {
-        this.root = new Root();
+    setState(state) {
         this.state = state;
-        state[$changes].setRoot(this.root);
+        this.state[$changes].setRoot(this.root);
     }
-    encode(it = { offset: 0 }, view, bytes = this.sharedBuffer, changeTrees = this.root.changes) {
-        const initialOffset = it.offset; // cache current offset in case we need to resize the buffer
-        const isEncodeAll = this.root.allChanges === changeTrees;
+    encode(it = { offset: 0 }, view, buffer = this.sharedBuffer, changeTrees = this.root.changes, isEncodeAll = this.root.allChanges === changeTrees, initialOffset = it.offset // cache current offset in case we need to resize the buffer
+    ) {
         const hasView = (view !== undefined);
         const rootChangeTree = this.state[$changes];
-        const changeTreesIterator = changeTrees.entries();
-        for (const [changeTree, changes] of changeTreesIterator) {
+        const shouldClearChanges = !isEncodeAll && !hasView;
+        for (const [changeTree, changes] of changeTrees.entries()) {
             const ref = changeTree.ref;
             const ctor = ref['constructor'];
             const encoder = ctor[$encoder];
             const filter = ctor[$filter];
+            // try { throw new Error(); } catch (e) {
+            //     // only print if not coming from Reflection.ts
+            //     if (!e.stack.includes("src/Reflection.ts")) {
+            //         console.log("ChangeTree:", { ref: ref.constructor.name, });
+            //     }
+            // }
             if (hasView) {
                 if (!view.items.has(changeTree)) {
                     view.invisible.add(changeTree);
@@ -3407,9 +3545,10 @@ class Encoder {
                 }
             }
             // skip root `refId` if it's the first change tree
-            if (it.offset !== initialOffset || changeTree !== rootChangeTree) {
-                bytes[it.offset++] = SWITCH_TO_STRUCTURE & 255;
-                number$1(bytes, changeTree.refId, it);
+            // (unless it "hasView", which will need to revisit the root)
+            if (hasView || it.offset > initialOffset || changeTree !== rootChangeTree) {
+                buffer[it.offset++] = SWITCH_TO_STRUCTURE & 255;
+                number$1(buffer, changeTree.refId, it);
             }
             const changesIterator = changes.entries();
             for (const [fieldIndex, operation] of changesIterator) {
@@ -3421,74 +3560,94 @@ class Encoder {
                 // TODO: avoid checking if no view tags were defined
                 //
                 if (filter && !filter(ref, fieldIndex, view)) {
-                    // console.log("SKIP FIELD:", { ref: changeTree.ref.constructor.name, fieldIndex, })
                     // console.log("ADD AS INVISIBLE:", fieldIndex, changeTree.ref.constructor.name)
                     // view?.invisible.add(changeTree);
                     continue;
                 }
-                // console.log("WILL ENCODE", {
-                //     ref: changeTree.ref.constructor.name,
-                //     fieldIndex,
-                //     operation: OPERATION[operation],
-                // });
-                encoder(this, bytes, changeTree, fieldIndex, operation, it, isEncodeAll, hasView);
+                // try { throw new Error(); } catch (e) {
+                //     // only print if not coming from Reflection.ts
+                //     if (!e.stack.includes("src/Reflection.ts")) {
+                //         console.log("WILL ENCODE", {
+                //             ref: changeTree.ref.constructor.name,
+                //             fieldIndex,
+                //             operation: OPERATION[operation],
+                //         });
+                //     }
+                // }
+                encoder(this, buffer, changeTree, fieldIndex, operation, it, isEncodeAll, hasView);
             }
+            // if (shouldClearChanges) {
+            //     changeTree.endEncode();
+            // }
         }
-        if (it.offset > bytes.byteLength) {
-            const newSize = getNextPowerOf2(this.sharedBuffer.byteLength * 2);
-            console.warn("@colyseus/schema encode buffer overflow. Current buffer size: " + bytes.byteLength + ", encoding offset: " + it.offset + ", new size: " + newSize);
+        if (it.offset > buffer.byteLength) {
+            const newSize = getNextPowerOf2(buffer.byteLength * 2);
+            console.warn(`@colyseus/schema buffer overflow. Encoded state is higher than default BUFFER_SIZE. Use the following to increase default BUFFER_SIZE:
+
+    import { Encoder } from "@colyseus/schema";
+    Encoder.BUFFER_SIZE = ${Math.round(newSize / 1024)} * 1024; // ${Math.round(newSize / 1024)} KB
+`);
             //
             // resize buffer and re-encode (TODO: can we avoid re-encoding here?)
             //
-            this.sharedBuffer = Buffer.allocUnsafeSlow(newSize);
-            return this.encode({ offset: initialOffset }, view);
+            buffer = Buffer.allocUnsafeSlow(newSize);
+            // assign resized buffer to local sharedBuffer
+            if (buffer === this.sharedBuffer) {
+                this.sharedBuffer = buffer;
+            }
+            return this.encode({ offset: initialOffset }, view, buffer, changeTrees, isEncodeAll);
         }
         else {
             //
             // only clear changes after making sure buffer resize is not required.
             //
-            if (!isEncodeAll && !hasView) {
+            if (shouldClearChanges) {
                 //
                 // FIXME: avoid iterating over change trees twice.
                 //
                 this.onEndEncode(changeTrees);
             }
-            // return bytes;
-            return bytes.slice(0, it.offset);
+            return buffer.subarray(0, it.offset);
         }
     }
-    encodeAll(it = { offset: 0 }) {
-        // console.log(`encodeAll(), this.$root.allChanges (${this.$root.allChanges.size})`);
-        // Array.from(this.$root.allChanges.entries()).map((item) => {
-        //     console.log("->", item[0].refId, item[0].ref.toJSON());
-        // });
-        return this.encode(it, undefined, this.sharedBuffer, this.root.allChanges);
+    encodeAll(it = { offset: 0 }, buffer = this.sharedBuffer) {
+        // console.log(`\nencodeAll(), this.root.allChanges (${this.root.allChanges.size})`);
+        // this.debugChanges("allChanges");
+        return this.encode(it, undefined, buffer, this.root.allChanges, true);
     }
     encodeAllView(view, sharedOffset, it, bytes = this.sharedBuffer) {
         const viewOffset = it.offset;
-        // console.log(`encodeAllView(), this.$root.allFilteredChanges (${this.$root.allFilteredChanges.size})`);
-        // this.debugAllFilteredChanges();
+        // console.log(`\nencodeAllView(), this.root.allFilteredChanges (${this.root.allFilteredChanges.size})`);
+        // this.debugChanges("allFilteredChanges");
         // try to encode "filtered" changes
-        this.encode(it, view, bytes, this.root.allFilteredChanges);
+        this.encode(it, view, bytes, this.root.allFilteredChanges, true, viewOffset);
         return Buffer.concat([
-            bytes.slice(0, sharedOffset),
-            bytes.slice(viewOffset, it.offset)
+            bytes.subarray(0, sharedOffset),
+            bytes.subarray(viewOffset, it.offset)
         ]);
     }
-    // debugAllFilteredChanges() {
-    //     Array.from(this.$root.allFilteredChanges.entries()).map((item) => {
-    //         console.log("->", { refId: item[0].refId }, item[0].ref.toJSON());
-    //         if (Array.isArray(item[0].ref.toJSON())) {
-    //             item[1].forEach((op, key) => {
-    //                 console.log("  ->", { key, op: OPERATION[op] });
-    //             })
-    //         }
-    //     });
-    // }
+    debugChanges(field) {
+        const changeSet = (typeof (field) === "string")
+            ? this.root[field]
+            : field;
+        Array.from(changeSet.entries()).map((item) => {
+            const metadata = item[0].ref.constructor[Symbol.metadata];
+            console.log("->", { ref: item[0].ref.constructor.name, refId: item[0].refId, changes: item[1].size });
+            item[1].forEach((op, index) => {
+                console.log("  ->", {
+                    index,
+                    field: metadata?.[index],
+                    op: exports.OPERATION[op],
+                });
+            });
+        });
+    }
     encodeView(view, sharedOffset, it, bytes = this.sharedBuffer) {
         const viewOffset = it.offset;
-        // try to encode "filtered" changes
-        this.encode(it, view, bytes, this.root.filteredChanges);
+        // console.log(`\nencodeView(), view.changes (${view.changes.size})`);
+        // this.debugChanges(view.changes);
+        // console.log(`\nencodeView(), this.root.filteredChanges (${this.root.filteredChanges.size})`);
+        // this.debugChanges("filteredChanges");
         // encode visibility changes (add/remove for this view)
         const viewChangesIterator = view.changes.entries();
         for (const [changeTree, changes] of viewChangesIterator) {
@@ -3515,15 +3674,22 @@ class Encoder {
         //
         // clear "view" changes after encoding
         view.changes.clear();
+        // try to encode "filtered" changes
+        this.encode(it, view, bytes, this.root.filteredChanges, false, viewOffset);
         return Buffer.concat([
-            bytes.slice(0, sharedOffset),
-            bytes.slice(viewOffset, it.offset)
+            bytes.subarray(0, sharedOffset),
+            bytes.subarray(viewOffset, it.offset)
         ]);
     }
     onEndEncode(changeTrees = this.root.changes) {
         const changeTreesIterator = changeTrees.entries();
         for (const [changeTree, _] of changeTreesIterator) {
             changeTree.endEncode();
+            // changeTree.changes.clear();
+            // // ArraySchema and MapSchema have a custom "encode end" method
+            // changeTree.ref[$onEncodeEnd]?.();
+            // // Not a new instance anymore
+            // delete changeTree[$isNew];
         }
     }
     discardChanges() {
@@ -3639,8 +3805,9 @@ class ReferenceTracker {
             // Ensure child schema instances have their references removed as well.
             //
             if (Metadata.isValidInstance(ref)) {
-                const metadata = ref['constructor'][Symbol.metadata];
-                for (const field in metadata) {
+                const metadata = ref.constructor[Symbol.metadata];
+                for (const index in metadata) {
+                    const field = metadata[index].name;
                     const childRefId = typeof (ref[field]) === "object" && this.refIds.get(ref[field]);
                     if (childRefId) {
                         this.removeRef(childRefId);
@@ -3687,21 +3854,21 @@ class ReferenceTracker {
 class Decoder {
     constructor(root, context) {
         this.currentRefId = 0;
-        this.setRoot(root);
+        this.setState(root);
         this.context = context || new TypeContext(root.constructor);
         // console.log(">>>>>>>>>>>>>>>> Decoder types");
         // this.context.schemas.forEach((id, schema) => {
         //     console.log("type:", id, schema.name, Object.keys(schema[Symbol.metadata]));
         // });
     }
-    setRoot(root) {
+    setState(root) {
         this.state = root;
-        this.$root = new ReferenceTracker();
-        this.$root.addRef(0, root);
+        this.root = new ReferenceTracker();
+        this.root.addRef(0, root);
     }
     decode(bytes, it = { offset: 0 }, ref = this.state) {
         const allChanges = [];
-        const $root = this.$root;
+        const $root = this.root;
         const totalBytes = bytes.byteLength;
         let decoder = ref['constructor'][$decoder];
         this.currentRefId = 0;
@@ -3782,7 +3949,7 @@ class Decoder {
                 previousValue: value
             });
             if (needRemoveRef) {
-                this.$root.removeRef(this.$root.refIds.get(value));
+                this.root.removeRef(this.root.refIds.get(value));
             }
         });
     }
@@ -3822,14 +3989,14 @@ class Reflection extends Schema {
         super(...arguments);
         this.types = new ArraySchema();
     }
-    static encode(instance, context) {
-        if (!context) {
-            context = new TypeContext(instance.constructor);
-        }
+    static encode(instance, context, it = { offset: 0 }) {
+        context ??= new TypeContext(instance.constructor);
         const reflection = new Reflection();
         const encoder = new Encoder(reflection);
         const buildType = (currentType, metadata) => {
-            for (const fieldName in metadata) {
+            for (const fieldIndex in metadata) {
+                const index = Number(fieldIndex);
+                const fieldName = metadata[index].name;
                 // skip fields from parent classes
                 if (!Object.prototype.hasOwnProperty.call(metadata, fieldName)) {
                     continue;
@@ -3837,7 +4004,7 @@ class Reflection extends Schema {
                 const field = new ReflectionField();
                 field.name = fieldName;
                 let fieldType;
-                const type = metadata[fieldName].type;
+                const type = metadata[index].type;
                 if (typeof (type) === "string") {
                     fieldType = type;
                 }
@@ -3879,7 +4046,6 @@ class Reflection extends Schema {
             }
             buildType(type, klass[Symbol.metadata]);
         }
-        const it = { offset: 0 };
         const buf = encoder.encodeAll(it);
         return Buffer.from(buf, 0, it.offset);
     }
@@ -3887,59 +4053,304 @@ class Reflection extends Schema {
         const reflection = new Reflection();
         const reflectionDecoder = new Decoder(reflection);
         reflectionDecoder.decode(bytes, it);
-        const context = new TypeContext();
-        const schemaTypes = reflection.types.reduce((types, reflectionType) => {
-            const parentKlass = types[reflectionType.extendsId] || Schema;
-            const schema = class _ extends parentKlass {
+        const typeContext = new TypeContext();
+        // 1st pass, initialize metadata + inheritance
+        reflection.types.forEach((reflectionType) => {
+            const parentClass = typeContext.get(reflectionType.extendsId) ?? Schema;
+            const schema = class _ extends parentClass {
             };
-            // const _metadata = Object.create(_classSuper[Symbol.metadata] ?? null);
-            const _metadata = parentKlass && parentKlass[Symbol.metadata] || Object.create(null);
-            Object.defineProperty(schema, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            const parentMetadata = parentClass[Symbol.metadata];
             // register for inheritance support
             TypeContext.register(schema);
-            const typeid = reflectionType.id;
-            types[typeid] = schema;
-            context.add(schema, typeid);
-            return types;
+            // for inheritance support
+            Metadata.initialize(schema, parentMetadata);
+            typeContext.add(schema, reflectionType.id);
         }, {});
+        // 2nd pass, set fields
         reflection.types.forEach((reflectionType) => {
-            const schemaType = schemaTypes[reflectionType.id];
+            const schemaType = typeContext.get(reflectionType.id);
             const metadata = schemaType[Symbol.metadata];
-            const parentKlass = reflection.types[reflectionType.extendsId];
-            const parentFieldIndex = parentKlass && parentKlass.fields.length || 0;
+            const parentFieldIndex = 0;
             reflectionType.fields.forEach((field, i) => {
                 const fieldIndex = parentFieldIndex + i;
                 if (field.referencedType !== undefined) {
                     let fieldType = field.type;
-                    let refType = schemaTypes[field.referencedType];
+                    let refType = typeContext.get(field.referencedType);
                     // map or array of primitive type (-1)
                     if (!refType) {
                         const typeInfo = field.type.split(":");
                         fieldType = typeInfo[0];
-                        refType = typeInfo[1];
+                        refType = typeInfo[1]; // string
                     }
                     if (fieldType === "ref") {
-                        // type(refType)(schemaType.prototype, field.name);
                         Metadata.addField(metadata, fieldIndex, field.name, refType);
                     }
                     else {
-                        // type({ [fieldType]: refType } as DefinitionType)(schemaType.prototype, field.name);
                         Metadata.addField(metadata, fieldIndex, field.name, { [fieldType]: refType });
                     }
                 }
                 else {
-                    // type(field.type as PrimitiveType)(schemaType.prototype, field.name);
                     Metadata.addField(metadata, fieldIndex, field.name, field.type);
                 }
             });
         });
-        return new (schemaTypes[0])();
+        // @ts-ignore
+        return new (typeContext.get(0))();
     }
 }
 __decorate([
     type([ReflectionType])
 ], Reflection.prototype, "types", void 0);
 
+function getDecoderStateCallbacks(decoder) {
+    const $root = decoder.root;
+    const callbacks = $root.callbacks;
+    const onAddCalls = new WeakMap();
+    let currentOnAddCallback;
+    decoder.triggerChanges = function (allChanges) {
+        const uniqueRefIds = new Set();
+        for (let i = 0, l = allChanges.length; i < l; i++) {
+            const change = allChanges[i];
+            const refId = change.refId;
+            const ref = change.ref;
+            const $callbacks = callbacks[refId];
+            if (!$callbacks) {
+                continue;
+            }
+            //
+            // trigger onRemove on child structure.
+            //
+            if ((change.op & exports.OPERATION.DELETE) === exports.OPERATION.DELETE &&
+                change.previousValue instanceof Schema) {
+                const deleteCallbacks = callbacks[$root.refIds.get(change.previousValue)]?.[exports.OPERATION.DELETE];
+                for (let i = deleteCallbacks?.length - 1; i >= 0; i--) {
+                    deleteCallbacks[i]();
+                }
+            }
+            if (ref instanceof Schema) {
+                //
+                // Handle schema instance
+                //
+                if (!uniqueRefIds.has(refId)) {
+                    // trigger onChange
+                    const replaceCallbacks = $callbacks?.[exports.OPERATION.REPLACE];
+                    for (let i = replaceCallbacks?.length - 1; i >= 0; i--) {
+                        replaceCallbacks[i]();
+                        // try {
+                        // } catch (e) {
+                        //     console.error(e);
+                        // }
+                    }
+                }
+                if ($callbacks.hasOwnProperty(change.field)) {
+                    const fieldCallbacks = $callbacks[change.field];
+                    for (let i = fieldCallbacks?.length - 1; i >= 0; i--) {
+                        fieldCallbacks[i](change.value, change.previousValue);
+                        // try {
+                        // } catch (e) {
+                        //     console.error(e);
+                        // }
+                    }
+                }
+            }
+            else {
+                //
+                // Handle collection of items
+                //
+                if ((change.op & exports.OPERATION.DELETE) === exports.OPERATION.DELETE) {
+                    //
+                    // FIXME: `previousValue` should always be available.
+                    //
+                    if (change.previousValue !== undefined) {
+                        // triger onRemove
+                        const deleteCallbacks = $callbacks[exports.OPERATION.DELETE];
+                        for (let i = deleteCallbacks?.length - 1; i >= 0; i--) {
+                            deleteCallbacks[i](change.previousValue, change.dynamicIndex ?? change.field);
+                        }
+                    }
+                    // Handle DELETE_AND_ADD operations
+                    if ((change.op & exports.OPERATION.ADD) === exports.OPERATION.ADD) {
+                        const addCallbacks = $callbacks[exports.OPERATION.ADD];
+                        for (let i = addCallbacks?.length - 1; i >= 0; i--) {
+                            addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
+                        }
+                    }
+                }
+                else if ((change.op & exports.OPERATION.ADD) === exports.OPERATION.ADD && change.previousValue === undefined) {
+                    // triger onAdd
+                    const addCallbacks = $callbacks[exports.OPERATION.ADD];
+                    for (let i = addCallbacks?.length - 1; i >= 0; i--) {
+                        addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
+                    }
+                }
+                // trigger onChange
+                if (change.value !== change.previousValue) {
+                    const replaceCallbacks = $callbacks[exports.OPERATION.REPLACE];
+                    for (let i = replaceCallbacks?.length - 1; i >= 0; i--) {
+                        replaceCallbacks[i](change.value, change.dynamicIndex ?? change.field);
+                    }
+                }
+            }
+            uniqueRefIds.add(refId);
+        }
+    };
+    function getProxy(metadataOrType, context) {
+        let metadata = context.instance?.constructor[Symbol.metadata] || metadataOrType;
+        let isCollection = ((context.instance && typeof (context.instance['forEach']) === "function") ||
+            (metadataOrType && typeof (metadataOrType[Symbol.metadata]) === "undefined"));
+        if (metadata && !isCollection) {
+            const onAddListen = function (ref, prop, callback, immediate) {
+                // immediate trigger
+                if (immediate &&
+                    context.instance[prop] !== undefined &&
+                    !onAddCalls.has(currentOnAddCallback) // Workaround for https://github.com/colyseus/schema/issues/147
+                ) {
+                    callback(context.instance[prop], undefined);
+                }
+                return $root.addCallback($root.refIds.get(ref), prop, callback);
+            };
+            /**
+             * Schema instances
+             */
+            return new Proxy({
+                listen: function listen(prop, callback, immediate = true) {
+                    if (context.instance) {
+                        return onAddListen(context.instance, prop, callback, immediate);
+                    }
+                    else {
+                        // collection instance not received yet
+                        let detachCallback = () => { };
+                        context.onInstanceAvailable((ref, existing) => {
+                            detachCallback = onAddListen(ref, prop, callback, immediate && existing && !onAddCalls.has(currentOnAddCallback));
+                        });
+                        return () => detachCallback();
+                    }
+                },
+                onChange: function onChange(callback) {
+                    return $root.addCallback($root.refIds.get(context.instance), exports.OPERATION.REPLACE, callback);
+                },
+                //
+                // TODO: refactor `bindTo()` implementation.
+                // There is room for improvement.
+                //
+                bindTo: function bindTo(targetObject, properties) {
+                    if (!properties) {
+                        properties = Object.keys(metadata).map((index) => metadata[index].name);
+                    }
+                    return $root.addCallback($root.refIds.get(context.instance), exports.OPERATION.REPLACE, () => {
+                        properties.forEach((prop) => targetObject[prop] = context.instance[prop]);
+                    });
+                }
+            }, {
+                get(target, prop) {
+                    const metadataField = metadata[metadata[prop]];
+                    if (metadataField) {
+                        const instance = context.instance?.[prop];
+                        const onInstanceAvailable = ((callback) => {
+                            const unbind = $(context.instance).listen(prop, (value, _) => {
+                                callback(value, false);
+                                // FIXME: by "unbinding" the callback here,
+                                // it will not support when the server
+                                // re-instantiates the instance.
+                                //
+                                unbind?.();
+                            }, false);
+                            // has existing value
+                            if ($root.refIds.get(instance) !== undefined) {
+                                callback(instance, true);
+                            }
+                        });
+                        return getProxy(metadataField.type, {
+                            // make sure refId is available, otherwise need to wait for the instance to be available.
+                            instance: ($root.refIds.get(instance) && instance),
+                            parentInstance: context.instance,
+                            onInstanceAvailable,
+                        });
+                    }
+                    else {
+                        // accessing the function
+                        return target[prop];
+                    }
+                },
+                has(target, prop) { return metadata[prop] !== undefined; },
+                set(_, _1, _2) { throw new Error("not allowed"); },
+                deleteProperty(_, _1) { throw new Error("not allowed"); },
+            });
+        }
+        else {
+            /**
+             * Collection instances
+             */
+            const onAdd = function (ref, callback, immediate) {
+                // Trigger callback on existing items
+                if (immediate) {
+                    ref.forEach((v, k) => callback(v, k));
+                }
+                return $root.addCallback($root.refIds.get(ref), exports.OPERATION.ADD, (value, key) => {
+                    onAddCalls.set(callback, true);
+                    currentOnAddCallback = callback;
+                    callback(value, key);
+                    onAddCalls.delete(callback);
+                    currentOnAddCallback = undefined;
+                });
+            };
+            const onRemove = function (ref, callback) {
+                return $root.addCallback($root.refIds.get(ref), exports.OPERATION.DELETE, callback);
+            };
+            return new Proxy({
+                onAdd: function (callback, immediate = true) {
+                    //
+                    // https://github.com/colyseus/schema/issues/147
+                    // If parent instance has "onAdd" registered, avoid triggering immediate callback.
+                    //
+                    if (context.instance) {
+                        return onAdd(context.instance, callback, immediate && !onAddCalls.has(currentOnAddCallback));
+                    }
+                    else if (context.onInstanceAvailable) {
+                        // collection instance not received yet
+                        let detachCallback = () => { };
+                        context.onInstanceAvailable((ref, existing) => {
+                            detachCallback = onAdd(ref, callback, immediate && existing && !onAddCalls.has(currentOnAddCallback));
+                        });
+                        return () => detachCallback();
+                    }
+                },
+                onRemove: function (callback) {
+                    if (context.onInstanceAvailable) {
+                        // collection instance not received yet
+                        let detachCallback = () => { };
+                        context.onInstanceAvailable((ref) => {
+                            detachCallback = onRemove(ref, callback);
+                        });
+                        return () => detachCallback();
+                    }
+                    else if (context.instance) {
+                        return onRemove(context.instance, callback);
+                    }
+                },
+            }, {
+                get(target, prop) {
+                    if (!target[prop]) {
+                        throw new Error(`Can't access '${prop}' through callback proxy. access the instance directly.`);
+                    }
+                    return target[prop];
+                },
+                has(target, prop) { return target[prop] !== undefined; },
+                set(_, _1, _2) { throw new Error("not allowed"); },
+                deleteProperty(_, _1) { throw new Error("not allowed"); },
+            });
+        }
+    }
+    function $(instance) {
+        return getProxy(undefined, { instance });
+    }
+    return $;
+}
+
+function getRawChangesCallback(decoder, callback) {
+    decoder.triggerChanges = callback;
+}
+
 class StateView {
     constructor() {
         /**
@@ -3957,20 +4368,21 @@ class StateView {
         this.changes = new Map();
     }
     // TODO: allow to set multiple tags at once
-    add(obj, tag = DEFAULT_VIEW_TAG) {
+    add(obj, tag = DEFAULT_VIEW_TAG, checkIncludeParent = true) {
         if (!obj[$changes]) {
             console.warn("StateView#add(), invalid object:", obj);
             return this;
         }
-        let changeTree = obj[$changes];
-        this.items.add(changeTree);
-        // Add children of this ChangeTree to this view
-        changeTree.forEachChild((change, _) => this.add(change.ref, tag));
-        // FIXME: ArraySchema/MapSchema does not have metadata
+        // FIXME: ArraySchema/MapSchema do not have metadata
         const metadata = obj.constructor[Symbol.metadata];
-        // add parent ChangeTree's, if they are invisible to this view
-        // TODO: REFACTOR addParent()
-        this.addParent(changeTree, tag);
+        const changeTree = obj[$changes];
+        this.items.add(changeTree);
+        // add parent ChangeTree's
+        // - if it was invisible to this view
+        // - if it were previously filtered out
+        if (checkIncludeParent && changeTree.parent) {
+            this.addParent(changeTree.parent[$changes], changeTree.parentIndex, tag);
+        }
         //
         // TODO: when adding an item of a MapSchema, the changes may not
         // be set (only the parent's changes are set)
@@ -3994,7 +4406,6 @@ class StateView {
                 tags = this.tags.get(changeTree);
             }
             tags.add(tag);
-            // console.log("BY TAG:", tag);
             // Ref: add tagged properties
             metadata?.[-3]?.[tag]?.forEach((index) => {
                 if (changeTree.getChange(index) !== exports.OPERATION.DELETE) {
@@ -4003,73 +4414,63 @@ class StateView {
             });
         }
         else {
-            // console.log("DEFAULT TAG", changeTree.allChanges);
-            // // add default tag properties
-            // metadata?.[-3]?.[DEFAULT_VIEW_TAG]?.forEach((index) => {
-            //     if (changeTree.getChange(index) !== OPERATION.DELETE) {
-            //         changes.set(index, OPERATION.ADD);
-            //     }
-            // });
-            const allChangesSet = (changeTree.isFiltered || changeTree.isPartiallyFiltered)
+            const isInvisible = this.invisible.has(changeTree);
+            const changeSet = (changeTree.isFiltered || changeTree.isPartiallyFiltered)
                 ? changeTree.allFilteredChanges
                 : changeTree.allChanges;
-            const it = allChangesSet.keys();
-            const isInvisible = this.invisible.has(changeTree);
-            for (const index of it) {
-                if ((isInvisible || metadata?.[metadata?.[index]].tag === tag) &&
-                    changeTree.getChange(index) !== exports.OPERATION.DELETE) {
-                    changes.set(index, exports.OPERATION.ADD);
+            changeSet.forEach((op, index) => {
+                const tagAtIndex = metadata?.[index].tag;
+                if ((isInvisible || // if "invisible", include all
+                    tagAtIndex === undefined || // "all change" with no tag
+                    tagAtIndex === tag // tagged property
+                ) &&
+                    op !== exports.OPERATION.DELETE) {
+                    changes.set(index, op);
                 }
-            }
-        }
-        // TODO: avoid unnecessary iteration here
-        while (changeTree.parent &&
-            (changeTree = changeTree.parent[$changes]) &&
-            (changeTree.isFiltered || changeTree.isPartiallyFiltered)) {
-            this.items.add(changeTree);
+            });
         }
+        // Add children of this ChangeTree to this view
+        changeTree.forEachChild((change, index) => {
+            // Do not ADD children that don't have the same tag
+            if (metadata && metadata[index].tag !== tag) {
+                return;
+            }
+            this.add(change.ref, tag, false);
+        });
         return this;
     }
-    addParent(changeTree, tag) {
-        const parentRef = changeTree.parent;
-        if (!parentRef) {
-            return;
+    addParent(changeTree, parentIndex, tag) {
+        // view must have all "changeTree" parent tree
+        this.items.add(changeTree);
+        // add parent's parent
+        const parentChangeTree = changeTree.parent?.[$changes];
+        if (parentChangeTree && (parentChangeTree.isFiltered || parentChangeTree.isPartiallyFiltered)) {
+            this.addParent(parentChangeTree, changeTree.parentIndex, tag);
         }
-        const parentChangeTree = parentRef[$changes];
-        const parentIndex = changeTree.parentIndex;
-        if (!this.invisible.has(parentChangeTree)) {
-            // parent is already available, no need to add it!
+        // parent is already available, no need to add it!
+        if (!this.invisible.has(changeTree)) {
             return;
         }
-        this.addParent(parentChangeTree, tag);
         // add parent's tag properties
-        if (parentChangeTree.getChange(parentIndex) !== exports.OPERATION.DELETE) {
-            let parentChanges = this.changes.get(parentChangeTree);
-            if (parentChanges === undefined) {
-                parentChanges = new Map();
-                this.changes.set(parentChangeTree, parentChanges);
+        if (changeTree.getChange(parentIndex) !== exports.OPERATION.DELETE) {
+            let changes = this.changes.get(changeTree);
+            if (changes === undefined) {
+                changes = new Map();
+                this.changes.set(changeTree, changes);
             }
-            // console.log("add parent change", {
-            //     parentIndex,
-            //     parentChanges,
-            //     parentChange: (
-            //         parentChangeTree.getChange(parentIndex) &&
-            //         OPERATION[parentChangeTree.getChange(parentIndex)]
-            //     ),
-            // })
             if (!this.tags) {
                 this.tags = new WeakMap();
             }
             let tags;
-            if (!this.tags.has(parentChangeTree)) {
+            if (!this.tags.has(changeTree)) {
                 tags = new Set();
-                this.tags.set(parentChangeTree, tags);
+                this.tags.set(changeTree, tags);
             }
             else {
-                tags = this.tags.get(parentChangeTree);
+                tags = this.tags.get(changeTree);
             }
             tags.add(tag);
-            parentChanges.set(parentIndex, exports.OPERATION.ADD);
+            changes.set(parentIndex, exports.OPERATION.ADD);
         }
     }
     remove(obj, tag = DEFAULT_VIEW_TAG) {
@@ -4164,6 +4565,8 @@ exports.dumpChanges = dumpChanges;
 exports.encode = encode;
 exports.encodeKeyValueOperation = encodeArray;
 exports.encodeSchemaOperation = encodeSchemaOperation;
+exports.getDecoderStateCallbacks = getDecoderStateCallbacks;
+exports.getRawChangesCallback = getRawChangesCallback;
 exports.registerType = registerType;
 exports.type = type;
 exports.view = view;