@fluidframework/tree 2.41.0 → 2.42.0

package/lib/simple-tree/core/unhydratedFlexTree.js

@@ -8,72 +8,92 @@ import { assert, oob, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { EmptyKey, forbiddenFieldKindIdentifier, } from "../../core/index.js";
 import { FlexTreeEntityKind, flexTreeMarker, indexForAt, FieldKinds, cursorForMapTreeNode, } from "../../feature-libraries/index.js";
-import { brand, getOrCreate, mapIterable } from "../../util/index.js";
+import { brand, filterIterable, getOrCreate } from "../../util/index.js";
 /**
- * An unhydrated implementation of {@link FlexTreeNode} which wraps a {@link MapTree}.
- * @remarks
- * MapTreeNodes are unconditionally cached -
- * when retrieved via {@link getOrCreateNodeFromInnerNode}, the same {@link MapTree} object will always produce the same `UnhydratedFlexTreeNode` object.
- *
- * Create a `UnhydratedFlexTreeNode` by calling {@link getOrCreate}.
+ * The {@link Unhydrated} implementation of {@link FlexTreeNode}.
  */
 export class UnhydratedFlexTreeNode {
-    get schema() {
-        return this.mapTree.type;
+    isHydrated() {
+        return false;
     }
     get storedSchema() {
-        return (this.context.schema.nodeSchema.get(this.mapTree.type) ?? fail(0xb46 /* missing schema */));
+        return (this.context.schema.nodeSchema.get(this.data.type) ?? fail(0xb46 /* missing schema */));
     }
     get events() {
         return this._events;
     }
-    /**
-     * Create a {@link UnhydratedFlexTreeNode} 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`.
-     */
-    static getOrCreate(context, mapTree) {
-        return nodeCache.get(mapTree) ?? new UnhydratedFlexTreeNode(context, mapTree, undefined);
-    }
     get context() {
         return this.simpleContext.flexContext;
     }
     /**
      * Create a new UnhydratedFlexTreeNode.
-     * @param location - the parentage of this node, if it is being created underneath an existing node and field, or undefined if not
-     * @remarks This class (and its subclasses) should not be directly constructed outside of this module.
-     * Instead, use {@link getOrCreateNodeFromInnerNode} to create a UnhydratedFlexTreeNode from a {@link MapTree}.
-     * A `UnhydratedFlexTreeNode` may never be constructed more than once for the same {@link MapTree} object.
-     * Instead, it should always be acquired via {@link getOrCreateNodeFromInnerNode}.
      */
-    constructor(simpleContext, 
-    /** The underlying {@link MapTree} that this `UnhydratedFlexTreeNode` reads its data from */
-    mapTree, location = unparentedLocation) {
+    constructor(
+    /**
+     * The {@link NodeData} for this node.
+     */
+    data, 
+    /**
+     * All {@link UnhydratedFlexTreeField} for this node that have been created so far.
+     * @remarks
+     * This includes all non-empty fields, but also any empty fields which have been previously requested.
+     */
+    fieldsAll, 
+    /**
+     * The {@link Context} for this node.
+     * @remarks
+     * Provides access to all schema reachable from this node.
+     * See {@link getUnhydratedContext}.
+     */
+    simpleContext) {
+        this.data = data;
+        this.fieldsAll = fieldsAll;
         this.simpleContext = simpleContext;
-        this.mapTree = mapTree;
-        this.location = location;
+        this.location = unparentedLocation;
         this[_a] = FlexTreeEntityKind.Node;
         this._events = createEmitter();
-        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.
-        // When a UnhydratedFlexTreeNode is constructed, its MapTree may contain nodes (anywhere below) that map (via the `nodeCache`) to pre-existing UnhydratedFlexTreeNodes.
-        // Put another way, for a given MapTree, some ancestor UnhydratedFlexTreeNode can be created after any number of its descendant UnhydratedFlexTreeNodes already exist.
-        // In such a case, the spine of nodes between the descendant and ancestor need to exist in order for the ancestor to be able to walk upwards via the `parentField` property.
-        // This needs to happen for all UnhydratedFlexTreeNodes that are descendants of the ancestor UnhydratedFlexTreeNode.
-        // Demanding the entire tree is overkill to solve this problem since not all descendant MapTree nodes will have corresponding UnhydratedFlexTreeNodes.
-        // However, demanding the full tree also lets us eagerly validate that there are no duplicate MapTrees (i.e. same MapTree object) anywhere in the tree.
-        this.walkTree();
+        /**
+         * The non-empty fields on this node.
+         * @remarks
+         * This is needed to implement {@link MapTreeNodeViewGeneric.fields}, which must omit empty fields.
+         * Due to having to detect if a field is empty, this forces the evaluation of any pending defaults in the fields.
+         * Use {@link allFieldsLazy} to avoid evaluating pending defaults.
+         */
+        this.fields = {
+            get: (key) => this.tryGetField(key),
+            [Symbol.iterator]: () => filterIterable(this.fieldsAll, ([, field]) => field.length > 0),
+        };
+        for (const [_key, field] of this.fieldsAll) {
+            field.parent = this;
+        }
+    }
+    /**
+     * Gets all fields, without filtering out empty ones.
+     * @remarks
+     * This avoids forcing the evaluating of pending defaults in the fields, and also saves a copy on access.
+     */
+    get allFieldsLazy() {
+        return this.fieldsAll;
     }
     get type() {
-        return this.mapTree.type;
+        return this.data.type;
+    }
+    get schema() {
+        return this.data.type;
+    }
+    getOrCreateField(key) {
+        return getOrCreate(this.fieldsAll, key, () => {
+            const stored = this.storedSchema.getFieldSchema(key).kind;
+            const field = createField(this.context, stored, key, []);
+            field.parent = this;
+            return field;
+        });
     }
     adoptBy(parent, index) {
         if (parent !== undefined) {
             assert(index !== undefined, 0xa08 /* Expected index */);
             if (this.location !== unparentedLocation) {
-                throw new UsageError("A node may not be inserted if it's already in a tree");
+                throw new UsageError("A node may not be in more than one place in the tree");
             }
             let unhydratedNode = parent.parent;
             while (unhydratedNode !== undefined) {
@@ -99,49 +119,27 @@ export class UnhydratedFlexTreeNode {
         return this.location;
     }
     borrowCursor() {
-        return cursorForMapTreeNode(this.mapTree);
+        return cursorForMapTreeNode(this);
     }
     tryGetField(key) {
-        const field = this.mapTree.fields.get(key);
+        const field = this.fieldsAll.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, this.storedSchema.getFieldSchema(key).kind, () => this.emitChangedEvent(key));
+            return field;
         }
     }
     getBoxed(key) {
         const fieldKey = brand(key);
-        return getOrCreateField(this, fieldKey, this.storedSchema.getFieldSchema(fieldKey).kind, () => this.emitChangedEvent(fieldKey));
+        return this.getOrCreateField(fieldKey);
     }
     boxedIterator() {
-        return mapIterable(this.mapTree.fields.entries(), ([key]) => getOrCreateField(this, key, this.storedSchema.getFieldSchema(key).kind, () => this.emitChangedEvent(key)));
+        return Array.from(this.fields, ([key, field]) => field)[Symbol.iterator]();
     }
     keys() {
-        // TODO: how this should handle missing defaults (and empty keys if they end up being allowed) needs to be determined.
-        return this.mapTree.fields.keys();
+        return Array.from(this.fields, ([key]) => key)[Symbol.iterator]();
     }
     get value() {
-        return this.mapTree.value;
-    }
-    get anchorNode() {
-        // This API is relevant to `LazyTreeNode`s, but not `UnhydratedFlexTreeNode`s.
-        // TODO: Refactor the FlexTreeNode interface so that stubbing this out isn't necessary.
-        return fail(0xb47 /* UnhydratedFlexTreeNode does not implement anchorNode */);
-    }
-    walkTree() {
-        for (const [key, mapTrees] of this.mapTree.fields) {
-            const field = getOrCreateField(this, key, this.storedSchema.getFieldSchema(key).kind, () => this.emitChangedEvent(key));
-            for (let index = 0; index < field.length; index++) {
-                const child = getOrCreateChild(this.simpleContext, mapTrees[index] ?? oob(), {
-                    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 */);
-                assert(child.location.index === index, 0x98f /* Node may not be multi-parented */);
-                child.walkTree();
-            }
-        }
+        return this.data.value;
     }
     emitChangedEvent(key) {
         this._events.emit("childrenChangedAfterBatch", { changedFields: new Set([key]) });
@@ -202,61 +200,82 @@ const unparentedLocation = {
     },
     index: -1,
 };
-class UnhydratedFlexTreeField {
-    get context() {
-        return this.simpleContext.flexContext;
-    }
-    constructor(simpleContext, schema, key, parent, onEdit) {
-        this.simpleContext = simpleContext;
+/**
+ * The {@link Unhydrated} implementation of {@link FlexTreeField}.
+ */
+export class UnhydratedFlexTreeField {
+    constructor(context, schema, key, 
+    /**
+     * The children of this field.
+     * @remarks
+     * This is either an array of {@link UnhydratedFlexTreeNode}s or a {@link ContextualFieldProvider} that will be used to populate the children lazily (after which it will become an array).
+     * See {@link fillPendingDefaults}.
+     * Note that any fields using a {@link ConstantFieldProvider} should be evaluated before constructing the UnhydratedFlexTreeField.
+     */
+    lazyChildren) {
+        this.context = context;
         this.schema = schema;
         this.key = key;
-        this.parent = parent;
-        this.onEdit = onEdit;
+        this.lazyChildren = lazyChildren;
         this[_b] = FlexTreeEntityKind.Field;
-        const fieldKeyCache = getFieldKeyCache(parent);
-        assert(!fieldKeyCache.has(key), 0x990 /* A field already exists for the given MapTrees */);
-        fieldKeyCache.set(key, this);
+        this.parent = undefined;
         // 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 (const [i, mapTree] of this.mapTrees.entries()) {
-            const mapTreeNodeChild = nodeCache.get(mapTree);
-            if (mapTreeNodeChild !== undefined) {
-                if (mapTreeNodeChild.parentField !== unparentedLocation) {
-                    throw new UsageError("A node may not be in more than one place in the tree");
-                }
-                mapTreeNodeChild.adoptBy(this, i);
+        if (Array.isArray(lazyChildren)) {
+            for (const [i, child] of lazyChildren.entries()) {
+                child.adoptBy(this, i);
             }
         }
     }
-    get mapTrees() {
-        return this.parent.mapTree.fields.get(this.key) ?? [];
+    getPendingDefault() {
+        return !Array.isArray(this.lazyChildren) ? this.lazyChildren : undefined;
+    }
+    /**
+     * Populate pending default (if present) using the provided context.
+     * @remarks
+     * This apply to just this field: caller will likely want to recursively walk the tree.
+     * @see {@link pendingDefault}.
+     */
+    fillPendingDefaults(context) {
+        const provider = this.getPendingDefault();
+        if (provider) {
+            const content = provider(context);
+            this.lazyChildren = content;
+        }
+    }
+    /**
+     * Returns true if this field has a pending default due to defined defined using a {@link ContextualFieldProvider}.
+     */
+    get pendingDefault() {
+        return this.getPendingDefault() !== undefined;
+    }
+    get children() {
+        const provider = this.getPendingDefault();
+        if (provider) {
+            const content = provider("UseGlobalContext");
+            this.lazyChildren = content;
+        }
+        return this.lazyChildren;
     }
     get length() {
-        return this.mapTrees.length;
+        return this.children.length;
     }
     is(kind) {
         return this.schema === kind.identifier;
     }
     boxedIterator() {
-        return this.mapTrees
-            .map((m, index) => getOrCreateChild(this.simpleContext, m, {
-            parent: this,
-            index,
-        }))
-            .values();
+        return this.children[Symbol.iterator]();
     }
     boxedAt(index) {
         const i = indexForAt(index, this.length);
         if (i === undefined) {
             return undefined;
         }
-        const m = this.mapTrees[i];
-        if (m !== undefined) {
-            return getOrCreateChild(this.simpleContext, m, {
-                parent: this,
-                index: i,
-            });
-        }
+        const m = this.children[i];
+        return m;
+    }
+    [(_b = flexTreeMarker, Symbol.iterator)]() {
+        return this.boxedIterator();
     }
     /**
      * Mutate this field.
@@ -267,43 +286,40 @@ class UnhydratedFlexTreeField {
      * 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);
+        // Clear parents for all old map trees.
+        for (const tree of this.children) {
+            tree.adoptBy(undefined);
         }
-        else {
-            this.parent.mapTree.fields.delete(this.key);
+        this.lazyChildren = edit(this.children) ?? this.children;
+        // Set parents for all new map trees.
+        for (const [index, tree] of this.children.entries()) {
+            tree.adoptBy(this, index);
         }
-        this.onEdit?.();
+        this.parent?.emitChangedEvent(this.key);
     }
     getFieldPath() {
         throw unsupportedUsageError("Editing an array");
     }
     /** Unboxes leaf nodes to their values */
     unboxed(index) {
-        const mapTree = this.mapTrees[index] ?? oob();
-        const value = mapTree.value;
+        const child = this.children[index] ?? oob();
+        const value = child.value;
         if (value !== undefined) {
             return value;
         }
-        return getOrCreateChild(this.simpleContext, mapTree, { parent: this, index });
+        return child;
     }
 }
-_b = flexTreeMarker;
-class EagerMapTreeOptionalField extends UnhydratedFlexTreeField {
+/**
+ * The {@link Unhydrated} implementation of {@link FlexTreeOptionalField}.
+ */
+export class UnhydratedOptionalField extends UnhydratedFlexTreeField {
     constructor() {
         super(...arguments);
         this.editor = {
             set: (newContent) => {
-                // If the new content is a UnhydratedFlexTreeNode, it needs to have its parent pointer updated
                 if (newContent !== undefined) {
-                    nodeCache.get(newContent)?.adoptBy(this, 0);
-                }
-                // If the old content is a UnhydratedFlexTreeNode, it needs to have its parent pointer unset
-                const oldContent = this.mapTrees[0];
-                if (oldContent !== undefined) {
-                    nodeCache.get(oldContent)?.adoptBy(undefined);
+                    assert(newContent instanceof UnhydratedFlexTreeNode, 0xbb7 /* Expected unhydrated node */);
                 }
                 this.edit((mapTrees) => {
                     if (newContent !== undefined) {
@@ -317,46 +333,48 @@ class EagerMapTreeOptionalField extends UnhydratedFlexTreeField {
         };
     }
     get content() {
-        const value = this.mapTrees[0];
+        const value = this.children[0];
         if (value !== undefined) {
             return this.unboxed(0);
         }
         return undefined;
     }
 }
-class EagerMapTreeRequiredField extends EagerMapTreeOptionalField {
+class UnhydratedRequiredField extends UnhydratedOptionalField {
     get content() {
         // This cannot use ?? since null is a legal value here.
         assert(super.content !== undefined, 0xa57 /* Expected EagerMapTree required field to have a value */);
         return super.content;
     }
 }
-export class UnhydratedTreeSequenceField extends UnhydratedFlexTreeField {
+/**
+ * The {@link Unhydrated} implementation of {@link FlexTreeSequenceField}.
+ */
+export class UnhydratedSequenceField extends UnhydratedFlexTreeField {
     constructor() {
         super(...arguments);
         this.editor = {
             insert: (index, newContent) => {
-                for (let i = 0; i < newContent.length; i++) {
-                    const c = newContent[i];
+                for (const c of newContent) {
                     assert(c !== undefined, 0xa0a /* Unexpected sparse array content */);
-                    nodeCache.get(c)?.adoptBy(this, index + i);
+                    assert(c instanceof UnhydratedFlexTreeNode, 0xbb8 /* Expected unhydrated node */);
                 }
+                const newContentChecked = newContent;
                 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);
+                        mapTrees.splice(index, 0, ...newContentChecked);
                     }
                     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));
+                        return mapTrees.slice(0, index).concat(newContentChecked, mapTrees.slice(index));
                     }
                 });
             },
             remove: (index, count) => {
                 for (let i = index; i < index + count; i++) {
-                    const c = this.mapTrees[i];
+                    const c = this.children[i];
                     assert(c !== undefined, 0xa0b /* Unexpected sparse array */);
-                    nodeCache.get(c)?.adoptBy(undefined);
                 }
                 let removed;
                 this.edit((mapTrees) => {
@@ -376,58 +394,25 @@ export class UnhydratedTreeSequenceField extends UnhydratedFlexTreeField {
     map(callbackfn) {
         return Array.from(this, callbackfn);
     }
-    *[Symbol.iterator]() {
-        for (const [i] of this.mapTrees.entries()) {
-            yield this.unboxed(i);
-        }
-    }
 }
 // #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 UnhydratedFlexTreeNode} for the given {@link MapTree}, returns it, otherwise returns `undefined`.
- * @remarks {@link UnhydratedFlexTreeNode | UnhydratedFlexTreeNodes} are created via {@link getOrCreateNodeFromInnerNode}.
- */
-export function tryUnhydratedFlexTreeNode(mapTree) {
-    return nodeCache.get(mapTree);
-}
-/** Helper for creating a `UnhydratedFlexTreeNode` given the parent field (e.g. when "walking down") */
-function getOrCreateChild(context, mapTree, parent) {
-    const cached = nodeCache.get(mapTree);
-    if (cached !== undefined) {
-        return cached;
-    }
-    return new UnhydratedFlexTreeNode(context, mapTree, parent);
-}
-/** Creates a field with the given attributes, or returns a cached field if there is one */
-function getOrCreateField(parent, key, schema, onEdit) {
-    const cached = getFieldKeyCache(parent).get(key);
-    if (cached !== undefined) {
-        return cached;
-    }
-    if (schema === FieldKinds.required.identifier ||
-        schema === FieldKinds.identifier.identifier) {
-        return new EagerMapTreeRequiredField(parent.simpleContext, schema, key, parent, onEdit);
-    }
-    if (schema === FieldKinds.optional.identifier) {
-        return new EagerMapTreeOptionalField(parent.simpleContext, schema, key, parent, onEdit);
-    }
-    if (schema === FieldKinds.sequence.identifier) {
-        return new UnhydratedTreeSequenceField(parent.simpleContext, schema, key, parent, onEdit);
-    }
-    // TODO: this seems to used by unknown optional fields. They should probably use "optional" not "Forbidden" schema.
-    if (schema === FieldKinds.forbidden.identifier) {
-        return new UnhydratedFlexTreeField(parent.simpleContext, schema, key, parent, onEdit);
+/** Creates a field with the given attributes */
+export function createField(...args) {
+    switch (args[1]) {
+        case FieldKinds.required.identifier:
+        case FieldKinds.identifier.identifier:
+            return new UnhydratedRequiredField(...args);
+        case FieldKinds.optional.identifier:
+            return new UnhydratedOptionalField(...args);
+        case FieldKinds.sequence.identifier:
+            return new UnhydratedSequenceField(...args);
+        case FieldKinds.forbidden.identifier:
+            // TODO: this seems to used by unknown optional fields. They should probably use "optional" not "Forbidden" schema.
+            return new UnhydratedFlexTreeField(...args);
+        default:
+            return fail(0xb9d /* unsupported field kind */);
     }
-    return fail(0xb9d /* unsupported field kind */);
 }
-// #endregion Caching and unboxing utilities
 export function unsupportedUsageError(message) {
     return new UsageError(`${message ?? "Operation"} is not supported for content that has not yet been inserted into the tree`);
 }