tree: Allow MapNodes from Records (#22042)

## Description

Allow `Record` typed object to be used to construct MapNodes.

More details in changeset.

This is one change of several working toward improved JSON
compatibility.

.changeset/green-spies-arrive.md

@@ -0,0 +1,24 @@
+---
+"fluid-framework": minor
+"@fluidframework/tree": minor
+---
+
+Allow `Record` typed object to be used to construct MapNodes.
+
+It is now allowed to construct MapNodes from `Record` typed objects, similar to how maps are expressed in JSON.
+
+Before this change, an `Iterable<string, Child>` was required, but now an object like `{key1: Child1, key2: Child2}` is allowed.
+
+Full example using this new API:
+```typescript
+class Schema extends schemaFactory.map("ExampleMap", schemaFactory.number) {}
+const fromRecord = new Schema({ x: 5 });
+```
+
+This new feature makes it possible for schemas to construct a tree entirely from JSON compatible objects using their constructors,
+as long as they do not require unhydrated nodes to differentiate ambiguous unions,
+or IFluidHandles (which themselevs are not JSON compatible).
+
+Due to limitations of TypeScript and recursive types,
+recursive maps do not advertise support for this feature in their typing,
+but it works at runtime.

packages/dds/tree/api-report/tree.alpha.api.md

@@ -208,6 +208,9 @@ export type Listeners<T extends object> = {
 export interface MakeNominal {
 }
 
+// @public
+export type MapNodeInsertableData<T extends ImplicitAllowedTypes> = Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]> | RestrictiveReadonlyRecord<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>;
+
 // @public
 type NodeBuilderData<T extends TreeNodeSchema> = T extends TreeNodeSchema<string, NodeKind, unknown, infer TBuild> ? TBuild : never;
 
@@ -314,8 +317,8 @@ export class SchemaFactory<out TScope extends string | undefined = string | unde
     readonly boolean: TreeNodeSchema<"com.fluidframework.leaf.boolean", NodeKind.Leaf, boolean, boolean>;
     readonly handle: TreeNodeSchema<"com.fluidframework.leaf.handle", NodeKind.Leaf, IFluidHandle<unknown>, IFluidHandle<unknown>>;
     get identifier(): FieldSchema<FieldKind.Identifier, typeof SchemaFactory.string>;
-    map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>, Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, true, T>;
-    map<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>, Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, true, T>;
+    map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>, MapNodeInsertableData<T>, true, T>;
+    map<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>, MapNodeInsertableData<T>, true, T>;
     mapRecursive<Name extends TName, const T extends Unenforced<ImplicitAllowedTypes>>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>>, {
         [Symbol.iterator](): Iterator<[
         string,

packages/dds/tree/api-report/tree.beta.api.md

@@ -208,6 +208,9 @@ export type Listeners<T extends object> = {
 export interface MakeNominal {
 }
 
+// @public
+export type MapNodeInsertableData<T extends ImplicitAllowedTypes> = Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]> | RestrictiveReadonlyRecord<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>;
+
 // @public
 type NodeBuilderData<T extends TreeNodeSchema> = T extends TreeNodeSchema<string, NodeKind, unknown, infer TBuild> ? TBuild : never;
 
@@ -314,8 +317,8 @@ export class SchemaFactory<out TScope extends string | undefined = string | unde
     readonly boolean: TreeNodeSchema<"com.fluidframework.leaf.boolean", NodeKind.Leaf, boolean, boolean>;
     readonly handle: TreeNodeSchema<"com.fluidframework.leaf.handle", NodeKind.Leaf, IFluidHandle<unknown>, IFluidHandle<unknown>>;
     get identifier(): FieldSchema<FieldKind.Identifier, typeof SchemaFactory.string>;
-    map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>, Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, true, T>;
-    map<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>, Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, true, T>;
+    map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>, MapNodeInsertableData<T>, true, T>;
+    map<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>, MapNodeInsertableData<T>, true, T>;
     mapRecursive<Name extends TName, const T extends Unenforced<ImplicitAllowedTypes>>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>>, {
         [Symbol.iterator](): Iterator<[
         string,

packages/dds/tree/api-report/tree.public.api.md

@@ -208,6 +208,9 @@ export type Listeners<T extends object> = {
 export interface MakeNominal {
 }
 
+// @public
+export type MapNodeInsertableData<T extends ImplicitAllowedTypes> = Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]> | RestrictiveReadonlyRecord<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>;
+
 // @public
 type NodeBuilderData<T extends TreeNodeSchema> = T extends TreeNodeSchema<string, NodeKind, unknown, infer TBuild> ? TBuild : never;
 
@@ -314,8 +317,8 @@ export class SchemaFactory<out TScope extends string | undefined = string | unde
     readonly boolean: TreeNodeSchema<"com.fluidframework.leaf.boolean", NodeKind.Leaf, boolean, boolean>;
     readonly handle: TreeNodeSchema<"com.fluidframework.leaf.handle", NodeKind.Leaf, IFluidHandle<unknown>, IFluidHandle<unknown>>;
     get identifier(): FieldSchema<FieldKind.Identifier, typeof SchemaFactory.string>;
-    map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>, Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, true, T>;
-    map<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>, Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, true, T>;
+    map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>, MapNodeInsertableData<T>, true, T>;
+    map<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>, MapNodeInsertableData<T>, true, T>;
     mapRecursive<Name extends TName, const T extends Unenforced<ImplicitAllowedTypes>>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>>, {
         [Symbol.iterator](): Iterator<[
         string,

packages/dds/tree/src/index.ts

@@ -384,3 +384,8 @@ export {
 	 */
 	InternalTypes,
 };
+
+// Internal/System types:
+// These would be put in `internalTypes` except doing so tents to cause errors like:
+// The inferred type of 'NodeMap' cannot be named without a reference to '../../node_modules/@fluidframework/tree/lib/internalTypes.js'. This is likely not portable. A type annotation is necessary.
+export type { MapNodeInsertableData } from "./simple-tree/index.js";

packages/dds/tree/src/simple-tree/index.ts

@@ -95,5 +95,5 @@ export {
 	type TreeObjectNode,
 	setField,
 } from "./objectNode.js";
-export type { TreeMapNode } from "./mapNode.js";
+export type { TreeMapNode, MapNodeInsertableData } from "./mapNode.js";
 export { mapTreeFromNodeData } from "./toMapTree.js";

packages/dds/tree/src/simple-tree/mapNode.ts

@@ -13,6 +13,7 @@ import {
 	isMapTreeNode,
 } from "../feature-libraries/index.js";
 import {
+	type FactoryContent,
 	type InsertableContent,
 	getProxyForField,
 	prepareContentForHydration,
@@ -33,6 +34,7 @@ import { mapTreeFromNodeData } from "./toMapTree.js";
 import { type MostDerivedData, type TreeNode, TreeNodeValid } from "./types.js";
 import { getFlexSchema } from "./toFlexSchema.js";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import type { RestrictiveReadonlyRecord } from "../util/index.js";
 
 /**
  * A map of string keys to tree objects.
@@ -125,7 +127,7 @@ const handler: ProxyHandler<TreeMapNode> = {
 };
 
 abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends TreeNodeValid<
-	Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>
+	MapNodeInsertableData<T>
 > {
 	public static readonly kind = NodeKind.Map;
 
@@ -237,10 +239,7 @@ export function mapSchema<
 		): MapTreeNode {
 			return getOrCreateMapTreeNode(
 				flexSchema,
-				mapTreeFromNodeData(
-					input as Iterable<readonly [string, InsertableContent]>,
-					this as unknown as ImplicitAllowedTypes,
-				),
+				mapTreeFromNodeData(input as FactoryContent, this as unknown as ImplicitAllowedTypes),
 			);
 		}
 
@@ -263,9 +262,17 @@ export function mapSchema<
 		TName,
 		NodeKind.Map,
 		TreeMapNode<T> & WithType<TName>,
-		Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,
+		MapNodeInsertableData<T>,
 		ImplicitlyConstructable,
 		T
 	> = schema;
 	return schemaErased;
 }
+
+/**
+ * Content which can be used to construct a Map node, explicitly or implicitly.
+ * @system @public
+ */
+export type MapNodeInsertableData<T extends ImplicitAllowedTypes> =
+	| Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>
+	| RestrictiveReadonlyRecord<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>;

packages/dds/tree/src/simple-tree/schemaFactory.ts

@@ -48,7 +48,7 @@ import {
 	type TreeObjectNode,
 	objectSchema,
 } from "./objectNode.js";
-import { type TreeMapNode, mapSchema } from "./mapNode.js";
+import { type MapNodeInsertableData, type TreeMapNode, mapSchema } from "./mapNode.js";
 import type {
 	FieldSchemaUnsafe,
 	// Adding these unused imports makes the generated d.ts file produced by TypeScript stop breaking API-Extractor's rollup generation.
@@ -297,7 +297,7 @@ export class SchemaFactory<
 		ScopedSchemaName<TScope, `Map<${string}>`>,
 		NodeKind.Map,
 		TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>,
-		Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,
+		MapNodeInsertableData<T>,
 		true,
 		T
 	>;
@@ -319,22 +319,15 @@ export class SchemaFactory<
 		ScopedSchemaName<TScope, Name>,
 		NodeKind.Map,
 		TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>,
-		Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,
+		MapNodeInsertableData<T>,
 		true,
 		T
 	>;
 
 	public map<const T extends ImplicitAllowedTypes>(
 		nameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),
 		allowedTypes?: T,
-	): TreeNodeSchema<
-		string,
-		NodeKind.Map,
-		TreeMapNode<T>,
-		Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,
-		true,
-		T
-	> {
+	): TreeNodeSchema<string, NodeKind.Map, TreeMapNode<T>, MapNodeInsertableData<T>, true, T> {
 		if (allowedTypes === undefined) {
 			const types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];
 			const fullName = structuralName("Map", types);
@@ -352,7 +345,7 @@ export class SchemaFactory<
 				string,
 				NodeKind.Map,
 				TreeMapNode<T>,
-				Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,
+				MapNodeInsertableData<T>,
 				true,
 				T
 			>;
@@ -378,7 +371,7 @@ export class SchemaFactory<
 		ScopedSchemaName<TScope, Name>,
 		NodeKind.Map,
 		TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>,
-		Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,
+		MapNodeInsertableData<T>,
 		ImplicitlyConstructable,
 		T
 	> {
@@ -722,6 +715,8 @@ export class SchemaFactory<
 					[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]
 				>;
 			},
+			// Ideally this would be included, but doing so breaks recursive types.
+			// | RestrictiveReadonlyRecord<string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,
 			false,
 			T
 		>;

packages/dds/tree/src/simple-tree/toMapTree.ts

@@ -375,14 +375,22 @@ function arrayToMapTree(data: InsertableContent, schema: TreeNodeSchema): Exclus
  */
 function mapToMapTree(data: InsertableContent, schema: TreeNodeSchema): ExclusiveMapTree {
 	assert(schema.kind === NodeKind.Map, 0x923 /* Expected a Map schema. */);
-	if (!(typeof data === "object" && data !== null && Symbol.iterator in data)) {
+	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 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 data as Iterable<readonly [string, InsertableContent]>) {
+	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}`);
 		}
@@ -595,11 +603,17 @@ function shallowCompatibilityTest(
 		return mapOrArray ? CompatibilityLevel.Normal : CompatibilityLevel.None;
 	}
 
-	if (mapOrArray) {
+	// 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.Map) {
+		// When not unioned with an ObjectNode, allow objects to be used to create maps.
+		return CompatibilityLevel.Low;
+	}
+
 	assert(isObjectNodeSchema(schema), "unexpected schema kind");
 
 	// TODO: Improve type inference by making this logic more thorough. Handle at least:

packages/dds/tree/src/test/simple-tree/mapNode.spec.ts

@@ -73,6 +73,8 @@ describe("MapNode", () => {
 		assert.deepEqual([...fromMap], data);
 		const fromIterable = new Schema(new Map(data).entries());
 		assert.deepEqual([...fromIterable], data);
+		const fromRecord = new Schema({ x: 5 });
+		assert.deepEqual([...fromRecord], data);
 	});
 
 	describe("implicit construction", () => {
@@ -91,5 +93,9 @@ describe("MapNode", () => {
 			const fromIterable = new Root({ data: new Map(data).entries() });
 			assert.deepEqual([...fromIterable.data], data);
 		});
+		it("fromRecord", () => {
+			const fromRecord = new Root({ data: { x: 5 } });
+			assert.deepEqual([...fromRecord.data], data);
+		});
 	});
 });

packages/framework/fluid-framework/api-report/fluid-framework.beta.api.md

@@ -545,6 +545,9 @@ export type Listeners<T extends object> = {
 export interface MakeNominal {
 }
 
+// @public
+export type MapNodeInsertableData<T extends ImplicitAllowedTypes> = Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]> | RestrictiveReadonlyRecord<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>;
+
 // @public
 export type MemberChangedListener<M extends IMember> = (clientId: string, member: M) => void;
 
@@ -660,8 +663,8 @@ export class SchemaFactory<out TScope extends string | undefined = string | unde
     readonly boolean: TreeNodeSchema<"com.fluidframework.leaf.boolean", NodeKind.Leaf, boolean, boolean>;
     readonly handle: TreeNodeSchema<"com.fluidframework.leaf.handle", NodeKind.Leaf, IFluidHandle<unknown>, IFluidHandle<unknown>>;
     get identifier(): FieldSchema<FieldKind.Identifier, typeof SchemaFactory.string>;
-    map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>, Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, true, T>;
-    map<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>, Iterable<readonly [string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, true, T>;
+    map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>, MapNodeInsertableData<T>, true, T>;
+    map<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>, MapNodeInsertableData<T>, true, T>;
     mapRecursive<Name extends TName, const T extends Unenforced<ImplicitAllowedTypes>>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>>, {
         [Symbol.iterator](): Iterator<[
         string,