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

package/build/esm/index.mjs

@@ -23,6 +23,7 @@ var OPERATION;
     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";
 })(OPERATION || (OPERATION = {}));
 
 Symbol.metadata ??= Symbol.for("Symbol.metadata");
@@ -139,6 +140,45 @@ const Metadata = {
     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++) {
+                    Object.defineProperty(metadata, i, {
+                        value: parentMetadata[i],
+                        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));
@@ -154,44 +194,6 @@ const Metadata = {
 };
 
 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; }
     ;
@@ -223,8 +225,6 @@ class ChangeTree {
         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);
         }
         if (!this.isFiltered) {
             this.root.allChanges.set(this, this.allChanges);
@@ -258,14 +258,12 @@ class ChangeTree {
         this.checkIsFiltered(parent, parentIndex);
         if (!this.isFiltered) {
             this.root.changes.set(this, this.changes);
+            this.root.allChanges.set(this, this.allChanges);
         }
         if (this.isFiltered || this.isPartiallyFiltered) {
             this.root.filteredChanges.set(this, this.filteredChanges);
             this.root.allFilteredChanges.set(this, this.filteredChanges);
         }
-        else {
-            this.root.allChanges.set(this, this.allChanges);
-        }
         this.ensureRefId();
         this.forEachChild((changeTree, atIndex) => {
             changeTree.setParent(this.ref, root, atIndex);
@@ -289,7 +287,7 @@ class ChangeTree {
             // MapSchema / ArraySchema, etc.
             this.ref.forEach((value, key) => {
                 if (Metadata.isValidInstance(value)) {
-                    callback(value[$changes], this.ref[$changes].indexes[key]);
+                    callback(value[$changes], this.ref[$changes].indexes[key] ?? key);
                 }
             });
         }
@@ -317,8 +315,9 @@ class ChangeTree {
         // TODO: are DELETE operations being encoded as ADD here ??
         //
         if (isFiltered) {
-            this.allFilteredChanges.set(index, OPERATION.ADD);
             this.root?.filteredChanges.set(this, this.filteredChanges);
+            this.allFilteredChanges.set(index, OPERATION.ADD);
+            this.root?.allFilteredChanges.set(this, this.allFilteredChanges);
         }
         else {
             this.allChanges.set(index, OPERATION.ADD);
@@ -357,7 +356,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);
@@ -498,16 +496,31 @@ class ChangeTree {
     }
     checkIsFiltered(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 = (this.ref['constructor']?.[Symbol.metadata]?.[-2] !== undefined);
+        if (parent && !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));
+        // this.isFiltered = this.ref['constructor']?.[Symbol.metadata]?.[-4];
+        // // Detect if parent has "filters" declared
+        // while (parent && !this.isFiltered) {
+        //     const metadata: Metadata = parent['constructor'][Symbol.metadata];
+        //     // this.isFiltered = metadata?.[-4];
+        //     const fieldName = metadata?.[parentIndex];
+        //     const isParentOwned = metadata?.[fieldName]?.tag !== undefined;
+        //     this.isFiltered = isParentOwned || parent[$changes].isFiltered; // metadata?.[-2]
+        //     parent = parent[$changes].parent;
+        // };
+        // console.log("ChangeTree.checkIsFiltered", {
+        //     parent: parent?.constructor.name,
+        //     ref: this.ref.constructor.name,
+        //     isFiltered: this.isFiltered,
+        //     isPartiallyFiltered: this.isPartiallyFiltered,
+        // });
         //
         // TODO: refactor this!
         //
@@ -559,26 +572,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++) {
@@ -673,8 +689,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) {
@@ -785,23 +800,23 @@ 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 {
@@ -943,6 +958,18 @@ const encodeKeyValueOperation = function (encoder, bytes, changeTree, field, ope
     }
     const type = changeTree.getType(field);
     const value = changeTree.getValue(field);
+    // 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);
 };
@@ -952,15 +979,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 === OPERATION.DELETE &&
-        typeof (changeTree.getType(field)) !== "string") {
-        // encode delete by refId (array of schemas)
-        bytes[it.offset++] = 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 === OPERATION.DELETE) {
+            operation = OPERATION.DELETE_BY_REFID;
+        }
+        else if (operation === OPERATION.ADD) {
+            operation = OPERATION.ADD_BY_REFID;
+        }
+    }
+    else {
+        refOrIndex = field;
     }
     // encode operation
     bytes[it.offset++] = operation & 255;
@@ -969,7 +1000,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 === OPERATION.DELETE) {
         return;
@@ -1010,7 +1041,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];
@@ -1047,6 +1077,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) {
@@ -1218,31 +1249,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 & OPERATION.DELETE) === OPERATION.DELETE) {
@@ -1348,6 +1379,7 @@ const decodeSchemaOperation = function (decoder, bytes, it, ref, allChanges) {
     // 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);
@@ -1428,7 +1460,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 === OPERATION.CLEAR) {
         //
         // When decoding:
@@ -1442,8 +1475,8 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
     else if (operation === 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,
@@ -1456,7 +1489,18 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
         });
         return;
     }
