@fluidframework/tree 2.43.0 → 2.50.0

package/src/simple-tree/api/simpleSchemaToJsonSchema.ts

@@ -18,17 +18,24 @@ import type {
 	JsonObjectNodeSchema,
 	JsonTreeSchema,
 	JsonLeafSchemaType,
+	JsonRecordNodeSchema,
 } from "./jsonSchema.js";
 import { FieldKind } from "../schemaTypes.js";
 import type {
 	SimpleArrayNodeSchema,
 	SimpleLeafNodeSchema,
 	SimpleMapNodeSchema,
+	SimpleRecordNodeSchema,
 } from "../simpleSchema.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import type { TreeSchema } from "./configuration.js";
 import type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
-import { ArrayNodeSchema, MapNodeSchema, ObjectNodeSchema } from "../node-kinds/index.js";
+import {
+	ArrayNodeSchema,
+	isMapNodeSchema,
+	isRecordNodeSchema,
+	ObjectNodeSchema,
+} from "../node-kinds/index.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
 
 /**
@@ -88,8 +95,8 @@ function convertNodeSchema(
 ): JsonNodeSchema {
 	if (schema instanceof ArrayNodeSchema) {
 		return convertArrayNodeSchema(schema);
-	} else if (schema instanceof MapNodeSchema) {
-		return convertMapNodeSchema(schema);
+	} else if (isMapNodeSchema(schema) || isRecordNodeSchema(schema)) {
+		return convertRecordLikeNodeSchema(schema);
 	} else if (schema instanceof ObjectNodeSchema) {
 		return convertObjectNodeSchema(schema, options);
 	} else if (schema instanceof LeafNodeSchema) {
@@ -191,15 +198,17 @@ export function convertObjectNodeSchema(
 	return transformedNode;
 }
 
-function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
+function convertRecordLikeNodeSchema(
+	schema: SimpleRecordNodeSchema | SimpleMapNodeSchema,
+): JsonMapNodeSchema | JsonRecordNodeSchema {
 	const allowedTypes: JsonSchemaRef[] = [];
 	schema.allowedTypesIdentifiers.forEach((type) => {
 		allowedTypes.push(createSchemaRef(type));
 	});
 
-	const output: Mutable<JsonMapNodeSchema> = {
+	const output = {
 		type: "object",
-		_treeNodeSchemaKind: NodeKind.Map,
+		_treeNodeSchemaKind: schema.kind,
 		patternProperties: {
 			"^.*$": hasSingle(allowedTypes)
 				? allowedTypes[0]
@@ -207,7 +216,7 @@ function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
 						anyOf: allowedTypes,
 					},
 		},
-	};
+	} as const;
 
 	copyProperty(schema.metadata, "description", output);
 

package/src/simple-tree/api/treeBeta.ts

@@ -85,8 +85,8 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>
 	 */
 	nodeChanged: (
 		data: NodeChangedData<TNode> &
-			// For object and Map nodes, make properties specific to them required instead of optional:
-			(TNode extends WithType<string, NodeKind.Map | NodeKind.Object>
+			// Make the properties of object, map, and record nodes required:
+			(TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record>
 				? Required<Pick<NodeChangedData<TNode>, "changedProperties">>
 				: unknown),
 	) => void;

package/src/simple-tree/api/treeNodeApi.ts

@@ -38,7 +38,7 @@ import {
 	getOrCreateInnerNode,
 } from "../core/index.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
-import { isObjectNodeSchema } from "../node-kinds/index.js";
+import { isArrayNodeSchema, isObjectNodeSchema } from "../node-kinds/index.js";
 import { tryGetTreeNodeForField } from "../getTreeNodeForField.js";
 
 /**
@@ -193,7 +193,7 @@ export const treeNodeApi: TreeNodeApi = {
 						);
 						listener({ changedProperties });
 					});
-				} else if (nodeSchema.kind === NodeKind.Array) {
+				} else if (isArrayNodeSchema(nodeSchema)) {
 					return kernel.events.on("childrenChangedAfterBatch", () => {
 						listener({ changedProperties: undefined });
 					});

package/src/simple-tree/api/typesUnsafe.ts

@@ -527,3 +527,18 @@ export interface MapNodeCustomizableSchemaUnsafe<
 			TCustomMetadata
 		>,
 		SimpleMapNodeSchema<TCustomMetadata> {}
+
+/**
+ * {@link Unenforced} version of {@link TreeRecordNode}.
+ * @remarks
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @sealed @alpha
+ */
+export interface TreeRecordNodeUnsafe<
+	TAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe,
+> extends Record<string, System_Unsafe.TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>>,
+		TreeNode {
+	[Symbol.iterator](): IterableIterator<
+		[string, System_Unsafe.TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>]
+	>;
+}

package/src/simple-tree/api/viewSchemaToSimpleSchema.ts

@@ -13,10 +13,16 @@ import type {
 	SimpleNodeSchema,
 	SimpleObjectFieldSchema,
 	SimpleObjectNodeSchema,
+	SimpleRecordNodeSchema,
 	SimpleTreeSchema,
 } from "../simpleSchema.js";
 import { NodeKind } from "../core/index.js";
-import { ArrayNodeSchema, MapNodeSchema, ObjectNodeSchema } from "../node-kinds/index.js";
+import {
+	ArrayNodeSchema,
+	MapNodeSchema,
+	ObjectNodeSchema,
+	RecordNodeSchema,
+} from "../node-kinds/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
 
@@ -49,7 +55,8 @@ export function toSimpleTreeSchema(
 				nodeSchema instanceof ArrayNodeSchema ||
 					nodeSchema instanceof MapNodeSchema ||
 					nodeSchema instanceof LeafNodeSchema ||
-					nodeSchema instanceof ObjectNodeSchema,
+					nodeSchema instanceof ObjectNodeSchema ||
+					nodeSchema instanceof RecordNodeSchema,
 				0xb60 /* Invalid schema */,
 			);
 			const outSchema = copySchemaObjects ? copySimpleNodeSchema(nodeSchema) : nodeSchema;
@@ -82,7 +89,8 @@ function copySimpleNodeSchema(schema: SimpleNodeSchema): SimpleNodeSchema {
 			return copySimpleLeafSchema(schema);
 		case NodeKind.Array:
 		case NodeKind.Map:
-			return copySimpleMapOrArraySchema(schema);
+		case NodeKind.Record:
+			return copySimpleSchemaWithAllowedTypes(schema);
 		case NodeKind.Object:
 			return copySimpleObjectSchema(schema);
 		default:
@@ -99,9 +107,9 @@ function copySimpleLeafSchema(schema: SimpleLeafNodeSchema): SimpleLeafNodeSchem
 	};
 }
 
