@fluidframework/tree 2.63.0 → 2.70.0-360753

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import { assert, debugAssert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -164,7 +164,7 @@ export interface ObjectSchemaOptionsAlpha<TCustomMetadata = unknown>
  * @remarks Omits parameters that are not relevant for common use cases.
  */
 export const defaultSchemaFactoryObjectOptions: Required<
-	Omit<ObjectSchemaOptionsAlpha, "metadata" | "persistedMetadata">
+	Pick<ObjectSchemaOptions, "allowUnknownOptionalFields">
 > = {
 	allowUnknownOptionalFields: false,
 };
@@ -397,12 +397,9 @@ export class SchemaFactory<
 		true,
 		T
 	> {
-		return objectSchema(
-			scoped(this, name),
-			fields,
-			true,
-			defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
-		);
+		return objectSchema(scoped(this, name), fields, true, {
+			...defaultSchemaFactoryObjectOptions,
+		});
 	}
 
 	/**
@@ -474,15 +471,17 @@ export class SchemaFactory<
 	 * This seems like a TypeScript bug getting variance backwards for overload return types since it's erroring when the relation between the overload
 	 * and the implementation is type safe, and forcing an unsafe typing instead.
 	 */
-	public map<const T extends ImplicitAllowedTypes>(
+	public map<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 		nameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),
 		allowedTypes?: T,
+		options?: NodeSchemaOptions<TCustomMetadata>,
 	): 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);
+			debugAssert(() => options === undefined || "No options for structural types");
 			return this.getStructuralType(fullName, types, () =>
-				this.namedMap(fullName, nameOrAllowedTypes as T, false, true),
+				this.namedMap(fullName, nameOrAllowedTypes as T, false, true, {}),
 			) as TreeNodeSchemaBoth<
 				string,
 				NodeKind.Map,
@@ -490,7 +489,8 @@ export class SchemaFactory<
 				MapNodeInsertableData<T>,
 				true,
 				T,
-				undefined
+				undefined,
+				TCustomMetadata
 			>;
 		}
 		// To actually have type safety, assign to the type this method should return before implicitly up-casting when returning.
@@ -501,8 +501,9 @@ export class SchemaFactory<
 			MapNodeInsertableData<T>,
 			true,
 			T,
-			undefined
-		> = this.namedMap(nameOrAllowedTypes as TName, allowedTypes, true, true);
+			undefined,
+			TCustomMetadata
+		> = this.namedMap(nameOrAllowedTypes as TName, allowedTypes, true, true, options ?? {});
 		return out;
 	}
 
@@ -515,11 +516,13 @@ export class SchemaFactory<
 		Name extends TName | string,
 		const T extends ImplicitAllowedTypes,
 		const ImplicitlyConstructable extends boolean,
+		const TCustomMetadata = unknown,
 	>(
 		name: Name,
 		allowedTypes: T,
 		customizable: boolean,
 		implicitlyConstructable: ImplicitlyConstructable,
+		options: NodeSchemaOptionsAlpha<TCustomMetadata>,
 	): TreeNodeSchemaBoth<
 		ScopedSchemaName<TScope, Name>,
 		NodeKind.Map,
@@ -527,7 +530,8 @@ export class SchemaFactory<
 		MapNodeInsertableData<T>,
 		ImplicitlyConstructable,
 		T,
-		undefined
+		undefined,
+		TCustomMetadata
 	> {
 		return mapSchema(
 			scoped(this, name),
@@ -535,7 +539,7 @@ export class SchemaFactory<
 			implicitlyConstructable,
 			// The current policy is customizable nodes don't get fake prototypes.
 			!customizable,
-			undefined,
+			options ?? {},
 		);
 	}
 
@@ -618,22 +622,25 @@ export class SchemaFactory<
 	 * @privateRemarks
 	 * This should return TreeNodeSchemaBoth: see note on "map" implementation for details.
 	 */
-	public array<const T extends ImplicitAllowedTypes>(
+	public array<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
 		nameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),
 		allowedTypes?: T,
+		options?: NodeSchemaOptions<TCustomMetadata>,
 	): TreeNodeSchema<
 		ScopedSchemaName<TScope, string>,
 		NodeKind.Array,
 		TreeArrayNode<T>,
 		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 		true,