-    const index = number(bytes, it);
+    else if (operation === OPERATION.ADD_BY_REFID) {
+        // operation = OPERATION.ADD;
+        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);
@@ -1617,7 +1661,6 @@ class ArraySchema {
             }
             const changeTree = this[$changes];
             changeTree.indexedOperation(length, OPERATION.ADD, this.items.length);
-            // changeTree.indexes[length] = length;
             this.items.push(value);
             this.tmpItems.push(value);
             //
@@ -1865,14 +1908,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);
     }
@@ -2316,7 +2351,6 @@ class MapSchema {
 }
 registerType("map", { constructor: MapSchema });
 
-const DEFAULT_VIEW_TAG = -1;
 class TypeContext {
     /**
      * For inheritance support
@@ -2338,6 +2372,7 @@ class TypeContext {
         this.types = {};
         this.schemas = new Map();
         this.hasFilters = false;
+        this.parentFiltered = {};
         if (rootClass) {
             this.discoverTypes(rootClass);
         }
@@ -2354,32 +2389,46 @@ 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;
         }
+        if (parentFieldViewTag !== undefined) {
+            this.parentFiltered[`${this.schemas.get(klass)}-${parentIndex}`] = true;
+        }
         for (const field in metadata) {
+            // //
+            // // Modify the field's metadata to include the parent field's view tag
+            // //
+            // if (
+            //     parentFieldViewTag !== undefined &&
+            //     metadata[field].tag === undefined
+            // ) {
+            //     metadata[field].tag = parentFieldViewTag;
+            // }
             const fieldType = metadata[field].type;
+            const viewTag = metadata[field].tag;
             if (typeof (fieldType) === "string") {
                 continue;
             }
@@ -2388,10 +2437,10 @@ class TypeContext {
                 if (type === "string") {
                     continue;
                 }
-                this.discoverTypes(type);
+                this.discoverTypes(type, metadata[field].index, viewTag);
             }
             else if (typeof (fieldType) === "function") {
-                this.discoverTypes(fieldType);
+                this.discoverTypes(fieldType, viewTag);
             }
             else {
                 const type = Object.values(fieldType)[0];
@@ -2399,11 +2448,13 @@ class TypeContext {
                 if (typeof (type) === "string") {
                     continue;
                 }
-                this.discoverTypes(type);
+                this.discoverTypes(type, metadata[field].index, viewTag);
             }
         }
     }
 }
+
+const DEFAULT_VIEW_TAG = -1;
 /**
  * [See documentation](https://docs.colyseus.io/state/schema/)
  *
@@ -2551,6 +2602,7 @@ 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]) {
             //
@@ -2575,8 +2627,8 @@ 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)));
+        const parentMetadata = parentClass && parentClass[Symbol.metadata];
+        const metadata = Metadata.initialize(constructor, parentMetadata);
         let fieldIndex;
         /**
          * skip if descriptor already exists for this field (`@deprecated()`)
@@ -2957,13 +3009,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];
@@ -3349,6 +3401,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;
@@ -3362,29 +3416,68 @@ 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();
@@ -3393,6 +3486,12 @@ class Encoder {
             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);
@@ -3403,9 +3502,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) {
@@ -3417,27 +3517,39 @@ 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 (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 {
             //
@@ -3449,42 +3561,47 @@ class Encoder {
                 //
                 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: 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) {
@@ -3511,9 +3628,11 @@ 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) {
@@ -3683,21 +3802,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;
@@ -3778,7 +3897,7 @@ class Decoder {
                 previousValue: value
             });
             if (needRemoveRef) {
-                this.$root.removeRef(this.$root.refIds.get(value));
+                this.root.removeRef(this.root.refIds.get(value));
             }
         });
     }
@@ -3818,10 +3937,8 @@ 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) => {
@@ -3875,7 +3992,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);
     }
@@ -3883,59 +3999,314 @@ 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;
+            // FIXME: use metadata[-1] to get field count
+            const parentFieldIndex = 0;
+            // console.log("--------------------");
+            // // console.log("reflectionType", reflectionType.toJSON());
+            // console.log("reflectionType.fields", reflectionType.fields.toJSON());
+            // console.log("parentFieldIndex", parentFieldIndex);
+            //
+            // FIXME: set fields using parentKlass as well
+            // currently the fields are duplicated on inherited classes
+            //
+            // // const parentKlass = reflection.types[reflectionType.extendsId];
+            // // parentKlass.fields
             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 & OPERATION.DELETE) === OPERATION.DELETE &&
+                change.previousValue instanceof Schema) {
+                const deleteCallbacks = callbacks[$root.refIds.get(change.previousValue)]?.[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?.[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 & OPERATION.DELETE) === OPERATION.DELETE) {
+                    //
+                    // FIXME: `previousValue` should always be available.
+                    //
+                    if (change.previousValue !== undefined) {
+                        // triger onRemove
+                        const deleteCallbacks = $callbacks[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 & OPERATION.ADD) === OPERATION.ADD) {
+                        const addCallbacks = $callbacks[OPERATION.ADD];
+                        for (let i = addCallbacks?.length - 1; i >= 0; i--) {
+                            addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
+                        }
+                    }
+                }
+                else if ((change.op & OPERATION.ADD) === OPERATION.ADD && change.previousValue === undefined) {
+                    // triger onAdd
+                    const addCallbacks = $callbacks[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[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), OPERATION.REPLACE, callback);
+                },
+                //
+                // TODO: refactor `bindTo()` implementation.
+                // There is room for improvement.
+                //
+                bindTo: function bindTo(targetObject, properties) {
+                    if (!properties) {
+                        properties = Object.keys(metadata);
+                    }
+                    return $root.addCallback($root.refIds.get(context.instance), OPERATION.REPLACE, () => {
+                        properties.forEach((prop) => targetObject[prop] = context.instance[prop]);
+                    });
+                }
+            }, {
+                get(target, prop) {
+                    if (metadata[prop]) {
+                        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(metadata[prop].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), 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), 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() {
         /**
@@ -3953,20 +4324,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
         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)
@@ -3990,7 +4362,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) !== OPERATION.DELETE) {
@@ -3999,73 +4370,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) !== OPERATION.DELETE) {
-                    changes.set(index, OPERATION.ADD);
+            changeSet.forEach((op, index) => {
+                const tagAtIndex = metadata?.[metadata?.[index]].tag;
+                if ((isInvisible || // if "invisible", include all
+                    tagAtIndex === undefined || // "all change" with no tag
+                    tagAtIndex === tag // tagged property
+                ) &&
+                    op !== 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[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) !== OPERATION.DELETE) {
-            let parentChanges = this.changes.get(parentChangeTree);
-            if (parentChanges === undefined) {
-                parentChanges = new Map();
-                this.changes.set(parentChangeTree, parentChanges);
+        if (changeTree.getChange(parentIndex) !== 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, OPERATION.ADD);
+            changes.set(parentIndex, OPERATION.ADD);
         }
     }
     remove(obj, tag = DEFAULT_VIEW_TAG) {
@@ -4129,5 +4490,5 @@ registerType("array", { constructor: ArraySchema });
 registerType("set", { constructor: SetSchema });
 registerType("collection", { constructor: CollectionSchema, });
 
-export { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $track, ArraySchema, ChangeTree, CollectionSchema, Decoder, Encoder, MapSchema, Metadata, OPERATION, Reflection, ReflectionField, ReflectionType, Schema, SetSchema, StateView, TypeContext, decode, decodeKeyValueOperation, decodeSchemaOperation, defineTypes, deprecated, dumpChanges, encode, encodeArray as encodeKeyValueOperation, encodeSchemaOperation, registerType, type, view };
+export { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $track, ArraySchema, ChangeTree, CollectionSchema, Decoder, Encoder, MapSchema, Metadata, OPERATION, Reflection, ReflectionField, ReflectionType, Schema, SetSchema, StateView, TypeContext, decode, decodeKeyValueOperation, decodeSchemaOperation, defineTypes, deprecated, dumpChanges, encode, encodeArray as encodeKeyValueOperation, encodeSchemaOperation, getDecoderStateCallbacks, getRawChangesCallback, registerType, type, view };
 //# sourceMappingURL=index.mjs.map