-function copySimpleMapOrArraySchema(
-	schema: SimpleMapNodeSchema | SimpleArrayNodeSchema,
-): SimpleMapNodeSchema | SimpleArrayNodeSchema {
+function copySimpleSchemaWithAllowedTypes(
+	schema: SimpleMapNodeSchema | SimpleArrayNodeSchema | SimpleRecordNodeSchema,
+): SimpleMapNodeSchema | SimpleArrayNodeSchema | SimpleRecordNodeSchema {
 	return {
 		kind: schema.kind,
 		allowedTypesIdentifiers: schema.allowedTypesIdentifiers,

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

@@ -42,6 +42,7 @@ export {
 	getOrCreateNodeFromInnerUnboxedNode,
 } from "./getOrCreateNode.js";
 export {
+	UnhydratedFlexTreeField,
 	UnhydratedFlexTreeNode,
 	UnhydratedSequenceField,
 	UnhydratedContext,

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

@@ -438,19 +438,23 @@ export enum NodeKind {
 	/**
 	 * A node which serves as a map, storing children under string keys.
 	 */
-	Map,
+	Map = 0,
 	/**
 	 * A node which serves as an array, storing children in an ordered sequence.
 	 */
-	Array,
+	Array = 1,
 	/**
 	 * A node which stores a heterogenous collection of children in named fields.
 	 * @remarks
 	 * Each field gets its own schema.
 	 */
-	Object,
+	Object = 2,
 	/**
 	 * A node which stores a single leaf value.
 	 */
-	Leaf,
+	Leaf = 3,
+	/**
+	 * A node which serves as a record, storing children under string keys.
+	 */
+	Record = 4,
 }

package/src/simple-tree/index.ts

@@ -69,6 +69,8 @@ export {
 	type JsonTreeSchema,
 	type JsonFieldSchema,
 	type JsonLeafSchemaType,
+	type JsonRecordNodeSchema,
+	type JsonStringKeyPatternProperties,
 	type TreeSchemaEncodingOptions,
 	getJsonSchema,
 	getSimpleSchema,
@@ -83,6 +85,7 @@ export {
 	type System_Unsafe,
 	type ArrayNodeCustomizableSchemaUnsafe,
 	type MapNodeCustomizableSchemaUnsafe,
+	type TreeRecordNodeUnsafe,
 	type TreeViewAlpha,
 	type TreeBranch,
 	type TreeBranchEvents,
@@ -136,6 +139,7 @@ export type {
 	SimpleNodeSchemaBase,
 	SimpleNodeSchemaBaseAlpha,
 	SimpleObjectFieldSchema,
+	SimpleRecordNodeSchema,
 } from "./simpleSchema.js";
 export {
 	type NodeFromSchema,
@@ -207,11 +211,18 @@ export {
 	type InsertableObjectFromSchemaRecord,
 	type ObjectFromSchemaRecord,
 	ObjectNodeSchema,
+	type ObjectNodeSchemaPrivate,
 	isObjectNodeSchema,
 	type InsertableObjectFromAnnotatedSchemaRecord,
 	type TreeObjectNode,
 	setField,
 	createUnknownOptionalFieldPolicy,
+	isRecordNodeSchema,
+	type RecordNodeCustomizableSchema,
+	type RecordNodeInsertableData,
+	type RecordNodePojoEmulationSchema,
+	RecordNodeSchema,
+	type TreeRecordNode,
 } from "./node-kinds/index.js";
 export {
 	unhydratedFlexTreeFromInsertable,

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

@@ -33,7 +33,18 @@ export {
 	isObjectNodeSchema,
 	type ObjectFromSchemaRecord,
 	ObjectNodeSchema,
+	type ObjectNodeSchemaPrivate,
 	objectSchema,
 	setField,
 	type TreeObjectNode,
 } from "./object/index.js";
+
+export {
+	isRecordNodeSchema,
+	type RecordNodeCustomizableSchema,
+	type RecordNodeInsertableData,
+	type RecordNodePojoEmulationSchema,
+	RecordNodeSchema,
+	recordSchema,
+	type TreeRecordNode,
+} from "./record/index.js";

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

@@ -13,4 +13,8 @@ export {
 	setField,
 	type TreeObjectNode,
 } from "./objectNode.js";
-export { isObjectNodeSchema, ObjectNodeSchema } from "./objectNodeTypes.js";
+export {
+	isObjectNodeSchema,
+	ObjectNodeSchema,
+	type ObjectNodeSchemaPrivate,
+} from "./objectNodeTypes.js";

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

@@ -40,6 +40,7 @@ import {
 	isObjectNodeSchema,
 	type ObjectNodeSchema,
 	type ObjectNodeSchemaInternalData,
+	type ObjectNodeSchemaPrivate,
 } from "./objectNodeTypes.js";
 import { prepareForInsertion } from "../../prepareForInsertion.js";
 import {
@@ -216,7 +217,7 @@ function createFlexKeyMapping(
  * If not provided `{}` is used for the target.
  */
 function createProxyHandler(
-	schema: ObjectNodeSchema & ObjectNodeSchemaInternalData,
+	schema: ObjectNodeSchemaPrivate,
 	allowAdditionalProperties: boolean,
 ): ProxyHandler<TreeNode> {
 	// To satisfy 'deepEquals' level scrutiny, the target of the proxy must be an object with the same
@@ -476,7 +477,7 @@ export function objectSchema<
 		protected static override oneTimeSetup<T2>(this: typeof TreeNodeValid<T2>): Context {
 			// One time initialization that required knowing the most derived type (from this.constructor) and thus has to be lazy.
 			customizable = (this as unknown) !== CustomObjectNode;
-			const schema = this as unknown as ObjectNodeSchema & ObjectNodeSchemaInternalData;
+			const schema = this as unknown as ObjectNodeSchemaPrivate;
 			handler = createProxyHandler(schema, customizable);
 			unhydratedContext = getUnhydratedContext(schema);
 

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

@@ -83,8 +83,11 @@ export const ObjectNodeSchema = {
 	},
 } as const;
 
-export function isObjectNodeSchema(
-	schema: TreeNodeSchema,
-): schema is ObjectNodeSchema & ObjectNodeSchemaInternalData {
+/**
+ * {@link ObjectNodeSchema} with data that is not part of the package-exported API surface.
+ */
+export type ObjectNodeSchemaPrivate = ObjectNodeSchema & ObjectNodeSchemaInternalData;
+
+export function isObjectNodeSchema(schema: TreeNodeSchema): schema is ObjectNodeSchemaPrivate {
 	return schema.kind === NodeKind.Object;
 }

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

@@ -0,0 +1,14 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { recordSchema } from "./recordNode.js";
+export {
+	isRecordNodeSchema,
+	type RecordNodeCustomizableSchema,
+	type RecordNodeInsertableData,
+	type RecordNodePojoEmulationSchema,
+	RecordNodeSchema,
+	type TreeRecordNode,
+} from "./recordNodeTypes.js";