@colyseus/schema 3.0.0-alpha.2 → 3.0.0-alpha.23

package/build/umd/index.js

@@ -29,6 +29,7 @@
         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");
@@ -145,6 +146,45 @@
         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.constructor[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));
@@ -264,14 +304,12 @@
             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);
@@ -363,7 +401,6 @@
         }
         _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);
@@ -504,7 +541,7 @@
         }
         checkIsFiltered(parent, parentIndex) {
             // Detect if current structure has "filters" declared
-            this.isPartiallyFiltered = this.ref['constructor']?.[Symbol.metadata]?.[-2];
+            this.isPartiallyFiltered = (this.ref['constructor']?.[Symbol.metadata]?.[-2] !== undefined);
             // 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) {
@@ -565,26 +602,29 @@
         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++) {
@@ -679,8 +719,7 @@
         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) {
@@ -791,23 +830,23 @@
 
     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 {
@@ -949,6 +988,18 @@
         }
         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);
     };
@@ -958,15 +1009,19 @@
      */
     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;
@@ -975,7 +1030,7 @@
             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;
@@ -1015,9 +1070,9 @@
      * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
      * SOFTWARE
      */
-    function utf8Read(bytes, offset, length) {
+    function utf8Read(bytes, it, length) {
         var string = '', chr = 0;
-        for (var i = offset, end = offset + length; i < end; i++) {
+        for (var i = it.offset, end = it.offset + length; i < end; i++) {
             var byte = bytes[i];
             if ((byte & 0x80) === 0x00) {
                 string += String.fromCharCode(byte);
@@ -1052,6 +1107,7 @@
             // (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) {
@@ -1119,9 +1175,7 @@
         else if (prefix === 0xdb) {
             length = uint32(bytes, it);
         }
-        const value = utf8Read(bytes, it.offset, length);
-        it.offset += length;
-        return value;
+        return utf8Read(bytes, it, length);
     }
     function stringCheck(bytes, it) {
         const prefix = bytes[it.offset];
@@ -1225,30 +1279,31 @@
 
     var decode = /*#__PURE__*/Object.freeze({
         __proto__: null,
-        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) {
@@ -1434,7 +1489,8 @@
     };
     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:
@@ -1448,8 +1504,8 @@
         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,
@@ -1462,7 +1518,18 @@
             });
             return;
         }
-        const index = number(bytes, it);
+        else if (operation === exports.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);
@@ -1871,14 +1938,6 @@
         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);
         }
@@ -2557,6 +2616,7 @@
             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]) {
                 //
@@ -2581,8 +2641,8 @@
             // 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()`)
@@ -3355,6 +3415,8 @@
     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;
@@ -3386,11 +3448,14 @@
         setRoot(state) {
             this.root = new Root();
             this.state = state;
+            // Workaround to allow using an empty Schema.
+            if (state.constructor[Symbol.metadata] === undefined) {
+                Metadata.init(state);
+            }
             state[$changes].setRoot(this.root);
         }
-        encode(it = { offset: 0 }, view, bytes = this.sharedBuffer, changeTrees = this.root.changes) {
+        encode(it = { offset: 0 }, view, buffer = this.sharedBuffer, changeTrees = this.root.changes, isEncodeAll = this.root.allChanges === changeTrees) {
             const initialOffset = it.offset; // cache current offset in case we need to resize the buffer
-            const isEncodeAll = this.root.allChanges === changeTrees;
             const hasView = (view !== undefined);
             const rootChangeTree = this.state[$changes];
             const changeTreesIterator = changeTrees.entries();
@@ -3399,6 +3464,12 @@
                 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);
@@ -3410,8 +3481,8 @@
                 }
                 // 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);
+                    buffer[it.offset++] = SWITCH_TO_STRUCTURE & 255;
+                    number$1(buffer, changeTree.refId, it);
                 }
                 const changesIterator = changes.entries();
                 for (const [fieldIndex, operation] of changesIterator) {
@@ -3428,22 +3499,35 @@
                         // 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 {
                 //
@@ -3455,38 +3539,37 @@
                     //
                     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());
