@colyseus/schema 3.0.42 → 3.0.44

package/build/umd/index.js

@@ -32,37 +32,37 @@
 
     Symbol.metadata ??= Symbol.for("Symbol.metadata");
 
-    const $track = Symbol("$track");
-    const $encoder = Symbol("$encoder");
-    const $decoder = Symbol("$decoder");
-    const $filter = Symbol("$filter");
-    const $getByIndex = Symbol("$getByIndex");
-    const $deleteByIndex = Symbol("$deleteByIndex");
+    const $track = "~track";
+    const $encoder = "~encoder";
+    const $decoder = "~decoder";
+    const $filter = "~filter";
+    const $getByIndex = "~getByIndex";
+    const $deleteByIndex = "~deleteByIndex";
     /**
      * Used to hold ChangeTree instances whitin the structures
      */
-    const $changes = Symbol('$changes');
+    const $changes = '~changes';
     /**
      * Used to keep track of the type of the child elements of a collection
      * (MapSchema, ArraySchema, etc.)
      */
-    const $childType = Symbol('$childType');
+    const $childType = '~childType';
     /**
      * Optional "discard" method for custom types (ArraySchema)
      * (Discards changes for next serialization)
      */
-    const $onEncodeEnd = Symbol('$onEncodeEnd');
+    const $onEncodeEnd = '~onEncodeEnd';
     /**
      * When decoding, this method is called after the instance is fully decoded
      */
-    const $onDecodeEnd = Symbol("$onDecodeEnd");
+    const $onDecodeEnd = "~onDecodeEnd";
     /**
      * Metadata
      */
-    const $descriptors = Symbol("$descriptors");
-    const $numFields = "$__numFields";
-    const $refTypeFieldIndexes = "$__refTypeFieldIndexes";
-    const $viewFieldIndexes = "$__viewFieldIndexes";
+    const $descriptors = "~descriptors";
+    const $numFields = "~__numFields";
+    const $refTypeFieldIndexes = "~__refTypeFieldIndexes";
+    const $viewFieldIndexes = "~__viewFieldIndexes";
     const $fieldIndexesByViewTag = "$__fieldIndexesByViewTag";
 
     /**
@@ -970,6 +970,24 @@
     function createChangeSet() {
         return { indexes: {}, operations: [] };
     }
+    // Linked list helper functions
+    function createChangeTreeList() {
+        return { next: undefined, tail: undefined, length: 0 };
+    }
+    function addToChangeTreeList(list, changeTree) {
+        const node = { changeTree, next: undefined, prev: undefined };
+        if (!list.next) {
+            list.next = node;
+            list.tail = node;
+        }
+        else {
+            node.prev = list.tail;
+            list.tail.next = node;
+            list.tail = node;
+        }
+        list.length++;
+        return node;
+    }
     function setOperationAtIndex(changeSet, index) {
         const operationsIndex = changeSet.indexes[index];
         if (operationsIndex === undefined) {
@@ -994,13 +1012,15 @@
         changeSet.operations[operationsIndex] = undefined;
         delete changeSet.indexes[index];
     }
-    function enqueueChangeTree(root, changeTree, changeSet, queueRootIndex = changeTree[changeSet].queueRootIndex) {
+    function enqueueChangeTree(root, changeTree, changeSet, queueRootNode = changeTree[changeSet].queueRootNode) {
+        // skip
         if (!root) {
-            // skip
             return;
         }
-        else if (root[changeSet][queueRootIndex] !== changeTree) {
-            changeTree[changeSet].queueRootIndex = root[changeSet].push(changeTree) - 1;
+        if (queueRootNode) ;
+        else {
+            // Add to linked list if not already present
+            changeTree[changeSet].queueRootNode = addToChangeTreeList(root[changeSet], changeTree);
         }
     }
     class ChangeTree {
@@ -1024,83 +1044,59 @@
              */
             this.isNew = true;
             this.ref = ref;
+            this.metadata = ref.constructor[Symbol.metadata];
             //
             // Does this structure have "filters" declared?
             //
