@fluidframework/tree 2.73.0 → 2.74.0-368706

package/dist/simple-tree/prepareForInsertion.js

@@ -4,14 +4,17 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.prepareContentForHydration = exports.prepareForInsertionContextless = exports.prepareArrayContentForInsertion = exports.prepareForInsertion = void 0;
-const index_js_1 = require("../feature-libraries/index.js");
-const unhydratedFlexTreeFromInsertable_js_1 = require("./unhydratedFlexTreeFromInsertable.js");
+exports.prepareForInsertionContextless = exports.prepareArrayContentForInsertion = exports.prepareForInsertion = void 0;
 const internal_1 = require("@fluidframework/telemetry-utils/internal");
-const index_js_2 = require("../util/index.js");
+const index_js_1 = require("../core/index.js");
+const index_js_2 = require("../feature-libraries/index.js");
+const fieldSchema_js_1 = require("./fieldSchema.js");
+const unhydratedFlexTreeFromInsertable_js_1 = require("./unhydratedFlexTreeFromInsertable.js");
 const index_js_3 = require("./core/index.js");
 const internal_2 = require("@fluidframework/core-utils/internal");
 const index_js_4 = require("../feature-libraries/index.js");
+const createContext_js_1 = require("./createContext.js");
+const toStoredSchema_js_1 = require("./toStoredSchema.js");
 /**
  * For now, schema validation for inserted content is always enabled.
  * @remarks
@@ -19,6 +22,17 @@ const index_js_4 = require("../feature-libraries/index.js");
  * this could be changed.
  */
 const validateSchema = true;
+// IDEA:
+// Have prepareForInsertion return a TreeChunk, and a function which should be called after its insertion with the path to its location (as Inner node?)
+function isHydrated(node) {
+    return (0, index_js_3.isTreeNode)(node) && (0, index_js_3.getKernel)(node).isHydrated();
+}
+function assertIsDetachedFlexTreeNode(node) {
+    if (node.parentField.parent.parent !== undefined ||
+        node.parentField.parent.key === index_js_1.rootFieldKey) {
+        throw new internal_1.UsageError("Can only attach a detached node (i.e., a root with TreeStatus.Removed status)");
+    }
+}
 /**
  * Prepare content from a user for insertion into a tree.
  * @remarks
@@ -28,7 +42,17 @@ const validateSchema = true;
  * (Triggering {@link ForestEvents.afterRootFieldCreated}) otherwise hydration will break.
  */
 function prepareForInsertion(data, schema, destinationContext, destinationSchema) {
-    return prepareForInsertionContextless(data, schema, (0, index_js_1.getSchemaAndPolicy)(destinationContext), destinationContext.isHydrated() ? destinationContext : undefined, destinationSchema);
+    if (data !== undefined && isHydrated(data)) {
+        const treeNode = (0, index_js_3.getInnerNode)(data);
+        assertIsDetachedFlexTreeNode(treeNode);
+        return treeNode;
+    }
+    const content = prepareForInsertionContextlessInternal(data, schema, (0, index_js_2.getSchemaAndPolicy)(destinationContext), destinationContext.isHydrated() ? destinationContext : undefined, destinationSchema);
+    (0, internal_2.assert)(content.toAttach !== undefined, "Expected toAttach to be defined");
+    (0, internal_2.assert)(content.toAttach.length < 2, "Expected toAttach to be a single element on none");
+    // TODO: when supporting back compat to not edit detached fields, caller will have to finalize after attaching to in document location.
+    content.finalize(content.toAttach);
+    return (content.toAttach.length === 0 ? undefined : content.toAttach[0]);
 }
 exports.prepareForInsertion = prepareForInsertion;
 /**
@@ -45,13 +69,31 @@ exports.prepareForInsertion = prepareForInsertion;
  * due to how the eventing in prepareContentForHydration works.
  */
 function prepareArrayContentForInsertion(data, schema, destinationContext, destinationSchema) {
-    const mapTrees = data.map((item) => (0, unhydratedFlexTreeFromInsertable_js_1.unhydratedFlexTreeFromInsertable)(item, schema));
-    validateAndPrepare((0, index_js_1.getSchemaAndPolicy)(destinationContext), destinationContext.isHydrated() ? destinationContext : undefined, {
-        kind: index_js_1.FieldKinds.sequence.identifier,
+    const hasHydratedData = data.find(isHydrated) !== undefined;
+    if (hasHydratedData) {
+        const hasUnhydratedData = data.find((item) => !isHydrated(item)) !== undefined;
+        if (hasUnhydratedData) {
+            throw new internal_1.UsageError("Mixed hydrated and unhydrated data not supported");
+        }
+        const treeNodes = data.map((item) => (0, index_js_3.getInnerNode)(item));
+        for (const node of treeNodes) {
+            assertIsDetachedFlexTreeNode(node);
+        }
+        return treeNodes;
+    }
+    const mapTrees = data.map((item) => (0, unhydratedFlexTreeFromInsertable_js_1.flexTreeFromInsertable)(item, schema));
+    const fieldSchema = (0, toStoredSchema_js_1.convertField)((0, fieldSchema_js_1.normalizeFieldSchema)(schema));
+    const normalizedFieldSchema = (0, fieldSchema_js_1.normalizeFieldSchema)(schema);
+    const field = (0, index_js_3.createField)((0, createContext_js_1.getUnhydratedContext)(normalizedFieldSchema).flexContext, fieldSchema.kind, index_js_1.dummyRoot, mapTrees);
+    const content = validateAndPrepare((0, index_js_2.getSchemaAndPolicy)(destinationContext), destinationContext.isHydrated() ? destinationContext : undefined, {
+        kind: index_js_2.FieldKinds.sequence.identifier,
         types: destinationSchema,
         persistedMetadata: undefined,
-    }, mapTrees);
-    return mapTrees;
+    }, field);
+    (0, internal_2.assert)(content.toAttach !== undefined, "Expected toAttach to be defined");
+    // TODO: when supporting back compat to not edit detached fields, caller will have to finalize after attaching to in document location.
+    content.finalize(content.toAttach);
+    return content.toAttach;
 }
 exports.prepareArrayContentForInsertion = prepareArrayContentForInsertion;
 /**
@@ -63,149 +105,165 @@ exports.prepareArrayContentForInsertion = prepareArrayContentForInsertion;
  * @remarks
  * Adding this entry point is a workaround for initialize not currently having a context.
  */