+        encodeAll(it = { offset: 0 }, buffer = this.sharedBuffer) {
+            // console.log(`encodeAll(), this.root.allChanges (${this.root.allChanges.size})`);
+            // Array.from(this.root.allChanges.entries()).map((item) => {
+            //     console.log("->", { ref: item[0].ref.constructor.name, refId: item[0].refId, changes: item[1].size });
             // });
-            return this.encode(it, undefined, this.sharedBuffer, this.root.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})`);
+            // console.log(`encodeAllView(), this.root.allFilteredChanges (${this.root.allFilteredChanges.size})`);
             // this.debugAllFilteredChanges();
             // try to encode "filtered" changes
-            this.encode(it, view, bytes, this.root.allFilteredChanges);
+            this.encode(it, view, bytes, this.root.allFilteredChanges, true);
             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] });
-        //             })
-        //         }
-        //     });
-        // }
+        debugAllFilteredChanges() {
+            Array.from(this.root.allFilteredChanges.entries()).map((item) => {
+                console.log("->", { refId: item[0].refId, changes: item[1].size }, item[0].ref.toJSON());
+                if (Array.isArray(item[0].ref.toJSON())) {
+                    item[1].forEach((op, key) => {
+                        console.log("  ->", { key, op: exports.OPERATION[op] });
+                    });
+                }
+            });
+        }
         encodeView(view, sharedOffset, it, bytes = this.sharedBuffer) {
             const viewOffset = it.offset;
             // try to encode "filtered" changes
@@ -3518,8 +3601,8 @@
             // clear "view" changes after encoding
             view.changes.clear();
             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) {
@@ -3698,12 +3781,12 @@
         }
         setRoot(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;
@@ -3784,7 +3867,7 @@
                     previousValue: value
                 });
                 if (needRemoveRef) {
-                    this.$root.removeRef(this.$root.refIds.get(value));
+                    this.root.removeRef(this.root.refIds.get(value));
                 }
             });
         }
@@ -3824,7 +3907,7 @@
             super(...arguments);
             this.types = new ArraySchema();
         }
-        static encode(instance, context) {
+        static encode(instance, context, it = { offset: 0 }) {
             if (!context) {
                 context = new TypeContext(instance.constructor);
             }
@@ -3881,7 +3964,6 @@
                 }
                 buildType(type, klass[Symbol.metadata]);
             }
-            const it = { offset: 0 };
             const buf = encoder.encodeAll(it);
             return Buffer.from(buf, 0, it.offset);
         }
@@ -3889,59 +3971,298 @@
             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;
+        let isTriggeringOnAdd = false;
+        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
+                        // FIXME: should we set "isTriggeringOnAdd" here?
+                        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
+                        isTriggeringOnAdd = true;
+                        const addCallbacks = $callbacks[exports.OPERATION.ADD];
+                        for (let i = addCallbacks?.length - 1; i >= 0; i--) {
+                            addCallbacks[i](change.value, change.dynamicIndex ?? change.field);
+                        }
+                        isTriggeringOnAdd = false;
+                    }
+                    // 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 onAdd = function (ref, prop, callback, immediate) {
+                    // immediate trigger
+                    if (immediate &&
+                        context.instance[prop] !== undefined &&
+                        !isTriggeringOnAdd // FIXME: This is a workaround (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 onAdd(context.instance, prop, callback, immediate);
+                        }
+                        else {
+                            // collection instance not received yet
+                            context.onInstanceAvailable((ref, existing) => onAdd(ref, prop, callback, immediate && existing));
+                        }
+                    },
+                    onChange: function onChange(callback) {
+                        return $root.addCallback($root.refIds.get(context.instance), exports.OPERATION.REPLACE, callback);
+                    },
+                    bindTo: function bindTo(targetObject, properties) {
+                        //
+                        // TODO: refactor this implementation. There is room for improvement here.
+                        //
+                        if (!properties) {
+                            properties = Object.keys(metadata);
+                        }
+                        return $root.addCallback($root.refIds.get(context.instance), exports.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, {
+                                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, callback);
+                };
+                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.
+                        //
+                        // FIXME: "isTriggeringOnAdd" is a workaround. We should find a better way to handle this.
+                        //
+                        if (context.onInstanceAvailable) {
+                            // collection instance not received yet
+                            context.onInstanceAvailable((ref, existing) => onAdd(ref, callback, immediate && existing && !isTriggeringOnAdd));
+                        }
+                        else if (context.instance) {
+                            onAdd(context.instance, callback, immediate && !isTriggeringOnAdd);
+                        }
+                    },
+                    onRemove: function (callback) {
+                        if (context.onInstanceAvailable) {
+                            // collection instance not received yet
+                            context.onInstanceAvailable((ref) => onRemove(ref, callback));
+                        }
+                        else if (context.instance) {
+                            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() {
             /**
@@ -3964,12 +4285,18 @@
                 console.warn("StateView#add(), invalid object:", obj);
                 return this;
             }
+            // FIXME: ArraySchema/MapSchema does not have metadata
+            const metadata = obj.constructor[Symbol.metadata];
             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];
+            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);
+            });
             // add parent ChangeTree's, if they are invisible to this view
             // TODO: REFACTOR addParent()
             this.addParent(changeTree, tag);
@@ -3996,7 +4323,6 @@
                     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) {
@@ -4166,10 +4492,10 @@
     exports.encode = encode;
     exports.encodeKeyValueOperation = encodeArray;
     exports.encodeSchemaOperation = encodeSchemaOperation;
+    exports.getDecoderStateCallbacks = getDecoderStateCallbacks;
+    exports.getRawChangesCallback = getRawChangesCallback;
     exports.registerType = registerType;
     exports.type = type;
     exports.view = view;
 
-    Object.defineProperty(exports, '__esModule', { value: true });
-
 }));