@fluidframework/tree 2.41.0 → 2.42.0

package/src/simple-tree/index.ts

@@ -22,6 +22,7 @@ export {
 	HydratedContext,
 	SimpleContextSlot,
 	getOrCreateInnerNode,
+	getOrCreateNodeFromInnerNode,
 	getKernel,
 } from "./core/index.js";
 export {
@@ -120,7 +121,6 @@ export {
 	type FixRecursiveRecursionLimit,
 	schemaStatics,
 	type TreeChangeEvents,
-	createFromMapTree,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,
@@ -207,11 +207,11 @@ export {
 	createUnknownOptionalFieldPolicy,
 } from "./node-kinds/index.js";
 export {
-	mapTreeFromNodeData,
+	unhydratedFlexTreeFromInsertable,
 	type InsertableContent,
 	type FactoryContent,
 	type FactoryContentObject,
-} from "./toMapTree.js";
+} from "./unhydratedFlexTreeFromInsertable.js";
 export {
 	prepareForInsertion,
 	prepareForInsertionContextless,

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -6,8 +6,9 @@
 import { Lazy, oob, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { EmptyKey, type ExclusiveMapTree } from "../../../core/index.js";
+import { EmptyKey } from "../../../core/index.js";
 import {
+	type FlexibleFieldContent,
 	type FlexTreeNode,
 	type FlexTreeSequenceField,
 	isFlexTreeNode,
@@ -37,14 +38,15 @@ import {
 	getSimpleNodeSchemaFromInnerNode,
 	getOrCreateInnerNode,
 	type TreeNodeSchemaClass,
-} from "../../core/index.js";
-import { type InsertableContent, mapTreeFromNodeData } from "../../toMapTree.js";
-import { prepareArrayContentForInsertion } from "../../prepareForInsertion.js";
-import {
 	getKernel,
-	UnhydratedFlexTreeNode,
-	UnhydratedTreeSequenceField,
+	type UnhydratedFlexTreeNode,
+	UnhydratedSequenceField,
 } from "../../core/index.js";
+import {
+	type InsertableContent,
+	unhydratedFlexTreeFromInsertable,
+} from "../../unhydratedFlexTreeFromInsertable.js";
+import { prepareArrayContentForInsertion } from "../../prepareForInsertion.js";
 import { TreeNodeValid, type MostDerivedData } from "../../treeNodeValid.js";
 import { getUnhydratedContext } from "../../createContext.js";
 import type { System_Unsafe } from "../../api/index.js";
@@ -852,7 +854,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		super(input ?? []);
 	}
 
-	#mapTreesFromFieldData(value: Insertable<T>): ExclusiveMapTree[] {
+	#mapTreesFromFieldData(value: Insertable<T>): FlexibleFieldContent {
 		const sequenceField = getSequenceField(this);
 		const content = value as readonly (
 			| InsertableContent
@@ -1014,7 +1016,7 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 
 		const movedCount = sourceEnd - sourceStart;
 		if (!destinationField.context.isHydrated()) {
-			if (!(sourceField instanceof UnhydratedTreeSequenceField)) {
+			if (!(sourceField instanceof UnhydratedSequenceField)) {
 				throw new UsageError(
 					"Cannot move elements from a hydrated array to an unhydrated array.",
 				);
@@ -1139,10 +1141,7 @@ export function arraySchema<
 			instance: TreeNodeValid<T2>,
 			input: T2,
 		): UnhydratedFlexTreeNode {
-			return UnhydratedFlexTreeNode.getOrCreate(
-				unhydratedContext,
-				mapTreeFromNodeData(input as object, this as unknown as ImplicitAllowedTypes),
-			);
+			return unhydratedFlexTreeFromInsertable(input as object, this as typeof Schema);
 		}
 
 		public static get allowedTypesIdentifiers(): ReadonlySet<string> {

package/src/simple-tree/node-kinds/index.ts

@@ -31,7 +31,6 @@ export {
 	type InsertableObjectFromAnnotatedSchemaRecord,
 	type InsertableObjectFromSchemaRecord,
 	isObjectNodeSchema,
-	lazilyAllocateIdentifier,
 	type ObjectFromSchemaRecord,
 	ObjectNodeSchema,
 	objectSchema,

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -5,6 +5,7 @@
 
 import { Lazy } from "@fluidframework/core-utils/internal";
 import type {
+	FlexibleNodeContent,
 	FlexTreeNode,
 	FlexTreeOptionalField,
 	OptionalFieldEditBuilder,
@@ -32,19 +33,18 @@ import {
 	type TreeNode,
 	typeSchemaSymbol,
 	type Context,
-	UnhydratedFlexTreeNode,
 	getOrCreateInnerNode,
 	type InternalTreeNode,
+	type UnhydratedFlexTreeNode,
 } from "../../core/index.js";
 import {
-	mapTreeFromNodeData,
+	unhydratedFlexTreeFromInsertable,
 	type FactoryContent,
 	type InsertableContent,
-} from "../../toMapTree.js";
+} from "../../unhydratedFlexTreeFromInsertable.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";
 import { getUnhydratedContext } from "../../createContext.js";
 import type { MapNodeCustomizableSchema, MapNodePojoEmulationSchema } from "./mapNodeTypes.js";
 
@@ -158,7 +158,7 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 		return getOrCreateInnerNode(this);
 	}
 
-	private editor(key: string): OptionalFieldEditBuilder<ExclusiveMapTree> {
+	private editor(key: string): OptionalFieldEditBuilder<FlexibleNodeContent> {
 		const field = this.innerNode.getBoxed(brand(key)) as FlexTreeOptionalField;
 		return field.editor;
 	}
@@ -271,10 +271,7 @@ export function mapSchema<
 			instance: TreeNodeValid<T2>,
 			input: T2,
 		): UnhydratedFlexTreeNode {
-			return UnhydratedFlexTreeNode.getOrCreate(
-				unhydratedContext,
-				mapTreeFromNodeData(input as FactoryContent, this as unknown as ImplicitAllowedTypes),
-			);
+			return unhydratedFlexTreeFromInsertable(input as FactoryContent, this as typeof Schema);
 		}
 
 		public static get allowedTypesIdentifiers(): ReadonlySet<string> {

package/src/simple-tree/node-kinds/object/index.ts

@@ -8,7 +8,6 @@ export {
 	type FieldHasDefault,
 	type InsertableObjectFromAnnotatedSchemaRecord,
 	type InsertableObjectFromSchemaRecord,
-	lazilyAllocateIdentifier,
 	type ObjectFromSchemaRecord,
 	objectSchema,
 	setField,

package/src/simple-tree/node-kinds/object/objectNode.ts

@@ -5,8 +5,6 @@
 
 import { assert, Lazy, fail, debugAssert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
-import { createIdCompressor } from "@fluidframework/id-compressor/internal";
 
 import type { FieldKey, SchemaPolicy } from "../../../core/index.js";
 import {
@@ -16,7 +14,7 @@ import {
 	type FlexTreeOptionalField,
 	type FlexTreeRequiredField,
 } from "../../../feature-libraries/index.js";
-import { type RestrictiveStringRecord, type FlattenKeys, brand } from "../../../util/index.js";
+import type { RestrictiveStringRecord, FlattenKeys } from "../../../util/index.js";
 
 import {
 	type TreeNodeSchema,
@@ -28,7 +26,7 @@ import {
 	type InternalTreeNode,
 	type TreeNode,
 	type Context,
-	UnhydratedFlexTreeNode,
+	type UnhydratedFlexTreeNode,
 	getOrCreateInnerNode,
 } from "../../core/index.js";
 import { getUnhydratedContext } from "../../createContext.js";
@@ -47,7 +45,6 @@ import {
 	type InsertableTreeFieldFromImplicitField,
 	type FieldSchema,
 	normalizeFieldSchema,
-	type ImplicitAllowedTypes,
 	FieldKind,
 	type NodeSchemaMetadata,
 	type FieldSchemaAlpha,
@@ -57,9 +54,11 @@ import {
 	type UnannotateSchemaRecord,
 } from "../../schemaTypes.js";
 import type { SimpleObjectFieldSchema } from "../../simpleSchema.js";
-import { mapTreeFromNodeData, type InsertableContent } from "../../toMapTree.js";
+import {
+	unhydratedFlexTreeFromInsertable,
+	type InsertableContent,
+} from "../../unhydratedFlexTreeFromInsertable.js";
 import { TreeNodeValid, type MostDerivedData } from "../../treeNodeValid.js";
-import { stringSchema } from "../../leafNodeSchema.js";
 
 /**
  * Generates the properties for an ObjectNode from its field schema object.
@@ -201,37 +200,6 @@ function createFlexKeyMapping(fields: Record<string, ImplicitFieldSchema>): Simp
 	return keyMap;
 }
 
-const globalIdentifierAllocator: IIdCompressor = createIdCompressor();
-
-/**
- * Modify `flexNode` to add a newly generated identifier under the given `storedKey`.
- * @remarks
- * This is used after checking if the user is trying to read an identifier field of an unhydrated node, but the identifier is not present.
- * This means the identifier is an "auto-generated identifier", because otherwise it would have been supplied by the user at construction time and would have been successfully read just above.
- * In this case, it is categorically impossible to provide an identifier (auto-generated identifiers can't be created until hydration/insertion time), so we emit an error.
- * @privateRemarks
- * TODO: this special case logic should move to the inner node (who's schema claims it has an identifier), rather than here, after we already read undefined out of a required field.
- * TODO: unify this with a more general defaults mechanism.
- */
-export function lazilyAllocateIdentifier(
-	flexNode: UnhydratedFlexTreeNode,
-	storedKey: FieldKey,
-): string {
-	debugAssert(() => !flexNode.mapTree.fields.has(storedKey) || "Identifier field already set");
-	const value = globalIdentifierAllocator.decompress(
-		globalIdentifierAllocator.generateCompressedId(),
-	);
-	flexNode.mapTree.fields.set(storedKey, [
-		{
-			type: brand(stringSchema.identifier),
-			value,
-			fields: new Map(),
-		},
-	]);
-
-	return value;
-}
-
 /**
  * Creates a proxy handler for the given schema.
  *
@@ -265,13 +233,6 @@ function createProxyHandler(
 					return getTreeNodeForField(field);
 				}
 
-				if (
-					fieldInfo.schema.kind === FieldKind.Identifier &&
-					flexNode instanceof UnhydratedFlexTreeNode
-				) {
-					return lazilyAllocateIdentifier(flexNode, fieldInfo.storedKey);
-				}
-
 				return undefined;
 			}
 
@@ -495,10 +456,7 @@ export function objectSchema<
 			instance: TreeNodeValid<T2>,
 			input: T2,
 		): UnhydratedFlexTreeNode {
-			return UnhydratedFlexTreeNode.getOrCreate(
-				unhydratedContext,
-				mapTreeFromNodeData(input as object, this as unknown as ImplicitAllowedTypes),
-			);
+			return unhydratedFlexTreeFromInsertable(input as object, this as Output);
 		}
 
 		protected static override constructorCached: MostDerivedData | undefined = undefined;

package/src/simple-tree/prepareForInsertion.ts

@@ -4,10 +4,8 @@
  */
 
 import type {
-	ExclusiveMapTree,
 	SchemaAndPolicy,
 	IForestSubscription,
-	MapTree,
 	UpPath,
 	NodeIndex,
 	FieldKey,
@@ -17,23 +15,23 @@ import type {
 import {
 	type FlexTreeContext,
 	getSchemaAndPolicy,
-	type FlexTreeHydratedContext,
+	type FlexTreeHydratedContextMinimal,
 	FieldKinds,
+	type FlexibleFieldContent,
+	type FlexibleNodeContent,
 } from "../feature-libraries/index.js";
 import {
 	normalizeFieldSchema,
 	type ImplicitAllowedTypes,
 	type ImplicitFieldSchema,
 } from "./schemaTypes.js";
-import { type InsertableContent, mapTreeFromNodeData } from "./toMapTree.js";
+import {
+	type InsertableContent,
+	unhydratedFlexTreeFromInsertable,
+} from "./unhydratedFlexTreeFromInsertable.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { brand } from "../util/index.js";
-import {
-	getKernel,
-	type TreeNode,
-	tryUnhydratedFlexTreeNode,
-	unhydratedFlexTreeNodeToTreeNode,
-} from "./core/index.js";
+import { getKernel, type TreeNode, type UnhydratedFlexTreeNode } from "./core/index.js";
 import { debugAssert, oob } from "@fluidframework/core-utils/internal";
 import { inSchemaOrThrow, isFieldInSchema } from "../feature-libraries/index.js";
 import { convertField } from "./toStoredSchema.js";
@@ -50,7 +48,7 @@ export function prepareForInsertion<TIn extends InsertableContent | undefined>(
 	data: TIn,
 	schema: ImplicitFieldSchema,
 	destinationContext: FlexTreeContext,
-): TIn extends undefined ? undefined : ExclusiveMapTree {
+): TIn extends undefined ? undefined : FlexibleNodeContent {
 	return prepareForInsertionContextless(
 		data,
 		schema,
@@ -76,13 +74,9 @@ export function prepareArrayContentForInsertion(
 	data: readonly InsertableContent[],
 	schema: ImplicitAllowedTypes,
 	destinationContext: FlexTreeContext,
-): ExclusiveMapTree[] {
-	const mapTrees: ExclusiveMapTree[] = data.map((item) =>
-		mapTreeFromNodeData(
-			item,
-			schema,
-			destinationContext.isHydrated() ? destinationContext.nodeKeyManager : undefined,
-		),
+): FlexibleFieldContent {
+	const mapTrees: UnhydratedFlexTreeNode[] = data.map((item) =>
+		unhydratedFlexTreeFromInsertable(item, schema),
 	);
 
 	const fieldSchema = convertField(normalizeFieldSchema(schema));
@@ -110,9 +104,9 @@ export function prepareForInsertionContextless<TIn extends InsertableContent | u
 	data: TIn,
 	schema: ImplicitFieldSchema,
 	schemaAndPolicy: SchemaAndPolicy,
-	hydratedData: Pick<FlexTreeHydratedContext, "checkout" | "nodeKeyManager"> | undefined,
-): TIn extends undefined ? undefined : ExclusiveMapTree {
-	const mapTree = mapTreeFromNodeData(data, schema, hydratedData?.nodeKeyManager);
+	hydratedData: FlexTreeHydratedContextMinimal | undefined,
+): TIn extends undefined ? undefined : FlexibleNodeContent {
+	const mapTree = unhydratedFlexTreeFromInsertable(data, schema);
 
 	const contentArray = mapTree === undefined ? [] : [mapTree];
 	const fieldSchema = convertField(normalizeFieldSchema(schema));
@@ -129,16 +123,19 @@ export function prepareForInsertionContextless<TIn extends InsertableContent | u
  */
 function validateAndPrepare(
 	schemaAndPolicy: SchemaAndPolicy,
-	hydratedData: Pick<FlexTreeHydratedContext, "checkout" | "nodeKeyManager"> | undefined,
+	hydratedData: FlexTreeHydratedContextMinimal | undefined,
 	fieldSchema: TreeFieldStoredSchema,
-	mapTrees: ExclusiveMapTree[],
+	mapTrees: readonly UnhydratedFlexTreeNode[],
 ): void {
 	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`.
+		prepareContentForHydration(mapTrees, hydratedData.checkout.forest, hydratedData);
 		if (schemaAndPolicy.policy.validateSchema === true) {
 			const maybeError = isFieldInSchema(mapTrees, fieldSchema, schemaAndPolicy);
 			inSchemaOrThrow(maybeError);
 		}
-		prepareContentForHydration(mapTrees, hydratedData.checkout.forest);
 	}
 }
 
@@ -176,17 +173,21 @@ interface LocatedNodesBatch {
 const placeholderKey: DetachedField & FieldKey = brand("placeholder" as const);
 
 /**
- * Records any proxies in the given content tree and does the necessary bookkeeping to ensure they are synchronized with subsequent reads of the tree.
- * @remarks If the content tree contains any proxies, this function must be called just prior to inserting the content into the tree.
+ * 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.
- * See {@link extractFactoryContent} for more details.
  */
-function prepareContentForHydration(
-	content: readonly MapTree[],
+export function prepareContentForHydration(
+	content: readonly UnhydratedFlexTreeNode[],
 	forest: IForestSubscription,
+	context: FlexTreeHydratedContextMinimal,
 ): void {
 	const batches: LocatedNodesBatch[] = [];
 	for (const item of content) {
@@ -199,39 +200,45 @@ function prepareContentForHydration(
 			paths: [],
 		};
 		batches.push(batch);
-		walkMapTree(item, batch.rootPath, (p, node) => {
-			batch.paths.push({ path: p, node });
-		});
+		walkMapTree(
+			item,
+			batch.rootPath,
+			(p, node) => {
+				batch.paths.push({ path: p, node });
+			},
+			context,
+		);
 	}
 
 	scheduleHydration(batches, forest);
 }
 
 function walkMapTree(
-	mapTree: MapTree,
+	root: UnhydratedFlexTreeNode,
 	path: UpPath,
 	onVisitTreeNode: (path: UpPath, treeNode: TreeNode) => void,
+	context: FlexTreeHydratedContextMinimal,
 ): void {
-	if (tryUnhydratedFlexTreeNode(mapTree)?.parentField.parent.parent !== undefined) {
+	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.",
 		);
 	}
 
-	type Next = [path: UpPath, tree: MapTree];
+	type Next = [path: UpPath, tree: UnhydratedFlexTreeNode];
 	const nexts: Next[] = [];
-	for (let next: Next | undefined = [path, mapTree]; next !== undefined; next = nexts.pop()) {
-		const [p, m] = next;
-		const mapTreeNode = tryUnhydratedFlexTreeNode(m);
-		if (mapTreeNode !== undefined) {
-			const treeNode = unhydratedFlexTreeNodeToTreeNode.get(mapTreeNode);
+	for (let next: Next | undefined = [path, root]; next !== undefined; next = nexts.pop()) {
+		const [p, node] = next;
+		if (node !== undefined) {
+			const treeNode = node.treeNode;
 			if (treeNode !== undefined) {
 				onVisitTreeNode(p, treeNode);
 			}
 		}
 
-		for (const [key, field] of m.fields) {
-			for (const [i, child] of field.entries()) {
+		for (const [key, field] of node.allFieldsLazy) {
+			field.fillPendingDefaults(context);
+			for (const [i, child] of field.children.entries()) {
 				nexts.push([
 					{
 						parent: p,

package/src/simple-tree/schemaTypes.ts

@@ -8,7 +8,7 @@ import { Lazy } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { FieldKey } from "../core/index.js";
-import type { NodeIdentifierManager } from "../feature-libraries/index.js";
+import type { FlexTreeHydratedContextMinimal } from "../feature-libraries/index.js";
 import {
 	type MakeNominal,
 	brand,
@@ -30,12 +30,13 @@ import type {
 	TreeNode,
 	TreeNodeSchemaCore,
 	TreeNodeSchemaNonClass,
+	UnhydratedFlexTreeNode,
 } from "./core/index.js";
 import { inPrototypeChain } from "./core/index.js";
 import { isLazy, type FlexListToUnion, type LazyItem } from "./flexList.js";
 import { LeafNodeSchema } from "./leafNodeSchema.js";
 import type { SimpleFieldSchema, SimpleObjectFieldSchema } from "./simpleSchema.js";
-import type { InsertableContent } from "./toMapTree.js";
+import type { InsertableContent } from "./unhydratedFlexTreeFromInsertable.js";
 import { TreeNodeValid } from "./treeNodeValid.js";
 
 /**
@@ -296,17 +297,17 @@ export interface FieldProps<TCustomMetadata = unknown> {
 }
 
 /**
- * A {@link FieldProvider} which requires additional context in order to produce its content
+ * A {@link FieldProvider} which prefers to have additional context in order to produce its content.
  */
 export type ContextualFieldProvider = (
-	context: NodeIdentifierManager,
-) => InsertableContent | undefined;
+	context: FlexTreeHydratedContextMinimal | "UseGlobalContext",
+) => UnhydratedFlexTreeNode[];
 /**
- * A {@link FieldProvider} which can produce its content in a vacuum
+ * A {@link FieldProvider} which can produce its content in a vacuum.
  */
-export type ConstantFieldProvider = () => InsertableContent | undefined;
+export type ConstantFieldProvider = () => UnhydratedFlexTreeNode[];
 /**
- * A function which produces content for a field every time that it is called
+ * A function which produces content for a field every time that it is called.
  */
 export type FieldProvider = ContextualFieldProvider | ConstantFieldProvider;
 /**

package/src/simple-tree/toStoredSchema.ts

@@ -93,7 +93,13 @@ export function convertField(schema: SimpleFieldSchema): TreeFieldStoredSchema {
 	return { kind, types };
 }
 
-const convertFieldKind = new Map<FieldKind, FlexFieldKind>([
+/**
+ * A map that converts {@link FieldKind} to {@link FlexFieldKind}.
+ */
+export const convertFieldKind: ReadonlyMap<FieldKind, FlexFieldKind> = new Map<
+	FieldKind,
+	FlexFieldKind
+>([
 	[FieldKind.Optional, FieldKinds.optional],
 	[FieldKind.Required, FieldKinds.required],
 	[FieldKind.Identifier, FieldKinds.identifier],