-function prepareForInsertionContextless(data, schema, schemaAndPolicy, hydratedData, destinationSchema, scheduleHydrationOverride) {
-    const mapTree = (0, unhydratedFlexTreeFromInsertable_js_1.unhydratedFlexTreeFromInsertable)(data, schema);
-    const contentArray = mapTree === undefined ? [] : [mapTree];
-    validateAndPrepare(schemaAndPolicy, hydratedData, destinationSchema, contentArray, scheduleHydrationOverride);
-    return mapTree;
+function prepareForInsertionContextless(data, schema, schemaAndPolicy, hydratedData, destinationSchema) {
+    const final = prepareForInsertionContextlessInternal(data, schema, schemaAndPolicy, hydratedData, destinationSchema);
+    (0, internal_2.assert)(final.rootsLocations !== undefined, "Expected rootIds to be defined");
+    (0, internal_2.assert)(final.rootsLocations.length <= 1, "Expected at most one node to be returned from prepareForInsertionContextless");
+    // For some reason TypeScript can't figure out that final.rootsLocations is defined unless we handle is separately.
+    return { ...final, rootsLocations: final.rootsLocations };
 }
 exports.prepareForInsertionContextless = prepareForInsertionContextless;
+/**
+ * Split out from {@link prepareForInsertion} as to allow use without a context.
+ *
+ * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.
+ * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.
+ */
+function prepareForInsertionContextlessInternal(data, schema, schemaAndPolicy, hydratedData, destinationSchema) {
+    const mapTree = (0, unhydratedFlexTreeFromInsertable_js_1.flexTreeFromInsertable)(data, schema);
+    const contentArray = mapTree === undefined ? [] : [mapTree];
+    const normalizedFieldSchema = (0, fieldSchema_js_1.normalizeFieldSchema)(schema);
+    const fieldSchema = (0, toStoredSchema_js_1.convertField)(normalizedFieldSchema);
+    const field = (0, index_js_3.createField)((0, createContext_js_1.getUnhydratedContext)(normalizedFieldSchema).flexContext, fieldSchema.kind, index_js_1.dummyRoot, contentArray);
+    return validateAndPrepare(schemaAndPolicy, hydratedData, destinationSchema, field);
+}
 /**
  * If hydrating, do a final validation against the schema and prepare the content for hydration.
  *
  * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.
  * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.
+ *
+ * TODO: return nodes flex tree nodes to insert (might be newly hydrated) or reused unhydrated nodes when hydratedData is undefined.
  */
-function validateAndPrepare(schemaAndPolicy, hydratedData, fieldSchema, mapTrees, scheduleHydrationOverride) {
+function validateAndPrepare(schemaAndPolicy, hydratedData, fieldSchema, field) {
+    const cleanup = () => {
+        // Discard the parent dummy field for the nodes before returning so they are unparented and can be inserted.
+        for (const child of field.children) {
+            (0, internal_2.assert)(child instanceof index_js_3.UnhydratedFlexTreeNode, "TODO");
+            child.adoptBy(undefined);
+        }
+    };
     if (hydratedData !== undefined) {
-        // Run `prepareContentForHydration` before walking the tree in `isFieldInSchema`.
+        // Run `chunkForInsertion` before walking the tree in `isFieldInSchema`.
         // This ensures that when `isFieldInSchema` requests identifiers (or any other contextual defaults),
         // they were already creating used the more specific context we have access to from `hydratedData`.
-        prepareContentForHydration(mapTrees, scheduleHydrationOverride ??
-            ((batch, doHydration) => scheduleHydration(batch, hydratedData.checkout.forest, doHydration)), hydratedData);
+        const chunk = chunkForInsertion(hydratedData, field);
         // TODO: AB#45723
         // Now that staged schema rely on this validation, its a bit odd we don't do it for insertion into unhydrated contexts.
         // We can't simply enable it for them however due to contextual default fields which would not have been created yet (see comment above).
         // Specifically at least clone can result in unhydrated trees which can end up violating their stored schema (but not view schema) just using the type safe APIs.
         if (validateSchema === true) {
-            (0, index_js_4.isFieldInSchema)(mapTrees, fieldSchema, schemaAndPolicy, index_js_1.throwOutOfSchema);
+            (0, index_js_4.isFieldInSchema)(field, fieldSchema, schemaAndPolicy, index_js_2.throwOutOfSchema);
         }
-    }
-}
-/**
- * A dummy key value used in {@link LocatedNodesBatch.rootPath} which will be replaced with the actual detached field once it is known.
- */
-const placeholderKey = (0, index_js_2.brand)("placeholder");
-/**
- * Records any {@link TreeNode}s in the given `content` tree and does the necessary bookkeeping to ensure they are synchronized with subsequent reads of the tree.
- * Additionally populates any {@link UnhydratedFlexTreeField.pendingDefault}s using the provided `context`.
- *
- * @remarks If the content tree contains has any associated {@link TreeNode}s, this function must be called just prior to inserting the content into the tree.
- * Specifically, no other content may be inserted into the tree between the invocation of this function and the insertion of `content`.
- * The insertion of `content` must occur or else this function will cause memory leaks.
- *
- * Exported for testing purposes: otherwise should not be used outside this module.
- * @param content - the content subsequence to be inserted, of which might deeply contain {@link TreeNode}s which need to be hydrated.
- * @param forest - the forest the content is being inserted into.
- */
-function prepareContentForHydration(content, scheduler, context) {
-    const batches = [];
-    for (const item of content) {
-        const batch = {
-            rootPath: {
-                parent: undefined,
-                parentField: placeholderKey,
-                parentIndex: 0,
+        const rootsLocations = hydratedData.checkout.editor.buildRoots(chunk.chunk);
+        // console.log(`built nodes: ${JSON.stringify(rootsLocations)}`);
+        const toAttach = hydratedData.detachedField === undefined
+            ? undefined
+            : rootsLocations.map((f) => {
+                (0, internal_2.assert)(hydratedData.detachedField !== undefined, "detachedField should not stop being defined");
+                const rootField = hydratedData.detachedField((0, index_js_1.keyAsDetachedField)(f.field), index_js_2.FieldKinds.optional.identifier);
+                (0, internal_2.assert)(rootField.length === 1, "Expected single root in detached field");
+                return rootField.boxedAt(0) ?? (0, internal_2.fail)("Expected root to be present");
+            });
+        return {
+            toAttach,
+            rootsLocations,
+            finalize: (attached) => {
+                // do edits to move existing content into newly built tree and hydrate nodes as needed
+                attachAndHydratedNodes([...attached], chunk.attaches);
+                cleanup();
             },
-            paths: [],
         };
-        batches.push(batch);
-        walkMapTree(item, batch.rootPath, (p, node) => {
-            batch.paths.push({ path: p, node });
-        }, context);
     }
-    const doHydration = hydrator(batches, context.checkout.forest);
-    scheduler(batches, doHydration);
-}
-exports.prepareContentForHydration = prepareContentForHydration;
-function walkMapTree(root, path, onVisitTreeNode, context) {
-    if (root.parentField.parent.parent !== undefined) {
-        throw new internal_1.UsageError("Attempted to insert a node which is already under a parent. If this is desired, remove the node from its parent before inserting it elsewhere.");
+    else {
+        return { toAttach: [...field.children], finalize: cleanup };
     }
-    const nexts = [];
-    for (let next = [path, root]; next !== undefined; next = nexts.pop()) {
-        const [p, node] = next;
-        if (node !== undefined) {
-            const treeNode = node.treeNode;
-            if (treeNode !== undefined) {
-                onVisitTreeNode(p, treeNode);
-            }
+}
+function chunkForInsertion(context, field) {
+    const x = chunkFieldForInsertion(context, field);
+    const chunks = context.checkout.forest.chunkField((0, index_js_2.cursorForMapTreeField)(x.chunk));
+    const chunk = (0, index_js_4.combineChunks)(chunks);
+    return {
+        chunk,
+        attaches: x.attaches,
+    };
+}
+function chunkFieldForInsertion(context, field) {
+    const chunk = [];
+    const attaches = [];
+    for (const [i, child] of field.children.entries()) {
+        if (child.isHydrated()) {
+            // TODO: error if there is a hydrated parent.
+            attaches.push({
+                index: i,
+                content: child,
+                type: "hydrated",
+            });
         }
-        for (const [key, field] of node.allFieldsLazy) {
-            field.fillPendingDefaults(context);
-            for (const [i, child] of field.children.entries()) {
-                nexts.push([
-                    {
-                        parent: p,
-                        parentField: key,
-                        parentIndex: i,
-                    },
-                    child,
-                ]);
+        else {
+            (0, internal_2.assert)(child instanceof index_js_3.UnhydratedFlexTreeNode, "Expected child to be an UnhydratedFlexTreeNode");
+            const fields = new Map();
+            const childAttaches = new Map();
+            for (const [key, fieldInner] of child.allFieldsLazy) {
+                fieldInner.fillPendingDefaults(context);
+                if (fieldInner.length > 0) {
+                    const inner = chunkFieldForInsertion(context, fieldInner);
+                    fields.set(key, inner.chunk);
+                    childAttaches.set(key, inner.attaches);
+                }
             }
+            // As an optimization, if there are no attach data, skip tracking it.
+            if (childAttaches.size !== 0 || child.treeNode !== undefined) {
+                attaches.push({
+                    index: i,
+                    toHydrate: child.treeNode,
+                    content: childAttaches,
+                    type: "unhydrated",
+                });
+            }
+            chunk.push({ type: child.type, value: child.value, fields });
         }
     }
+    return {
+        chunk,
+        attaches,
+    };
 }
-/**
- * Register events which will hydrate batches of nodes when they are inserted.
- * The next edits to forest must be their insertions, in order, or data corruption can occur.
- * @param locatedNodes - the nodes to register with the forest.
- * Each index in this array expects its content to be added and produce its own `afterRootFieldCreated` event.
- * If array subsequence insertion is optimized to produce a single event, this will not work correctly as is, and will need to be modified to take in a single {@link LocatedNodesBatch}.
- */
-function scheduleHydration(locatedNodes, forest, doHydration) {
-    // Only subscribe to the event if there is at least one TreeNode tree to hydrate - this is not the case when inserting an empty array [].
-    if (locatedNodes.length > 0) {
-        // Creating a new array emits one event per element in the array, so listen to the event once for each element
-        let index = 0;
-        const off = forest.events.on("afterRootFieldCreated", (fieldKey) => {
-            // Indexing is safe here because of the length check above. This assumes the array has not been modified which should be the case.
-            const batch = locatedNodes[index] ?? (0, internal_2.oob)();
-            doHydration(batch, { parent: undefined, parentField: fieldKey, parentIndex: 0 });
-            if (++index === locatedNodes.length) {
-                off();
+function attachAndHydratedNodes(field, attaches) {
+    for (const attach of attaches) {
+        if (attach.type === "hydrated") {
+            // TODO: suppress events for these attaches?
+            if (Array.isArray(field)) {
+                // Move items after attach over by 1.
+                for (let index = field.length; index > attach.index; index--) {
+                    field[index] = field[index - 1] ?? (0, internal_2.fail)("No item at index");
+                }
+                field[attach.index] = attach.content;
             }
-        });
-    }
-}
-/**
- * Implementation of {@link Hydrator}.
- */
-function hydrator(locatedNodes, forest) {
-    return (batch, attachedPath) => {
-        const context = forest.anchors.slots.get(index_js_1.ContextSlot) ?? (0, internal_2.fail)(0xb41 /* missing context */);
-        // Modify paths in batch to point to correct location:
-        (0, internal_2.debugAssert)(() => batch.rootPath.parentField === placeholderKey);
-        batch.rootPath.parentField = attachedPath.parentField;
-        batch.rootPath.parent = attachedPath.parent;
-        batch.rootPath.parentIndex = attachedPath.parentIndex;
-        // To hydrate a TreeNode, it must be associated with a HydratedFlexTreeNode.
-        // Find or create one as necessary.
-        for (const { path, node } of batch.paths) {
-            const anchor = forest.anchors.track(path);
-            const anchorNode = forest.anchors.locate(anchor) ?? (0, internal_2.fail)(0xc7b /* missing anchor */);
-            let flexNode = anchorNode.slots.get(index_js_1.flexTreeSlot);
-            if (flexNode === undefined) {
-                // the flex node must be created
-                const cursor = forest.allocateCursor("getFlexNode");
-                forest.moveCursorToPath(anchorNode, cursor);
-                flexNode = (0, index_js_1.getOrCreateHydratedFlexTreeNode)(context, cursor);
-                cursor.free();
-                (0, index_js_1.assertFlexTreeEntityNotFreed)(flexNode);
+            else if (field.is(index_js_2.FieldKinds.sequence)) {
+                field.editor.insert(attach.index, [attach.content]);
+            }
+            else if (field.is(index_js_2.FieldKinds.optional)) {
+                (0, internal_2.assert)(field.length === 0, "Expected empty field for hydrated attach");
+                field.editor.set(attach.content, false);
+            }
+            else {
+                // TODO: ensure a good user facing error for this case.
+                (0, internal_2.fail)("Invalid field kind for hydrated attach");
             }
-            (0, index_js_3.getKernel)(node).hydrate(flexNode);
-            forest.anchors.forget(anchor);
         }
-    };
+        else {
+            const child = (Array.isArray(field) ? field[attach.index] : field.boxedAt(attach.index)) ??
+                (0, internal_2.fail)("No child at index");
+            if (attach.toHydrate !== undefined) {
+                (0, internal_2.assert)(child.isHydrated(), "Expected child to be hydrated");
+                (0, index_js_3.getKernel)(attach.toHydrate).hydrate(child);
+            }
+            for (const [key, children] of attach.content) {
+                const childField = child.getBoxed(key);
+                attachAndHydratedNodes(childField, children);
+            }
+        }
+    }
 }
 //# sourceMappingURL=prepareForInsertion.js.map

package/dist/simple-tree/prepareForInsertion.js.map

@@ -1 +1 @@
-{"version":3,"file":"prepareForInsertion.js","sourceRoot":"","sources":["../../src/simple-tree/prepareForInsertion.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tSchemaAndPolicy,\n\tIForestSubscription,\n\tUpPath,\n\tFieldKey,\n\tDetachedField,\n\tTreeFieldStoredSchema,\n\tTreeTypeSet,\n} from \"../core/index.js\";\nimport {\n\ttype FlexTreeContext,\n\tgetSchemaAndPolicy,\n\ttype FlexTreeHydratedContextMinimal,\n\tFieldKinds,\n\ttype FlexibleFieldContent,\n\ttype FlexibleNodeContent,\n\tthrowOutOfSchema,\n\tflexTreeSlot,\n\tContextSlot,\n\tgetOrCreateHydratedFlexTreeNode,\n\tassertFlexTreeEntityNotFreed,\n} from \"../feature-libraries/index.js\";\nimport type { ImplicitFieldSchema } from \"./fieldSchema.js\";\nimport {\n\ttype InsertableContent,\n\tunhydratedFlexTreeFromInsertable,\n} from \"./unhydratedFlexTreeFromInsertable.js\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { brand, type Mutable } from \"../util/index.js\";\nimport {\n\tgetKernel,\n\ttype ImplicitAllowedTypes,\n\ttype TreeNode,\n\ttype UnhydratedFlexTreeNode,\n} from \"./core/index.js\";\nimport { debugAssert, fail, oob } from \"@fluidframework/core-utils/internal\";\nimport { isFieldInSchema } from \"../feature-libraries/index.js\";\n\n/**\n * For now, schema validation for inserted content is always enabled.\n * @remarks\n * If this ends up being too much of a performance overhead, AND nothing depends on it (like staged allowed types likely will),\n * this could be changed.\n */\nconst validateSchema = true;\n\n/**\n * Prepare content from a user for insertion into a tree.\n * @remarks\n * This validates and converts the input, and if necessary invokes {@link prepareContentForHydration}.\n *\n * The next edit made to `destinationContext`'s forest must be the creation of a detached field containing this content,\n * (Triggering {@link ForestEvents.afterRootFieldCreated}) otherwise hydration will break.\n */\nexport function prepareForInsertion<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tschema: ImplicitFieldSchema,\n\tdestinationContext: FlexTreeContext,\n\tdestinationSchema: TreeFieldStoredSchema,\n): TIn extends undefined ? undefined : FlexibleNodeContent {\n\treturn prepareForInsertionContextless(\n\t\tdata,\n\t\tschema,\n\t\tgetSchemaAndPolicy(destinationContext),\n\t\tdestinationContext.isHydrated() ? destinationContext : undefined,\n\t\tdestinationSchema,\n\t);\n}\n\n/**\n * {@link prepareForInsertion} but batched for array content.\n * @remarks\n * This is for inserting items into an array, not a inserting a {@link TreeArrayNode} (that would use {@link prepareForInsertion}).\n *\n * The next edits made to `destinationContext`'s forest must be the creation of a detached field.\n * One edit for each item in `data`, in order.\n *\n * @privateRemarks\n * This has to be done as a single operation for all items in data\n * (as opposed to mapping {@link prepareForInsertion} over the array)\n * due to how the eventing in prepareContentForHydration works.\n */\nexport function prepareArrayContentForInsertion(\n\tdata: readonly InsertableContent[],\n\tschema: ImplicitAllowedTypes,\n\tdestinationContext: FlexTreeContext,\n\tdestinationSchema: TreeTypeSet,\n): FlexibleFieldContent {\n\tconst mapTrees: UnhydratedFlexTreeNode[] = data.map((item) =>\n\t\tunhydratedFlexTreeFromInsertable(item, schema),\n\t);\n\n\tvalidateAndPrepare(\n\t\tgetSchemaAndPolicy(destinationContext),\n\t\tdestinationContext.isHydrated() ? destinationContext : undefined,\n\t\t{\n\t\t\tkind: FieldKinds.sequence.identifier,\n\t\t\ttypes: destinationSchema,\n\t\t\tpersistedMetadata: undefined,\n\t\t},\n\t\tmapTrees,\n\t);\n\n\treturn mapTrees;\n}\n\n/**\n * Split out from {@link prepareForInsertion} as to allow use without a context.\n *\n * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.\n * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.\n *\n * @remarks\n * Adding this entry point is a workaround for initialize not currently having a context.\n */\nexport function prepareForInsertionContextless<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tschema: ImplicitFieldSchema,\n\tschemaAndPolicy: SchemaAndPolicy,\n\thydratedData: FlexTreeHydratedContextMinimal | undefined,\n\tdestinationSchema: TreeFieldStoredSchema,\n\tscheduleHydrationOverride?: HydrationScheduler,\n): TIn extends undefined ? undefined : FlexibleNodeContent {\n\tconst mapTree = unhydratedFlexTreeFromInsertable(data, schema);\n\n\tconst contentArray = mapTree === undefined ? [] : [mapTree];\n\tvalidateAndPrepare(\n\t\tschemaAndPolicy,\n\t\thydratedData,\n\t\tdestinationSchema,\n\t\tcontentArray,\n\t\tscheduleHydrationOverride,\n\t);\n\n\treturn mapTree;\n}\n\n/**\n * If hydrating, do a final validation against the schema and prepare the content for hydration.\n *\n * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.\n * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.\n */\nfunction validateAndPrepare(\n\tschemaAndPolicy: SchemaAndPolicy,\n\thydratedData: FlexTreeHydratedContextMinimal | undefined,\n\tfieldSchema: TreeFieldStoredSchema,\n\tmapTrees: readonly UnhydratedFlexTreeNode[],\n\tscheduleHydrationOverride?: HydrationScheduler,\n): void {\n\tif (hydratedData !== undefined) {\n\t\t// Run `prepareContentForHydration` before walking the tree in `isFieldInSchema`.\n\t\t// This ensures that when `isFieldInSchema` requests identifiers (or any other contextual defaults),\n\t\t// they were already creating used the more specific context we have access to from `hydratedData`.\n\t\tprepareContentForHydration(\n\t\t\tmapTrees,\n\t\t\tscheduleHydrationOverride ??\n\t\t\t\t((batch, doHydration) =>\n\t\t\t\t\tscheduleHydration(batch, hydratedData.checkout.forest, doHydration)),\n\t\t\thydratedData,\n\t\t);\n\t\t// TODO: AB#45723\n\t\t// Now that staged schema rely on this validation, its a bit odd we don't do it for insertion into unhydrated contexts.\n\t\t// We can't simply enable it for them however due to contextual default fields which would not have been created yet (see comment above).\n\t\t// Specifically at least clone can result in unhydrated trees which can end up violating their stored schema (but not view schema) just using the type safe APIs.\n\t\tif (validateSchema === true) {\n\t\t\tisFieldInSchema(mapTrees, fieldSchema, schemaAndPolicy, throwOutOfSchema);\n\t\t}\n\t}\n}\n\n/**\n * The path from the included node to the root of the content tree it was inserted as part of.\n */\ninterface RelativeNodePath {\n\treadonly path: UpPath;\n\treadonly node: TreeNode;\n}\n\n/**\n * {@link RelativeNodePath}s for every {@link TreeNode} in the content tree inserted as an atomic operation.\n */\ninterface LocatedNodesBatch {\n\t/**\n\t * UpPath shared by all {@link RelativeNodePath}s in this batch corresponding to the root of the inserted content.\n\t */\n\treadonly rootPath: Mutable<UpPath>;\n\treadonly paths: RelativeNodePath[];\n}\n\n/**\n * A dummy key value used in {@link LocatedNodesBatch.rootPath} which will be replaced with the actual detached field once it is known.\n */\nconst placeholderKey: DetachedField & FieldKey = brand(\"placeholder\" as const);\n\n/**\n * Records any {@link TreeNode}s in the given `content` tree and does the necessary bookkeeping to ensure they are synchronized with subsequent reads of the tree.\n * Additionally populates any {@link UnhydratedFlexTreeField.pendingDefault}s using the provided `context`.\n *\n * @remarks If the content tree contains has any associated {@link TreeNode}s, this function must be called just prior to inserting the content into the tree.\n * Specifically, no other content may be inserted into the tree between the invocation of this function and the insertion of `content`.\n * The insertion of `content` must occur or else this function will cause memory leaks.\n *\n * Exported for testing purposes: otherwise should not be used outside this module.\n * @param content - the content subsequence to be inserted, of which might deeply contain {@link TreeNode}s which need to be hydrated.\n * @param forest - the forest the content is being inserted into.\n */\nexport function prepareContentForHydration(\n\tcontent: readonly UnhydratedFlexTreeNode[],\n\tscheduler: HydrationScheduler,\n\tcontext: FlexTreeHydratedContextMinimal,\n): void {\n\tconst batches: LocatedNodesBatch[] = [];\n\tfor (const item of content) {\n\t\tconst batch: LocatedNodesBatch = {\n\t\t\trootPath: {\n\t\t\t\tparent: undefined,\n\t\t\t\tparentField: placeholderKey,\n\t\t\t\tparentIndex: 0,\n\t\t\t},\n\t\t\tpaths: [],\n\t\t};\n\t\tbatches.push(batch);\n\t\twalkMapTree(\n\t\t\titem,\n\t\t\tbatch.rootPath,\n\t\t\t(p, node) => {\n\t\t\t\tbatch.paths.push({ path: p, node });\n\t\t\t},\n\t\t\tcontext,\n\t\t);\n\t}\n\n\tconst doHydration = hydrator(batches, context.checkout.forest);\n\tscheduler(batches, doHydration);\n}\n\nfunction walkMapTree(\n\troot: UnhydratedFlexTreeNode,\n\tpath: UpPath,\n\tonVisitTreeNode: (path: UpPath, treeNode: TreeNode) => void,\n\tcontext: FlexTreeHydratedContextMinimal,\n): void {\n\tif (root.parentField.parent.parent !== undefined) {\n\t\tthrow new UsageError(\n\t\t\t\"Attempted to insert a node which is already under a parent. If this is desired, remove the node from its parent before inserting it elsewhere.\",\n\t\t);\n\t}\n\n\ttype Next = [path: UpPath, tree: UnhydratedFlexTreeNode];\n\tconst nexts: Next[] = [];\n\tfor (let next: Next | undefined = [path, root]; next !== undefined; next = nexts.pop()) {\n\t\tconst [p, node] = next;\n\t\tif (node !== undefined) {\n\t\t\tconst treeNode = node.treeNode;\n\t\t\tif (treeNode !== undefined) {\n\t\t\t\tonVisitTreeNode(p, treeNode);\n\t\t\t}\n\t\t}\n\n\t\tfor (const [key, field] of node.allFieldsLazy) {\n\t\t\tfield.fillPendingDefaults(context);\n\t\t\tfor (const [i, child] of field.children.entries()) {\n\t\t\t\tnexts.push([\n\t\t\t\t\t{\n\t\t\t\t\t\tparent: p,\n\t\t\t\t\t\tparentField: key,\n\t\t\t\t\t\tparentIndex: i,\n\t\t\t\t\t},\n\t\t\t\t\tchild,\n\t\t\t\t]);\n\t\t\t}\n\t\t}\n\t}\n}\n\n/**\n * A function which can schedule hydration of batches of nodes to occur at a later time (which must be after they have been inserted into the tree).\n */\ntype HydrationScheduler = (\n\tlocatedNodes: readonly LocatedNodesBatch[],\n\t/**\n\t * Does the actual hydration. Should be called for each index in `locatedNodes` once the corresponding content has been inserted into the tree.\n\t */\n\tdoHydration: Hydrator,\n) => void;\n\n/**\n * Does the actual hydration.\n * The provided `attachPath` is the path the content is currently under (where it was attached in the tree).\n */\ntype Hydrator = (batch: LocatedNodesBatch, attachPath: UpPath) => void;\n\n/**\n * Register events which will hydrate batches of nodes when they are inserted.\n * The next edits to forest must be their insertions, in order, or data corruption can occur.\n * @param locatedNodes - the nodes to register with the forest.\n * Each index in this array expects its content to be added and produce its own `afterRootFieldCreated` event.\n * If array subsequence insertion is optimized to produce a single event, this will not work correctly as is, and will need to be modified to take in a single {@link LocatedNodesBatch}.\n */\nfunction scheduleHydration(\n\tlocatedNodes: readonly LocatedNodesBatch[],\n\tforest: IForestSubscription,\n\tdoHydration: Hydrator,\n): void {\n\t// Only subscribe to the event if there is at least one TreeNode tree to hydrate - this is not the case when inserting an empty array [].\n\tif (locatedNodes.length > 0) {\n\t\t// Creating a new array emits one event per element in the array, so listen to the event once for each element\n\t\tlet index = 0;\n\t\tconst off = forest.events.on(\"afterRootFieldCreated\", (fieldKey) => {\n\t\t\t// Indexing is safe here because of the length check above. This assumes the array has not been modified which should be the case.\n\t\t\tconst batch = locatedNodes[index] ?? oob();\n\t\t\tdoHydration(batch, { parent: undefined, parentField: fieldKey, parentIndex: 0 });\n\t\t\tif (++index === locatedNodes.length) {\n\t\t\t\toff();\n\t\t\t}\n\t\t});\n\t}\n}\n\n/**\n * Implementation of {@link Hydrator}.\n */\nfunction hydrator(\n\tlocatedNodes: readonly LocatedNodesBatch[],\n\tforest: IForestSubscription,\n): (batch: LocatedNodesBatch, attachedPath: UpPath) => void {\n\treturn (batch: LocatedNodesBatch, attachedPath: UpPath) => {\n\t\tconst context = forest.anchors.slots.get(ContextSlot) ?? fail(0xb41 /* missing context */);\n\n\t\t// Modify paths in batch to point to correct location:\n\t\tdebugAssert(() => batch.rootPath.parentField === placeholderKey);\n\t\tbatch.rootPath.parentField = attachedPath.parentField;\n\t\tbatch.rootPath.parent = attachedPath.parent;\n\t\tbatch.rootPath.parentIndex = attachedPath.parentIndex;\n\n\t\t// To hydrate a TreeNode, it must be associated with a HydratedFlexTreeNode.\n\t\t// Find or create one as necessary.\n\t\tfor (const { path, node } of batch.paths) {\n\t\t\tconst anchor = forest.anchors.track(path);\n\t\t\tconst anchorNode = forest.anchors.locate(anchor) ?? fail(0xc7b /* missing anchor */);\n\n\t\t\tlet flexNode = anchorNode.slots.get(flexTreeSlot);\n\t\t\tif (flexNode === undefined) {\n\t\t\t\t// the flex node must be created\n\t\t\t\tconst cursor = forest.allocateCursor(\"getFlexNode\");\n\t\t\t\tforest.moveCursorToPath(anchorNode, cursor);\n\n\t\t\t\tflexNode = getOrCreateHydratedFlexTreeNode(context, cursor);\n\t\t\t\tcursor.free();\n\t\t\t\tassertFlexTreeEntityNotFreed(flexNode);\n\t\t\t}\n\n\t\t\tgetKernel(node).hydrate(flexNode);\n\t\t\tforest.anchors.forget(anchor);\n\t\t}\n\t};\n}\n"]}
+{"version":3,"file":"prepareForInsertion.js","sourceRoot":"","sources":["../../src/simple-tree/prepareForInsertion.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport type {\n\tSchemaAndPolicy,\n\tFieldKey,\n\tTreeFieldStoredSchema,\n\tTreeTypeSet,\n} from \"../core/index.js\";\nimport { dummyRoot, keyAsDetachedField, rootFieldKey } from \"../core/index.js\";\nimport {\n\ttype FlexTreeContext,\n\tgetSchemaAndPolicy,\n\ttype FlexTreeHydratedContextMinimal,\n\tFieldKinds,\n\ttype FlexibleFieldContent,\n\ttype FlexibleNodeContent,\n\ttype FlexTreeNode,\n\tcursorForMapTreeField,\n\tthrowOutOfSchema,\n\ttype TreeChunk,\n\ttype HydratedFlexTreeNode,\n\ttype MinimalMapTreeNodeView,\n\ttype FlexTreeField,\n\ttype DetachedRootsLocation,\n} from \"../feature-libraries/index.js\";\nimport { normalizeFieldSchema, type ImplicitFieldSchema } from \"./fieldSchema.js\";\nimport {\n\ttype InsertableContent,\n\tflexTreeFromInsertable,\n} from \"./unhydratedFlexTreeFromInsertable.js\";\nimport {\n\tcreateField,\n\tgetInnerNode,\n\tgetKernel,\n\tisTreeNode,\n\tUnhydratedFlexTreeNode,\n\ttype ImplicitAllowedTypes,\n\ttype TreeNode,\n\ttype UnhydratedFlexTreeField,\n} from \"./core/index.js\";\nimport { assert, fail } from \"@fluidframework/core-utils/internal\";\nimport { combineChunks, isFieldInSchema } from \"../feature-libraries/index.js\";\nimport { getUnhydratedContext } from \"./createContext.js\";\nimport { convertField } from \"./toStoredSchema.js\";\nimport type { SchemaType, SimpleFieldSchema } from \"./simpleSchema.js\";\n\n/**\n * For now, schema validation for inserted content is always enabled.\n * @remarks\n * If this ends up being too much of a performance overhead, AND nothing depends on it (like staged allowed types likely will),\n * this could be changed.\n */\nconst validateSchema = true;\n\n// IDEA:\n// Have prepareForInsertion return a TreeChunk, and a function which should be called after its insertion with the path to its location (as Inner node?)\n\nfunction isHydrated(node: InsertableContent): boolean {\n\treturn isTreeNode(node) && getKernel(node).isHydrated();\n}\n\nfunction assertIsDetachedFlexTreeNode(node: FlexTreeNode): void {\n\tif (\n\t\tnode.parentField.parent.parent !== undefined ||\n\t\tnode.parentField.parent.key === rootFieldKey\n\t) {\n\t\tthrow new UsageError(\n\t\t\t\"Can only attach a detached node (i.e., a root with TreeStatus.Removed status)\",\n\t\t);\n\t}\n}\n\n/**\n * Prepare content from a user for insertion into a tree.\n * @remarks\n * This validates and converts the input, and if necessary invokes {@link prepareContentForHydration}.\n *\n * The next edit made to `destinationContext`'s forest must be the creation of a detached field containing this content,\n * (Triggering {@link ForestEvents.afterRootFieldCreated}) otherwise hydration will break.\n */\nexport function prepareForInsertion<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tschema: ImplicitFieldSchema,\n\tdestinationContext: FlexTreeContext,\n\tdestinationSchema: TreeFieldStoredSchema,\n): TIn extends undefined ? undefined : FlexibleNodeContent {\n\tif (data !== undefined && isHydrated(data)) {\n\t\tconst treeNode = getInnerNode(data as TreeNode);\n\t\tassertIsDetachedFlexTreeNode(treeNode);\n\t\treturn treeNode as TIn extends undefined ? undefined : FlexibleNodeContent;\n\t}\n\n\tconst content = prepareForInsertionContextlessInternal(\n\t\tdata,\n\t\tschema,\n\t\tgetSchemaAndPolicy(destinationContext),\n\t\tdestinationContext.isHydrated() ? destinationContext : undefined,\n\t\tdestinationSchema,\n\t);\n\n\tassert(content.toAttach !== undefined, \"Expected toAttach to be defined\");\n\tassert(content.toAttach.length < 2, \"Expected toAttach to be a single element on none\");\n\n\t// TODO: when supporting back compat to not edit detached fields, caller will have to finalize after attaching to in document location.\n\tcontent.finalize(content.toAttach);\n\treturn (\n\t\tcontent.toAttach.length === 0 ? undefined : content.toAttach[0]\n\t) as TIn extends undefined ? undefined : FlexibleNodeContent;\n}\n\n/**\n * {@link prepareForInsertion} but batched for array content.\n * @remarks\n * This is for inserting items into an array, not a inserting a {@link TreeArrayNode} (that would use {@link prepareForInsertion}).\n *\n * The next edits made to `destinationContext`'s forest must be the creation of a detached field.\n * One edit for each item in `data`, in order.\n *\n * @privateRemarks\n * This has to be done as a single operation for all items in data\n * (as opposed to mapping {@link prepareForInsertion} over the array)\n * due to how the eventing in prepareContentForHydration works.\n */\nexport function prepareArrayContentForInsertion(\n\tdata: readonly InsertableContent[],\n\tschema: ImplicitAllowedTypes,\n\tdestinationContext: FlexTreeContext,\n\tdestinationSchema: TreeTypeSet,\n): FlexibleFieldContent {\n\tconst hasHydratedData = data.find(isHydrated) !== undefined;\n\tif (hasHydratedData) {\n\t\tconst hasUnhydratedData = data.find((item) => !isHydrated(item)) !== undefined;\n\t\tif (hasUnhydratedData) {\n\t\t\tthrow new UsageError(\"Mixed hydrated and unhydrated data not supported\");\n\t\t}\n\t\tconst treeNodes = data.map((item) => getInnerNode(item as TreeNode));\n\t\tfor (const node of treeNodes) {\n\t\t\tassertIsDetachedFlexTreeNode(node);\n\t\t}\n\t\treturn treeNodes;\n\t}\n\n\tconst mapTrees: FlexTreeNode[] = data.map((item) => flexTreeFromInsertable(item, schema));\n\n\tconst fieldSchema = convertField(\n\t\tnormalizeFieldSchema(schema) as unknown as SimpleFieldSchema<SchemaType.Stored>,\n\t\t// permissiveStoredSchemaGenerationOptions,\n\t);\n\n\tconst normalizedFieldSchema = normalizeFieldSchema(schema);\n\tconst field = createField(\n\t\tgetUnhydratedContext(normalizedFieldSchema).flexContext,\n\t\tfieldSchema.kind,\n\t\tdummyRoot,\n\t\tmapTrees,\n\t);\n\n\tconst content = validateAndPrepare(\n\t\tgetSchemaAndPolicy(destinationContext),\n\t\tdestinationContext.isHydrated() ? destinationContext : undefined,\n\t\t{\n\t\t\tkind: FieldKinds.sequence.identifier,\n\t\t\ttypes: destinationSchema,\n\t\t\tpersistedMetadata: undefined,\n\t\t},\n\t\tfield,\n\t);\n\n\tassert(content.toAttach !== undefined, \"Expected toAttach to be defined\");\n\n\t// TODO: when supporting back compat to not edit detached fields, caller will have to finalize after attaching to in document location.\n\tcontent.finalize(content.toAttach);\n\treturn content.toAttach;\n}\n\nexport interface PreparedContent {\n\t/**\n\t * New content which to be attached. Rooted in detached fields.\n\t * @remarks\n\t * When destination is a hydrated context, this will contain hydrated flex tree nodes.\n\t * The corresponding TreeNodes will not yet be hydrated, and some subtrees may be in separate detached fields.\n\t *\n\t * TODO: Eventually, this should be a single detached field, not an array of nodes each in their own detached field.\n\t */\n\treadonly toAttach?: readonly FlexTreeNode[];\n\n\t/**\n\t * Location of toAttach.\n\t * @remarks\n\t * This is redundant with `toAttach.key` but in a different format/type.\n\t * Only provided for hydrated destinations.\n\t */\n\treadonly rootsLocations?: DetachedRootsLocation;\n\n\t/**\n\t * Finalizes the prepared content. Moves in missing subtrees from detached fields, and hydrates TreeNodes as needed.\n\t *\n\t * @param attached - The nodes that were attached to the tree.\n\t *\n\t * @remarks\n\t * Call this exactly once, after `toAttach` has been attached to its final location.\n\t * There must be no app facing events between creation of this `PreparedContent` and its finalization since during this time TreeNodes may be in an invalid state (inner node hydrated, but TreeNode not).\n\t *\n\t * The implementation of this must not assume the context provided to `prepareForInsertion*` is still valid.\n\t */\n\treadonly finalize: (attached: readonly FlexTreeNode[]) => void;\n}\n\n/**\n * This exists to handle the required root initialize case where the flex tree nodes get invalidated by a schema change and thus new node instances need to be provided.\n */\nexport interface PreparedContentInitialize extends PreparedContent {\n\t/**\n\t * {@inheritDoc PreparedContent.rootIds}\n\t */\n\treadonly rootsLocations: DetachedRootsLocation;\n}\n\n/**\n * This exists to handle the required root initialize case where the flex tree nodes get invalidated by a schema change and thus new node instances need to be provided.\n */\nexport interface PreparedContentRegular extends PreparedContent {\n\t/**\n\t * {@inheritDoc PreparedContent.toAttach}\n\t */\n\treadonly toAttach: readonly FlexTreeNode[];\n\n\t/**\n\t * {@link PreparedContent.finalize} but without `attached` parameter: assumes `toAttach` is the same is still valid and uses that.\n\t */\n\treadonly finalize: () => void;\n}\n\n/**\n * Split out from {@link prepareForInsertion} as to allow use without a context.\n *\n * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.\n * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.\n *\n * @remarks\n * Adding this entry point is a workaround for initialize not currently having a context.\n */\nexport function prepareForInsertionContextless<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tschema: ImplicitFieldSchema,\n\tschemaAndPolicy: SchemaAndPolicy,\n\thydratedData: FlexTreeHydratedContextMinimal,\n\tdestinationSchema: TreeFieldStoredSchema,\n): PreparedContentInitialize {\n\tconst final = prepareForInsertionContextlessInternal(\n\t\tdata,\n\t\tschema,\n\t\tschemaAndPolicy,\n\t\thydratedData,\n\t\tdestinationSchema,\n\t);\n\tassert(final.rootsLocations !== undefined, \"Expected rootIds to be defined\");\n\tassert(\n\t\tfinal.rootsLocations.length <= 1,\n\t\t\"Expected at most one node to be returned from prepareForInsertionContextless\",\n\t);\n\n\t// For some reason TypeScript can't figure out that final.rootsLocations is defined unless we handle is separately.\n\treturn { ...final, rootsLocations: final.rootsLocations };\n}\n\n/**\n * Split out from {@link prepareForInsertion} as to allow use without a context.\n *\n * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.\n * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.\n */\nfunction prepareForInsertionContextlessInternal<TIn extends InsertableContent | undefined>(\n\tdata: TIn,\n\tschema: ImplicitFieldSchema,\n\tschemaAndPolicy: SchemaAndPolicy,\n\thydratedData: FlexTreeHydratedContextMinimal | undefined,\n\tdestinationSchema: TreeFieldStoredSchema,\n): PreparedContent {\n\tconst mapTree = flexTreeFromInsertable(data, schema);\n\n\tconst contentArray = mapTree === undefined ? [] : [mapTree];\n\tconst normalizedFieldSchema = normalizeFieldSchema(schema);\n\tconst fieldSchema = convertField(\n\t\tnormalizedFieldSchema as unknown as SimpleFieldSchema<SchemaType.Stored>,\n\t\t// permissiveStoredSchemaGenerationOptions,\n\t);\n\n\tconst field = createField(\n\t\tgetUnhydratedContext(normalizedFieldSchema).flexContext,\n\t\tfieldSchema.kind,\n\t\tdummyRoot,\n\t\tcontentArray,\n\t);\n\n\treturn validateAndPrepare(schemaAndPolicy, hydratedData, destinationSchema, field);\n}\n\n/**\n * If hydrating, do a final validation against the schema and prepare the content for hydration.\n *\n * @param hydratedData - If specified, the `mapTrees` will be prepared for hydration into this context.\n * `undefined` when `mapTrees` are being inserted into an {@link Unhydrated} tree.\n *\n * TODO: return nodes flex tree nodes to insert (might be newly hydrated) or reused unhydrated nodes when hydratedData is undefined.\n */\nfunction validateAndPrepare(\n\tschemaAndPolicy: SchemaAndPolicy,\n\thydratedData: FlexTreeHydratedContextMinimal | undefined,\n\tfieldSchema: TreeFieldStoredSchema,\n\tfield: UnhydratedFlexTreeField,\n): PreparedContent {\n\tconst cleanup = (): void => {\n\t\t// Discard the parent dummy field for the nodes before returning so they are unparented and can be inserted.\n\t\tfor (const child of field.children) {\n\t\t\tassert(child instanceof UnhydratedFlexTreeNode, \"TODO\");\n\t\t\tchild.adoptBy(undefined);\n\t\t}\n\t};\n\n\tif (hydratedData !== undefined) {\n\t\t// Run `chunkForInsertion` before walking the tree in `isFieldInSchema`.\n\t\t// This ensures that when `isFieldInSchema` requests identifiers (or any other contextual defaults),\n\t\t// they were already creating used the more specific context we have access to from `hydratedData`.\n\t\tconst chunk = chunkForInsertion(hydratedData, field);\n\t\t// TODO: AB#45723\n\t\t// Now that staged schema rely on this validation, its a bit odd we don't do it for insertion into unhydrated contexts.\n\t\t// We can't simply enable it for them however due to contextual default fields which would not have been created yet (see comment above).\n\t\t// Specifically at least clone can result in unhydrated trees which can end up violating their stored schema (but not view schema) just using the type safe APIs.\n\t\tif (validateSchema === true) {\n\t\t\tisFieldInSchema(field, fieldSchema, schemaAndPolicy, throwOutOfSchema);\n\t\t}\n\n\t\tconst rootsLocations = hydratedData.checkout.editor.buildRoots(chunk.chunk);\n\t\t// console.log(`built nodes: ${JSON.stringify(rootsLocations)}`);\n\n\t\tconst toAttach =\n\t\t\thydratedData.detachedField === undefined\n\t\t\t\t? undefined\n\t\t\t\t: rootsLocations.map((f) => {\n\t\t\t\t\t\tassert(\n\t\t\t\t\t\t\thydratedData.detachedField !== undefined,\n\t\t\t\t\t\t\t\"detachedField should not stop being defined\",\n\t\t\t\t\t\t);\n\t\t\t\t\t\tconst rootField = hydratedData.detachedField(\n\t\t\t\t\t\t\tkeyAsDetachedField(f.field),\n\t\t\t\t\t\t\tFieldKinds.optional.identifier,\n\t\t\t\t\t\t);\n\t\t\t\t\t\tassert(rootField.length === 1, \"Expected single root in detached field\");\n\t\t\t\t\t\treturn rootField.boxedAt(0) ?? fail(\"Expected root to be present\");\n\t\t\t\t\t});\n\n\t\treturn {\n\t\t\ttoAttach,\n\t\t\trootsLocations,\n\t\t\tfinalize: (attached: readonly FlexTreeNode[]) => {\n\t\t\t\t// do edits to move existing content into newly built tree and hydrate nodes as needed\n\t\t\t\tattachAndHydratedNodes([...attached], chunk.attaches);\n\t\t\t\tcleanup();\n\t\t\t},\n\t\t};\n\t} else {\n\t\treturn { toAttach: [...field.children], finalize: cleanup };\n\t}\n}\n\n/**\n * A field to insert, which can contain some attach operations for already hydrated content.\n */\ninterface ChunkedInsertion<TChunk = TreeChunk> {\n\treadonly chunk: TChunk;\n\treadonly attaches: readonly SubFieldAttach[];\n}\n\ntype SubFieldAttach = SubFieldAttachHydrated | SubFieldAttachUnhydrated;\n\n/**\n * A an unhydrated subtree is being attached to a hydrated context and it\n * contains content which need fixing up after the initial creation in the hydrated context.\n *\n */\ninterface SubFieldAttachUnhydrated {\n\treadonly type: \"unhydrated\";\n\treadonly index: number;\n\t/**\n\t * If provided a preexisting TreeNode which was unhydrated was attached.\n\t *\n\t * It will require hydration to associate the existing TreeNode with the new hydrated flex-tree node.\n\t */\n\treadonly toHydrate: TreeNode | undefined;\n\treadonly content: Map<FieldKey, readonly SubFieldAttach[]>;\n}\n\n/**\n * A preexisting TreeNode which was already hydrated was attached.\n *\n * It will require an attach to move its existing flex-tree node to the new location.\n */\ninterface SubFieldAttachHydrated {\n\treadonly type: \"hydrated\";\n\treadonly index: number;\n\treadonly content: HydratedFlexTreeNode;\n}\n\nfunction chunkForInsertion(\n\tcontext: FlexTreeHydratedContextMinimal,\n\tfield: UnhydratedFlexTreeField,\n): ChunkedInsertion {\n\tconst x = chunkFieldForInsertion(context, field);\n\tconst chunks = context.checkout.forest.chunkField(cursorForMapTreeField(x.chunk));\n\tconst chunk = combineChunks(chunks);\n\treturn {\n\t\tchunk,\n\t\tattaches: x.attaches,\n\t};\n}\n\nfunction chunkFieldForInsertion(\n\tcontext: FlexTreeHydratedContextMinimal,\n\tfield: UnhydratedFlexTreeField,\n): ChunkedInsertion<readonly MinimalMapTreeNodeView[]> {\n\tconst chunk: MinimalMapTreeNodeView[] = [];\n\tconst attaches: SubFieldAttach[] = [];\n\tfor (const [i, child] of field.children.entries()) {\n\t\tif (child.isHydrated()) {\n\t\t\t// TODO: error if there is a hydrated parent.\n\t\t\tattaches.push({\n\t\t\t\tindex: i,\n\t\t\t\tcontent: child,\n\t\t\t\ttype: \"hydrated\",\n\t\t\t});\n\t\t} else {\n\t\t\tassert(\n\t\t\t\tchild instanceof UnhydratedFlexTreeNode,\n\t\t\t\t\"Expected child to be an UnhydratedFlexTreeNode\",\n\t\t\t);\n\t\t\tconst fields: Map<FieldKey, readonly MinimalMapTreeNodeView[]> = new Map();\n\t\t\tconst childAttaches: Map<FieldKey, readonly SubFieldAttach[]> = new Map();\n\t\t\tfor (const [key, fieldInner] of child.allFieldsLazy) {\n\t\t\t\tfieldInner.fillPendingDefaults(context);\n\t\t\t\tif (fieldInner.length > 0) {\n\t\t\t\t\tconst inner = chunkFieldForInsertion(context, fieldInner);\n\t\t\t\t\tfields.set(key, inner.chunk);\n\t\t\t\t\tchildAttaches.set(key, inner.attaches);\n\t\t\t\t}\n\t\t\t}\n\t\t\t// As an optimization, if there are no attach data, skip tracking it.\n\t\t\tif (childAttaches.size !== 0 || child.treeNode !== undefined) {\n\t\t\t\tattaches.push({\n\t\t\t\t\tindex: i,\n\t\t\t\t\ttoHydrate: child.treeNode,\n\t\t\t\t\tcontent: childAttaches,\n\t\t\t\t\ttype: \"unhydrated\",\n\t\t\t\t});\n\t\t\t}\n\t\t\tchunk.push({ type: child.type, value: child.value, fields });\n\t\t}\n\t}\n\treturn {\n\t\tchunk,\n\t\tattaches,\n\t};\n}\n\nfunction attachAndHydratedNodes(\n\tfield: FlexTreeField | FlexTreeNode[],\n\tattaches: readonly SubFieldAttach[],\n): void {\n\tfor (const attach of attaches) {\n\t\tif (attach.type === \"hydrated\") {\n\t\t\t// TODO: suppress events for these attaches?\n\n\t\t\tif (Array.isArray(field)) {\n\t\t\t\t// Move items after attach over by 1.\n\t\t\t\tfor (let index = field.length; index > attach.index; index--) {\n\t\t\t\t\tfield[index] = field[index - 1] ?? fail(\"No item at index\");\n\t\t\t\t}\n\t\t\t\tfield[attach.index] = attach.content;\n\t\t\t} else if (field.is(FieldKinds.sequence)) {\n\t\t\t\tfield.editor.insert(attach.index, [attach.content]);\n\t\t\t} else if (field.is(FieldKinds.optional)) {\n\t\t\t\tassert(field.length === 0, \"Expected empty field for hydrated attach\");\n\t\t\t\tfield.editor.set(attach.content, false);\n\t\t\t} else {\n\t\t\t\t// TODO: ensure a good user facing error for this case.\n\t\t\t\tfail(\"Invalid field kind for hydrated attach\");\n\t\t\t}\n\t\t} else {\n\t\t\tconst child =\n\t\t\t\t(Array.isArray(field) ? field[attach.index] : field.boxedAt(attach.index)) ??\n\t\t\t\tfail(\"No child at index\");\n\t\t\tif (attach.toHydrate !== undefined) {\n\t\t\t\tassert(child.isHydrated(), \"Expected child to be hydrated\");\n\t\t\t\tgetKernel(attach.toHydrate).hydrate(child);\n\t\t\t}\n\t\t\tfor (const [key, children] of attach.content) {\n\t\t\t\tconst childField = child.getBoxed(key);\n\t\t\t\tattachAndHydratedNodes(childField, children);\n\t\t\t}\n\t\t}\n\t}\n}\n"]}