@fluidframework/tree 2.41.0-337492 → 2.41.0-338401

package/src/simple-tree/arrayNode.ts

@@ -10,10 +10,8 @@ import { EmptyKey, type ExclusiveMapTree } from "../core/index.js";
 import {
 	type FlexTreeNode,
 	type FlexTreeSequenceField,
-	getSchemaAndPolicy,
 	isFlexTreeNode,
 } from "../feature-libraries/index.js";
-import { prepareContentForHydration } from "./proxies.js";
 import {
 	normalizeAllowedTypes,
 	unannotateImplicitAllowedTypes,
@@ -41,6 +39,7 @@ import {
 	type TreeNodeSchemaClass,
 } from "./core/index.js";
 import { type InsertableContent, mapTreeFromNodeData } from "./toMapTree.js";
+import { prepareArrayContentForInsertion } from "./prepareForInsertion.js";
 import {
 	getKernel,
 	UnhydratedFlexTreeNode,
@@ -860,24 +859,14 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 			| IterableTreeArrayContent<InsertableContent>
 		)[];
 
-		const mapTrees = content
-			.flatMap((c): InsertableContent[] =>
-				c instanceof IterableTreeArrayContent ? Array.from(c) : [c],
-			)
-			.map((c) =>
-				mapTreeFromNodeData(
-					c,
-					this.simpleSchema,
-					sequenceField.context.isHydrated()
-						? sequenceField.context.nodeKeyManager
-						: undefined,
-					getSchemaAndPolicy(sequenceField),
-				),
-			);
-
-		if (sequenceField.context.isHydrated()) {
-			prepareContentForHydration(mapTrees, sequenceField.context.checkout.forest);
-		}
+		const contentArray = content.flatMap((c): InsertableContent[] =>
+			c instanceof IterableTreeArrayContent ? Array.from(c) : [c],
+		);
+		const mapTrees = prepareArrayContentForInsertion(
+			contentArray,
+			this.simpleSchema,
+			sequenceField.context,
+		);
 
 		return mapTrees;
 	}

package/src/simple-tree/core/getOrCreateNode.ts

@@ -7,7 +7,7 @@ import type { TreeValue } from "../../core/index.js";
 import {
 	type InnerNode,
 	unhydratedFlexTreeNodeToTreeNode,
-	proxySlot,
+	simpleTreeNodeSlot,
 	createTreeNodeFromInner,
 } from "./treeNodeKernel.js";
 import type { TreeNode } from "./treeNode.js";
@@ -23,7 +23,7 @@ export function getOrCreateNodeFromInnerNode(flexNode: InnerNode): TreeNode | Tr
 	const cached =
 		flexNode instanceof UnhydratedFlexTreeNode
 			? unhydratedFlexTreeNodeToTreeNode.get(flexNode)
-			: flexNode.anchorNode.slots.get(proxySlot);
+			: flexNode.anchorNode.slots.get(simpleTreeNodeSlot);
 
 	if (cached !== undefined) {
 		return cached;

package/src/simple-tree/core/treeNodeKernel.ts

@@ -175,12 +175,7 @@ export class TreeNodeKernel {
 			};
 		} else {
 			// Hydrated case
-			const { anchorNode } = innerNode;
-			assert(
-				!anchorNode.slots.has(proxySlot),
-				0x7f5 /* Cannot associate an flex node with multiple simple-tree nodes */,
-			);
-			this.#hydrationState = this.createHydratedState(anchorNode);
+			this.#hydrationState = this.createHydratedState(innerNode.anchorNode);
 		}
 	}
 