-		T
+		T,
+		TCustomMetadata
 	> {
 		if (allowedTypes === undefined) {
 			const types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];
 			const fullName = structuralName("Array", types);
+			debugAssert(() => options === undefined || "No options for structural types");
 			return this.getStructuralType(fullName, types, () =>
-				this.namedArray(fullName, nameOrAllowedTypes as T, false, true),
+				this.namedArray(fullName, nameOrAllowedTypes as T, false, true, {}),
 			) as TreeNodeSchemaClass<
 				ScopedSchemaName<TScope, string>,
 				NodeKind.Array,
@@ -641,9 +648,11 @@ export class SchemaFactory<
 				Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 				true,
 				T,
-				undefined
+				undefined,
+				TCustomMetadata
 			>;
 		}
+
 		const out: TreeNodeSchemaBoth<
 			ScopedSchemaName<TScope, string>,
 			NodeKind.Array,
@@ -651,8 +660,9 @@ export class SchemaFactory<
 			Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 			true,
 			T,
-			undefined
-		> = this.namedArray(nameOrAllowedTypes as TName, allowedTypes, true, true);
+			undefined,
+			TCustomMetadata
+		> = this.namedArray(nameOrAllowedTypes as TName, allowedTypes, true, true, options ?? {});
 		return out;
 	}
 
@@ -698,11 +708,13 @@ export class SchemaFactory<
 		Name extends TName | string,
 		const T extends ImplicitAllowedTypes,
 		const ImplicitlyConstructable extends boolean,
+		const TCustomMetadata = unknown,
 	>(
 		name: Name,
 		allowedTypes: T,
 		customizable: boolean,
 		implicitlyConstructable: ImplicitlyConstructable,
+		options: NodeSchemaOptionsAlpha<TCustomMetadata>,
 	): TreeNodeSchemaBoth<
 		ScopedSchemaName<TScope, Name>,
 		NodeKind.Array,
@@ -710,13 +722,15 @@ export class SchemaFactory<
 		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 		ImplicitlyConstructable,
 		T,
-		undefined
+		undefined,
+		TCustomMetadata
 	> {
 		return arraySchema(
 			scoped(this, name),
 			allowedTypes,
 			implicitlyConstructable,
 			customizable,
+			options,
 		);
 	}
 
@@ -822,6 +836,7 @@ export class SchemaFactory<
 			allowedTypes as T & ImplicitAllowedTypes,
 			true,
 			false,
+			{},
 		);
 
 		return RecursiveArray as TreeNodeSchemaClass<
@@ -870,6 +885,7 @@ export class SchemaFactory<
 			// Setting this (implicitlyConstructable) to true seems to work ok currently, but not for other node kinds.
 			// Supporting this could be fragile and might break other future changes, so it's being kept as false for now.
 			false,
+			{},
 		);
 
 		return MapSchema as TreeNodeSchemaClass<

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

