@fluidframework/tree 2.1.0 → 2.3.0-288113

package/src/simple-tree/toMapTree.ts

@@ -3,8 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, oob } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
 import {
 	EmptyKey,
@@ -13,13 +14,10 @@ import {
 	type TreeValue,
 	type ValueSchema,
 	type SchemaAndPolicy,
+	type ExclusiveMapTree,
 } from "../core/index.js";
 import {
-	type CursorWithNode,
-	cursorForMapTreeField,
-	cursorForMapTreeNode,
 	isTreeValue,
-	typeNameSymbol,
 	valueSchemaAllows,
 	type NodeKeyManager,
 	isMapTreeNode,
@@ -29,21 +27,21 @@ import { brand, fail, isReadonlyArray, find } from "../util/index.js";
 import { nullSchema } from "./leafNodeSchema.js";
 import type { InsertableContent } from "./proxies.js";
 import {
-	FieldKind,
-	FieldSchema,
+	type FieldSchema,
 	type ImplicitAllowedTypes,
-	type ImplicitFieldSchema,
-	NodeKind,
-	type TreeNodeSchema,
 	normalizeAllowedTypes,
-	normalizeFieldSchema,
-	getStoredKey,
 	extractFieldProvider,
 	isConstant,
 	type FieldProvider,
+	type ImplicitFieldSchema,
+	normalizeFieldSchema,
+	FieldKind,
+	type TreeLeafValue,
 } from "./schemaTypes.js";
+import { NodeKind, tryGetSimpleNodeSchema, type TreeNodeSchema } from "./core/index.js";
 import { SchemaValidationErrors, isNodeInSchema } from "../feature-libraries/index.js";
-import { tryGetFlexNode } from "./proxyBinding.js";
+import { tryGetInnerNode } from "./proxyBinding.js";
+import { isObjectNodeSchema } from "./objectNodeTypes.js";
 
 /**
  * Module notes:
@@ -56,93 +54,6 @@ import { tryGetFlexNode } from "./proxyBinding.js";
  * schema than on the input data.
  */
 
-/**
- * Transforms an input {@link TypedNode} tree to a {@link MapTree}, and wraps the tree in a {@link CursorWithNode}.
- * @param data - The input tree to be converted.
- * @param allowedTypes - The set of types allowed by the parent context. Used to validate the input tree.
- * @param context - An optional context which, if present, will allow defaults to be created by {@link ContextualFieldProvider}s.
- * If absent, only defaults from {@link ConstantFieldProvider}s will be created.
- * @param schemaValidationPolicy - The stored schema and policy to be used for validation, if the policy says schema
- * validation should happen. If it does, the input tree will be validated against this schema + policy, and an error will
- * be thrown if the tree does not conform to the schema. If undefined, no validation against the stored schema is done.
- *
- * @returns A cursor (in nodes mode) for the mapped tree if the input data was defined. Otherwise, returns `undefined`.
- * @remarks The resulting tree will be populated with any defaults from {@link FieldProvider}s in the schema.
- */
-export function cursorFromNodeData(
-	data: InsertableContent,
-	allowedTypes: ImplicitAllowedTypes,
-	context?: NodeKeyManager,
-	schemaValidationPolicy?: SchemaAndPolicy,
-): CursorWithNode<MapTree>;
-export function cursorFromNodeData(
-	data: InsertableContent | undefined,
-	allowedTypes: ImplicitAllowedTypes,
-	context?: NodeKeyManager,
-	schemaValidationPolicy?: SchemaAndPolicy,
-): CursorWithNode<MapTree> | undefined;
-export function cursorFromNodeData(
-	data: InsertableContent | undefined,
-	allowedTypes: ImplicitAllowedTypes,
-	context?: NodeKeyManager,
-	schemaValidationPolicy?: SchemaAndPolicy,
-): CursorWithNode<MapTree> | undefined {
-	if (data === undefined) {
-		return undefined;
-	}
-	const mappedContent = nodeDataToMapTree(
-		data,
-		normalizeAllowedTypes(allowedTypes),
-		schemaValidationPolicy,
-	);
-	addDefaultsToMapTree(mappedContent, allowedTypes, context);
-	return cursorForMapTreeNode(mappedContent);
-}
-
-/**
- * Transforms an input {@link InsertableContent} tree to an array of {@link MapTree}s, and wraps the tree in a {@link CursorWithNode}.
- * @param data - The input tree to be converted.
- * @param schema - Schema of the field with which the input `data` is associated.
- * @param context - An optional context which, if present, will allow defaults to be created by {@link ContextualFieldProvider}s.
- * If absent, only defaults from {@link ConstantFieldProvider}s will be created.
- * @param schemaValidationPolicy - The stored schema and policy to be used for validation, if the policy says schema
- * validation should happen. If it does, the input tree will be validated against this schema + policy, and an error will
- * be thrown if the tree does not conform to the schema. If undefined, no validation against the stored schema is done.
- * @remarks The resulting tree will be populated with any defaults from {@link FieldProvider}s in the schema.
- */
-export function cursorFromFieldData(
-	data: InsertableContent,
-	schema: FieldSchema,
-	context?: NodeKeyManager,
-	schemaValidationPolicy?: SchemaAndPolicy,
-): CursorWithNode<MapTree>;
-export function cursorFromFieldData(
-	data: InsertableContent | undefined,
-	schema: FieldSchema,
-	context?: NodeKeyManager,
-	schemaValidationPolicy?: SchemaAndPolicy,
-): CursorWithNode<MapTree> | undefined;
-export function cursorFromFieldData(
-	data: InsertableContent | undefined,
-	schema: FieldSchema,
-	context?: NodeKeyManager,
-	schemaValidationPolicy?: SchemaAndPolicy,
-): CursorWithNode<MapTree> | undefined {
-	if (data === undefined) {
-		return undefined;
-	}
-
-	// TODO: array node content should not go through here since sequence fields don't exist at this abstraction layer.
-	const mappedContent = Array.isArray(data)
-		? arrayToMapTreeFields(data, schema.allowedTypeSet, schemaValidationPolicy)
-		: [nodeDataToMapTree(data, schema.allowedTypeSet, schemaValidationPolicy)];
-
-	for (const content of mappedContent) {
-		addDefaultsToMapTree(content, schema.allowedTypes, context);
-	}
-	return cursorForMapTreeField(mappedContent);
-}
-
 /**
  * Transforms an input {@link TypedNode} tree to a {@link MapTree}.
  * @param data - The input tree to be converted.
@@ -157,70 +68,100 @@ export function cursorFromFieldData(
  *
  * * `-0` =\> `+0`
  *
+ * For fields with a default value, the field may be omitted.
+ * If `context` is not provided, defaults which require a context will be left empty which can be out of schema.
+ *
  * @param allowedTypes - The set of types allowed by the parent context. Used to validate the input tree.
  * @param context - An optional context which, if present, will allow defaults to be created by {@link ContextualFieldProvider}s.
  * If absent, only defaults from {@link ConstantFieldProvider}s will be created.
  * @param schemaValidationPolicy - The stored schema and policy to be used for validation, if the policy says schema
  * validation should happen. If it does, the input tree will be validated against this schema + policy, and an error will
  * be thrown if the tree does not conform to the schema. If undefined, no validation against the stored schema is done.
+ *
+ * TODO:BUG: AB#9131
+ * This schema validation is done before defaults are provided.
+ * This can not easily be fixed by reordering things within this implementation since even at the end of this function defaults requiring a context may not have been filled.
+ * This means schema validation reject required fields getting their value from a default like identifier fields.
+ *
  * @remarks The resulting tree will be populated with any defaults from {@link FieldProvider}s in the schema.
+ *
+ * @privateRemarks
+ * TODO: AB#9126 AB#9131
+ * When an app wants schema validation, we should ensure data is validated. Doing the validation here is not robust (since many callers to this don't have a context and thus can't opt into validation).
+ * Additionally the validation here does not correctly handle default values, and introduces a second schema representation which is a bit odd API wise as its typically derivable from the view schema.
+ * It may make more sense to validate when hydrating the MapTreeNode when the context is known and the defaults are available.
+ * Applying the "parse don't validate" idiom here could help ensuring we capture when the validation optionally happens in the type system to avoid missing or redundant validation,
+ * as well as ensuring validation happens after defaulting (or can handle validating data missing defaults)
  */
 export function mapTreeFromNodeData(
 	data: InsertableContent,
 	allowedTypes: ImplicitAllowedTypes,
 	context?: NodeKeyManager,
 	schemaValidationPolicy?: SchemaAndPolicy,
-): MapTree;
+): ExclusiveMapTree;
 export function mapTreeFromNodeData(
 	data: InsertableContent | undefined,
-	allowedTypes: ImplicitAllowedTypes,
+	allowedTypes: ImplicitFieldSchema,
 	context?: NodeKeyManager,
 	schemaValidationPolicy?: SchemaAndPolicy,
-): MapTree | undefined;
+): ExclusiveMapTree | undefined;
 export function mapTreeFromNodeData(
 	data: InsertableContent | undefined,
-	allowedTypes: ImplicitAllowedTypes,
+	allowedTypes: ImplicitFieldSchema,
 	context?: NodeKeyManager,
 	schemaValidationPolicy?: SchemaAndPolicy,
-): MapTree | undefined {
+): ExclusiveMapTree | undefined {
+	const normalizedFieldSchema = normalizeFieldSchema(allowedTypes);
+
 	if (data === undefined) {
+		// TODO: this code-path should support defaults
+		if (normalizedFieldSchema.kind !== FieldKind.Optional) {
+			throw new UsageError("Got undefined for non-optional field.");
+		}
 		return undefined;
 	}
 
-	const mapTree = nodeDataToMapTree(
-		data,
-		normalizeAllowedTypes(allowedTypes),
-		schemaValidationPolicy,
-	);
-	addDefaultsToMapTree(mapTree, allowedTypes, context);
+	const mapTree = nodeDataToMapTree(data, normalizedFieldSchema.allowedTypeSet);
+	// Add what defaults can be provided. If no `context` is providing, some defaults may still be missing.
+	addDefaultsToMapTree(mapTree, normalizedFieldSchema.allowedTypes, context);
+
+	// TODO:
+	// Since some defaults may still be missing, this can give false positives when context is undefined but schemaValidationPolicy is provided.
+	if (schemaValidationPolicy?.policy.validateSchema === true) {
+		const maybeError = isNodeInSchema(mapTree, schemaValidationPolicy);
+		inSchemaOrThrow(maybeError);
+	}
+
 	return mapTree;
 }
 
