@fluidframework/tree 2.50.0 → 2.51.0

package/src/simple-tree/index.ts

@@ -27,7 +27,35 @@ export {
 	getOrCreateNodeFromInnerNode,
 	getOrCreateNodeFromInnerUnboxedNode,
 	getKernel,
+	type NodeFromSchema,
+	isTreeNodeSchemaClass,
+	type TreeNodeFromImplicitAllowedTypes,
+	type InsertableTreeNodeFromImplicitAllowedTypes,
+	type TreeLeafValue,
+	type AllowedTypes,
+	type InsertableTreeNodeFromAllowedTypes,
+	type InsertableTypedNode,
+	type NodeBuilderData,
+	type Input,
+	normalizeAllowedTypes,
+	type NodeSchemaMetadata,
+	type ImplicitAllowedTypes,
+	type ImplicitAnnotatedAllowedTypes,
+	type UnannotateImplicitAllowedTypes,
+	type AllowedTypesMetadata,
+	evaluateLazySchema,
+	type UnannotateAllowedTypes,
+	type UnannotateAllowedType,
+	type UnannotateAllowedTypesList,
+	type UnannotateAllowedTypeOrLazyItem,
+	type AllowedTypeMetadata,
+	type AnnotatedAllowedTypes,
+	type LazyItem,
+	type FlexList,
+	type FlexListToUnion,
+	type ExtractItemType,
 } from "./core/index.js";