@@ -218,15 +218,10 @@ export class SchemaFactoryAlpha<
 		 */
 		readonly createFromInsertable: unknown;
 	} {
-		return objectSchema(
-			scoped<TScope, TName, Name>(this, name),
-			fields,
-			true,
-			options?.allowUnknownOptionalFields ??
-				defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
-			options?.metadata,
-			options?.persistedMetadata,
-		);
+		return objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {
+			...defaultSchemaFactoryObjectOptions,
+			...(options ?? {}),
+		});
 	}
 
 	/**
@@ -408,8 +403,7 @@ export class SchemaFactoryAlpha<
 			allowedTypes,
 			true,
 			true,
-			options?.metadata,
-			options?.persistedMetadata,
+			options,
 		);
 	}
 
@@ -459,8 +453,7 @@ export class SchemaFactoryAlpha<
 			allowedTypes,
 			true,
 			true,
-			options?.metadata,
-			options?.persistedMetadata,
+			options ?? {},
 		);
 	}
 
@@ -510,8 +503,7 @@ export class SchemaFactoryAlpha<
 			info: allowedTypes,
 			customizable: true,
 			implicitlyConstructable: true,
-			metadata: options?.metadata,
-			persistedMetadata: options?.persistedMetadata,
+			nodeOptions: options,
 		});
 	}
 
@@ -535,8 +527,7 @@ export class SchemaFactoryAlpha<
 			// Setting this to true seems to work ok currently, but not for other node kinds.
 			// Supporting this could be fragile and might break other future changes, so it's being kept as false for now.
 			implicitlyConstructable: false,
-			metadata: options?.metadata,
-			persistedMetadata: options?.persistedMetadata,
+			nodeOptions: options,
 		});
 
 		return RecordSchema as TreeNodeSchemaClass<

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

@@ -90,14 +90,10 @@ export class SchemaFactoryBeta<
 		true,
 		T
 	> {
-		return objectSchema(
-			scoped<TScope, TName, Name>(this, name),
-			fields,
-			true,
-			options?.allowUnknownOptionalFields ??
-				defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
-			options?.metadata,
-		);
+		return objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {
+			...defaultSchemaFactoryObjectOptions,
+			...(options ?? {}),
+		});
 	}
 
 	public override objectRecursive<
@@ -192,6 +188,7 @@ export class SchemaFactoryBeta<
 	 *
 	 * @param name - Unique identifier for this schema within this factory's scope.
 	 * @param allowedTypes - The types that may appear in the record.
+	 * @param options - Additional options for the schema.
 	 *
 	 * @remarks
 	 * The underlying data format for `Record` nodes is the same as that for `Map` nodes.
@@ -211,9 +208,14 @@ export class SchemaFactoryBeta<
 	 *
 	 * {@label NAMED}
 	 */
-	public record<const Name extends TName, const T extends ImplicitAllowedTypes>(
+	public record<
+		const Name extends TName,
+		const T extends ImplicitAllowedTypes,
+		const TCustomMetadata = unknown,
+	>(
 		name: Name,
 		allowedTypes: T,
+		options?: NodeSchemaOptions<TCustomMetadata>,
 	): TreeNodeSchemaClass<
 		/* Name */ ScopedSchemaName<TScope, Name>,
 		/* Kind */ NodeKind.Record,
@@ -221,7 +223,8 @@ export class SchemaFactoryBeta<
 		/* TInsertable */ RecordNodeInsertableData<T>,
 		/* ImplicitlyConstructable */ true,
 		/* Info */ T,
-		/* TConstructorExtra */ undefined
+		/* TConstructorExtra */ undefined,
+		/* TCustomMetadata */ TCustomMetadata
 	>;
 
 	/**
@@ -233,6 +236,7 @@ export class SchemaFactoryBeta<
 	public record<const T extends ImplicitAllowedTypes>(
 		nameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),
 		maybeAllowedTypes?: T,
+		options?: NodeSchemaOptions,
 	): TreeNodeSchema<
 		/* Name */ ScopedSchemaName<TScope, string>,
 		/* Kind */ NodeKind.Record,
@@ -274,6 +278,7 @@ export class SchemaFactoryBeta<
 			maybeAllowedTypes,
 			/* customizable */ true,
 			/* implicitlyConstructable */ true,
+			options,
 		);
 		return out;
 	}