+/**
+ * Copy content from `data` into a MapTree.
+ * Does NOT generate and default values for fields.
+ * Often throws UsageErrors for invalid data, but may miss some cases.
+ * @remarks
+ * Output is likely out of schema even for valid input due to missing defaults.
+ */
 function nodeDataToMapTree(
 	data: InsertableContent,
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
-	schemaValidationPolicy: SchemaAndPolicy | undefined,
-): MapTree;
-function nodeDataToMapTree(
-	data: InsertableContent | undefined,
-	allowedTypes: ReadonlySet<TreeNodeSchema>,
-	schemaValidationPolicy: SchemaAndPolicy | undefined,
-): MapTree | undefined;
-function nodeDataToMapTree(
-	data: InsertableContent | undefined,
-	allowedTypes: ReadonlySet<TreeNodeSchema>,
-	schemaValidationPolicy: SchemaAndPolicy | undefined,
-): MapTree | undefined {
-	if (data === undefined) {
-		return undefined;
-	}
-
+): ExclusiveMapTree {
 	// A special cache path for processing unhydrated nodes.
 	// They already have the mapTree, so there is no need to recompute it.
-	const flexNode = tryGetFlexNode(data);
+	const flexNode = tryGetInnerNode(data);
 	if (flexNode !== undefined) {
 		if (isMapTreeNode(flexNode)) {
-			return flexNode.mapTree;
+			if (
+				!allowedTypes.has(tryGetSimpleNodeSchema(flexNode.schema) ?? fail("missing schema"))
+			) {
+				throw new UsageError("Invalid schema for this context.");
+			}
+			// TODO: mapTreeFromNodeData modifies the trees it gets to add defaults.
+			// Using a cached value here can result in this tree having defaults applied to it more than once.
+			// This is unnecessary and inefficient, but should be a no-op if all calls provide the same context (which they might not).
+			// A cleaner design (avoiding this cast) might be to apply defaults eagerly if they don't need a context, and lazily (when hydrating) if they do.
+			// This could avoid having to mutate the map tree to apply defaults, removing the need for this cast.
+			return flexNode.mapTree as ExclusiveMapTree;
 		} else {
 			// The node is already hydrated, meaning that it already got inserted into the tree previously
 			throw new UsageError("A node may not be inserted into the tree more than once");
@@ -229,7 +170,7 @@ function nodeDataToMapTree(
 
 	const schema = getType(data, allowedTypes);
 
-	let result: MapTree;
+	let result: ExclusiveMapTree;
 	switch (schema.kind) {
 		case NodeKind.Leaf:
 			result = leafToMapTree(data, schema, allowedTypes);
@@ -247,16 +188,18 @@ function nodeDataToMapTree(
 			fail(`Unrecognized schema kind: ${schema.kind}.`);
 	}
 
-	if (schemaValidationPolicy?.policy.validateSchema === true) {
-		const maybeError = isNodeInSchema(result, schemaValidationPolicy);
-		if (maybeError !== SchemaValidationErrors.NoError) {
-			throw new UsageError("Tree does not conform to schema.");
-		}
-	}
-
 	return result;
 }
 
+/**
+ * Throws a UsageError if maybeError indicates a tree is out of schema.
+ */
+export function inSchemaOrThrow(maybeError: SchemaValidationErrors): void {
+	if (maybeError !== SchemaValidationErrors.NoError) {
+		throw new UsageError("Tree does not conform to schema.");
+	}
+}
+
 /**
  * Transforms data under a Leaf schema.
  * @param data - The tree data to be transformed. Must be a {@link TreeValue}.
@@ -268,7 +211,7 @@ function leafToMapTree(
 	data: InsertableContent,
 	schema: TreeNodeSchema,
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
-): MapTree {
+): ExclusiveMapTree {
 	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]`.
@@ -293,13 +236,13 @@ function leafToMapTree(
 }
 
 /**
- * Checks an incoming value to ensure it is compatible with our serialization format.
+ * 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: TreeValue,
+	value: TreeLeafValue,
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
 ): TreeValue {
 	switch (typeof value) {
@@ -321,8 +264,19 @@ function mapValueWithFallbacks(
 				return value;
 			}
 		}
-		default:
+		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 TypeError(`Received unsupported leaf value: ${value}.`);
 	}
 }
 
@@ -330,90 +284,88 @@ function mapValueWithFallbacks(
  * Transforms data under an Array schema.
  * @param data - The tree data to be transformed.
  * @param allowedTypes - The set of types allowed by the parent context. Used to validate the input tree.
- * @param schemaValidationPolicy - The stored schema and policy to be used for validation, if the policy says schema
- * validation should happen. If it does, the input tree will be validated against this schema + policy, and an error will
- * be thrown if the tree does not conform to the schema. If undefined, no validation against the stored schema is done.
  */
-function arrayToMapTreeFields(
-	data: readonly InsertableContent[],
+function arrayChildToMapTree(
+	child: InsertableContent,
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
-	schemaValidationPolicy: SchemaAndPolicy | undefined,
-): MapTree[] {
-	const mappedData: MapTree[] = [];
-	for (const child of data) {
-		// 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}.`);
-			}
+): ExclusiveMapTree {
+	// 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}.`);
 		}
-		const mappedChild = nodeDataToMapTree(
-			childWithFallback,
-			allowedTypes,
-			schemaValidationPolicy,
-		);
-		mappedData.push(mappedChild);
 	}
-
-	return mappedData;
+	return nodeDataToMapTree(childWithFallback, allowedTypes);
 }
 
 /**
  * Transforms data under an Array schema.
- * @param data - The tree data to be transformed. Must be an array.
+ * @param data - The tree data to be transformed. Must be an iterable.
  * @param schema - The schema associated with the value.
  * @param schemaValidationPolicy - The stored schema and policy to be used for validation, if the policy says schema
  * validation should happen. If it does, the input tree will be validated against this schema + policy, and an error will
  * be thrown if the tree does not conform to the schema. If undefined, no validation against the stored schema is done.
  */
-function arrayToMapTree(data: InsertableContent, schema: TreeNodeSchema): MapTree {
+function arrayToMapTree(data: InsertableContent, schema: TreeNodeSchema): ExclusiveMapTree {
 	assert(schema.kind === NodeKind.Array, 0x922 /* Expected an array schema. */);
-	if (!isReadonlyArray(data)) {
+	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 = arrayToMapTreeFields(data, allowedChildTypes, undefined);
+	const mappedData = Array.from(data, (child) =>
+		arrayChildToMapTree(child, allowedChildTypes),
+	);
 
-	// Array node children are represented as a single field entry denoted with `EmptyKey`
-	const fieldsEntries: [FieldKey, MapTree[]][] =
-		mappedData.length === 0 ? [] : [[EmptyKey, mappedData]];
-	const fields = new Map<FieldKey, MapTree[]>(fieldsEntries);
+	// Array nodes have a single `EmptyKey` field:
+	const fieldsEntries = mappedData.length === 0 ? [] : ([[EmptyKey, mappedData]] as const);
 
 	return {
 		type: brand(schema.identifier),
-		fields,
+		fields: new Map(fieldsEntries),
 	};
 }
 
 /**
  * Transforms data under a Map schema.
- * @param data - The tree data to be transformed. Must be a TypeScript Map.
+ * @param data - The tree data to be transformed. Must be an iterable.
  * @param schema - The schema associated with the value.
  * @param schemaValidationPolicy - The stored schema and policy to be used for validation, if the policy says schema
  * validation should happen. If it does, the input tree will be validated against this schema + policy, and an error will
  * be thrown if the tree does not conform to the schema. If undefined, no validation against the stored schema is done.
  */
-function mapToMapTree(data: InsertableContent, schema: TreeNodeSchema): MapTree {
+function mapToMapTree(data: InsertableContent, schema: TreeNodeSchema): ExclusiveMapTree {
 	assert(schema.kind === NodeKind.Map, 0x923 /* Expected a Map schema. */);
-	if (!(data instanceof Map)) {
+	if (!(typeof data === "object" && data !== null)) {
 		throw new UsageError(`Input data is incompatible with Map schema: ${data}`);
 	}
 
 	const allowedChildTypes = normalizeAllowedTypes(schema.info as ImplicitAllowedTypes);
 
-	const transformedFields = new Map<FieldKey, MapTree[]>();
-	for (const [key, value] of data) {
+	const fieldsIterator = (
+		Symbol.iterator in data
+			? // Support iterables of key value pairs (including Map objects)
+				data
+			: // Support record objects for JSON style Map data
+				Object.entries(data)
+	) as Iterable<readonly [string, InsertableContent]>;
+
+	const transformedFields = new Map<FieldKey, ExclusiveMapTree[]>();
+	for (const item of fieldsIterator) {
+		if (!isReadonlyArray(item) || item.length !== 2 || typeof item[0] !== "string") {
+			throw new UsageError(`Input data is incompatible with map entry: ${item}`);
+		}
+		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 mappedField = nodeDataToMapTree(value, allowedChildTypes, undefined);
+			const mappedField = nodeDataToMapTree(value, allowedChildTypes);
 			transformedFields.set(brand(key), [mappedField]);
 		}
 	}
@@ -429,19 +381,20 @@ function mapToMapTree(data: InsertableContent, schema: TreeNodeSchema): MapTree
  * @param data - The tree data to be transformed. Must be a Record-like object.
  * @param schema - The schema associated with the value.
  */
-function objectToMapTree(data: InsertableContent, schema: TreeNodeSchema): MapTree {
-	assert(schema.kind === NodeKind.Object, 0x924 /* Expected an Object schema. */);
+function objectToMapTree(data: InsertableContent, schema: TreeNodeSchema): ExclusiveMapTree {
+	assert(isObjectNodeSchema(schema), 0x924 /* Expected an Object schema. */);
 	if (typeof data !== "object" || data === null) {
 		throw new UsageError(`Input data is incompatible with Object schema: ${data}`);
 	}
 
-	const fields = new Map<FieldKey, MapTree[]>();
+	const fields = new Map<FieldKey, ExclusiveMapTree[]>();
 
-	// Loop through field keys without data, and assign value from its default provider.
-	for (const key of Object.keys(schema.info as Record<string, ImplicitFieldSchema>)) {
-		const value = (data as Record<string, InsertableContent>)[key];
-		if (value !== undefined && Object.hasOwnProperty.call(data, key)) {
-			setFieldValue(fields, value, getObjectFieldSchema(schema, key), key);
+	// Loop through field keys without data.
+	// This does NOT apply defaults.
+	for (const [key, fieldInfo] of schema.flexKeyMap) {
+		if (Object.hasOwnProperty.call(data, key)) {
+			const value = (data as Record<string, InsertableContent>)[key as string];
+			setFieldValue(fields, value, fieldInfo.schema, fieldInfo.storedKey);
 		}
 	}
 
@@ -455,31 +408,16 @@ function setFieldValue(
 	fields: Map<FieldKey, readonly MapTree[]>,
 	fieldValue: InsertableContent | undefined,
 	fieldSchema: FieldSchema,
-	key: string,
+	flexKey: FieldKey,
 ): void {
 	if (fieldValue !== undefined) {
-		const mappedChildTree = nodeDataToMapTree(
-			fieldValue,
-			fieldSchema.allowedTypeSet,
-			undefined,
-		);
-		const flexKey: FieldKey = brand(getStoredKey(key, fieldSchema));
+		const mappedChildTree = nodeDataToMapTree(fieldValue, fieldSchema.allowedTypeSet);
 
 		assert(!fields.has(flexKey), 0x956 /* Keys must not be duplicated */);
 		fields.set(flexKey, [mappedChildTree]);
 	}
 }
 
-function getObjectFieldSchema(schema: TreeNodeSchema, key: string): FieldSchema {
-	assert(schema.kind === NodeKind.Object, 0x926 /* Expected an Object schema. */);
-	const fields = schema.info as Record<string, ImplicitFieldSchema>;
-	if (fields[key] === undefined) {
-		fail(`Field "${key}" not found in schema "${schema.identifier}".`);
-	} else {
-		return normalizeFieldSchema(fields[key]);
-	}
-}
-
 function getType(
 	data: InsertableContent,
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
@@ -496,31 +434,17 @@ function getType(
 		possibleTypes.length !== 0,
 		0x84e /* data is incompatible with all types allowed by the schema */,
 	);
-	checkInput(
-		possibleTypes.length === 1,
-		() =>
+	if (possibleTypes.length !== 1) {
+		throw new UsageError(
 			`The provided data is compatible with more than one type allowed by the schema.
 The set of possible types is ${JSON.stringify([
 				...possibleTypes.map((schema) => schema.identifier),
 			])}.
 Explicitly construct an unhydrated node of the desired type to disambiguate.
 For class-based schema, this can be done by replacing an expression like "{foo: 1}" with "new MySchema({foo: 1})".`,
-	);
-	return possibleTypes[0];
-}
-
-/**
- * An invalid tree has been provided, presumably by the user of this package.
- * Throw and an error that properly preserves the message (unlike asserts which will get hard to read short codes intended for package internal logic errors).
- */
-function invalidInput(message: string): never {
-	throw new UsageError(message);
-}
-
-function checkInput(condition: boolean, message: string | (() => string)): asserts condition {
-	if (!condition) {
-		invalidInput(typeof message === "string" ? message : message());
+		);
 	}
+	return possibleTypes[0] ?? oob();
 }
 
 /**
@@ -530,13 +454,41 @@ export function getPossibleTypes(
 	allowedTypes: ReadonlySet<TreeNodeSchema>,
 	data: ContextuallyTypedNodeData,
 ): TreeNodeSchema[] {
+	let best = CompatibilityLevel.None;
 	const possibleTypes: TreeNodeSchema[] = [];
 	for (const schema of allowedTypes) {
-		if (shallowCompatibilityTest(schema, data)) {
+		const level = shallowCompatibilityTest(schema, data);
+		if (level > best) {
+			possibleTypes.length = 0;
+			best = level;
+		}
+		if (best === level) {
 			possibleTypes.push(schema);
 		}
 	}
-	return possibleTypes;
+	return best === CompatibilityLevel.None ? [] : possibleTypes;
+}
+
+/**
+ * Indicates a compatibility level for inferring a schema to apply to insertable data.
+ * @remarks
+ * Only the highest compatibility options are used.
+ * This approach allows adding new possible matching at a new lower compatibility level as a non breaking change,
+ * since that way they can't make a case that was compatible before ambiguous now.
+ */
+enum CompatibilityLevel {
+	/**
+	 * Not compatible. Constructor typing indicates incompatibility.
+	 */
+	None = 0,
+	/**
+	 * Additional compatibility cases added in Fluid Framework 2.2.
+	 */
+	Low = 1,
+	/**
+	 * Compatible in Fluid Framework 2.0.
+	 */
+	Normal = 2,
 }
 
 /**
@@ -549,43 +501,69 @@ export function getPossibleTypes(
 function shallowCompatibilityTest(
 	schema: TreeNodeSchema,
 	data: ContextuallyTypedNodeData,
-): boolean {
+): CompatibilityLevel {
 	assert(
 		data !== undefined,
 		0x889 /* undefined cannot be used as contextually typed data. Use ContextuallyTypedFieldData. */,
 	);
 
 	if (isTreeValue(data)) {
-		return allowsValue(schema, data);
+		return allowsValue(schema, data) ? CompatibilityLevel.Normal : CompatibilityLevel.None;
 	}
 	if (schema.kind === NodeKind.Leaf) {
-		return false;
+		return CompatibilityLevel.None;
 	}
 
-	if (typeNameSymbol in data) {
-		return data[typeNameSymbol] === schema.identifier;
+	// Typing (of schema based constructors and thus implicit node construction)
+	// allows iterables for constructing maps and arrays.
+	// Some users of this API may have unions of maps and arrays,
+	// and rely on Arrays ending up as array nodes and maps as Map nodes,
+	// despite both being iterable and thus compatible with both.
+	// This uses a priority based system where an array would be parsed as an array when unioned with a map,
+	// but if in a map only context, could still be used as a map.
+
+	if (data instanceof Map) {
+		switch (schema.kind) {
+			case NodeKind.Map:
+				return CompatibilityLevel.Normal;
+			case NodeKind.Array:
+				// Maps are iterable, so type checking does allow constructing an ArrayNode from a map if the array's type is an array that includes the key and value types of the map.
+				return CompatibilityLevel.Low;
+			default:
+				return CompatibilityLevel.None;
+		}
 	}
 
 	if (isReadonlyArray(data)) {
-		return schema.kind === NodeKind.Array;
-	}
-	if (schema.kind === NodeKind.Array) {
-		return false;
+		switch (schema.kind) {
+			case NodeKind.Array:
+				return CompatibilityLevel.Normal;
+			case NodeKind.Map:
+				// Arrays are iterable, so type checking does allow constructing an array from a MapNode from an if the array's type is key values pairs for the map.
+				return CompatibilityLevel.Low;
+			default:
+				return CompatibilityLevel.None;
+		}
 	}
 
-	if (data instanceof Map) {
-		return schema.kind === NodeKind.Map;
+	const mapOrArray = schema.kind === NodeKind.Array || schema.kind === NodeKind.Map;
+
+	if (Symbol.iterator in data) {
+		return mapOrArray ? CompatibilityLevel.Normal : CompatibilityLevel.None;
 	}
-	if (schema.kind === NodeKind.Map) {
-		return false;
+
+	// At this point, it is assumed data is a record-like object since all the other cases have been eliminated.
+
+	if (schema.kind === NodeKind.Array) {
+		return CompatibilityLevel.None;
 	}
 
-	// Assume record-like object
-	if (schema.kind !== NodeKind.Object) {
-		return false;
+	if (schema.kind === NodeKind.Map) {
+		// When not unioned with an ObjectNode, allow objects to be used to create maps.
+		return CompatibilityLevel.Low;
 	}
 
-	const fields = schema.info as Record<string, ImplicitFieldSchema>;
+	assert(isObjectNodeSchema(schema), 0x9e6 /* unexpected schema kind */);
 
 	// TODO: Improve type inference by making this logic more thorough. Handle at least:
 	// * Types which are strict subsets of other types in the same polymorphic union
@@ -595,14 +573,13 @@ function shallowCompatibilityTest(
 	// TODO#7441: Consider allowing data to be inserted which has keys that are extraneous/unknown to the schema (those keys are ignored)
 
 	// If the schema has a required key which is not present in the input object, reject it.
-	for (const [fieldKey, fieldSchema] of Object.entries(fields)) {
-		const normalizedFieldSchema = normalizeFieldSchema(fieldSchema);
-		if (data[fieldKey] === undefined && normalizedFieldSchema.kind === FieldKind.Required) {
-			return false;
+	for (const [fieldKey, fieldSchema] of schema.fields) {
+		if (data[fieldKey] === undefined && fieldSchema.requiresValue) {
+			return CompatibilityLevel.None;
 		}
 	}
 
-	return true;
+	return CompatibilityLevel.Normal;
 }
 
 function allowsValue(schema: TreeNodeSchema, value: TreeValue): boolean {
@@ -626,7 +603,10 @@ export type ContextuallyTypedNodeData =
 	| boolean
 	// eslint-disable-next-line @rushstack/no-new-null
 	| null
-	| readonly ContextuallyTypedNodeData[];
+	| readonly ContextuallyTypedNodeData[]
+	| ReadonlyMap<string, ContextuallyTypedNodeData>
+	| Iterable<ContextuallyTypedNodeData>
+	| Iterable<[string, ContextuallyTypedNodeData]>;
 
 /**
  * Content of a field which needs external schema information to interpret.
@@ -641,12 +621,6 @@ export type ContextuallyTypedFieldData = ContextuallyTypedNodeData | undefined;
  * Object case of {@link ContextuallyTypedNodeData}.
  */
 export interface ContextuallyTypedNodeDataObject {
-	/**
-	 * The type of the node.
-	 * If this node is well-formed, it must follow this schema.
-	 */
-	readonly [typeNameSymbol]?: string;
-
 	/**
 	 * Fields of this node, indexed by their field keys.
 	 *
@@ -664,17 +638,16 @@ export interface ContextuallyTypedNodeDataObject {
 }
 
 /**
- * Walk the given {@link MapTree} and provide any field defaults for fields that are missing in the tree but present in the schema.
- * @param mapTree - The tree to populate with defaults
+ * Walk the given {@link ExclusiveMapTree} and deeply provide any field defaults for fields that are missing in the tree but present in the schema.
+ * @param mapTree - The tree to populate with defaults. This is borrowed: no references to it are kept by this function.
  * @param allowedTypes - Some {@link TreeNodeSchema}, at least one of which the input tree must conform to
  * @param context - An optional context for generating defaults.
  * If present, all applicable defaults will be provided.
  * If absent, only defaults produced by a {@link ConstantFieldProvider} will be provided, and defaults produced by a {@link ContextualFieldProvider} will be ignored.
- * @remarks This function mutates the input tree by adding new fields to the field maps where applicable.
- * @privateRemarks TODO: Create a more established type for mutable MapTrees, and use where appropriate.
+ * @remarks This function mutates the input tree by deeply adding new fields to the field maps where applicable.
  */
-function addDefaultsToMapTree(
-	mapTree: MapTree,
+export function addDefaultsToMapTree(
+	mapTree: ExclusiveMapTree,
 	allowedTypes: ImplicitAllowedTypes,
 	context: NodeKeyManager | undefined,
 ): void {
@@ -682,6 +655,32 @@ function addDefaultsToMapTree(
 		find(normalizeAllowedTypes(allowedTypes), (s) => s.identifier === mapTree.type) ??
 		fail("MapTree is incompatible with schema");
 
+	if (isObjectNodeSchema(schema)) {
+		for (const [_key, fieldInfo] of schema.flexKeyMap) {
+			const field = mapTree.fields.get(fieldInfo.storedKey);
+			if (field !== undefined) {
+				for (const child of field) {
+					addDefaultsToMapTree(child, fieldInfo.schema.allowedTypes, context);
+				}
+			} else {
+				const defaultProvider = fieldInfo.schema.props?.defaultProvider;
+				if (defaultProvider !== undefined) {
+					const fieldProvider = extractFieldProvider(defaultProvider);
+					const data = provideDefault(fieldProvider, context);
+					if (data !== undefined) {
+						setFieldValue(mapTree.fields, data, fieldInfo.schema, fieldInfo.storedKey);
+						// call addDefaultsToMapTree on newly inserted default values
+						for (const child of mapTree.fields.get(fieldInfo.storedKey) ??
+							fail("Expected field to be populated")) {
+							addDefaultsToMapTree(child, fieldInfo.schema.allowedTypes, context);
+						}
+					}
+				}
+			}
+		}
+		return;
+	}
+
 	switch (schema.kind) {
 		case NodeKind.Array:
 		case NodeKind.Map:
@@ -693,46 +692,18 @@ function addDefaultsToMapTree(
 				}
 			}
 			break;
-		case NodeKind.Object:
-			{
-				for (const [key, fieldSchema] of Object.entries(
-					schema.info as Record<FieldKey, ImplicitFieldSchema>,
-				) as [FieldKey, ImplicitFieldSchema][]) {
-					const field = mapTree.fields.get(key);
-					if (field !== undefined) {
-						for (const child of field) {
-							addDefaultsToMapTree(
-								child,
-								getObjectFieldSchema(schema, key).allowedTypes,
-								context,
-							);
-						}
-					} else if (fieldSchema instanceof FieldSchema) {
-						const defaultProvider = fieldSchema.props?.defaultProvider;
-						if (defaultProvider !== undefined) {
-							const fieldProvider = extractFieldProvider(defaultProvider);
-							const data = provideDefault(fieldProvider, context);
-							if (data !== undefined) {
-								const mutableMapTree = mapTree as typeof mapTree & {
-									fields: Map<FieldKey, readonly MapTree[]>;
-								};
-								setFieldValue(mutableMapTree.fields, data, fieldSchema, key);
-								for (const child of mutableMapTree.fields.get(key) ??
-									fail("Expected field to be populated")) {
-									addDefaultsToMapTree(child, fieldSchema.allowedTypes, context);
-								}
-							}
-						}
-					}
-				}
-			}
-			break;
 		default:
 			assert(schema.kind === NodeKind.Leaf, 0x989 /* Unrecognized schema kind */);
 			break;
 	}
 }
 
+/**
+ * Provides the default value (which can be undefined, for example with optional fields), or undefined if a context is required but not provided.
+ * @privateRemarks
+ * It is a bit concerning that there is no way for the caller to know when undefined is returned if that is the default value, or a context was required.
+ * TODO: maybe better formalize the two stage defaulting (without then with context), or rework this design we only do one stage.
+ */
 function provideDefault(
 	fieldProvider: FieldProvider,
 	context: NodeKeyManager | undefined,
@@ -742,6 +713,9 @@ function provideDefault(
 	} else {
 		if (isConstant(fieldProvider)) {
 			return fieldProvider();
+		} else {
+			// Leaving field empty despite it needing a default value since a context was required and non was provided.
+			// Caller better handle this case by providing the default at some other point in time when the context becomes known.
 		}
 	}
 }