@fluidframework/tree 2.80.0 → 2.81.0-374083

package/lib/simple-tree/prepareForInsertion.d.ts

@@ -2,12 +2,11 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import type { SchemaAndPolicy, UpPath, TreeFieldStoredSchema, TreeTypeSet } from "../core/index.js";
-import { type FlexTreeContext, type FlexTreeHydratedContextMinimal, type FlexibleFieldContent, type FlexibleNodeContent } from "../feature-libraries/index.js";
-import type { ImplicitFieldSchema } from "./fieldSchema.js";
+import type { SchemaAndPolicy, TreeFieldStoredSchema, TreeTypeSet } from "../core/index.js";
+import { type FlexTreeContext, type FlexTreeHydratedContextMinimal, type FlexibleFieldContent, type FlexibleNodeContent, type FlexTreeNode, type DetachedRootsLocation } from "../feature-libraries/index.js";
+import { type ImplicitFieldSchema } from "./fieldSchema.js";
 import { type InsertableContent } from "./unhydratedFlexTreeFromInsertable.js";
-import { type Mutable } from "../util/index.js";
-import { type ImplicitAllowedTypes, type TreeNode, type UnhydratedFlexTreeNode } from "./core/index.js";
+import { type ImplicitAllowedTypes } from "./core/index.js";
 /**
  * Prepare content from a user for insertion into a tree.
  * @remarks
@@ -31,58 +30,66 @@ export declare function prepareForInsertion<TIn extends InsertableContent | unde
  * due to how the eventing in prepareContentForHydration works.
  */
 export declare function prepareArrayContentForInsertion(data: readonly InsertableContent[], schema: ImplicitAllowedTypes, destinationContext: FlexTreeContext, destinationSchema: TreeTypeSet): FlexibleFieldContent;
+export interface PreparedContent {
+    /**
+     * New content which to be attached. Rooted in detached fields.
+     * @remarks
+     * When destination is a hydrated context, this will contain hydrated flex tree nodes.
+     * The corresponding TreeNodes will not yet be hydrated, and some subtrees may be in separate detached fields.
+     *
+     * TODO: Eventually, this should be a single detached field, not an array of nodes each in their own detached field.
+     */
+    readonly toAttach?: readonly FlexTreeNode[];
+    /**
+     * Location of toAttach.
+     * @remarks
+     * This is redundant with `toAttach.key` but in a different format/type.
+     * Only provided for hydrated destinations.
+     */
+    readonly rootsLocations?: DetachedRootsLocation;
+    /**
+     * Finalizes the prepared content. Moves in missing subtrees from detached fields, and hydrates TreeNodes as needed.
+     *
+     * @param attached - The nodes that were attached to the tree.
+     *
+     * @remarks
+     * Call this exactly once, after `toAttach` has been attached to its final location.
+     * 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).
+     *
+     * The implementation of this must not assume the context provided to `prepareForInsertion*` is still valid.
+     */
+    readonly finalize: (attached: readonly FlexTreeNode[]) => void;
+}
 /**
- * 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.
- *
- * @remarks
- * Adding this entry point is a workaround for initialize not currently having a context.
- */
-export declare function prepareForInsertionContextless<TIn extends InsertableContent | undefined>(data: TIn, schema: ImplicitFieldSchema, schemaAndPolicy: SchemaAndPolicy, hydratedData: FlexTreeHydratedContextMinimal | undefined, destinationSchema: TreeFieldStoredSchema, scheduleHydrationOverride?: HydrationScheduler): TIn extends undefined ? undefined : FlexibleNodeContent;
-/**
- * The path from the included node to the root of the content tree it was inserted as part of.
+ * 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.
  */