-            const metadata = ref.constructor[Symbol.metadata];
-            if (metadata?.[$viewFieldIndexes]) {
+            if (this.metadata?.[$viewFieldIndexes]) {
                 this.allFilteredChanges = { indexes: {}, operations: [] };
                 this.filteredChanges = { indexes: {}, operations: [] };
             }
         }
         setRoot(root) {
             this.root = root;
-            this.checkIsFiltered(this.parent, this.parentIndex);
-            //
-            // TODO: refactor and possibly unify .setRoot() and .setParent()
-            //
+            const isNewChangeTree = this.root.add(this);
+            this.checkIsFiltered(this.parent, this.parentIndex, isNewChangeTree);
             // Recursively set root on child structures
-            const metadata = this.ref.constructor[Symbol.metadata];
-            if (metadata) {
-                metadata[$refTypeFieldIndexes]?.forEach((index) => {
-                    const field = metadata[index];
-                    const changeTree = this.ref[field.name]?.[$changes];
-                    if (changeTree) {
-                        if (changeTree.root !== root) {
-                            changeTree.setRoot(root);
-                        }
-                        else {
-                            root.add(changeTree); // increment refCount
-                        }
-                    }
-                });
-            }
-            else if (this.ref[$childType] && typeof (this.ref[$childType]) !== "string") {
-                // MapSchema / ArraySchema, etc.
-                this.ref.forEach((value, key) => {
-                    const changeTree = value[$changes];
-                    if (changeTree.root !== root) {
-                        changeTree.setRoot(root);
+            if (isNewChangeTree) {
+                this.forEachChild((child, _) => {
+                    if (child.root !== root) {
+                        child.setRoot(root);
                     }
                     else {
-                        root.add(changeTree); // increment refCount
+                        root.add(child); // increment refCount
                     }
                 });
             }
         }
         setParent(parent, root, parentIndex) {
-            this.parent = parent;
-            this.parentIndex = parentIndex;
+            this.addParent(parent, parentIndex);
             // avoid setting parents with empty `root`
             if (!root) {
                 return;
             }
+            const isNewChangeTree = root.add(this);
             // skip if parent is already set
             if (root !== this.root) {
                 this.root = root;
-                this.checkIsFiltered(parent, parentIndex);
-            }
-            else {
-                root.add(this);
+                this.checkIsFiltered(parent, parentIndex, isNewChangeTree);
             }
             // assign same parent on child structures
-            const metadata = this.ref.constructor[Symbol.metadata];
-            if (metadata) {
-                metadata[$refTypeFieldIndexes]?.forEach((index) => {
-                    const field = metadata[index];
-                    const changeTree = this.ref[field.name]?.[$changes];
-                    if (changeTree && changeTree.root !== root) {
-                        changeTree.setParent(this.ref, root, index);
-                    }
-                });
-            }
-            else if (this.ref[$childType] && typeof (this.ref[$childType]) !== "string") {
-                // MapSchema / ArraySchema, etc.
-                this.ref.forEach((value, key) => {
-                    const changeTree = value[$changes];
-                    if (changeTree.root !== root) {
-                        changeTree.setParent(this.ref, root, this.indexes[key] ?? key);
+            if (isNewChangeTree) {
+                //
+                // assign same parent on child structures
+                //
+                this.forEachChild((child, index) => {
+                    if (child.root === root) {
+                        //
+                        // re-assigning a child of the same root, move it to the end
+                        // of the changes queue so encoding order is preserved
+                        //
+                        root.add(child);
+                        root.moveToEndOfChanges(child);
+                        return;
                     }
+                    child.setParent(this.ref, root, index);
                 });
             }
         }
@@ -1108,21 +1104,23 @@
             //
             // assign same parent on child structures
             //
-            const metadata = this.ref.constructor[Symbol.metadata];
-            if (metadata) {
-                metadata[$refTypeFieldIndexes]?.forEach((index) => {
-                    const field = metadata[index];
-                    const value = this.ref[field.name];
-                    if (value) {
-                        callback(value[$changes], index);
+            if (this.ref[$childType]) {
+                if (typeof (this.ref[$childType]) !== "string") {
+                    // MapSchema / ArraySchema, etc.
+                    for (const [key, value] of this.ref.entries()) {
+                        callback(value[$changes], key);
                     }
-                });
+                }
             }
-            else if (this.ref[$childType] && typeof (this.ref[$childType]) !== "string") {
-                // MapSchema / ArraySchema, etc.
-                this.ref.forEach((value, key) => {
-                    callback(value[$changes], this.indexes[key] ?? key);
-                });
+            else {
+                for (const index of this.metadata?.[$refTypeFieldIndexes] ?? []) {
+                    const field = this.metadata[index];
+                    const value = this.ref[field.name];
+                    if (!value) {
+                        continue;
+                    }
+                    callback(value[$changes], index);
+                }
             }
         }
         operation(op) {
@@ -1138,8 +1136,7 @@
             }
         }
         change(index, operation = exports.OPERATION.ADD) {
-            const metadata = this.ref.constructor[Symbol.metadata];
-            const isFiltered = this.isFiltered || (metadata?.[index]?.tag !== undefined);
+            const isFiltered = this.isFiltered || (this.metadata?.[index]?.tag !== undefined);
             const changeSet = (isFiltered)
                 ? this.filteredChanges
                 : this.changes;
@@ -1229,19 +1226,16 @@
             }
         }
         getType(index) {
-            if (Metadata.isValidInstance(this.ref)) {
-                const metadata = this.ref.constructor[Symbol.metadata];
-                return metadata[index].type;
-            }
-            else {
-                //
-                // Get the child type from parent structure.
-                // - ["string"] => "string"
-                // - { map: "string" } => "string"
-                // - { set: "string" } => "string"
-                //
-                return this.ref[$childType];
-            }
+            return (
+            //
+            // Get the child type from parent structure.
+            // - ["string"] => "string"
+            // - { map: "string" } => "string"
+            // - { set: "string" } => "string"
+            //
+            this.ref[$childType] || // ArraySchema | MapSchema | SetSchema | CollectionSchema
+                this.metadata[index].type // Schema
+            );
         }
         getChange(index) {
             return this.indexedOperations[index];
@@ -1301,9 +1295,7 @@
         endEncode(changeSetName) {
             this.indexedOperations = {};
             // clear changeset
-            this[changeSetName].indexes = {};
-            this[changeSetName].operations.length = 0;
-            this[changeSetName].queueRootIndex = undefined;
+            this[changeSetName] = createChangeSet();
             // ArraySchema and MapSchema have a custom "encode end" method
             this.ref[$onEncodeEnd]?.();
             // Not a new instance anymore
@@ -1317,20 +1309,14 @@
             //
             this.ref[$onEncodeEnd]?.();
             this.indexedOperations = {};
-            this.changes.indexes = {};
-            this.changes.operations.length = 0;
-            this.changes.queueRootIndex = undefined;
+            this.changes = createChangeSet();
             if (this.filteredChanges !== undefined) {
-                this.filteredChanges.indexes = {};
-                this.filteredChanges.operations.length = 0;
-                this.filteredChanges.queueRootIndex = undefined;
+                this.filteredChanges = createChangeSet();
             }
             if (discardAll) {
-                this.allChanges.indexes = {};
-                this.allChanges.operations.length = 0;
+                this.allChanges = createChangeSet();
                 if (this.allFilteredChanges !== undefined) {
-                    this.allFilteredChanges.indexes = {};
-                    this.allFilteredChanges.operations.length = 0;
+                    this.allFilteredChanges = createChangeSet();
                 }
             }
         }
@@ -1348,18 +1334,10 @@
             }
             this.discard();
         }
-        ensureRefId() {
-            // skip if refId is already set.
-            if (this.refId !== undefined) {
-                return;
-            }
-            this.refId = this.root.getNextUniqueId();
-        }
         get changed() {
             return (Object.entries(this.indexedOperations).length > 0);
         }
-        checkIsFiltered(parent, parentIndex) {
-            const isNewChangeTree = this.root.add(this);
+        checkIsFiltered(parent, parentIndex, isNewChangeTree) {
             if (this.root.types.hasFilters) {
                 //
                 // At Schema initialization, the "root" structure might not be available
@@ -1371,14 +1349,14 @@
                 if (this.filteredChanges !== undefined) {
                     enqueueChangeTree(this.root, this, 'filteredChanges');
                     if (isNewChangeTree) {
-                        this.root.allFilteredChanges.push(this);
+                        enqueueChangeTree(this.root, this, 'allFilteredChanges');
                     }
                 }
             }
             if (!this.isFiltered) {
                 enqueueChangeTree(this.root, this, 'changes');
                 if (isNewChangeTree) {
-                    this.root.allChanges.push(this);
+                    enqueueChangeTree(this.root, this, 'allChanges');
                 }
             }
         }
@@ -1435,6 +1413,90 @@
                 }
             }
         }
+        /**
+         * Get the immediate parent
+         */
+        get parent() {
+            return this.parentChain?.ref;
+        }
+        /**
+         * Get the immediate parent index
+         */
+        get parentIndex() {
+            return this.parentChain?.index;
+        }
+        /**
+         * Add a parent to the chain
+         */
+        addParent(parent, index) {
+            // Check if this parent already exists in the chain
+            if (this.hasParent((p, i) => p[$changes] === parent[$changes] && i === index)) {
+                return;
+            }
+            this.parentChain = {
+                ref: parent,
+                index,
+                next: this.parentChain
+            };
+        }
+        /**
+         * Remove a parent from the chain
+         * @param parent - The parent to remove
+         * @returns true if parent was removed
+         */
+        removeParent(parent = this.parent) {
+            let current = this.parentChain;
+            let previous = null;
+            while (current) {
+                //
+                // FIXME: it is required to check against `$changes` here because
+                // ArraySchema is instance of Proxy
+                //
+                if (current.ref[$changes] === parent[$changes]) {
+                    if (previous) {
+                        previous.next = current.next;
+                    }
+                    else {
+                        this.parentChain = current.next;
+                    }
+                    return true;
+                }
+                previous = current;
+                current = current.next;
+            }
+            return this.parentChain === undefined;
+        }
+        /**
+         * Find a specific parent in the chain
+         */
+        findParent(predicate) {
+            let current = this.parentChain;
+            while (current) {
+                if (predicate(current.ref, current.index)) {
+                    return current;
+                }
+                current = current.next;
+            }
+            return undefined;
+        }
+        /**
+         * Check if this ChangeTree has a specific parent
+         */
+        hasParent(predicate) {
+            return this.findParent(predicate) !== undefined;
+        }
+        /**
+         * Get all parents as an array (for debugging/testing)
+         */
+        getAllParents() {
+            const parents = [];
+            let current = this.parentChain;
+            while (current) {
+                parents.push({ ref: current.ref, index: current.index });
+                current = current.next;
+            }
+            return parents;
+        }
     }
 
     function encodeValue(encoder, bytes, type, value, operation, it) {
@@ -1952,7 +2014,7 @@
                                 }
                                 if (previousValue !== undefined) {
                                     // remove root reference from previous value
-                                    previousValue[$changes].root?.remove(previousValue[$changes]);
+                                    previousValue[$changes].root?.remove(previousValue[$changes], obj);
                                 }
                             }
                             else {
@@ -1983,8 +2045,11 @@
                     return Reflect.has(obj, key);
                 }
             });
-            this[$changes] = new ChangeTree(proxy);
-            this[$changes].indexes = {};
+            Object.defineProperty(this, $changes, {
+                value: new ChangeTree(proxy),
+                enumerable: false,
+                writable: true,
+            });
             if (items.length > 0) {
                 this.push(...items);
             }
@@ -2106,7 +2171,7 @@
             const changeTree = this[$changes];
             // remove children references
             changeTree.forEachChild((childChangeTree, _) => {
-                changeTree.root?.remove(childChangeTree);
+                changeTree.root?.remove(childChangeTree, this);
             });
             changeTree.discard(true);
             changeTree.operation(exports.OPERATION.CLEAR);
@@ -2145,7 +2210,6 @@
             if (this.items.length === 0) {
                 return undefined;
             }
-            // const index = Number(Object.keys(changeTree.indexes)[0]);
             const changeTree = this[$changes];
             const index = this.tmpItems.findIndex(item => item === this.items[0]);
             const allChangesIndex = this.items.findIndex(item => item === this.items[0]);
@@ -2604,8 +2668,13 @@
             this.$items = new Map();
             this.$indexes = new Map();
             this.deletedItems = {};
-            this[$changes] = new ChangeTree(this);
-            this[$changes].indexes = {};
+            const changeTree = new ChangeTree(this);
+            changeTree.indexes = {};
+            Object.defineProperty(this, $changes, {
+                value: changeTree,
+                enumerable: false,
+                writable: true,
+            });
             if (initialValues) {
                 if (initialValues instanceof Map ||
                     initialValues instanceof MapSchema) {
@@ -2656,7 +2725,7 @@
                     operation = exports.OPERATION.DELETE_AND_ADD;
                     // remove reference from previous value
                     if (previousValue !== undefined) {
-                        previousValue[$changes].root?.remove(previousValue[$changes]);
+                        previousValue[$changes].root?.remove(previousValue[$changes], this);
                     }
                 }
             }
@@ -2693,7 +2762,7 @@
             changeTree.indexes = {};
             // remove children references
             changeTree.forEachChild((childChangeTree, _) => {
-                changeTree.root?.remove(childChangeTree);
+                changeTree.root?.remove(childChangeTree, this);
             });
             // clear previous indexes
             this.$indexes.clear();
@@ -3149,10 +3218,13 @@
             refs: []
         };
         // for (const refId in $root.changes) {
