@fluidframework/tree 2.41.0 → 2.43.0-343119

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,
@@ -20,6 +20,7 @@ import {
 	getOrCreate,
 	type RestrictiveStringRecord,
 	type IsUnion,
+	type JsonCompatibleReadOnlyObject,
 } from "../util/index.js";
 
 import type {
@@ -30,12 +31,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";
 
 /**
@@ -295,18 +297,34 @@ export interface FieldProps<TCustomMetadata = unknown> {
 	readonly metadata?: FieldSchemaMetadata<TCustomMetadata>;
 }
 
+/**
+ * {@link FieldProps} extended with additional `alpha` options.
+ *
+ * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+ * See {@link FieldSchemaMetadata.custom}.
+ *
+ * @alpha @input
+ */
+export interface FieldPropsAlpha<TCustomMetadata = unknown>
+	extends FieldProps<TCustomMetadata> {
+	/**
+	 * The persisted metadata for this schema element.
+	 */
+	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
+}
+
 /**
  * A {@link FieldProvider} which requires 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;
 /**
@@ -360,6 +378,22 @@ export interface FieldSchemaMetadata<TCustomMetadata = unknown> {
 	readonly description?: string | undefined;
 }
 
+/**
+ * Metadata associated with a {@link FieldSchema}. Includes fields used by alpha features.
+ *
+ * @remarks Specified via {@link FieldProps.metadata}.
+ *
+ * @sealed
+ * @alpha
+ */
+export interface FieldSchemaMetadataAlpha<TCustomMetadata = unknown>
+	extends FieldSchemaMetadata<TCustomMetadata> {
+	/**
+	 * The persisted metadata for this schema element.
+	 */
+	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
+}
+
 /**
  * Package internal construction API.
  */
@@ -508,12 +542,20 @@ export class FieldSchemaAlpha<
 {
 	private readonly lazyIdentifiers: Lazy<ReadonlySet<string>>;
 	private readonly lazyAnnotatedTypes: Lazy<ReadonlyMap<TreeNodeSchema, AllowedTypeMetadata>>;
+	private readonly propsAlpha: FieldPropsAlpha<TCustomMetadata> | undefined;
 
 	/**
 	 * Metadata on the types of tree nodes allowed on this field.
 	 */
 	public readonly allowedTypesMetadata: AllowedTypesMetadata;
 
+	/**
+	 * Persisted metadata for this field schema.
+	 */
+	public get persistedMetadata(): JsonCompatibleReadOnlyObject | undefined {
+		return this.propsAlpha?.persistedMetadata;
+	}
+
 	static {
 		createFieldSchemaPrivate = <
 			Kind2 extends FieldKind,
@@ -522,7 +564,7 @@ export class FieldSchemaAlpha<
 		>(
 			kind: Kind2,
 			annotatedAllowedTypes: Types2,
-			props?: FieldProps<TCustomMetadata2>,
+			props?: FieldPropsAlpha<TCustomMetadata2>,
 		) =>
 			new FieldSchemaAlpha(
 				kind,
@@ -536,7 +578,7 @@ export class FieldSchemaAlpha<
 		kind: Kind,
 		types: Types,
 		public readonly annotatedAllowedTypes: ImplicitAnnotatedAllowedTypes,
-		props?: FieldProps<TCustomMetadata>,
+		props?: FieldPropsAlpha<TCustomMetadata>,
 	) {
 		super(kind, types, props);
 
@@ -549,6 +591,7 @@ export class FieldSchemaAlpha<
 		this.lazyIdentifiers = new Lazy(
 			() => new Set([...this.allowedTypeSet].map((t) => t.identifier)),
 		);
+		this.propsAlpha = props;
 	}
 
 	public get allowedTypesIdentifiers(): ReadonlySet<string> {
@@ -774,17 +817,48 @@ function areFieldPropsEqual(a: FieldProps | undefined, b: FieldProps | undefined
  * @remarks FieldSchemaMetadata are considered equivalent if their custom data and descriptions are (respectively) reference equal.
  */
 function areMetadataEqual(
-	a: FieldSchemaMetadata | undefined,
-	b: FieldSchemaMetadata | undefined,
+	a: FieldSchemaMetadataAlpha | undefined,
+	b: FieldSchemaMetadataAlpha | undefined,
 ): boolean {
 	// If any new fields are added to FieldSchemaMetadata, this check will stop compiling as a reminder that this function needs to be updated.
-	type _keys = requireTrue<areOnlyKeys<FieldSchemaMetadata, "custom" | "description">>;
+	type _keys = requireTrue<
+		areOnlyKeys<FieldSchemaMetadataAlpha, "custom" | "description" | "persistedMetadata">
+	>;
 
 	if (a === b) {
 		return true;
 	}
 
-	return a?.custom === b?.custom && a?.description === b?.description;
+	return (
+		Object.is(a?.custom, b?.custom) &&
+		a?.description === b?.description &&
+		arePersistedMetadataEqual(a?.persistedMetadata, b?.persistedMetadata)
+	);
+}
+
+/**
+ * Returns true if the given persisted metadata fields are equivalent, otherwise false.
+ * @remarks
+ * Currently only handles shallow equality in the case where the keys are in the same order. This is acceptable for current use cases.
+ */
+function arePersistedMetadataEqual(
+	a: JsonCompatibleReadOnlyObject | undefined,
+	b: JsonCompatibleReadOnlyObject | undefined,
+): boolean {
+	if (Object.is(a, b)) {
+		return true;
+	}
+
+	if (a === undefined || b === undefined) {
+		return false;
+	}
+
+	// Note that the key order matters. If `a` and `b` have the same content but the keys are in a different order,
+	// this method will return false.
+	const aStringified = JSON.stringify(a);
+	const bStringified = JSON.stringify(b);
+
+	return aStringified === bStringified;
 }
 
 const cachedLazyItem = new WeakMap<() => unknown, unknown>();
@@ -1312,6 +1386,22 @@ export interface NodeSchemaOptions<out TCustomMetadata = unknown> {
 	readonly metadata?: NodeSchemaMetadata<TCustomMetadata> | undefined;
 }
 
+/**
+ * Additional information to provide to Node Schema creation. Includes fields for alpha features.
+ *
+ * @typeParam TCustomMetadata - Custom metadata properties to associate with the Node Schema.
+ * See {@link NodeSchemaMetadata.custom}.
+ *
+ * @alpha
+ */
+export interface NodeSchemaOptionsAlpha<out TCustomMetadata = unknown>
+	extends NodeSchemaOptions<TCustomMetadata> {
+	/**
+	 * The persisted metadata for this schema element.
+	 */
+	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
+}
+
 /**
  * Metadata associated with a Node Schema.
  *

package/src/simple-tree/simpleSchema.ts

@@ -4,7 +4,7 @@
  */
 
 import type { ValueSchema } from "../core/index.js";
-
+import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
 import type { NodeKind } from "./core/index.js";
 import type { FieldKind, FieldSchemaMetadata, NodeSchemaMetadata } from "./schemaTypes.js";
 
@@ -37,6 +37,23 @@ export interface SimpleNodeSchemaBase<
 	readonly metadata: NodeSchemaMetadata<TCustomMetadata>;
 }
 
+/**
+ * A {@link SimpleNodeSchema} containing fields for alpha features.
+ *
+ * @system
+ * @alpha
+ * @sealed
+ */
+export interface SimpleNodeSchemaBaseAlpha<
+	out TNodeKind extends NodeKind,
+	out TCustomMetadata = unknown,
+> extends SimpleNodeSchemaBase<TNodeKind, TCustomMetadata> {
+	/**
+	 * Persisted metadata for this node schema.
+	 */
+	readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined;
+}
+
 /**
  * A {@link SimpleNodeSchema} for an object node.
  *
@@ -44,7 +61,7 @@ export interface SimpleNodeSchemaBase<
  * @sealed
  */
 export interface SimpleObjectNodeSchema<out TCustomMetadata = unknown>
-	extends SimpleNodeSchemaBase<NodeKind.Object, TCustomMetadata> {
+	extends SimpleNodeSchemaBaseAlpha<NodeKind.Object, TCustomMetadata> {
 	/**
 	 * Schemas for each of the object's fields, keyed off of schema's keys.
 	 * @remarks
@@ -82,7 +99,7 @@ export interface SimpleObjectFieldSchema extends SimpleFieldSchema {
  * @sealed
  */
 export interface SimpleArrayNodeSchema<out TCustomMetadata = unknown>
-	extends SimpleNodeSchemaBase<NodeKind.Array, TCustomMetadata> {
+	extends SimpleNodeSchemaBaseAlpha<NodeKind.Array, TCustomMetadata> {
 	/**
 	 * The types allowed in the array.
 	 *
@@ -99,7 +116,7 @@ export interface SimpleArrayNodeSchema<out TCustomMetadata = unknown>
  * @sealed
  */
 export interface SimpleMapNodeSchema<out TCustomMetadata = unknown>
-	extends SimpleNodeSchemaBase<NodeKind.Map, TCustomMetadata> {
+	extends SimpleNodeSchemaBaseAlpha<NodeKind.Map, TCustomMetadata> {
 	/**
 	 * The types allowed as values in the map.
 	 *
@@ -115,7 +132,7 @@ export interface SimpleMapNodeSchema<out TCustomMetadata = unknown>
  * @alpha
  * @sealed
  */
-export interface SimpleLeafNodeSchema extends SimpleNodeSchemaBase<NodeKind.Leaf> {
+export interface SimpleLeafNodeSchema extends SimpleNodeSchemaBaseAlpha<NodeKind.Leaf> {
 	/**
 	 * The kind of leaf node.
 	 */
@@ -170,6 +187,11 @@ export interface SimpleFieldSchema {
 	 * {@inheritDoc FieldSchemaMetadata}
 	 */
 	readonly metadata: FieldSchemaMetadata;
+
+	/**
+	 * Persisted metadata for this field schema.
+	 */
+	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
 }
 
 /**

package/src/simple-tree/toStoredSchema.ts

@@ -90,10 +90,16 @@ export function convertField(schema: SimpleFieldSchema): TreeFieldStoredSchema {
 	const kind: FieldKindIdentifier =
 		convertFieldKind.get(schema.kind)?.identifier ?? fail(0xae3 /* Invalid field kind */);
 	const types: TreeTypeSet = schema.allowedTypesIdentifiers as TreeTypeSet;
-	return { kind, types };
+	return { kind, types, persistedMetadata: schema.persistedMetadata };
 }
 
-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],
@@ -101,6 +107,8 @@ const convertFieldKind = new Map<FieldKind, FlexFieldKind>([
 
 /**
  * Converts a {@link TreeNodeSchema} into a {@link TreeNodeStoredSchema}.
+ * @privateRemarks
+ * TODO: Persist node metadata once schema FormatV2 is supported.
  */
 export function getStoredSchema(schema: SimpleNodeSchema): TreeNodeStoredSchema {
 	const kind = schema.kind;
@@ -111,23 +119,32 @@ export function getStoredSchema(schema: SimpleNodeSchema): TreeNodeStoredSchema
 		}
 		case NodeKind.Map: {
 			const types = schema.allowedTypesIdentifiers as TreeTypeSet;
-			return new MapNodeStoredSchema({ kind: FieldKinds.optional.identifier, types });
+			return new MapNodeStoredSchema(
+				{
+					kind: FieldKinds.optional.identifier,
+					types,
+					persistedMetadata: schema.persistedMetadata,
+				},
+				// TODO: Find a way to avoid injecting persistedMetadata twice in these constructor calls.
+				schema.persistedMetadata,
+			);
 		}
 		case NodeKind.Array: {
 			const types = schema.allowedTypesIdentifiers as TreeTypeSet;
 			const field = {
 				kind: FieldKinds.sequence.identifier,
 				types,
+				persistedMetadata: schema.persistedMetadata,
 			};
 			const fields = new Map([[EmptyKey, field]]);
-			return new ObjectNodeStoredSchema(fields);
+			return new ObjectNodeStoredSchema(fields, schema.persistedMetadata);
 		}
 		case NodeKind.Object: {
 			const fields: Map<FieldKey, TreeFieldStoredSchema> = new Map();
 			for (const fieldSchema of schema.fields.values()) {
 				fields.set(brand(fieldSchema.storedKey), convertField(fieldSchema));
 			}
-			return new ObjectNodeStoredSchema(fields);
+			return new ObjectNodeStoredSchema(fields, schema.persistedMetadata);
 		}
 		default:
 			unreachableCase(kind);