-interface RelativeNodePath {
-    readonly path: UpPath;
-    readonly node: TreeNode;
+export interface PreparedContentInitialize extends PreparedContent {
+    /**
+     * {@inheritDoc PreparedContent.rootIds}
+     */
+    readonly rootsLocations: DetachedRootsLocation;
 }
 /**
- * {@link RelativeNodePath}s for every {@link TreeNode} in the content tree inserted as an atomic operation.
+ * 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.
  */
-interface LocatedNodesBatch {
+export interface PreparedContentRegular extends PreparedContent {
+    /**
+     * {@inheritDoc PreparedContent.toAttach}
+     */
+    readonly toAttach: readonly FlexTreeNode[];
     /**
-     * UpPath shared by all {@link RelativeNodePath}s in this batch corresponding to the root of the inserted content.
+     * {@link PreparedContent.finalize} but without `attached` parameter: assumes `toAttach` is the same is still valid and uses that.
      */
-    readonly rootPath: Mutable<UpPath>;
-    readonly paths: RelativeNodePath[];
+    readonly finalize: () => void;
 }
 /**
- * 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`.
+ * Split out from {@link prepareForInsertion} as to allow use without a 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.
+ * @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.
  *
- * 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.
- */
-export declare function prepareContentForHydration(content: readonly UnhydratedFlexTreeNode[], scheduler: HydrationScheduler, context: FlexTreeHydratedContextMinimal): void;
-/**
- * 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).
- */
-type HydrationScheduler = (locatedNodes: readonly LocatedNodesBatch[], 
-/**
- * Does the actual hydration. Should be called for each index in `locatedNodes` once the corresponding content has been inserted into the tree.
- */
-doHydration: Hydrator) => void;
-/**
- * Does the actual hydration.
- * The provided `attachPath` is the path the content is currently under (where it was attached in the tree).
+ * @remarks
+ * Adding this entry point is a workaround for initialize not currently having a context.
  */
-type Hydrator = (batch: LocatedNodesBatch, attachPath: UpPath) => void;
-export {};
+export declare function prepareForInsertionContextless<TIn extends InsertableContent | undefined>(data: TIn, schema: ImplicitFieldSchema, schemaAndPolicy: SchemaAndPolicy, hydratedData: FlexTreeHydratedContextMinimal, destinationSchema: TreeFieldStoredSchema): PreparedContentInitialize;
 //# sourceMappingURL=prepareForInsertion.d.ts.map

package/lib/simple-tree/prepareForInsertion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepareForInsertion.d.ts","sourceRoot":"","sources":["../../src/simple-tree/prepareForInsertion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACX,eAAe,EAEf,MAAM,EAGN,qBAAqB,EACrB,WAAW,EACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACN,KAAK,eAAe,EAEpB,KAAK,8BAA8B,EAEnC,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAMxB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EACN,KAAK,iBAAiB,EAEtB,MAAM,uCAAuC,CAAC;AAE/C,OAAO,EAAS,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAEN,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,MAAM,iBAAiB,CAAC;AAYzB;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,SAAS,iBAAiB,GAAG,SAAS,EAC5E,IAAI,EAAE,GAAG,EACT,MAAM,EAAE,mBAAmB,EAC3B,kBAAkB,EAAE,eAAe,EACnC,iBAAiB,EAAE,qBAAqB,GACtC,GAAG,SAAS,SAAS,GAAG,SAAS,GAAG,mBAAmB,CAQzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAC9C,IAAI,EAAE,SAAS,iBAAiB,EAAE,EAClC,MAAM,EAAE,oBAAoB,EAC5B,kBAAkB,EAAE,eAAe,EACnC,iBAAiB,EAAE,WAAW,GAC5B,oBAAoB,CAiBtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,SAAS,iBAAiB,GAAG,SAAS,EACvF,IAAI,EAAE,GAAG,EACT,MAAM,EAAE,mBAAmB,EAC3B,eAAe,EAAE,eAAe,EAChC,YAAY,EAAE,8BAA8B,GAAG,SAAS,EACxD,iBAAiB,EAAE,qBAAqB,EACxC,yBAAyB,CAAC,EAAE,kBAAkB,GAC5C,GAAG,SAAS,SAAS,GAAG,SAAS,GAAG,mBAAmB,CAazD;AAoCD;;GAEG;AACH,UAAU,gBAAgB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACxB;AAED;;GAEG;AACH,UAAU,iBAAiB;IAC1B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,CAAC;CACnC;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,SAAS,EAAE,kBAAkB,EAC7B,OAAO,EAAE,8BAA8B,GACrC,IAAI,CAwBN;AAyCD;;GAEG;AACH,KAAK,kBAAkB,GAAG,CACzB,YAAY,EAAE,SAAS,iBAAiB,EAAE;AAC1C;;GAEG;AACH,WAAW,EAAE,QAAQ,KACjB,IAAI,CAAC;AAEV;;;GAGG;AACH,KAAK,QAAQ,GAAG,CAAC,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC"}
+{"version":3,"file":"prepareForInsertion.d.ts","sourceRoot":"","sources":["../../src/simple-tree/prepareForInsertion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACX,eAAe,EAEf,qBAAqB,EACrB,WAAW,EACX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,KAAK,eAAe,EAEpB,KAAK,8BAA8B,EAEnC,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAOjB,KAAK,qBAAqB,EAC1B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EACN,KAAK,iBAAiB,EAEtB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAMN,KAAK,oBAAoB,EAGzB,MAAM,iBAAiB,CAAC;AAiCzB;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,SAAS,iBAAiB,GAAG,SAAS,EAC5E,IAAI,EAAE,GAAG,EACT,MAAM,EAAE,mBAAmB,EAC3B,kBAAkB,EAAE,eAAe,EACnC,iBAAiB,EAAE,qBAAqB,GACtC,GAAG,SAAS,SAAS,GAAG,SAAS,GAAG,mBAAmB,CAuBzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAC9C,IAAI,EAAE,SAAS,iBAAiB,EAAE,EAClC,MAAM,EAAE,oBAAoB,EAC5B,kBAAkB,EAAE,eAAe,EACnC,iBAAiB,EAAE,WAAW,GAC5B,oBAAoB,CA6CtB;AAED,MAAM,WAAW,eAAe;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAE5C;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,qBAAqB,CAAC;IAEhD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,KAAK,IAAI,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,eAAe;IACjE;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,qBAAqB,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC9D;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAE3C;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,SAAS,iBAAiB,GAAG,SAAS,EACvF,IAAI,EAAE,GAAG,EACT,MAAM,EAAE,mBAAmB,EAC3B,eAAe,EAAE,eAAe,EAChC,YAAY,EAAE,8BAA8B,EAC5C,iBAAiB,EAAE,qBAAqB,GACtC,yBAAyB,CAgB3B"}

package/lib/simple-tree/prepareForInsertion.js

@@ -2,13 +2,16 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { getSchemaAndPolicy, FieldKinds, throwOutOfSchema, flexTreeSlot, ContextSlot, getOrCreateHydratedFlexTreeNode, assertFlexTreeEntityNotFreed, } from "../feature-libraries/index.js";
-import { unhydratedFlexTreeFromInsertable, } from "./unhydratedFlexTreeFromInsertable.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { brand } from "../util/index.js";
-import { getKernel, } from "./core/index.js";
-import { debugAssert, fail, oob } from "@fluidframework/core-utils/internal";
-import { isFieldInSchema } from "../feature-libraries/index.js";
+import { dummyRoot, keyAsDetachedField, rootFieldKey } from "../core/index.js";
+import { getSchemaAndPolicy, FieldKinds, cursorForMapTreeField, throwOutOfSchema, } from "../feature-libraries/index.js";
+import { normalizeFieldSchema } from "./fieldSchema.js";
+import { flexTreeFromInsertable, } from "./unhydratedFlexTreeFromInsertable.js";
+import { createField, getInnerNode, getKernel, isTreeNode, UnhydratedFlexTreeNode, } from "./core/index.js";
+import { assert, fail } from "@fluidframework/core-utils/internal";
+import { combineChunks, isFieldInSchema } from "../feature-libraries/index.js";
+import { getUnhydratedContext } from "./createContext.js";
+import { convertField } from "./toStoredSchema.js";
 /**
  * For now, schema validation for inserted content is always enabled.
  * @remarks
@@ -16,6 +19,17 @@ import { isFieldInSchema } from "../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 isTreeNode(node) && getKernel(node).isHydrated();
+}
+function assertIsDetachedFlexTreeNode(node) {
+    if (node.parentField.parent.parent !== undefined ||
+        node.parentField.parent.key === rootFieldKey) {
+        throw new 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
@@ -25,7 +39,17 @@ const validateSchema = true;
  * (Triggering {@link ForestEvents.afterRootFieldCreated}) otherwise hydration will break.
  */
 export function prepareForInsertion(data, schema, destinationContext, destinationSchema) {
-    return prepareForInsertionContextless(data, schema, getSchemaAndPolicy(destinationContext), destinationContext.isHydrated() ? destinationContext : undefined, destinationSchema);
+    if (data !== undefined && isHydrated(data)) {
+        const treeNode = getInnerNode(data);
+        assertIsDetachedFlexTreeNode(treeNode);
+        return treeNode;
+    }
+    const content = prepareForInsertionContextlessInternal(data, schema, getSchemaAndPolicy(destinationContext), destinationContext.isHydrated() ? destinationContext : undefined, destinationSchema);
+    assert(content.toAttach !== undefined, "Expected toAttach to be defined");
+    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]);
 }
 /**
  * {@link prepareForInsertion} but batched for array content.
@@ -41,13 +65,31 @@ export function prepareForInsertion(data, schema, destinationContext, destinatio
  * due to how the eventing in prepareContentForHydration works.
  */
 export function prepareArrayContentForInsertion(data, schema, destinationContext, destinationSchema) {
-    const mapTrees = data.map((item) => unhydratedFlexTreeFromInsertable(item, schema));
-    validateAndPrepare(getSchemaAndPolicy(destinationContext), destinationContext.isHydrated() ? destinationContext : undefined, {
+    const hasHydratedData = data.some(isHydrated);
+    if (hasHydratedData) {
+        const hasUnhydratedData = data.some((item) => !isHydrated(item));
+        if (hasUnhydratedData) {
+            throw new UsageError("Mixed hydrated and unhydrated data not supported");
+        }
+        const treeNodes = data.map((item) => getInnerNode(item));
+        for (const node of treeNodes) {
+            assertIsDetachedFlexTreeNode(node);
+        }
+        return treeNodes;
+    }
+    const mapTrees = data.map((item) => flexTreeFromInsertable(item, schema));
+    const fieldSchema = convertField(normalizeFieldSchema(schema));
+    const normalizedFieldSchema = normalizeFieldSchema(schema);
+    const field = createField(getUnhydratedContext(normalizedFieldSchema).flexContext, fieldSchema.kind, dummyRoot, mapTrees);
+    const content = validateAndPrepare(getSchemaAndPolicy(destinationContext), destinationContext.isHydrated() ? destinationContext : undefined, {
         kind: FieldKinds.sequence.identifier,
         types: destinationSchema,
         persistedMetadata: undefined,
-    }, mapTrees);
-    return mapTrees;
+    }, field);
+    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;
 }
 /**
  * Split out from {@link prepareForInsertion} as to allow use without a context.
@@ -58,147 +100,164 @@ export function prepareArrayContentForInsertion(data, schema, destinationContext
  * @remarks
  * Adding this entry point is a workaround for initialize not currently having a context.
  */
-export function prepareForInsertionContextless(data, schema, schemaAndPolicy, hydratedData, destinationSchema, scheduleHydrationOverride) {
-    const mapTree = unhydratedFlexTreeFromInsertable(data, schema);
+export function prepareForInsertionContextless(data, schema, schemaAndPolicy, hydratedData, destinationSchema) {
+    const final = prepareForInsertionContextlessInternal(data, schema, schemaAndPolicy, hydratedData, destinationSchema);
+    assert(final.rootsLocations !== undefined, "Expected rootIds to be defined");
+    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 };
+}
+/**
+ * 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 = flexTreeFromInsertable(data, schema);
     const contentArray = mapTree === undefined ? [] : [mapTree];
-    validateAndPrepare(schemaAndPolicy, hydratedData, destinationSchema, contentArray, scheduleHydrationOverride);
-    return mapTree;
+    const normalizedFieldSchema = normalizeFieldSchema(schema);
+    const fieldSchema = convertField(normalizedFieldSchema);
+    const field = createField(getUnhydratedContext(normalizedFieldSchema).flexContext, fieldSchema.kind, 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) {
-    if (hydratedData !== undefined) {
-        // Run `prepareContentForHydration` before walking the tree in `isFieldInSchema`.
+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) {
+            assert(child instanceof UnhydratedFlexTreeNode, "TODO");
+            child.adoptBy(undefined);
+        }
+    };
+    if (hydratedData === undefined) {
+        return { toAttach: [...field.children], finalize: cleanup };
+    }
+    else {
+        // 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) {
-            isFieldInSchema(mapTrees, fieldSchema, schemaAndPolicy, throwOutOfSchema);
+            isFieldInSchema(field, fieldSchema, schemaAndPolicy, 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 = 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.
- */
-export 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) => {
+                assert(hydratedData.detachedField !== undefined, "detachedField should not stop being defined");
+                const rootField = hydratedData.detachedField(keyAsDetachedField(f.field), FieldKinds.optional.identifier);
+                assert(rootField.length === 1, "Expected single root in detached field");
+                return rootField.boxedAt(0) ?? 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);
 }
