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

package/build/cjs/index.js

@@ -1,7 +1,5 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 const SWITCH_TO_STRUCTURE = 255; // (decoding collides with DELETE_AND_ADD + fieldIndex = 63)
 const TYPE_ID = 213;
 /**
@@ -27,6 +25,7 @@ exports.OPERATION = void 0;
     OPERATION[OPERATION["REVERSE"] = 15] = "REVERSE";
     OPERATION[OPERATION["MOVE"] = 32] = "MOVE";
     OPERATION[OPERATION["DELETE_BY_REFID"] = 33] = "DELETE_BY_REFID";
+    OPERATION[OPERATION["ADD_BY_REFID"] = 129] = "ADD_BY_REFID";
 })(exports.OPERATION || (exports.OPERATION = {}));
 
 Symbol.metadata ??= Symbol.for("Symbol.metadata");
@@ -143,6 +142,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.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));
@@ -262,14 +300,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);
@@ -361,7 +397,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);
@@ -502,7 +537,7 @@ class ChangeTree {
     }
     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) {
@@ -563,26 +598,29 @@ try {
     textEncoder = new TextEncoder();
 }
 catch (e) { }
-function utf8Length(str) {
-    var c = 0, length = 0;
-    for (var i = 0, l = str.length; i < l; i++) {
-        c = str.charCodeAt(i);
-        if (c < 0x80) {
-            length += 1;
-        }
-        else if (c < 0x800) {
-            length += 2;
-        }
-        else if (c < 0xd800 || c >= 0xe000) {
-            length += 3;
-        }
-        else {
-            i++;
-            length += 4;
+const hasBufferByteLength = (typeof Buffer !== 'undefined' && Buffer.byteLength);
+const utf8Length = (hasBufferByteLength)
+    ? Buffer.byteLength // node
+    : function (str, _) {
+        var c = 0, length = 0;
+        for (var i = 0, l = str.length; i < l; i++) {
+            c = str.charCodeAt(i);
+            if (c < 0x80) {
+                length += 1;
+            }
+            else if (c < 0x800) {
+                length += 2;
+            }
+            else if (c < 0xd800 || c >= 0xe000) {
+                length += 3;
+            }
+            else {
+                i++;
+                length += 4;
+            }
         }
-    }
-    return length;
-}
+        return length;
+    };
 function utf8Write(view, str, it) {
     var c = 0;
     for (var i = 0, l = str.length; i < l; i++) {
@@ -677,8 +715,7 @@ function string$1(bytes, value, it) {
     if (!value) {
         value = "";
     }
-    // let length = utf8Length(value);
-    let length = Buffer.byteLength(value, "utf8");
+    let length = utf8Length(value, "utf8");
     let size = 0;
     // fixstr
     if (length < 0x20) {
@@ -789,23 +826,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 {
@@ -947,6 +984,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);
 };
@@ -956,15 +1005,19 @@ const encodeKeyValueOperation = function (encoder, bytes, changeTree, field, ope
  */
 const encodeArray = function (encoder, bytes, changeTree, field, operation, it, isEncodeAll, hasView) {
     const ref = changeTree.ref;
-    if (hasView &&
-        operation === exports.OPERATION.DELETE &&
-        typeof (changeTree.getType(field)) !== "string") {
-        // encode delete by refId (array of schemas)
-        bytes[it.offset++] = exports.OPERATION.DELETE_BY_REFID;
-        const value = ref['tmpItems'][field];
-        const refId = value[$changes].refId;
-        number$1(bytes, refId, it);
-        return;
+    const useOperationByRefId = hasView && changeTree.isFiltered && (typeof (changeTree.getType(field)) !== "string");
+    let refOrIndex;
+    if (useOperationByRefId) {
+        refOrIndex = ref['tmpItems'][field][$changes].refId;
+        if (operation === exports.OPERATION.DELETE) {
+            operation = exports.OPERATION.DELETE_BY_REFID;
+        }
+        else if (operation === exports.OPERATION.ADD) {
+            operation = exports.OPERATION.ADD_BY_REFID;
+        }
+    }
+    else {
+        refOrIndex = field;
     }
     // encode operation
     bytes[it.offset++] = operation & 255;
@@ -973,7 +1026,7 @@ const encodeArray = function (encoder, bytes, changeTree, field, operation, it,
         return;
     }
     // encode index
-    number$1(bytes, field, it);
+    number$1(bytes, refOrIndex, it);
     // Do not encode value for DELETE operations
     if (operation === exports.OPERATION.DELETE) {
         return;
@@ -1013,9 +1066,9 @@ const encodeArray = function (encoder, bytes, changeTree, field, operation, it,
  * 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);
@@ -1050,6 +1103,7 @@ function utf8Read(bytes, offset, 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) {
@@ -1117,9 +1171,7 @@ function string(bytes, it) {
     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];
@@ -1223,30 +1275,31 @@ function switchStructureCheck(bytes, it) {
 
 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) {
@@ -1432,7 +1485,8 @@ const decodeKeyValueOperation = function (decoder, bytes, it, ref, allChanges) {
 };
 const decodeArray = function (decoder, bytes, it, ref, allChanges) {
     // "uncompressed" index + operation (array/map items)
-    const operation = bytes[it.offset++];
+    let operation = bytes[it.offset++];
+    let index;
     if (operation === exports.OPERATION.CLEAR) {
         //
         // When decoding:
@@ -1446,8 +1500,8 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
     else if (operation === exports.OPERATION.DELETE_BY_REFID) {
         // TODO: refactor here, try to follow same flow as below
         const refId = number(bytes, it);
-        const previousValue = decoder.$root.refs.get(refId);
-        const index = ref.findIndex((value) => value === previousValue);
+        const previousValue = decoder.root.refs.get(refId);
+        index = ref.findIndex((value) => value === previousValue);
         ref[$deleteByIndex](index);
         allChanges.push({
             ref,
@@ -1460,7 +1514,18 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
         });
         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);
@@ -1869,14 +1934,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);
     }
@@ -2555,6 +2612,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]) {
             //
@@ -2579,8 +2637,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()`)
@@ -3353,6 +3411,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;
@@ -3384,11 +3444,14 @@ class Encoder {
     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();
@@ -3397,6 +3460,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);
@@ -3408,8 +3477,8 @@ 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);
+                buffer[it.offset++] = SWITCH_TO_STRUCTURE & 255;
+                number$1(buffer, changeTree.refId, it);
             }
             const changesIterator = changes.entries();
             for (const [fieldIndex, operation] of changesIterator) {
@@ -3426,22 +3495,35 @@ class Encoder {
                     // 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 {
             //
@@ -3453,38 +3535,37 @@ 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());
+    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
@@ -3516,8 +3597,8 @@ class Encoder {
         // 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) {
@@ -3696,12 +3777,12 @@ class Decoder {
     }
     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;
@@ -3782,7 +3863,7 @@ class Decoder {
                 previousValue: value
             });
             if (needRemoveRef) {
-                this.$root.removeRef(this.$root.refIds.get(value));
+                this.root.removeRef(this.root.refIds.get(value));
             }
         });
     }
@@ -3822,7 +3903,7 @@ class Reflection extends Schema {
         super(...arguments);
         this.types = new ArraySchema();
     }
-    static encode(instance, context) {
+    static encode(instance, context, it = { offset: 0 }) {
         if (!context) {
             context = new TypeContext(instance.constructor);
         }
@@ -3879,7 +3960,6 @@ class Reflection extends Schema {
             }
             buildType(type, klass[Symbol.metadata]);
         }
-        const it = { offset: 0 };
         const buf = encoder.encodeAll(it);
         return Buffer.from(buf, 0, it.offset);
     }
@@ -3887,59 +3967,298 @@ 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;
+    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() {
         /**
@@ -3962,12 +4281,18 @@ class StateView {
             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);
@@ -3994,7 +4319,6 @@ class StateView {
                 tags = this.tags.get(changeTree);
             }
             tags.add(tag);
-            // console.log("BY TAG:", tag);
             // Ref: add tagged properties
             metadata?.[-3]?.[tag]?.forEach((index) => {
                 if (changeTree.getChange(index) !== exports.OPERATION.DELETE) {
@@ -4164,6 +4488,8 @@ exports.dumpChanges = dumpChanges;
 exports.encode = encode;
 exports.encodeKeyValueOperation = encodeArray;
 exports.encodeSchemaOperation = encodeSchemaOperation;
+exports.getDecoderStateCallbacks = getDecoderStateCallbacks;
+exports.getRawChangesCallback = getRawChangesCallback;
 exports.registerType = registerType;
 exports.type = type;
 exports.view = view;