@@ -307,24 +312,13 @@ export class SchemaFactoryBeta<
 		/* Info */ T,
 		/* TConstructorExtra */ undefined
 	> {
-		const record = recordSchema({
+		return recordSchema({
 			identifier: scoped<TScope, TName, Name>(this, name),
 			info: allowedTypes,
 			customizable,
 			implicitlyConstructable,
-			metadata: options?.metadata,
+			nodeOptions: options,
 		});
-
-		return record as TreeNodeSchemaBoth<
-			/* Name */ ScopedSchemaName<TScope, Name>,
-			/* Kind */ NodeKind.Record,
-			/* TNode */ TreeRecordNode<T> &
-				WithType<ScopedSchemaName<TScope, string>, NodeKind.Record>,
-			/* TInsertable */ RecordNodeInsertableData<T>,
-			/* ImplicitlyConstructable */ ImplicitlyConstructable,
-			/* Info */ T,
-			/* TConstructorExtra */ undefined
-		>;
 	}
 
 	/**

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

@@ -283,6 +283,6 @@ export function allowUnused<T>(t?: T): void {}
  * }
  * ```
  *
- * @alpha
+ * @beta
  */
 export type FixRecursiveArraySchema<T> = T extends TreeNodeSchema ? undefined : undefined;

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

@@ -59,7 +59,7 @@ import {
 	getTreeNodeSchemaInitializedData,
 	getUnhydratedContext,
 } from "../../createContext.js";
-import type { System_Unsafe } from "../../api/index.js";
+import type { NodeSchemaOptionsAlpha, System_Unsafe } from "../../api/index.js";
 import type {
 	ArrayNodeCustomizableSchema,
 	ArrayNodePojoEmulationSchema,
@@ -1152,8 +1152,7 @@ export function arraySchema<
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
 	customizable: boolean,
-	metadata?: NodeSchemaMetadata<TCustomMetadata>,
-	persistedMetadata?: JsonCompatibleReadOnlyObject | undefined,
+	nodeOptions: NodeSchemaOptionsAlpha<TCustomMetadata>,
 ) {
 	type Output = ArrayNodeCustomizableSchema<
 		TName,
@@ -1164,6 +1163,7 @@ export function arraySchema<
 		ArrayNodePojoEmulationSchema<TName, T, ImplicitlyConstructable, TCustomMetadata> &
 		TreeNodeSchemaCorePrivate;
 
+	const persistedMetadata = nodeOptions?.persistedMetadata;
 	const normalizedTypes = normalizeAllowedTypes(info);
 	const lazyAllowedTypesIdentifiers = new Lazy(
 		() => new Set(normalizedTypes.evaluate().map((type) => type.identifier)),
@@ -1252,7 +1252,8 @@ export function arraySchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return normalizedTypes.evaluateSet();
 		}
-		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> = metadata ?? {};
+		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> =
+			nodeOptions.metadata ?? {};
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 

package/src/simple-tree/node-kinds/map/mapNode.ts

@@ -65,6 +65,7 @@ import type {
 } from "./mapNodeTypes.js";
 import { recordLikeDataToFlexContent } from "../common.js";
 import { MapNodeStoredSchema } from "../../../core/index.js";
+import type { NodeSchemaOptionsAlpha } from "../../api/index.js";
 
 /**
  * A map of string keys to tree objects.
@@ -268,8 +269,7 @@ export function mapSchema<
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
 	useMapPrototype: boolean,
-	metadata?: NodeSchemaMetadata<TCustomMetadata>,
-	persistedMetadata?: JsonCompatibleReadOnlyObject | undefined,
+	nodeOptions: NodeSchemaOptionsAlpha<TCustomMetadata> = {},
 ) {
 	const normalizedTypes = normalizeAllowedTypes(info);
 	const lazyAllowedTypesIdentifiers = new Lazy(
@@ -277,6 +277,7 @@ export function mapSchema<
 	);
 
 	let privateData: TreeNodeSchemaPrivateData | undefined;
+	const persistedMetadata = nodeOptions.persistedMetadata;
 
 	class Schema extends CustomMapNodeBase<T> implements TreeMapNode<T> {
 		public static override prepareInstance<T2>(
@@ -319,7 +320,8 @@ export function mapSchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return normalizedTypes.evaluateSet();
 		}
-		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> = metadata ?? {};
+		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> =
+			nodeOptions.metadata ?? {};
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 

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

@@ -87,6 +87,7 @@ import {
 	type InsertableContent,
 } from "../../unhydratedFlexTreeFromInsertable.js";
 import { convertField, convertFieldKind } from "../../toStoredSchema.js";
+import type { ObjectSchemaOptionsAlpha } from "../../api/index.js";
 
 /**
  * Generates the properties for an ObjectNode from its field schema object.
@@ -415,9 +416,7 @@ export function objectSchema<
 	identifier: TName,
 	info: T,
 	implicitlyConstructable: ImplicitlyConstructable,
-	allowUnknownOptionalFields: boolean,
-	metadata?: NodeSchemaMetadata<TCustomMetadata>,
-	persistedMetadata?: JsonCompatibleReadOnlyObject | undefined,
+	nodeOptions: ObjectSchemaOptionsAlpha<TCustomMetadata>,
 ): ObjectNodeSchema<TName, T, ImplicitlyConstructable, TCustomMetadata> &
 	ObjectNodeSchemaInternalData &
 	TreeNodeSchemaCorePrivate {
@@ -471,7 +470,8 @@ export function objectSchema<
 			]),
 		);
 		public static readonly identifierFieldKeys: readonly FieldKey[] = identifierFieldKeys;
-		public static readonly allowUnknownOptionalFields: boolean = allowUnknownOptionalFields;
+		public static readonly allowUnknownOptionalFields: boolean =
+			nodeOptions.allowUnknownOptionalFields ?? false;
 
 		public static override prepareInstance<T2>(
 			this: typeof TreeNodeValid<T2>,
@@ -561,9 +561,10 @@ export function objectSchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;
 		}
-		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> = metadata ?? {};
+		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> =
+			nodeOptions.metadata ?? {};
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
-			persistedMetadata;
+			nodeOptions.persistedMetadata;
 
 		// eslint-disable-next-line import/no-deprecated
 		public get [typeNameSymbol](): TName {
@@ -592,7 +593,7 @@ export function objectSchema<
 							convertField(fieldSchema.schema, storedOptions),
 						);
 					}
-					return new ObjectNodeStoredSchema(fields, persistedMetadata);
+					return new ObjectNodeStoredSchema(fields, nodeOptions.persistedMetadata);
 				},
 			));
 		}

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

@@ -57,6 +57,7 @@ import {
 import { prepareForInsertion } from "../../prepareForInsertion.js";
 import { recordLikeDataToFlexContent } from "../common.js";
 import { MapNodeStoredSchema } from "../../../core/index.js";
+import type { NodeSchemaOptionsAlpha } from "../../api/index.js";
 
 /**
  * Create a proxy which implements the {@link TreeRecordNode} API.
@@ -227,15 +228,7 @@ export interface RecordSchemaOptions<
 
 	readonly implicitlyConstructable: TImplicitlyConstructable;
 
-	/**
-	 * Optional ephemeral metadata for the object node schema.
-	 */
-	readonly metadata?: NodeSchemaMetadata<TCustomMetadata>;
-
-	/**
-	 * Optional persisted metadata for the object node schema.
-	 */
-	readonly persistedMetadata?: JsonCompatibleReadOnlyObject | undefined;
+	readonly nodeOptions?: NodeSchemaOptionsAlpha<TCustomMetadata>;
 }
 
 /**
@@ -258,14 +251,8 @@ export function recordSchema<
 		TCustomMetadata
 	>,
 ) {
-	const {
-		identifier,
-		info,
-		customizable,
-		implicitlyConstructable,
-		metadata,
-		persistedMetadata,
-	} = options;
+	const { identifier, info, customizable, implicitlyConstructable, nodeOptions } = options;
+	const persistedMetadata = nodeOptions?.persistedMetadata;
 
 	const normalizedTypes = normalizeAllowedTypes(info);
 	const lazyAllowedTypesIdentifiers = new Lazy(
@@ -369,7 +356,8 @@ export function recordSchema<
 		public static get childTypes(): ReadonlySet<TreeNodeSchema> {
 			return normalizedTypes.evaluateSet();
 		}
-		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> = metadata ?? {};
+		public static readonly metadata: NodeSchemaMetadata<TCustomMetadata> =
+			nodeOptions?.metadata ?? {};
 		public static readonly persistedMetadata: JsonCompatibleReadOnlyObject | undefined =
 			persistedMetadata;
 

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

@@ -64,7 +64,7 @@ export interface RecordNodeCustomizableSchema<
 			/* TInsertable */ RecordNodeInsertableData<T>,
 			/* ImplicitlyConstructable */ ImplicitlyConstructable,
 			/* Info */ T,
-			/* TConstructorExtra */ never,
+			/* TConstructorExtra */ undefined,
 			/* TCustomMetadata */ TCustomMetadata
 		>,
 		SimpleRecordNodeSchema<TCustomMetadata> {}
@@ -85,7 +85,7 @@ export interface RecordNodePojoEmulationSchema<
 			/* TInsertable */ RecordNodeInsertableData<T>,
 			/* ImplicitlyConstructable */ ImplicitlyConstructable,
 			/* Info */ T,
-			/* TConstructorExtra */ never,
+			/* TConstructorExtra */ undefined,
 			/* TCustomMetadata */ TCustomMetadata
 		>,
 		SimpleRecordNodeSchema<TCustomMetadata> {}