@@ -197,16 +192,22 @@ export class TreeNodeKernel {
 
 	/**
 	 * Transition from {@link Unhydrated} to hydrated.
-	 * Bi-directionally associates the given hydrated TreeNode to the given anchor node.
+	 * Bi-directionally associates the given hydrated TreeNode to the anchor node at the provided path.
 	 * @remarks
 	 * Happens at most once for any given node.
-	 * Cleans up mappings to {@link UnhydratedFlexTreeNode} - it is assumed that they are no longer needed once the proxy has an anchor node.
+	 * Cleans up mappings to {@link UnhydratedFlexTreeNode} - it is assumed that they are no longer needed once this node has an anchor node.
 	 */
-	private hydrate(anchorNode: AnchorNode): void {
+	public hydrate(anchors: AnchorSet, path: UpPath): void {
 		assert(!this.disposed, 0xa2a /* cannot hydrate a disposed node */);
 		assert(!isHydrated(this.#hydrationState), 0xa2b /* hydration should only happen once */);
 		unhydratedFlexTreeNodeToTreeNodeInternal.delete(this.#hydrationState.innerNode);
+
+		const anchor = anchors.track(path);
+		const anchorNode =
+			anchors.locate(anchor) ?? fail(0xb42 /* Expected anchor node to be present */);
+
 		this.#hydrationState = this.createHydratedState(anchorNode);
+		this.#hydrationState.offAnchorNode.add(() => anchors.forget(anchor));
 
 		// If needed, register forwarding emitters for events from before hydration
 		if (this.#unhydratedEvents.evaluated) {
@@ -224,7 +225,11 @@ export class TreeNodeKernel {
 	}
 
 	private createHydratedState(anchorNode: AnchorNode): HydratedState {
-		anchorNode.slots.set(proxySlot, this.node);
+		assert(
+			!anchorNode.slots.has(simpleTreeNodeSlot),
+			0x7f5 /* Cannot associate an flex node with multiple simple-tree nodes */,
+		);
+		anchorNode.slots.set(simpleTreeNodeSlot, this.node);
 		return {
 			anchorNode,
 			offAnchorNode: new Set([
@@ -265,6 +270,7 @@ export class TreeNodeKernel {
 	}
 
 	public dispose(): void {
+		debugAssert(() => !this.disposed || "Cannot dispose a disposed node");
 		this.disposed = true;
 		if (isHydrated(this.#hydrationState)) {
 			for (const off of this.#hydrationState.offAnchorNode) {
@@ -305,7 +311,7 @@ export class TreeNodeKernel {
 		if (this.#hydrationState.innerNode === undefined) {
 			// Marinated case -> cooked
 			const anchorNode = this.#hydrationState.anchorNode;
-			// The proxy is bound to an anchor node, but it may or may not have an actual flex node yet
+			// This TreeNode is bound to an anchor node, but it may or may not have an actual flex node yet
 			const flexNode = anchorNode.slots.get(flexTreeSlot);
 			if (flexNode !== undefined) {
 				// If the flex node already exists, use it...
@@ -318,8 +324,6 @@ export class TreeNodeKernel {
 				context.checkout.forest.moveCursorToPath(anchorNode, cursor);
 				this.#hydrationState.innerNode = makeTree(context, cursor);
 				cursor.free();
-				// Calling this is a performance improvement, however, do this only after demand to avoid momentarily having no anchors to anchorNode
-				anchorForgetters?.get(this.node)?.();
 				if (!allowDeleted) {
 					assertFlexTreeEntityNotFreed(this.#hydrationState.innerNode);
 				}
@@ -335,35 +339,6 @@ export class TreeNodeKernel {
 		return this.#hydrationState.innerNode;
 	}
 
-	/**
-	 * Creates an anchor node and associates it with the given proxy.
-	 * @privateRemarks
-	 * Use `forgetters` to cleanup the anchor allocated by this function once the anchor is no longer needed.
-	 * In practice, this happens when either the anchor node is destroyed, or another anchor to the same node is created by a new flex node.
-	 *
-	 * The FlexTreeNode holds a reference to the same anchor, and has a lifetime at least as long as the simple-tree,
-	 * so this would be unnecessary except for the case of "marinated" nodes, which have an anchor,
-	 * but might not have a FlexTreeNode.
-	 * Handling this case is an optimization assuming that this extra anchor reference is cheaper than eagerly creating FlexTreeNodes.
-	 */
-	public anchorProxy(anchors: AnchorSet, path: UpPath): AnchorNode {
-		assert(!anchorForgetters.has(this.node), 0x91c /* Proxy anchor should not be set twice */);
-		const anchor = anchors.track(path);
-		const anchorNode =
-			anchors.locate(anchor) ?? fail(0xb42 /* Expected anchor node to be present */);
-		this.hydrate(anchorNode);
-		const forget = (): void => {
-			if (anchors.locate(anchor)) {
-				anchors.forget(anchor);
-			}
-			anchorForgetters.delete(this.node);
-			off();
-		};
-		anchorForgetters.set(this.node, forget);
-		const off = anchorNode.events.on("afterDestroy", forget);
-		return anchorNode;
-	}
-
 	/**
 	 * Retrieves the InnerNode associated with the given target via {@link setInnerNode}, if any.
 	 * @remarks
@@ -383,11 +358,6 @@ export class TreeNodeKernel {
 	}
 }
 
-/**
- * Used by {@link anchorProxy} as an optimization to ensure that only one anchor is remembered at a time for a given anchor node
- */
-const anchorForgetters = new WeakMap<TreeNode, () => void>();
-
 const kernelEvents = ["childrenChangedAfterBatch", "subtreeChangedAfterBatch"] as const;
 
 type KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;
@@ -423,22 +393,22 @@ export const unhydratedFlexTreeNodeToTreeNode =
 	>;
 
 /**
- * An anchor slot which associates an anchor with its corresponding TreeNode, if there is one.
+ * An anchor slot which associates an anchor with its corresponding {@link TreeNode}, if there is one.
  * @remarks
  * For this to work, we have to require that there is at most a single view using a given AnchorSet.
  * FlexTree already has this assumption, and we also assume there is a single simple-tree per FlexTree, so this is valid.
  */
-export const proxySlot = anchorSlot<TreeNode>();
+export const simpleTreeNodeSlot = anchorSlot<TreeNode>();
 
 /**
  * Dispose a TreeNode (if any) for an existing anchor without disposing the anchor.
  */
 export function tryDisposeTreeNode(anchorNode: AnchorNode): void {
-	const treeNode = anchorNode.slots.get(proxySlot);
+	const treeNode = anchorNode.slots.get(simpleTreeNodeSlot);
 	if (treeNode !== undefined) {
 		const kernel = getKernel(treeNode);
 		kernel.dispose();
-		anchorNode.slots.delete(proxySlot);
+		anchorNode.slots.delete(simpleTreeNodeSlot);
 	}
 }
 
@@ -483,7 +453,6 @@ export function getOrCreateInnerNode(treeNode: TreeNode, allowDeleted = false):
  * Gets a flex node from an anchor node
  */
 function flexNodeFromAnchor(anchorNode: AnchorNode): FlexTreeNode {
-	// the proxy is bound to an anchor node, but it may or may not have an actual flex node yet
 	const flexNode = anchorNode.slots.get(flexTreeSlot);
 	if (flexNode !== undefined) {
 		return flexNode; // If it does have a flex node, return it...
@@ -501,7 +470,7 @@ function flexNodeFromAnchor(anchorNode: AnchorNode): FlexTreeNode {
  * Gets a tree node from an anchor node
  */
 export function treeNodeFromAnchor(anchorNode: AnchorNode): TreeNode | TreeValue {
-	const cached = anchorNode.slots.get(proxySlot);
+	const cached = anchorNode.slots.get(simpleTreeNodeSlot);
 	if (cached !== undefined) {
 		return cached;
 	}

package/src/simple-tree/core/unhydratedFlexTree.ts

@@ -69,7 +69,7 @@ interface LocationInField {
  * An unhydrated implementation of {@link FlexTreeNode} which wraps a {@link MapTree}.
  * @remarks
  * MapTreeNodes are unconditionally cached -
- * when retrieved via {@link getOrCreateNode}, the same {@link MapTree} object will always produce the same `UnhydratedFlexTreeNode` object.
+ * when retrieved via {@link getOrCreateNodeFromInnerNode}, the same {@link MapTree} object will always produce the same `UnhydratedFlexTreeNode` object.
  *
  * Create a `UnhydratedFlexTreeNode` by calling {@link getOrCreate}.
  */
@@ -112,9 +112,9 @@ export class UnhydratedFlexTreeNode implements FlexTreeNode {
 	 * Create a new UnhydratedFlexTreeNode.
 	 * @param location - the parentage of this node, if it is being created underneath an existing node and field, or undefined if not
 	 * @remarks This class (and its subclasses) should not be directly constructed outside of this module.
-	 * Instead, use {@link getOrCreateNode} to create a UnhydratedFlexTreeNode from a {@link MapTree}.
+	 * Instead, use {@link getOrCreateNodeFromInnerNode} to create a UnhydratedFlexTreeNode from a {@link MapTree}.
 	 * A `UnhydratedFlexTreeNode` may never be constructed more than once for the same {@link MapTree} object.
-	 * Instead, it should always be acquired via {@link getOrCreateNode}.
+	 * Instead, it should always be acquired via {@link getOrCreateNodeFromInnerNode}.
 	 */
 	public constructor(
 		public readonly simpleContext: Context,
@@ -548,7 +548,7 @@ function getFieldKeyCache(
 
 /**
  * If there exists a {@link UnhydratedFlexTreeNode} for the given {@link MapTree}, returns it, otherwise returns `undefined`.
- * @remarks {@link UnhydratedFlexTreeNode | UnhydratedFlexTreeNodes} are created via {@link getOrCreateNode}.
+ * @remarks {@link UnhydratedFlexTreeNode | UnhydratedFlexTreeNodes} are created via {@link getOrCreateNodeFromInnerNode}.
  */
 export function tryUnhydratedFlexTreeNode(
 	mapTree: MapTree,

package/src/simple-tree/getTreeNodeForField.ts

@@ -0,0 +1,46 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { fail } from "@fluidframework/core-utils/internal";
+import type { TreeValue } from "../core/index.js";
+import {
+	FieldKinds,
+	type FlexTreeField,
+	isFlexTreeNode,
+	type FlexTreeRequiredField,
+	type FlexTreeOptionalField,
+} from "../feature-libraries/index.js";
+import { type TreeNode, getOrCreateNodeFromInnerNode } from "./core/index.js";
+
+/**
+ * Retrieve the associated {@link TreeNode} for the given field's content.
+ */
+export function getTreeNodeForField(field: FlexTreeField): TreeNode | TreeValue | undefined {
+	function tryToUnboxLeaves(
+		flexField: FlexTreeOptionalField | FlexTreeRequiredField,
+	): TreeNode | TreeValue | undefined {
+		const maybeContent = flexField.content;
+		return isFlexTreeNode(maybeContent)
+			? getOrCreateNodeFromInnerNode(maybeContent)
+			: maybeContent;
+	}
+	switch (field.schema) {
+		case FieldKinds.required.identifier: {
+			const typedField = field as FlexTreeRequiredField;
+			return tryToUnboxLeaves(typedField);
+		}
+		case FieldKinds.optional.identifier: {
+			const typedField = field as FlexTreeOptionalField;
+			return tryToUnboxLeaves(typedField);
+		}
+		case FieldKinds.identifier.identifier: {
+			// Identifier fields are just value fields that hold strings
+			return (field as FlexTreeRequiredField).content as string;
+		}
+
+		default:
+			fail(0xadf /* invalid field kind */);
+	}
+}

package/src/simple-tree/index.ts

@@ -79,7 +79,6 @@ export {
 	extractPersistedSchema,
 	comparePersistedSchema,
 	type ConciseTree,
-	comparePersistedSchemaInternal,
 	SchemaCompatibilityTester,
 	type Unenforced,
 	type System_Unsafe,
@@ -89,6 +88,8 @@ export {
 	type TreeBranch,
 	type TreeBranchEvents,
 	tryGetSchema,
+	getStoredKey,
+	getPropertyKeyFromStoredKey,
 	applySchemaToParserOptions,
 	cursorFromVerbose,
 	verboseFromCursor,
@@ -123,6 +124,7 @@ export {
 	type FixRecursiveRecursionLimit,
 	schemaStatics,
 	type TreeChangeEvents,
+	createFromMapTree,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,
@@ -184,10 +186,7 @@ export {
 	type NodeSchemaMetadata,
 	evaluateLazySchema,
 } from "./schemaTypes.js";
-export {
-	getTreeNodeForField,
-	prepareContentForHydration,
-} from "./proxies.js";
+export { getTreeNodeForField } from "./getTreeNodeForField.js";
 export {
 	TreeArrayNode,
 	IterableTreeArrayContent,
@@ -220,6 +219,10 @@ export {
 	type FactoryContent,
 	type FactoryContentObject,
 } from "./toMapTree.js";
+export {
+	prepareForInsertion,
+	prepareForInsertionContextless,
+} from "./prepareForInsertion.js";
 export { toStoredSchema, getStoredSchema } from "./toStoredSchema.js";
 export {
 	numberSchema,

package/src/simple-tree/mapNode.ts

@@ -4,13 +4,12 @@
  */
 
 import { Lazy } from "@fluidframework/core-utils/internal";
-import {
-	type FlexTreeNode,
-	type FlexTreeOptionalField,
-	type OptionalFieldEditBuilder,
-	getSchemaAndPolicy,
+import type {
+	FlexTreeNode,
+	FlexTreeOptionalField,
+	OptionalFieldEditBuilder,
 } from "../feature-libraries/index.js";
-import { getTreeNodeForField, prepareContentForHydration } from "./proxies.js";
+import { getTreeNodeForField } from "./getTreeNodeForField.js";
 import {
 	createFieldSchema,
 	FieldKind,
@@ -42,6 +41,7 @@ import {
 	type FactoryContent,
 	type InsertableContent,
 } from "./toMapTree.js";
+import { prepareForInsertion } from "./prepareForInsertion.js";
 import { brand, count, type RestrictiveStringRecord } from "../util/index.js";
 import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 import type { ExclusiveMapTree } from "../core/index.js";
@@ -191,17 +191,13 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 	public set(key: string, value: InsertableTreeNodeFromImplicitAllowedTypes<T>): this {
 		const kernel = getKernel(this);
 		const node = this.innerNode;
-		const mapTree = mapTreeFromNodeData(
+		const mapTree = prepareForInsertion(
 			value as InsertableContent | undefined,
 			createFieldSchema(FieldKind.Optional, kernel.schema.info as ImplicitAllowedTypes),
-			node.context.isHydrated() ? node.context.nodeKeyManager : undefined,
-			getSchemaAndPolicy(node),
+			node.context,
 		);
 
 		const field = node.getBoxed(brand(key));
-		if (node.context.isHydrated()) {
-			prepareContentForHydration(mapTree, node.context.checkout.forest);
-		}
 
 		this.editor(key).set(mapTree, field.length === 0);
 		return this;

package/src/simple-tree/objectNode.ts

@@ -13,9 +13,8 @@ import {
 	type FlexTreeNode,
 	type FlexTreeOptionalField,
 	type FlexTreeRequiredField,
-	getSchemaAndPolicy,
 } from "../feature-libraries/index.js";
-import { getTreeNodeForField, prepareContentForHydration } from "./proxies.js";
+import { getTreeNodeForField } from "./getTreeNodeForField.js";
 import {
 	type ImplicitFieldSchema,
 	getStoredKey,
@@ -47,6 +46,7 @@ import {
 	getOrCreateInnerNode,
 } from "./core/index.js";
 import { mapTreeFromNodeData, type InsertableContent } from "./toMapTree.js";
+import { prepareForInsertion } from "./prepareForInsertion.js";
 import type { RestrictiveStringRecord, FlattenKeys } from "../util/index.js";
 import {
 	isObjectNodeSchema,
@@ -328,16 +328,7 @@ export function setField(
 	simpleFieldSchema: FieldSchema,
 	value: InsertableContent | undefined,
 ): void {
-	const mapTree = mapTreeFromNodeData(
-		value,
-		simpleFieldSchema,
-		field.context.isHydrated() ? field.context.nodeKeyManager : undefined,
-		getSchemaAndPolicy(field),
-	);
-
-	if (field.context.isHydrated()) {
-		prepareContentForHydration(mapTree, field.context.checkout.forest);
-	}
+	const mapTree = prepareForInsertion(value, simpleFieldSchema, field.context);
 
 	switch (field.schema) {
 		case FieldKinds.required.identifier: {