@fluidframework/tree 2.1.0 → 2.2.0

package/lib/feature-libraries/flex-map-tree/mapTreeNode.js

@@ -3,11 +3,11 @@
  * Licensed under the MIT License.
  */
 var _a, _b;
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import { EmptyKey, } from "../../core/index.js";
-import { brand, fail, mapIterable } from "../../util/index.js";
+import { brand, fail, getOrCreate, mapIterable } from "../../util/index.js";
 import { FlexTreeEntityKind, flexTreeMarker, indexForAt, } from "../flex-tree/index.js";
-import { FlexFieldSchema, isLazy, schemaIsFieldNode, schemaIsLeaf, schemaIsMap, schemaIsObjectNode, } from "../typed-schema/index.js";
+import { FlexFieldSchema, isLazy, schemaIsLeaf, schemaIsMap, schemaIsObjectNode, } from "../typed-schema/index.js";
 import { normalizeAllowedTypes } from "../schemaBuilderBase.js";
 import { FieldKinds } from "../default-schema/index.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
@@ -17,6 +17,12 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 export function isMapTreeNode(flexNode) {
     return flexNode instanceof EagerMapTreeNode;
 }
+/**
+ * Checks if the given {@link FlexTreeField} is a {@link MapTreeSequenceField}.
+ */
+export function isMapTreeSequenceField(field) {
+    return field instanceof EagerMapTreeSequenceField;
+}
 /**
  * A readonly implementation of {@link FlexTreeNode} which wraps a {@link MapTree}.
  * @remarks Any methods that would mutate the node will fail,
@@ -35,11 +41,12 @@ export class EagerMapTreeNode {
      */
     constructor(schema, 
     /** The underlying {@link MapTree} that this `MapTreeNode` reads its data from */
-    mapTree, location) {
+    mapTree, location = unparentedLocation) {
         this.schema = schema;
         this.mapTree = mapTree;
         this.location = location;
         this[_a] = FlexTreeEntityKind.Node;
+        this.context = undefined;
         assert(!nodeCache.has(mapTree), 0x98b /* A node already exists for the given MapTree */);
         nodeCache.set(mapTree, this);
         // Fully demand the tree to ensure that parent pointers are present and accurate on all nodes.
@@ -54,25 +61,22 @@ export class EagerMapTreeNode {
     get type() {
         return this.schema.name;
     }
-    /**
-     * Set this node's parentage (see {@link FlexTreeNode.parentField}).
-     * @remarks A node may only be adopted to a new parent one time, and only if it was not constructed with a parent.
-     */
-    adopt(parent, index) {
-        assert(this.location === undefined, 0x98c /* Node may not be adopted if it already has a parent */);
-        this.location = { parent, index };
+    adoptBy(parent, index) {
+        if (parent !== undefined) {
+            assert(this.location === unparentedLocation, 0x98c /* Node may not be adopted if it already has a parent */);
+            assert(index !== undefined, 0xa08 /* Expected index */);
+            this.location = { parent, index };
+        }
+        else {
+            assert(this.location !== unparentedLocation, 0xa09 /* Node may not be un-adopted if it does not have a parent */);
+            this.location = unparentedLocation;
+        }
     }
     /**
      * The field this tree is in, and the index within that field.
-     * @remarks If this node is unparented, this method will return the special {@link rootMapTreeField} as the parent.
+     * @remarks If this node is unparented, this method will return the special {@link unparentedLocation} as the parent.
      */
     get parentField() {
-        if (this.location === undefined) {
-            return {
-                parent: rootMapTreeField,
-                index: -1,
-            };
-        }
         return this.location;
     }
     is(schema) {
@@ -82,25 +86,19 @@ export class EagerMapTreeNode {
         const field = this.mapTree.fields.get(key);
         // Only return the field if it is not empty, in order to fulfill the contract of `tryGetField`.
         if (field !== undefined && field.length > 0) {
-            return getOrCreateField(this, key, field, this.schema.getFieldSchema(key));
+            return getOrCreateField(this, key, this.schema.getFieldSchema(key));
         }
     }
     getBoxed(key) {
         const fieldKey = brand(key);
-        const field = this.mapTree.fields.get(fieldKey) ?? [];
-        return getOrCreateField(this, fieldKey, field, this.schema.getFieldSchema(fieldKey));
+        return getOrCreateField(this, fieldKey, this.schema.getFieldSchema(fieldKey));
     }
     boxedIterator() {
-        return mapIterable(this.mapTree.fields.entries(), ([key, field]) => getOrCreateField(this, key, field, this.schema.getFieldSchema(key)));
+        return mapIterable(this.mapTree.fields.entries(), ([key]) => getOrCreateField(this, key, this.schema.getFieldSchema(key)));
     }
     get value() {
         return this.mapTree.value;
     }
-    get context() {
-        // This API is relevant to `LazyTreeNode`s, but not `MapTreeNode`s.
-        // TODO: Refactor the FlexTreeNode interface so that stubbing this out isn't necessary.
-        return fail("MapTreeNode does not implement context");
-    }
     get anchorNode() {
         // This API is relevant to `LazyTreeNode`s, but not `MapTreeNode`s.
         // TODO: Refactor the FlexTreeNode interface so that stubbing this out isn't necessary.
@@ -108,9 +106,9 @@ export class EagerMapTreeNode {
     }
     walkTree() {
         for (const [key, mapTrees] of this.mapTree.fields) {
-            const field = getOrCreateField(this, key, mapTrees, this.schema.getFieldSchema(key));
+            const field = getOrCreateField(this, key, this.schema.getFieldSchema(key));
             for (let index = 0; index < field.length; index++) {
-                const child = getOrCreateChild(mapTrees[index], this.schema.getFieldSchema(key).allowedTypes, { parent: field, index });
+                const child = getOrCreateChild(mapTrees[index] ?? oob(), this.schema.getFieldSchema(key).allowedTypes, { parent: field, index });
                 // These next asserts detect the case where `getOrCreateChild` gets a cache hit of a different node than the one we're trying to create
                 assert(child.location !== undefined, 0x98d /* Expected node to have parent */);
                 assert(child.location.parent.parent === this, 0x98e /* Node may not be multi-parented */);
@@ -121,38 +119,10 @@ export class EagerMapTreeNode {
     }
 }
 _a = flexTreeMarker;
-/**
- * The implementation of a field node created by {@link getOrCreateNode}.
- */
-export class EagerMapTreeFieldNode extends EagerMapTreeNode {
-    get content() {
-        const field = this.tryGetField(EmptyKey);
-        if (field === undefined) {
-            return undefined;
-        }
-        return unboxedField(field, EmptyKey, this.mapTree, this);
-    }
-    getBoxed(key) {
-        return super.getBoxed(key);
-    }
-}
 /**
  * The implementation of a map node created by {@link getOrCreateNode}.
  */
 export class EagerMapTreeMapNode extends EagerMapTreeNode {
-    get size() {
-        return this.mapTree.fields.size;
-    }
-    has(key) {
-        return this.tryGetField(brand(key)) !== undefined;
-    }
-    get(key) {
-        const field = this.tryGetField(brand(key));
-        if (field === undefined) {
-            return undefined;
-        }
-        return unboxedField(field, brand(key), this.mapTree, this);
-    }
     keys() {
         return this.mapTree.fields.keys();
     }
@@ -174,14 +144,6 @@ export class EagerMapTreeMapNode extends EagerMapTreeNode {
     getBoxed(key) {
         return super.getBoxed(key);
     }
-    set(key, value) {
-        // `MapTreeNode`s cannot be mutated
-        throw unsupportedUsageError("Setting a map entry");
-    }
-    delete(key) {
-        // `MapTreeNode`s cannot be mutated
-        throw unsupportedUsageError("Deleting a map entry");
-    }
     [Symbol.iterator]() {
         return this.entries();
     }
@@ -194,54 +156,59 @@ class EagerMapTreeLeafNode extends EagerMapTreeNode {
         return super.value;
     }
 }
-// #endregion Nodes
-// #region Fields
 /**
- * A special singleton that is the implicit parent field of all un-parented {@link EagerMapTreeNode}s.
+ * A special singleton that is the implicit {@link LocationInField} of all un-parented {@link EagerMapTreeNode}s.
  * @remarks This exists because {@link EagerMapTreeNode.parentField} must return a field.
  * If a {@link EagerMapTreeNode} is created without a parent, its {@link EagerMapTreeNode.parentField} property will point to this object.
  * However, this field cannot be used in any practical way because it is empty, i.e. it does not actually contain the children that claim to be parented under it.
  * It has the "empty" schema and it will always contain zero children if queried.
+ * Any nodes with this location will have a dummy parent index of `-1`.
  */
-export const rootMapTreeField = {
-    [flexTreeMarker]: FlexTreeEntityKind.Field,
-    length: 0,
-    key: EmptyKey,
-    parent: undefined,
-    is(schema) {
-        return schema === FlexFieldSchema.empty;
-    },
-    boxedIterator() {
-        return [].values();
-    },
-    boxedAt(index) {
-        return undefined;
-    },
-    schema: FlexFieldSchema.empty,
-    get context() {
-        return fail("MapTreeField does not implement context");
+const unparentedLocation = {
+    parent: {
+        [flexTreeMarker]: FlexTreeEntityKind.Field,
+        length: 0,
+        key: EmptyKey,
+        parent: undefined,
+        is(schema) {
+            return schema === FlexFieldSchema.empty;
+        },
+        boxedIterator() {
+            return [].values();
+        },
+        boxedAt(index) {
+            return undefined;
+        },
+        schema: FlexFieldSchema.empty,
+        context: undefined,
+        mapTrees: [],
     },
-    mapTrees: [],
+    index: -1,
 };
-class MapTreeField {
-    constructor(schema, key, parent, mapTrees) {
+class EagerMapTreeField {
+    constructor(schema, key, parent) {
         this.schema = schema;
         this.key = key;
         this.parent = parent;
-        this.mapTrees = mapTrees;
         this[_b] = FlexTreeEntityKind.Field;
-        assert(!fieldCache.has(mapTrees), 0x990 /* A field already exists for the given MapTrees */);
-        fieldCache.set(mapTrees, this);
+        const fieldKeyCache = getFieldKeyCache(parent);
+        assert(!fieldKeyCache.has(key), 0x990 /* A field already exists for the given MapTrees */);
+        fieldKeyCache.set(key, this);
         // When this field is created (which only happens one time, because it is cached), all the children become parented for the first time.
         // "Adopt" each child by updating its parent information to point to this field.
-        for (let i = 0; i < mapTrees.length; i++) {
-            const mapTreeNodeChild = nodeCache.get(mapTrees[i]);
+        for (const [i, mapTree] of this.mapTrees.entries()) {
+            const mapTreeNodeChild = nodeCache.get(mapTree);
             if (mapTreeNodeChild !== undefined) {
-                assert(mapTreeNodeChild.parentField.parent === rootMapTreeField, 0x991 /* Node is already parented under a different field */);
-                mapTreeNodeChild.adopt(this, i);
+                if (mapTreeNodeChild.parentField !== unparentedLocation) {
+                    throw new UsageError("A node may not be in more than one place in the tree");
+                }
+                mapTreeNodeChild.adoptBy(this, i);
             }
         }
     }
+    get mapTrees() {
+        return this.parent.mapTree.fields.get(this.key) ?? [];
+    }
     get length() {
         return this.mapTrees.length;
     }
@@ -269,36 +236,108 @@ class MapTreeField {
             });
         }
     }
-    get context() {
-        return fail("MapTreeField does not implement context");
+    /**
+     * Mutate this field.
+     * @param edit - A function which receives the current `MapTree`s that comprise the contents of the field so that it may be mutated.
+     * The function may mutate the array in place or return a new array.
+     * If a new array is returned then it will be used as the new contents of the field, otherwise the original array will be continue to be used.
+     * @remarks All edits to the field (i.e. mutations of the field's MapTrees) should be directed through this function.
+     * This function ensures that the parent MapTree has no empty fields (which is an invariant of `MapTree`) after the mutation.
+     */
+    edit(edit) {
+        const oldMapTrees = this.parent.mapTree.fields.get(this.key) ?? [];
+        const newMapTrees = edit(oldMapTrees) ?? oldMapTrees;
+        if (newMapTrees.length > 0) {
+            this.parent.mapTree.fields.set(this.key, newMapTrees);
+        }
+        else {
+            this.parent.mapTree.fields.delete(this.key);
+        }
     }
 }
 _b = flexTreeMarker;
-class MapTreeRequiredField extends MapTreeField {
-    get content() {
-        return unboxedUnion(this.schema, this.mapTrees[0], { parent: this, index: 0 });
+class EagerMapTreeOptionalField extends EagerMapTreeField {
+    constructor() {
+        super(...arguments);
+        this.editor = {
+            set: (newContent) => {
+                // If the new content is a MapTreeNode, it needs to have its parent pointer updated
+                if (newContent !== undefined) {
+                    nodeCache.get(newContent)?.adoptBy(this, 0);
+                }
+                // If the old content is a MapTreeNode, it needs to have its parent pointer unset
+                const oldContent = this.mapTrees[0];
+                if (oldContent !== undefined) {
+                    nodeCache.get(oldContent)?.adoptBy(undefined);
+                }
+                this.edit((mapTrees) => {
+                    if (newContent !== undefined) {
+                        mapTrees[0] = newContent;
+                    }
+                    else {
+                        mapTrees.length = 0;
+                    }
+                });
+            },
+        };
     }
-    set content(_) {
-        throw unsupportedUsageError("Setting an optional field");
+    get content() {
+        const value = this.mapTrees[0];
+        if (value !== undefined) {
+            return unboxedUnion(this.schema, value, {
+                parent: this,
+                index: 0,
+            });
+        }
+        return undefined;
     }
 }
-class MapTreeOptionalField extends MapTreeField {
+class EagerMapTreeRequiredField extends EagerMapTreeOptionalField {
     get content() {
-        return this.mapTrees.length > 0
-            ? unboxedUnion(this.schema, this.mapTrees[0], { parent: this, index: 0 })
-            : undefined;
-    }
-    set content(_) {
-        throw unsupportedUsageError("Setting an optional field");
+        return super.content ?? fail("Expected EagerMapTree required field to have a value");
     }
 }
-class MapTreeSequenceField extends MapTreeField {
+class EagerMapTreeSequenceField extends EagerMapTreeField {
+    constructor() {
+        super(...arguments);
+        this.editor = {
+            insert: (index, newContent) => {
+                for (let i = 0; i < newContent.length; i++) {
+                    const c = newContent[i];
+                    assert(c !== undefined, 0xa0a /* Unexpected sparse array content */);
+                    nodeCache.get(c)?.adoptBy(this, index + i);
+                }
+                this.edit((mapTrees) => {
+                    if (newContent.length < 1000) {
+                        // For "smallish arrays" (`1000` is not empirically derived), the `splice` function is appropriate...
+                        mapTrees.splice(index, 0, ...newContent);
+                    }
+                    else {
+                        // ...but we avoid using `splice` + spread for very large input arrays since there is a limit on how many elements can be spread (too many will overflow the stack).
+                        return mapTrees.slice(0, index).concat(newContent, mapTrees.slice(index));
+                    }
+                });
+            },
+            remove: (index, count) => {
+                for (let i = index; i < index + count; i++) {
+                    const c = this.mapTrees[i];
+                    assert(c !== undefined, 0xa0b /* Unexpected sparse array */);
+                    nodeCache.get(c)?.adoptBy(undefined);
+                }
+                let removed;
+                this.edit((mapTrees) => {
+                    removed = mapTrees.splice(index, count);
+                });
+                return removed ?? fail("Expected removed to be set by edit");
+            },
+        };
+    }
     at(index) {
         const i = indexForAt(index, this.length);
         if (i === undefined) {
             return undefined;
         }
-        return unboxedUnion(this.schema, this.mapTrees[i], { parent: this, index: i });
+        return unboxedUnion(this.schema, this.mapTrees[i] ?? oob(), { parent: this, index: i });
     }
     map(callbackfn) {
         return Array.from(this, callbackfn);
@@ -307,51 +346,22 @@ class MapTreeSequenceField extends MapTreeField {
         return Array.from(this.boxedIterator(), callbackfn);
     }
     *[Symbol.iterator]() {
-        for (let i = 0; i < this.mapTrees.length; i++) {
-            yield unboxedUnion(this.schema, this.mapTrees[i], { parent: this, index: i });
+        for (const [i, mapTree] of this.mapTrees.entries()) {
+            yield unboxedUnion(this.schema, mapTree, { parent: this, index: i });
         }
     }
-    sequenceEditor() {
-        throw unsupportedUsageError("Editing a sequence");
-    }
-    insertAt(index, value) {
-        throw unsupportedUsageError("Editing a sequence");
-    }
-    insertAtStart(value) {
-        throw unsupportedUsageError("Editing a sequence");
-    }
-    insertAtEnd(value) {
-        throw unsupportedUsageError("Editing a sequence");
-    }
-    removeAt(index) {
-        throw unsupportedUsageError("Editing a sequence");
-    }
-    moveToStart(sourceIndex, source) {
-        throw unsupportedUsageError("Editing a sequence");
-    }
-    moveToEnd(sourceIndex, source) {
-        throw unsupportedUsageError("Editing a sequence");
-    }
-    moveToIndex(index, sourceIndex, source) {
-        throw unsupportedUsageError("Editing a sequence");
-    }
-    moveRangeToStart(sourceStart, sourceEnd, source) {
-        throw unsupportedUsageError("Editing a sequence");
-    }
-    moveRangeToEnd(sourceStart, sourceEnd, source) {
-        throw unsupportedUsageError("Editing a sequence");
-    }
-    moveRangeToIndex(index, sourceStart, sourceEnd, source) {
-        throw unsupportedUsageError("Editing a sequence");
-    }
     getFieldPath() {
-        throw unsupportedUsageError("Editing a sequence");
+        throw unsupportedUsageError("Editing an array");
     }
 }
 // #endregion Fields
 // #region Caching and unboxing utilities
 const nodeCache = new WeakMap();
+/** Node Parent -\> Field Key -\> Field */
 const fieldCache = new WeakMap();
+function getFieldKeyCache(parent) {
+    return getOrCreate(fieldCache, parent, () => new Map());
+}
 /**
  * If there exists a {@link EagerMapTreeNode} for the given {@link MapTree}, returns it, otherwise returns `undefined`.
  * @remarks {@link EagerMapTreeNode | MapTreeNodes} are created via {@link getOrCreateNode}.
@@ -360,20 +370,13 @@ export function tryGetMapTreeNode(mapTree) {
     return nodeCache.get(mapTree);
 }
 /**
- * Create a {@link MapTreeNode} that wraps the given {@link MapTree}, or get the node that already exists for that {@link MapTree} if there is one.
+ * Create a {@link EagerMapTreeNode} that wraps the given {@link MapTree}, or get the node that already exists for that {@link MapTree} if there is one.
  * @param nodeSchema - the {@link FlexTreeNodeSchema | schema} that the node conforms to
  * @param mapTree - the {@link MapTree} containing the data for this node.
  * @remarks It must conform to the `nodeSchema`.
  */
 export function getOrCreateMapTreeNode(nodeSchema, mapTree) {
-    return getOrCreateNode(nodeSchema, mapTree);
-}
-export function getOrCreateNode(nodeSchema, mapTree) {
-    const cached = tryGetMapTreeNode(mapTree);
-    if (cached !== undefined) {
-        return cached;
-    }
-    return createNode(nodeSchema, mapTree, undefined);
+    return nodeCache.get(mapTree) ?? createNode(nodeSchema, mapTree, undefined);
 }
 /** Helper for creating a `MapTreeNode` given the parent field (e.g. when "walking down") */
 function getOrCreateChild(mapTree, implicitAllowedTypes, parent) {
@@ -390,6 +393,7 @@ function getOrCreateChild(mapTree, implicitAllowedTypes, parent) {
     }) ?? fail("Unsupported node schema");
     return createNode(nodeSchema, mapTree, parent);
 }
+/** Always constructs a new node, therefore may not be called twice for the same `MapTree`. */
 function createNode(nodeSchema, mapTree, parentField) {
     if (schemaIsLeaf(nodeSchema)) {
         return new EagerMapTreeLeafNode(nodeSchema, mapTree, parentField);
@@ -397,31 +401,28 @@ function createNode(nodeSchema, mapTree, parentField) {
     if (schemaIsMap(nodeSchema)) {
         return new EagerMapTreeMapNode(nodeSchema, mapTree, parentField);
     }
-    if (schemaIsFieldNode(nodeSchema)) {
-        return new EagerMapTreeFieldNode(nodeSchema, mapTree, parentField);
-    }
     if (schemaIsObjectNode(nodeSchema)) {
         return new EagerMapTreeNode(nodeSchema, mapTree, parentField);
     }
     assert(false, 0x994 /* Unrecognized node kind */);
 }
 /** Creates a field with the given attributes, or returns a cached field if there is one */
-function getOrCreateField(parent, key, mapTrees, schema) {
-    const cached = fieldCache.get(mapTrees);
+function getOrCreateField(parent, key, schema) {
+    const cached = getFieldKeyCache(parent).get(key);
     if (cached !== undefined) {
         return cached;
     }
     if (schema.kind.identifier === FieldKinds.required.identifier ||
         schema.kind.identifier === FieldKinds.identifier.identifier) {
-        return new MapTreeRequiredField(schema, key, parent, mapTrees);
+        return new EagerMapTreeRequiredField(schema, key, parent);
     }
     if (schema.kind.identifier === FieldKinds.optional.identifier) {
-        return new MapTreeOptionalField(schema, key, parent, mapTrees);
+        return new EagerMapTreeOptionalField(schema, key, parent);
     }
     if (schema.kind.identifier === FieldKinds.sequence.identifier) {
-        return new MapTreeSequenceField(schema, key, parent, mapTrees);
+        return new EagerMapTreeSequenceField(schema, key, parent);
     }
-    return new MapTreeField(schema, key, parent, mapTrees);
+    return new EagerMapTreeField(schema, key, parent);
 }
 /** Unboxes non-polymorphic leaf nodes to their values, if applicable */
 function unboxedUnion(schema, mapTree, parent) {
@@ -439,17 +440,20 @@ function unboxedField(field, key, mapTree, parentNode) {
     const fieldSchema = field.schema;
     const mapTrees = mapTree.fields.get(key) ?? fail("Key does not exist in unhydrated map tree");
     if (fieldSchema.kind === FieldKinds.required) {
-        return unboxedUnion(fieldSchema, mapTrees[0], {
+        return unboxedUnion(fieldSchema, mapTrees[0] ?? oob(), {
             parent: field,
             index: 0,
         });
     }
     if (fieldSchema.kind === FieldKinds.optional) {
         return (mapTrees.length > 0
-            ? unboxedUnion(fieldSchema, mapTrees[0], { parent: field, index: 0 })
+            ? unboxedUnion(fieldSchema, mapTrees[0] ?? oob(), {
+                parent: field,
+                index: 0,
+            })
             : undefined);
     }
-    return getOrCreateField(parentNode, key, mapTrees, fieldSchema);
+    return getOrCreateField(parentNode, key, fieldSchema);
 }
 // #endregion Caching and unboxing utilities
 export function unsupportedUsageError(message) {