-function walkMapTree(root, path, onVisitTreeNode, context) {
-    if (root.parentField.parent.parent !== undefined) {
-        throw new 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.");
-    }
-    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(cursorForMapTreeField(x.chunk));
+    const chunk = 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 {
+            assert(child instanceof 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] ?? 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] ?? 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(ContextSlot) ?? fail(0xb41 /* missing context */);
-        // Modify paths in batch to point to correct location:
-        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) ?? fail(0xc7b /* missing anchor */);
-            let flexNode = anchorNode.slots.get(flexTreeSlot);
-            if (flexNode === undefined) {
-                // the flex node must be created
-                const cursor = forest.allocateCursor("getFlexNode");
-                forest.moveCursorToPath(anchorNode, cursor);
-                flexNode = getOrCreateHydratedFlexTreeNode(context, cursor);
-                cursor.free();
-                assertFlexTreeEntityNotFreed(flexNode);
+            else if (field.is(FieldKinds.sequence)) {
+                field.editor.insert(attach.index, [attach.content]);
+            }
+            else if (field.is(FieldKinds.optional)) {
+                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.
+                fail("Invalid field kind for hydrated attach");
             }
-            getKernel(node).hydrate(flexNode);
-            forest.anchors.forget(anchor);
         }
-    };
+        else {
+            const child = (Array.isArray(field) ? field[attach.index] : field.boxedAt(attach.index)) ??
+                fail("No child at index");
+            if (attach.toHydrate !== undefined) {
+                assert(child.isHydrated(), "Expected child to be hydrated");
+                getKernel(attach.toHydrate).hydrate(child);
+            }
+            for (const [key, children] of attach.content) {
+                const childField = child.getBoxed(key);
+                attachAndHydratedNodes(childField, children);
+            }
+        }
+    }
 }
 //# sourceMappingURL=prepareForInsertion.js.map