@colyseus/schema 3.0.42 → 3.0.44

package/build/esm/index.mjs

@@ -26,37 +26,37 @@ var OPERATION;
 
 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";
 
 /**
@@ -964,6 +964,24 @@ const Metadata = {
 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) {
@@ -988,13 +1006,15 @@ function deleteOperationAtIndex(changeSet, index) {
     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 {
@@ -1018,83 +1038,59 @@ class ChangeTree {
          */
         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);
             });
         }
     }
@@ -1102,21 +1098,23 @@ class ChangeTree {
         //
         // 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) {
@@ -1132,8 +1130,7 @@ class ChangeTree {
         }
     }
     change(index, operation = 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;
@@ -1223,19 +1220,16 @@ class ChangeTree {
         }
     }
     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];
@@ -1295,9 +1289,7 @@ class ChangeTree {
     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
@@ -1311,20 +1303,14 @@ class ChangeTree {
         //
         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();
             }
         }
     }
@@ -1342,18 +1328,10 @@ class ChangeTree {
         }
         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
@@ -1365,14 +1343,14 @@ class ChangeTree {
             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');
             }
         }
     }
@@ -1429,6 +1407,90 @@ class ChangeTree {
             }
         }
     }
+    /**
+     * 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) {
@@ -1946,7 +2008,7 @@ class ArraySchema {
                             }
                             if (previousValue !== undefined) {
                                 // remove root reference from previous value
-                                previousValue[$changes].root?.remove(previousValue[$changes]);
+                                previousValue[$changes].root?.remove(previousValue[$changes], obj);
                             }
                         }
                         else {
@@ -1977,8 +2039,11 @@ class ArraySchema {
                 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);
         }
@@ -2100,7 +2165,7 @@ class ArraySchema {
         const changeTree = this[$changes];
         // remove children references
         changeTree.forEachChild((childChangeTree, _) => {
-            changeTree.root?.remove(childChangeTree);
+            changeTree.root?.remove(childChangeTree, this);
         });
         changeTree.discard(true);
         changeTree.operation(OPERATION.CLEAR);
@@ -2139,7 +2204,6 @@ class ArraySchema {
         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]);
@@ -2598,8 +2662,13 @@ class MapSchema {
         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) {
@@ -2650,7 +2719,7 @@ class MapSchema {
                 operation = 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);
                 }
             }
         }
@@ -2687,7 +2756,7 @@ class MapSchema {
         changeTree.indexes = {};
         // remove children references
         changeTree.forEachChild((childChangeTree, _) => {
-            changeTree.root?.remove(childChangeTree);
+            changeTree.root?.remove(childChangeTree, this);
         });
         // clear previous indexes
         this.$indexes.clear();
@@ -3143,10 +3212,13 @@ function dumpChanges(schema) {
         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}`);
@@ -3158,7 +3230,8 @@ function dumpChanges(schema) {
             }
             dump.ops[OPERATION[op]]++;
         }
-    });
+        current = current.next;
+    }
     return dump;
 }
 
@@ -3308,7 +3381,7 @@ class Schema {
      * @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;
@@ -3317,11 +3390,25 @@ class Schema {
         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);
     }
     /**
@@ -3370,8 +3457,12 @@ class Schema {
         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];
@@ -3507,7 +3598,7 @@ class CollectionSchema {
         changeTree.indexes = {};
         // remove children references
         changeTree.forEachChild((childChangeTree, _) => {
-            changeTree.root?.remove(childChangeTree);
+            changeTree.root?.remove(childChangeTree, this);
         });
         // clear previous indexes
         this.$indexes.clear();
@@ -3794,18 +3885,20 @@ class Root {
         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;
@@ -3824,10 +3917,12 @@ class Root {
             }
         }
         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
@@ -3841,7 +3936,19 @@ class Root {
                 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;
@@ -3854,32 +3961,73 @@ class Root {
             // 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;
     }
 }
 
@@ -3909,12 +4057,9 @@ class Encoder {
     ) {
         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() });
@@ -4003,7 +4148,9 @@ class Encoder {
         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 });
@@ -4015,7 +4162,8 @@ class Encoder {
                     op: OPERATION[op],
                 });
             }
-        });
+            current = current.next;
+        }
     }
     encodeView(view, sharedOffset, it, bytes = this.sharedBuffer) {
         const viewOffset = it.offset;
@@ -4065,21 +4213,19 @@ class Encoder {
     }
     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);
@@ -4269,21 +4415,20 @@ class Decoder {
             //
             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);
@@ -4327,10 +4472,6 @@ class Decoder {
         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) {
@@ -4857,11 +4998,12 @@ class StateView {
     // 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
         ) {
             /**
@@ -4883,18 +5025,31 @@ class StateView {
         // 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) {
@@ -4916,11 +5071,12 @@ class StateView {
                 }
             });
         }
-        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) {
@@ -4928,27 +5084,17 @@ class StateView {
                 } // skip "undefined" indexes
                 const op = changeTree.indexedOperations[index] ?? 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 !== OPERATION.DELETE &&
                     (isInvisible || // if "invisible", include all
                         tagAtIndex === undefined || // "all change" with no tag
                         tagAtIndex === tag // tagged property
-                    ) &&
-                    op !== 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];