@fluidframework/tree 2.90.0-378676 → 2.90.0

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

@@ -2,10 +2,11 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-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 ImplicitAllowedTypes } from "./core/index.js";
-import { type ImplicitFieldSchema } from "./fieldSchema.js";
+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 Mutable } from "../util/index.js";
+import { type ImplicitAllowedTypes, type TreeNode, type UnhydratedFlexTreeNode } from "./core/index.js";
+import type { ImplicitFieldSchema } from "./fieldSchema.js";
 import { type InsertableContent } from "./unhydratedFlexTreeFromInsertable.js";
 /**
  * Prepare content from a user for insertion into a tree.
@@ -30,66 +31,58 @@ 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;
-}
 /**
- * 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.
+ * 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 interface PreparedContentInitialize extends PreparedContent {
-    /**
-     * {@inheritDoc PreparedContent.rootIds}
-     */
-    readonly rootsLocations: DetachedRootsLocation;
+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.
+ */
+interface RelativeNodePath {
+    readonly path: UpPath;
+    readonly node: TreeNode;
 }
 /**
- * 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.
+ * {@link RelativeNodePath}s for every {@link TreeNode} in the content tree inserted as an atomic operation.
  */
-export interface PreparedContentRegular extends PreparedContent {
-    /**
-     * {@inheritDoc PreparedContent.toAttach}
-     */
-    readonly toAttach: readonly FlexTreeNode[];
+interface LocatedNodesBatch {
     /**
-     * {@link PreparedContent.finalize} but without `attached` parameter: assumes `toAttach` is the same is still valid and uses that.
+     * UpPath shared by all {@link RelativeNodePath}s in this batch corresponding to the root of the inserted content.
      */
-    readonly finalize: () => void;
+    readonly rootPath: Mutable<UpPath>;
+    readonly paths: RelativeNodePath[];
 }
 /**
- * Split out from {@link prepareForInsertion} as to allow use without a context.
+ * 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`.
  *
- * @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 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.
  *
- * @remarks
- * Adding this entry point is a workaround for initialize not currently having a context.
+ * 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).
  */
-export declare function prepareForInsertionContextless<TIn extends InsertableContent | undefined>(data: TIn, schema: ImplicitFieldSchema, schemaAndPolicy: SchemaAndPolicy, hydratedData: FlexTreeHydratedContextMinimal, destinationSchema: TreeFieldStoredSchema): PreparedContentInitialize;
+type Hydrator = (batch: LocatedNodesBatch, attachPath: UpPath) => void;
+export {};
 //# 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;AAKH,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;AAGvC,OAAO,EAMN,KAAK,oBAAoB,EAGzB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGlF,OAAO,EACN,KAAK,iBAAiB,EAEtB,MAAM,uCAAuC,CAAC;AA4B/C;;;;;;;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"}
+{"version":3,"file":"prepareForInsertion.d.ts","sourceRoot":"","sources":["../../src/simple-tree/prepareForInsertion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,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;AAEvC,OAAO,EAAS,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAEN,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EACb,KAAK,sBAAsB,EAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EACN,KAAK,iBAAiB,EAEtB,MAAM,uCAAuC,CAAC;AAU/C;;;;;;;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"}

package/lib/simple-tree/prepareForInsertion.js

@@ -2,16 +2,13 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { assert, fail } from "@fluidframework/core-utils/internal";
+import { debugAssert, fail, oob } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { dummyRoot, keyAsDetachedField, rootFieldKey } from "../core/index.js";
-import { getSchemaAndPolicy, FieldKinds, cursorForMapTreeField, throwOutOfSchema, } from "../feature-libraries/index.js";
-import { combineChunks, isFieldInSchema } from "../feature-libraries/index.js";
-import { createField, getInnerNode, getKernel, isTreeNode, UnhydratedFlexTreeNode, } from "./core/index.js";
-import { getUnhydratedContext } from "./createContext.js";
-import { normalizeFieldSchema } from "./fieldSchema.js";
-import { convertField } from "./toStoredSchema.js";
-import { flexTreeFromInsertable, } from "./unhydratedFlexTreeFromInsertable.js";
+import { getSchemaAndPolicy, FieldKinds, throwOutOfSchema, flexTreeSlot, ContextSlot, getOrCreateHydratedFlexTreeNode, assertFlexTreeEntityNotFreed, } from "../feature-libraries/index.js";
+import { isFieldInSchema } from "../feature-libraries/index.js";
+import { brand } from "../util/index.js";
+import { getKernel, } from "./core/index.js";
+import { unhydratedFlexTreeFromInsertable, } from "./unhydratedFlexTreeFromInsertable.js";
 /**
  * For now, schema validation for inserted content is always enabled.
  * @remarks
@@ -19,17 +16,6 @@ import { flexTreeFromInsertable, } from "./unhydratedFlexTreeFromInsertable.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
@@ -39,17 +25,7 @@ function assertIsDetachedFlexTreeNode(node) {
  * (Triggering {@link ForestEvents.afterRootFieldCreated}) otherwise hydration will break.
  */
 export function prepareForInsertion(data, schema, destinationContext, 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]);
+    return prepareForInsertionContextless(data, schema, getSchemaAndPolicy(destinationContext), destinationContext.isHydrated() ? destinationContext : undefined, destinationSchema);
 }
 /**
  * {@link prepareForInsertion} but batched for array content.
@@ -65,31 +41,13 @@ export function prepareForInsertion(data, schema, destinationContext, destinatio
  * due to how the eventing in prepareContentForHydration works.
  */
 export function prepareArrayContentForInsertion(data, schema, destinationContext, destinationSchema) {
-    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, {
+    const mapTrees = data.map((item) => unhydratedFlexTreeFromInsertable(item, schema));
+    validateAndPrepare(getSchemaAndPolicy(destinationContext), destinationContext.isHydrated() ? destinationContext : undefined, {
         kind: FieldKinds.sequence.identifier,
         types: destinationSchema,
         persistedMetadata: undefined,
-    }, 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;
+    }, mapTrees);
+    return mapTrees;
 }
 /**
  * Split out from {@link prepareForInsertion} as to allow use without a context.
@@ -100,164 +58,147 @@ 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) {
-    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);
+export function prepareForInsertionContextless(data, schema, schemaAndPolicy, hydratedData, destinationSchema, scheduleHydrationOverride) {
+    const mapTree = unhydratedFlexTreeFromInsertable(data, schema);
     const contentArray = mapTree === undefined ? [] : [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);
+    validateAndPrepare(schemaAndPolicy, hydratedData, destinationSchema, contentArray, scheduleHydrationOverride);
+    return mapTree;
 }
 /**
  * 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, 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`.
+function validateAndPrepare(schemaAndPolicy, hydratedData, fieldSchema, mapTrees, scheduleHydrationOverride) {
+    if (hydratedData !== undefined) {
+        // Run `prepareContentForHydration` 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`.
-        const chunk = chunkForInsertion(hydratedData, field);
+        prepareContentForHydration(mapTrees, scheduleHydrationOverride ??
+            ((batch, doHydration) => scheduleHydration(batch, hydratedData.checkout.forest, doHydration)), hydratedData);
         // 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(field, fieldSchema, schemaAndPolicy, throwOutOfSchema);
+            isFieldInSchema(mapTrees, fieldSchema, schemaAndPolicy, throwOutOfSchema);
         }
-        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();
+    }
+}
+/**
+ * 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,
             },
+            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 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",
-            });
-        }
-        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);
-                }
+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);
             }
-            // 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",
-                });
+        }
+        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,
+                ]);
             }
-            chunk.push({ type: child.type, value: child.value, fields });
         }
     }
-    return {
-        chunk,
-        attaches,
-    };
 }
-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;
-            }
-            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");
-            }
-        }
-        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);
+/**
+ * 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();
             }
-            for (const [key, children] of attach.content) {
-                const childField = child.getBoxed(key);
-                attachAndHydratedNodes(childField, children);
+        });
+    }
+}
+/**
+ * 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);
             }
+            getKernel(node).hydrate(flexNode);
+            forest.anchors.forget(anchor);
         }
-    }
+    };
 }
 //# sourceMappingURL=prepareForInsertion.js.map