+export type { UnsafeUnknownSchema, Insertable } from "./unsafeUnknownSchema.js";
 export {
 	type ITree,
 	type TreeView,
@@ -127,6 +155,8 @@ export {
 	type FixRecursiveRecursionLimit,
 	schemaStatics,
 	type TreeChangeEvents,
+	type NodeSchemaOptions,
+	type NodeSchemaOptionsAlpha,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,
@@ -142,33 +172,14 @@ export type {
 	SimpleRecordNodeSchema,
 } from "./simpleSchema.js";
 export {
-	type NodeFromSchema,
-	isTreeNodeSchemaClass,
 	type ImplicitFieldSchema,
 	type ImplicitAnnotatedFieldSchema,
 	type TreeFieldFromImplicitField,
-	type ImplicitAllowedTypes,
-	type ImplicitAnnotatedAllowedTypes,
-	type UnannotateImplicitAllowedTypes,
-	type UnannotateAllowedTypes,
-	type UnannotateAllowedType,
-	type UnannotateAllowedTypesList,
-	type UnannotateAllowedTypeOrLazyItem,
 	type UnannotateImplicitFieldSchema,
-	type UnannotateSchemaRecord,
-	type TreeNodeFromImplicitAllowedTypes,
-	type InsertableTreeNodeFromImplicitAllowedTypes,
-	type TreeLeafValue,
-	type AllowedTypes,
-	type AllowedTypeMetadata,
-	type AllowedTypesMetadata,
-	type AnnotatedAllowedTypes,
 	FieldKind,
 	FieldSchema,
 	type FieldSchemaAlpha,
 	type InsertableTreeFieldFromImplicitField,
-	type InsertableTypedNode,
-	type NodeBuilderData,
 	type DefaultProvider,
 	type FieldProps,
 	type FieldPropsAlpha,
@@ -178,19 +189,10 @@ export {
 	type ApplyKind,
 	type FieldSchemaMetadata,
 	type InsertableField,
-	type Insertable,
-	type UnsafeUnknownSchema,
-	normalizeAllowedTypes,
 	type ApplyKindInput,
-	type InsertableTreeNodeFromAllowedTypes,
-	type Input,
 	type ReadableField,
 	type ReadSchema,
-	type NodeSchemaOptions,
-	type NodeSchemaOptionsAlpha,
-	type NodeSchemaMetadata,
-	evaluateLazySchema,
-} from "./schemaTypes.js";
+} from "./fieldSchema.js";
 export { tryGetTreeNodeForField } from "./getTreeNodeForField.js";
 export {
 	type ArrayNodeCustomizableSchema,
@@ -223,6 +225,7 @@ export {
 	type RecordNodePojoEmulationSchema,
 	RecordNodeSchema,
 	type TreeRecordNode,
+	type UnannotateSchemaRecord,
 } from "./node-kinds/index.js";
 export {
 	unhydratedFlexTreeFromInsertable,
@@ -234,7 +237,7 @@ export {
 	prepareForInsertion,
 	prepareForInsertionContextless,
 } from "./prepareForInsertion.js";
-export { toStoredSchema, getStoredSchema } from "./toStoredSchema.js";
+export { toStoredSchema, getStoredSchema, convertFieldKind } from "./toStoredSchema.js";
 export {
 	numberSchema,
 	stringSchema,
@@ -243,4 +246,11 @@ export {
 	nullSchema,
 } from "./leafNodeSchema.js";
 export type { LeafSchema } from "./leafNodeSchema.js";
-export type { LazyItem, FlexList, FlexListToUnion, ExtractItemType } from "./flexList.js";
+export {
+	getAllowedContentDiscrepancies,
+	type FieldDiscrepancy,
+	comparePosetElements,
+	fieldRealizer,
+	type Realizer,
+	PosetComparisonResult,
+} from "./discrepancies.js";

package/src/simple-tree/leafNodeSchema.ts

@@ -4,23 +4,34 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
 import { type TreeValue, ValueSchema } from "../core/index.js";
 import {
 	type FlexTreeNode,
 	isFlexTreeNode,
+	isTreeValue,
 	valueSchemaAllows,
 } from "../feature-libraries/index.js";
 
 import {
 	NodeKind,
-	type NormalizedAnnotatedAllowedTypes,
 	type TreeNodeSchema,
 	type TreeNodeSchemaNonClass,
+	type NodeSchemaMetadata,
+	type TreeLeafValue,
+	type TreeNodeSchemaCorePrivate,
+	type TreeNodeSchemaPrivateData,
+	privateDataSymbol,
+	type TreeNodeSchemaInitializedData,
+	CompatibilityLevel,
+	type FlexContent,
 } from "./core/index.js";
-import type { NodeSchemaMetadata, TreeLeafValue } from "./schemaTypes.js";
 import type { SimpleLeafNodeSchema } from "./simpleSchema.js";
-import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
+import { brand, type JsonCompatibleReadOnlyObject } from "../util/index.js";
+import { getTreeNodeSchemaInitializedData } from "./createContext.js";
+import type { FactoryContent } from "./unhydratedFlexTreeFromInsertable.js";
 
 /**
  * Instances of this class are schema for leaf nodes.
@@ -32,14 +43,29 @@ import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
  * This class refers to the underlying flex tree schema in its constructor, so this class can't be included in the package API.
  */
 export class LeafNodeSchema<Name extends string, const T extends ValueSchema>
-	implements TreeNodeSchemaNonClass<Name, NodeKind.Leaf, TreeValue<T>, TreeValue<T>>
+	implements
+		TreeNodeSchemaNonClass<Name, NodeKind.Leaf, TreeValue<T>, TreeValue<T>>,
+		SimpleLeafNodeSchema,
+		TreeNodeSchemaCorePrivate
 {
 	public readonly identifier: Name;
 	public readonly kind = NodeKind.Leaf;
 	public readonly info: T;
 	public readonly implicitlyConstructable = true as const;
 	public readonly childTypes: ReadonlySet<TreeNodeSchema> = new Set();
-	public readonly childAnnotatedAllowedTypes: readonly NormalizedAnnotatedAllowedTypes[] = [];
+	public readonly [privateDataSymbol]: TreeNodeSchemaPrivateData = {
+		idempotentInitialize: () =>
+			(this.#initializedData ??= getTreeNodeSchemaInitializedData(this, {
+				shallowCompatibilityTest: (data: FactoryContent): CompatibilityLevel =>
+					shallowCompatibilityTest(this, data),
+				toFlexContent: (
+					data: FactoryContent,
+					allowedTypes: ReadonlySet<TreeNodeSchema>,
+				): FlexContent => leafToFlexContent(data, this, allowedTypes),
+			})),
+		childAnnotatedAllowedTypes: [],
+	};
+	#initializedData: TreeNodeSchemaInitializedData | undefined;
 
 	public create(data: TreeValue<T> | FlexTreeNode): TreeValue<T> {
 		if (isFlexTreeNode(data)) {
@@ -103,3 +129,109 @@ export const numberSchema = makeLeaf("number", ValueSchema.Number);
 export const booleanSchema = makeLeaf("boolean", ValueSchema.Boolean);
 export const nullSchema = makeLeaf("null", ValueSchema.Null);
 export const handleSchema = makeLeaf("handle", ValueSchema.FluidHandle);
+
+/**
+ * Checks if data might be schema-compatible.
+ *
+ * @returns false if `data` is incompatible with `type` based on a cheap/shallow check.
+ *
+ * Note that this may return true for cases where data is incompatible, but it must not return false in cases where the data is compatible.
+ */
+function shallowCompatibilityTest(
+	schema: TreeNodeSchema,
+	data: FactoryContent,
+): CompatibilityLevel {
+	if (isTreeValue(data)) {
+		return allowsValue(schema, data) ? CompatibilityLevel.Normal : CompatibilityLevel.None;
+	}
+
+	return CompatibilityLevel.None;
+}
+
+function allowsValue(schema: TreeNodeSchema, value: TreeValue): boolean {
+	if (schema.kind === NodeKind.Leaf) {
+		return valueSchemaAllows(schema.info as ValueSchema, value);
+	}
+	return false;
+}
+
+/**
+ * Transforms data under a Leaf schema.
+ * @param data - The tree data to be transformed. Must be a {@link TreeValue}.
+ * @param schema - The schema associated with the value.
+ * @param allowedTypes - The allowed types specified by the parent.
+ * Used to determine which fallback values may be appropriate.
+ */
+export function leafToFlexContent(
+	data: FactoryContent,
+	schema: TreeNodeSchema,
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
+): FlexContent {
+	assert(schema.kind === NodeKind.Leaf, 0x921 /* Expected a leaf schema. */);
+	if (!isTreeValue(data)) {
+		// This rule exists to protect against useless `toString` output like `[object Object]`.
+		// In this case, that's actually reasonable behavior, since object input is not compatible with Leaf schemas.
+		// eslint-disable-next-line @typescript-eslint/no-base-to-string
+		throw new UsageError(`Input data is incompatible with leaf schema: ${data}`);
+	}
+
+	const mappedValue = mapValueWithFallbacks(data, allowedTypes);
+	const mappedSchema = [...allowedTypes].find((type) => allowsValue(type, mappedValue));
+
+	assert(mappedSchema !== undefined, 0x84a /* Unsupported schema for provided primitive. */);
+
+	const result: FlexContent = [
+		{
+			value: mappedValue,
+			type: brand(mappedSchema.identifier),
+		},
+		new Map(),
+	];
+
+	return result;
+}
+
+/**
+ * Checks an incoming {@link TreeLeafValue} to ensure it is compatible with its requirements.
+ * For unsupported values with a schema-compatible replacement, return the replacement value.
+ * For unsupported values without a schema-compatible replacement, throw.
+ * For supported values, return the input.
+ */
+function mapValueWithFallbacks(
+	value: TreeLeafValue,
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
+): TreeValue {
+	switch (typeof value) {
+		case "number": {
+			if (Object.is(value, -0)) {
+				// Our serialized data format does not support -0.
+				// Map such input to +0.
+				return 0;
+			} else if (!Number.isFinite(value)) {
+				// Our serialized data format does not support NaN nor +/-∞.
+				// If the schema supports `null`, fall back to that. Otherwise, throw.
+				// This is intended to match JSON's behavior for such values.
+				if (allowedTypes.has(nullSchema)) {
+					return null;
+				} else {
+					throw new UsageError(`Received unsupported numeric value: ${value}.`);
+				}
+			} else {
+				return value;
+			}
+		}
+		case "string":
+		// TODO:
+		// This should detect invalid strings. Something like @stdlib/regexp-utf16-unpaired-surrogate could be used to do this.
+		// See SchemaFactory.string for details.
+		case "boolean":
+			return value;
+		case "object": {
+			if (value === null || isFluidHandle(value)) {
+				return value;
+			}
+		}
+		default:
+			throw new UsageError(`Received unsupported leaf value: ${value}.`);
+	}
+}

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

@@ -12,19 +12,9 @@ import type {
 	FlexTreeNode,
 	FlexTreeSequenceField,
 } from "../../../feature-libraries/index.js";
+import { FieldKinds, isTreeValue } from "../../../feature-libraries/index.js";
 import {
-	normalizeAllowedTypes,
-	normalizeAnnotatedAllowedTypes,
-	unannotateImplicitAllowedTypes,
-	type ImplicitAllowedTypes,
-	type ImplicitAnnotatedAllowedTypes,
-	type InsertableTreeNodeFromImplicitAllowedTypes,
-	type NodeSchemaMetadata,
-	type TreeLeafValue,
-	type TreeNodeFromImplicitAllowedTypes,
-	type UnannotateImplicitAllowedTypes,
-} from "../../schemaTypes.js";
-import {
+	CompatibilityLevel,
 	type WithType,
 	// eslint-disable-next-line import/no-deprecated
 	typeNameSymbol,
@@ -33,7 +23,6 @@ import {
 	type InternalTreeNode,
 	type TreeNodeSchema,
 	typeSchemaSymbol,
-	type Context,
 	getOrCreateNodeFromInnerNode,
 	getSimpleNodeSchemaFromInnerNode,
 	getOrCreateInnerNode,
@@ -42,21 +31,43 @@ import {
 	type UnhydratedFlexTreeNode,
 	UnhydratedSequenceField,
 	getOrCreateNodeFromInnerUnboxedNode,
-	type NormalizedAnnotatedAllowedTypes,
+	normalizeAllowedTypes,
+	unannotateImplicitAllowedTypes,
+	type ImplicitAllowedTypes,
+	type ImplicitAnnotatedAllowedTypes,
+	type InsertableTreeNodeFromImplicitAllowedTypes,
+	type NodeSchemaMetadata,
+	type TreeLeafValue,
+	type TreeNodeFromImplicitAllowedTypes,
+	type UnannotateImplicitAllowedTypes,
+	TreeNodeValid,
+	type MostDerivedData,
+	type TreeNodeSchemaInitializedData,
+	type TreeNodeSchemaCorePrivate,
+	privateDataSymbol,
+	createTreeNodeSchemaPrivateData,
+	type FlexContent,
+	type TreeNodeSchemaPrivateData,
 } from "../../core/index.js";
 import {
+	type FactoryContent,
 	type InsertableContent,
 	unhydratedFlexTreeFromInsertable,
+	unhydratedFlexTreeFromInsertableNode,
 } from "../../unhydratedFlexTreeFromInsertable.js";
 import { prepareArrayContentForInsertion } from "../../prepareForInsertion.js";
-import { TreeNodeValid, type MostDerivedData } from "../../treeNodeValid.js";
-import { getUnhydratedContext } from "../../createContext.js";
+import {
+	getTreeNodeSchemaInitializedData,
+	getUnhydratedContext,
+} from "../../createContext.js";
 import type { System_Unsafe } from "../../api/index.js";
 import type {
 	ArrayNodeCustomizableSchema,
 	ArrayNodePojoEmulationSchema,
+	ArrayNodeSchema,
 } from "./arrayNodeTypes.js";
-import type { JsonCompatibleReadOnlyObject } from "../../../util/index.js";
+import { brand, type JsonCompatibleReadOnlyObject } from "../../../util/index.js";
+import { nullSchema } from "../../leafNodeSchema.js";
 
 /**
  * A covariant base type for {@link (TreeArrayNode:interface)}.
@@ -720,7 +731,7 @@ function createArrayNodeProxy(
 ): TreeArrayNode {
 	// To satisfy 'deepEquals' level scrutiny, the target of the proxy must be an array literal in order
 	// to pass 'Object.getPrototypeOf'.  It also satisfies 'Array.isArray' and 'Object.prototype.toString'
-	// requirements without use of Array[Symbol.species], which is potentially on a path ot deprecation.
+	// requirements without use of Array[Symbol.species], which is potentially on a path to deprecation.
 	const proxy: TreeArrayNode = new Proxy<TreeArrayNode>(proxyTarget as TreeArrayNode, {
 		get: (target, key, receiver) => {
 			const field = getSequenceField(receiver);
@@ -731,6 +742,12 @@ function createArrayNodeProxy(
 					return field.length;
 				}
 
+				// In NodeJS 22, assert.strict.deepEqual started special casing well known constructors like Array.
+				// That made this necessary, ensuring that in POJO mode, TreeArrayNode are still deepEqual to arrays.
+				if (key === "constructor") {
+					return proxyTarget.constructor;
+				}
+
 				// Pass the proxy as the receiver here, so that any methods on
 				// the prototype receive `proxy` as `this`.
 				return Reflect.get(dispatchTarget, key, receiver) as unknown;
@@ -1107,17 +1124,17 @@ export function arraySchema<
 		ImplicitlyConstructable,
 		TCustomMetadata
 	> &
-		ArrayNodePojoEmulationSchema<TName, T, ImplicitlyConstructable, TCustomMetadata>;
+		ArrayNodePojoEmulationSchema<TName, T, ImplicitlyConstructable, TCustomMetadata> &
+		TreeNodeSchemaCorePrivate;
 
 	const unannotatedTypes = unannotateImplicitAllowedTypes(info);
 
 	const lazyChildTypes = new Lazy(() => normalizeAllowedTypes(unannotatedTypes));
-	const lazyAnnotatedTypes = new Lazy(() => [normalizeAnnotatedAllowedTypes(info)]);
 	const lazyAllowedTypesIdentifiers = new Lazy(
 		() => new Set([...lazyChildTypes.value].map((type) => type.identifier)),
 	);
 
-	let unhydratedContext: Context;
+	let privateData: TreeNodeSchemaPrivateData | undefined;
 
 	// This class returns a proxy from its constructor to handle numeric indexing.
 	// Alternatively it could extend a normal class which gets tons of numeric properties added.
@@ -1156,10 +1173,7 @@ export function arraySchema<
 
 		protected static override constructorCached: MostDerivedData | undefined = undefined;
 
-		protected static override oneTimeSetup<T2>(this: typeof TreeNodeValid<T2>): Context {
-			const schema = this as unknown as TreeNodeSchema;
-			unhydratedContext = getUnhydratedContext(schema);
-
+		protected static override oneTimeSetup(): TreeNodeSchemaInitializedData {
 			// First run, do extra validation.
 			// TODO: provide a way for TreeConfiguration to trigger this same validation to ensure it gets run early.
 			// Scan for shadowing inherited members which won't work, but stop scan early to allow shadowing built in (which seems to work ok).
@@ -1184,8 +1198,16 @@ export function arraySchema<
 					prototype = Reflect.getPrototypeOf(prototype) as object;
 				}
 			}
-
-			return unhydratedContext;
+			const schema = this as ArrayNodeSchema;
+
+			return getTreeNodeSchemaInitializedData(this, {
+				shallowCompatibilityTest: (data: FactoryContent): CompatibilityLevel =>
+					shallowCompatibilityTest(data, schema),
+				toFlexContent: (
+					data: FactoryContent,
+					allowedTypes: ReadonlySet<TreeNodeSchema>,
+				): FlexContent => arrayToFlexContent(data, schema),
+			});
 		}
 
 		public static readonly identifier = identifier;
@@ -1195,9 +1217,6 @@ export function arraySchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;
 		}
-		public static get childAnnotatedAllowedTypes(): readonly NormalizedAnnotatedAllowedTypes[] {
-			return lazyAnnotatedTypes.value;
-		}
 		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> = metadata ?? {};
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
@@ -1216,6 +1235,10 @@ export function arraySchema<
 		protected get allowedTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;
 		}
+
+		public static get [privateDataSymbol](): TreeNodeSchemaPrivateData {
+			return (privateData ??= createTreeNodeSchemaPrivateData(this, [info]));
+		}
 	}
 
 	const output: Output = Schema;
@@ -1271,3 +1294,91 @@ function validateIndexRange(
 		);
 	}
 }
+
+/**
+ * Transforms data for a child of an array.
+ * @param child - The tree data to be transformed.
+ * @param allowedTypes - The set of types allowed by the parent context. Used to validate the input tree.
+ */
+function arrayChildToFlexTree(
+	child: InsertableContent,
+	allowedTypes: ReadonlySet<TreeNodeSchema>,
+): UnhydratedFlexTreeNode {
+	// We do not support undefined sequence entries.
+	// If we encounter an undefined entry, use null instead if supported by the schema, otherwise throw.
+	let childWithFallback = child;
+	if (child === undefined) {
+		if (allowedTypes.has(nullSchema)) {
+			childWithFallback = null;
+		} else {
+			throw new TypeError(`Received unsupported array entry value: ${child}.`);
+		}
+	}
+	return unhydratedFlexTreeFromInsertableNode(childWithFallback, allowedTypes);
+}
+
+/**
+ * {@link TreeNodeSchemaInitializedData.toFlexContent} for Array nodes.
+ *
+ * @param data - The tree data to be transformed. Must be an iterable.
+ * @param schema - The schema to comply with.
+ */
+function arrayToFlexContent(data: FactoryContent, schema: ArrayNodeSchema): FlexContent {
+	if (!(typeof data === "object" && data !== null && Symbol.iterator in data)) {
+		throw new UsageError(`Input data is incompatible with Array schema: ${data}`);
+	}
+
+	const allowedChildTypes = normalizeAllowedTypes(schema.info as ImplicitAllowedTypes);
+
+	const mappedData = Array.from(data, (child) =>
+		arrayChildToFlexTree(child, allowedChildTypes),
+	);
+
+	const context = getUnhydratedContext(schema).flexContext;
+
+	// Array nodes have a single `EmptyKey` field:
+	const fieldsEntries =
+		mappedData.length === 0
+			? []
+			: ([
+					[
+						EmptyKey,
+						new UnhydratedSequenceField(
+							context,
+							FieldKinds.sequence.identifier,
+							EmptyKey,
+							mappedData,
+						),
+					],
+				] as const);
+
+	return [
+		{
+			type: brand(schema.identifier),
+		},
+		new Map(fieldsEntries),
+	];
+}
+
+/**
+ * {@link TreeNodeSchemaInitializedData.shallowCompatibilityTest} for Array nodes.
+ */
+function shallowCompatibilityTest(
+	data: FactoryContent,
+	schema: ArrayNodeSchema,
+): CompatibilityLevel {
+	if (isTreeValue(data)) {
+		return CompatibilityLevel.None;
+	}
+
+	if (data instanceof Map) {
+		// Maps are iterable, so type checking does allow constructing an ArrayNode from a map if the ArrayNode's type is an array that includes the key and value types of the map.
+		return CompatibilityLevel.Low;
+	}
+
+	if (Symbol.iterator in data) {
+		return CompatibilityLevel.Normal;
+	}
+
+	return CompatibilityLevel.None;
+}

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

@@ -4,17 +4,15 @@
  */
 
 import type { TreeArrayNode } from "./arrayNode.js";
+import { NodeKind } from "../../core/index.js";
 import type {
+	TreeNodeSchemaClass,
+	TreeNodeSchema,
+	TreeNodeSchemaNonClass,
+	WithType,
 	ImplicitAnnotatedAllowedTypes,
 	InsertableTreeNodeFromImplicitAllowedTypes,
 	UnannotateImplicitAllowedTypes,
-} from "../../schemaTypes.js";
-import {
-	NodeKind,
-	type TreeNodeSchemaClass,
-	type TreeNodeSchema,
-	type TreeNodeSchemaNonClass,
-	type WithType,
 } from "../../core/index.js";
 
 import type { SimpleArrayNodeSchema } from "../../simpleSchema.js";

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

@@ -0,0 +1,60 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+
+import type { FieldKey } from "../../core/index.js";
+import { FieldKinds } from "../../feature-libraries/index.js";
+import { brand } from "../../util/index.js";
+
+import {
+	createField,
+	type UnhydratedFlexTreeField,
+	unannotateImplicitAllowedTypes,
+	normalizeAllowedTypes,
+	type FlexContent,
+} from "../core/index.js";
+import { getUnhydratedContext } from "../createContext.js";
+import {
+	unhydratedFlexTreeFromInsertableNode,
+	type InsertableContent,
+} from "../unhydratedFlexTreeFromInsertable.js";
+import type { MapNodeSchema } from "./map/index.js";
+import type { RecordNodeSchema } from "./record/index.js";
+
+/**
+ * Utilities shared by multiple node kinds.
+ */
+
+/**
+ * Converts record-like data to a FlexContent representation for map/record schema.
+ */
+export function recordLikeDataToFlexContent(
+	fieldsIterator: Iterable<readonly [string, InsertableContent]>,
+	schema: MapNodeSchema | RecordNodeSchema,
+): FlexContent {
+	const allowedChildTypes = normalizeAllowedTypes(unannotateImplicitAllowedTypes(schema.info));
+	const context = getUnhydratedContext(schema).flexContext;
+
+	const transformedFields = new Map<FieldKey, UnhydratedFlexTreeField>();
+	for (const item of fieldsIterator) {
+		const [key, value] = item;
+		assert(!transformedFields.has(brand(key)), 0x84c /* Keys should not be duplicated */);
+
+		// Omit undefined values - an entry with an undefined value is equivalent to one that has been removed or omitted
+		if (value !== undefined) {
+			const child = unhydratedFlexTreeFromInsertableNode(value, allowedChildTypes);
+			const field = createField(context, FieldKinds.optional.identifier, brand(key), [child]);
+			transformedFields.set(brand(key), field);
+		}
+	}
+
+	return [
+		{
+			type: brand(schema.identifier),
+		},
+		transformedFields,
+	];
+}

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

@@ -37,6 +37,8 @@ export {
 	objectSchema,
 	setField,
 	type TreeObjectNode,
+	type SimpleKeyMap,
+	type UnannotateSchemaRecord,
 } from "./object/index.js";
 
 export {