-        $root.changes.forEach(changeTree => {
+        let current = $root.changes.next;
+        while (current) {
+            const changeTree = current.changeTree;
             // skip if ChangeTree is undefined
             if (changeTree === undefined) {
-                return;
+                current = current.next;
+                continue;
             }
             const changes = changeTree.indexedOperations;
             dump.refs.push(`refId#${changeTree.refId}`);
@@ -3164,7 +3236,8 @@
                 }
                 dump.ops[exports.OPERATION[op]]++;
             }
-        });
+            current = current.next;
+        }
         return dump;
     }
 
@@ -3314,7 +3387,7 @@
          * @param showContents display JSON contents of the instance
          * @returns
          */
-        static debugRefIds(ref, showContents = false, level = 0, decoder) {
+        static debugRefIds(ref, showContents = false, level = 0, decoder, keyPrefix = "") {
             const contents = (showContents) ? ` - ${JSON.stringify(ref.toJSON())}` : "";
             const changeTree = ref[$changes];
             const refId = (decoder) ? decoder.root.refIds.get(ref) : changeTree.refId;
@@ -3323,11 +3396,25 @@
             const refCount = (root?.refCount?.[refId] > 1)
                 ? ` [×${root.refCount[refId]}]`
                 : '';
-            let output = `${getIndent(level)}${ref.constructor.name} (refId: ${refId})${refCount}${contents}\n`;
-            changeTree.forEachChild((childChangeTree) => output += this.debugRefIds(childChangeTree.ref, showContents, level + 1, decoder));
+            let output = `${getIndent(level)}${keyPrefix}${ref.constructor.name} (refId: ${refId})${refCount}${contents}\n`;
+            changeTree.forEachChild((childChangeTree, key) => {
+                const keyPrefix = (ref['forEach'] !== undefined && key !== undefined) ? `["${key}"]: ` : "";
+                output += this.debugRefIds(childChangeTree.ref, showContents, level + 1, decoder, keyPrefix);
+            });
             return output;
         }
-        static debugRefIdsDecoder(decoder) {
+        static debugRefIdEncodingOrder(ref, changeSet = 'allChanges') {
+            let encodeOrder = [];
+            let current = ref[$changes].root[changeSet].next;
+            while (current) {
+                if (current.changeTree) {
+                    encodeOrder.push(current.changeTree.refId);
+                }
+                current = current.next;
+            }
+            return encodeOrder;
+        }
+        static debugRefIdsFromDecoder(decoder) {
             return this.debugRefIds(decoder.state, false, 0, decoder);
         }
         /**
@@ -3376,8 +3463,12 @@
             const changeTrees = new Map();
             const instanceRefIds = [];
             let totalOperations = 0;
+            // TODO: FIXME: this method is not working as expected
             for (const [refId, changes] of Object.entries(root[changeSetName])) {
                 const changeTree = root.changeTrees[refId];
+                if (!changeTree) {
+                    continue;
+                }
                 let includeChangeTree = false;
                 let parentChangeTrees = [];
                 let parentChangeTree = changeTree.parent?.[$changes];
@@ -3513,7 +3604,7 @@
             changeTree.indexes = {};
             // remove children references
             changeTree.forEachChild((childChangeTree, _) => {
-                changeTree.root?.remove(childChangeTree);
+                changeTree.root?.remove(childChangeTree, this);
             });
             // clear previous indexes
             this.$indexes.clear();
@@ -3800,18 +3891,20 @@
             this.refCount = {};
             this.changeTrees = {};
             // all changes
-            this.allChanges = [];
-            this.allFilteredChanges = []; // TODO: do not initialize it if filters are not used
+            this.allChanges = createChangeTreeList();
+            this.allFilteredChanges = createChangeTreeList(); // TODO: do not initialize it if filters are not used
             // pending changes to be encoded
-            this.changes = [];
-            this.filteredChanges = []; // TODO: do not initialize it if filters are not used
+            this.changes = createChangeTreeList();
+            this.filteredChanges = createChangeTreeList(); // TODO: do not initialize it if filters are not used
         }
         getNextUniqueId() {
             return this.nextUniqueId++;
         }
         add(changeTree) {
-            // FIXME: move implementation of `ensureRefId` to `Root` class
-            changeTree.ensureRefId();
+            // Assign unique `refId` to changeTree if it doesn't have one yet.
+            if (changeTree.refId === undefined) {
+                changeTree.refId = this.getNextUniqueId();
+            }
             const isNewChangeTree = (this.changeTrees[changeTree.refId] === undefined);
             if (isNewChangeTree) {
                 this.changeTrees[changeTree.refId] = changeTree;
@@ -3830,10 +3923,12 @@
                 }
             }
             this.refCount[changeTree.refId] = (previousRefCount || 0) + 1;
+            // console.log("ADD", { refId: changeTree.refId, refCount: this.refCount[changeTree.refId] });
             return isNewChangeTree;
         }
-        remove(changeTree) {
+        remove(changeTree, parent) {
             const refCount = (this.refCount[changeTree.refId]) - 1;
+            // console.log("REMOVE", { refId: changeTree.refId, refCount });
             if (refCount <= 0) {
                 //
                 // Only remove "root" reference if it's the last reference
@@ -3847,7 +3942,19 @@
                     this.removeChangeFromChangeSet("filteredChanges", changeTree);
                 }
                 this.refCount[changeTree.refId] = 0;
-                changeTree.forEachChild((child, _) => this.remove(child));
+                changeTree.forEachChild((child, _) => {
+                    if (child.removeParent(changeTree.ref)) {
+                        if ((child.parentChain === undefined || // no parent, remove it
+                            (child.parentChain && this.refCount[child.refId] > 1) // parent is still in use, but has more than one reference, remove it
+                        )) {
+                            this.remove(child, changeTree.ref);
+                        }
+                        else if (child.parentChain) {
+                            // re-assigning a child of the same root, move it to the end
+                            this.moveToEndOfChanges(child);
+                        }
+                    }
+                });
             }
             else {
                 this.refCount[changeTree.refId] = refCount;
@@ -3860,32 +3967,73 @@
                 // containing instance is not available, the Decoder will throw
                 // "refId not found" error.
                 //
-                if (changeTree.filteredChanges !== undefined) {
-                    this.removeChangeFromChangeSet("filteredChanges", changeTree);
-                    enqueueChangeTree(this, changeTree, "filteredChanges");
-                }
-                else {
-                    this.removeChangeFromChangeSet("changes", changeTree);
-                    enqueueChangeTree(this, changeTree, "changes");
-                }
+                this.moveToEndOfChanges(changeTree);
+                changeTree.forEachChild((child, _) => this.moveToEndOfChanges(child));
             }
             return refCount;
         }
+        moveToEndOfChanges(changeTree) {
+            if (changeTree.filteredChanges) {
+                this.moveToEndOfChangeTreeList("filteredChanges", changeTree);
+                this.moveToEndOfChangeTreeList("allFilteredChanges", changeTree);
+            }
+            else {
+                this.moveToEndOfChangeTreeList("changes", changeTree);
+                this.moveToEndOfChangeTreeList("allChanges", changeTree);
+            }
+        }
+        moveToEndOfChangeTreeList(changeSetName, changeTree) {
+            const changeSet = this[changeSetName];
+            const node = changeTree[changeSetName].queueRootNode;
+            if (!node || node === changeSet.tail)
+                return;
+            // Remove from current position
+            if (node.prev) {
+                node.prev.next = node.next;
+            }
+            else {
+                changeSet.next = node.next;
+            }
+            if (node.next) {
+                node.next.prev = node.prev;
+            }
+            else {
+                changeSet.tail = node.prev;
+            }
+            // Add to end
+            node.prev = changeSet.tail;
+            node.next = undefined;
+            if (changeSet.tail) {
+                changeSet.tail.next = node;
+            }
+            else {
+                changeSet.next = node;
+            }
+            changeSet.tail = node;
+        }
         removeChangeFromChangeSet(changeSetName, changeTree) {
             const changeSet = this[changeSetName];
-            const changeSetIndex = changeSet.indexOf(changeTree);
-            if (changeSetIndex !== -1) {
-                changeTree[changeSetName].queueRootIndex = -1;
-                changeSet[changeSetIndex] = undefined;
+            const node = changeTree[changeSetName].queueRootNode;
+            if (node && node.changeTree === changeTree) {
+                // Remove the node from the linked list
+                if (node.prev) {
+                    node.prev.next = node.next;
+                }
+                else {
+                    changeSet.next = node.next;
+                }
+                if (node.next) {
+                    node.next.prev = node.prev;
+                }
+                else {
+                    changeSet.tail = node.prev;
+                }
+                changeSet.length--;
+                // Clear ChangeTree reference
+                changeTree[changeSetName].queueRootNode = undefined;
                 return true;
             }
-            // if (spliceOne(changeSet, changeSet.indexOf(changeTree))) {
-            //     changeTree[changeSetName].queueRootIndex = -1;
-            //     return true;
-            // }
-        }
-        clear() {
-            this.changes.length = 0;
+            return false;
         }
     }
 
@@ -3915,12 +4063,9 @@
         ) {
             const hasView = (view !== undefined);
             const rootChangeTree = this.state[$changes];
-            const changeTrees = this.root[changeSetName];
-            for (let i = 0, numChangeTrees = changeTrees.length; i < numChangeTrees; i++) {
-                const changeTree = changeTrees[i];
-                if (!changeTree) {
-                    continue;
-                }
+            let current = this.root[changeSetName];
+            while (current = current.next) {
+                const changeTree = current.changeTree;
                 if (hasView) {
                     if (!view.isChangeTreeVisible(changeTree)) {
                         // console.log("MARK AS INVISIBLE:", { ref: changeTree.ref.constructor.name, refId: changeTree.refId, raw: changeTree.ref.toJSON() });
@@ -4009,7 +4154,9 @@
             const rootChangeSet = (typeof (field) === "string")
                 ? this.root[field]
                 : field;
-            rootChangeSet.forEach((changeTree) => {
+            let current = rootChangeSet.next;
+            while (current) {
+                const changeTree = current.changeTree;
                 const changeSet = changeTree[field];
                 const metadata = changeTree.ref.constructor[Symbol.metadata];
                 console.log("->", { ref: changeTree.ref.constructor.name, refId: changeTree.refId, changes: Object.keys(changeSet).length });
@@ -4021,7 +4168,8 @@
                         op: exports.OPERATION[op],
                     });
                 }
-            });
+                current = current.next;
+            }
         }
         encodeView(view, sharedOffset, it, bytes = this.sharedBuffer) {
             const viewOffset = it.offset;
@@ -4071,21 +4219,19 @@
         }
         discardChanges() {
             // discard shared changes
-            let length = this.root.changes.length;
-            if (length > 0) {
-                while (length--) {
-                    this.root.changes[length]?.endEncode('changes');
-                }
-                this.root.changes.length = 0;
+            let current = this.root.changes.next;
+            while (current) {
+                current.changeTree.endEncode('changes');
+                current = current.next;
             }
+            this.root.changes = createChangeTreeList();
             // discard filtered changes
-            length = this.root.filteredChanges.length;
-            if (length > 0) {
-                while (length--) {
-                    this.root.filteredChanges[length]?.endEncode('filteredChanges');
-                }
-                this.root.filteredChanges.length = 0;
+            current = this.root.filteredChanges.next;
+            while (current) {
+                current.changeTree.endEncode('filteredChanges');
+                current = current.next;
             }
+            this.root.filteredChanges = createChangeTreeList();
         }
         tryEncodeTypeId(bytes, baseType, targetType, it) {
             const baseTypeId = this.context.getTypeId(baseType);
@@ -4275,21 +4421,20 @@
                 //
                 if (bytes[it.offset] == SWITCH_TO_STRUCTURE) {
                     it.offset++;
+                    ref[$onDecodeEnd]?.();
                     const nextRefId = decode.number(bytes, it);
                     const nextRef = $root.refs.get(nextRefId);
                     //
                     // Trying to access a reference that haven't been decoded yet.
                     //
                     if (!nextRef) {
-                        console.error(`"refId" not found: ${nextRefId}`, { previousRef: ref, previousRefId: this.currentRefId });
-                        console.warn("Please report this to the developers. All refIds =>");
-                        console.warn(Schema.debugRefIdsDecoder(this));
-                        this.skipCurrentStructure(bytes, it, totalBytes);
+                        throw new Error(`"refId" not found: ${nextRefId}`);
+                    }
+                    else {
+                        ref = nextRef;
+                        decoder = ref.constructor[$decoder];
+                        this.currentRefId = nextRefId;
                     }
-                    ref[$onDecodeEnd]?.();
-                    this.currentRefId = nextRefId;
-                    ref = nextRef;
-                    decoder = ref.constructor[$decoder];
                     continue;
                 }
                 const result = decoder(this, bytes, it, ref, allChanges);
@@ -4333,10 +4478,6 @@
             return type || defaultType;
         }
         createInstanceOfType(type) {
-            // let instance: Schema = new (type as any)();
-            // // assign root on $changes
-            // instance[$changes].root = this.root[$changes].root;
-            // return instance;
             return new type();
         }
         removeChildRefs(ref, allChanges) {
@@ -4863,11 +5004,12 @@
         // TODO: allow to set multiple tags at once
         add(obj, tag = DEFAULT_VIEW_TAG, checkIncludeParent = true) {
             const changeTree = obj?.[$changes];
+            const parentChangeTree = changeTree.parent;
             if (!changeTree) {
                 console.warn("StateView#add(), invalid object:", obj);
-                return this;
+                return false;
             }
-            else if (!changeTree.parent &&
+            else if (!parentChangeTree &&
                 changeTree.refId !== 0 // allow root object
             ) {
                 /**
@@ -4889,18 +5031,31 @@
             // add parent ChangeTree's
             // - if it was invisible to this view
             // - if it were previously filtered out
-            if (checkIncludeParent && changeTree.parent) {
+            if (checkIncludeParent && parentChangeTree) {
                 this.addParentOf(changeTree, tag);
             }
-            //
-            // TODO: when adding an item of a MapSchema, the changes may not
-            // be set (only the parent's changes are set)
-            //
             let changes = this.changes.get(changeTree.refId);
             if (changes === undefined) {
                 changes = {};
+                // FIXME / OPTIMIZE: do not add if no changes are needed
                 this.changes.set(changeTree.refId, changes);
             }
+            let isChildAdded = false;
+            //
+            // Add children of this ChangeTree first.
+            // If successful, we must link the current ChangeTree to the child.
+            //
+            changeTree.forEachChild((change, index) => {
+                // Do not ADD children that don't have the same tag
+                if (metadata &&
+                    metadata[index].tag !== undefined &&
+                    metadata[index].tag !== tag) {
+                    return;
+                }
+                if (this.add(change.ref, tag, false)) {
+                    isChildAdded = true;
+                }
+            });
             // set tag
             if (tag !== DEFAULT_VIEW_TAG) {
                 if (!this.tags) {
@@ -4922,11 +5077,12 @@
                     }
                 });
             }
-            else {
-                const isInvisible = this.invisible.has(changeTree);
+            else if (!changeTree.isNew || isChildAdded) {
+                // new structures will be added as part of .encode() call, no need to force it to .encodeView()
                 const changeSet = (changeTree.filteredChanges !== undefined)
                     ? changeTree.allFilteredChanges
                     : changeTree.allChanges;
+                const isInvisible = this.invisible.has(changeTree);
                 for (let i = 0, len = changeSet.operations.length; i < len; i++) {
                     const index = changeSet.operations[i];
                     if (index === undefined) {
@@ -4934,27 +5090,17 @@
                     } // skip "undefined" indexes
                     const op = changeTree.indexedOperations[index] ?? exports.OPERATION.ADD;
                     const tagAtIndex = metadata?.[index].tag;
-                    if (!changeTree.isNew && // new structures will be added as part of .encode() call, no need to force it to .encodeView()
+                    if (op !== exports.OPERATION.DELETE &&
                         (isInvisible || // if "invisible", include all
                             tagAtIndex === undefined || // "all change" with no tag
                             tagAtIndex === tag // tagged property
-                        ) &&
-                        op !== exports.OPERATION.DELETE) {
+                        )) {
                         changes[index] = op;
+                        isChildAdded = true; // FIXME: assign only once
                     }
                 }
             }
-            // Add children of this ChangeTree to this view
-            changeTree.forEachChild((change, index) => {
-                // Do not ADD children that don't have the same tag
-                if (metadata &&
-                    metadata[index].tag !== undefined &&
-                    metadata[index].tag !== tag) {
-                    return;
-                }
-                this.add(change.ref, tag, false);
-            });
-            return this;
+            return isChildAdded;
         }
         addParentOf(childChangeTree, tag) {
             const changeTree = childChangeTree.parent[$changes];