@fluidframework/tree 2.63.0-359461 → 2.63.0-359962

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

@@ -17,28 +17,37 @@ import {
 	defaultSchemaFactoryObjectOptions,
 	scoped,
 	type NodeSchemaOptionsAlpha,
-	type SchemaFactoryObjectOptions,
+	type ObjectSchemaOptionsAlpha,
 	type ScopedSchemaName,
 } from "./schemaFactory.js";
 import { schemaStatics } from "./schemaStatics.js";
-import type { ImplicitAnnotatedFieldSchema, ImplicitFieldSchema } from "../fieldSchema.js";
+import type { ImplicitFieldSchema } from "../fieldSchema.js";
 import type { RestrictiveStringRecord } from "../../util/index.js";
 import type {
 	NodeKind,
 	TreeNodeSchema,
 	TreeNodeSchemaClass,
 	ImplicitAllowedTypes,
-	ImplicitAnnotatedAllowedTypes,
 	AnnotatedAllowedType,
 	LazyItem,
 	WithType,
+	AllowedTypesMetadata,
+	AllowedTypesFullFromMixed,
+} from "../core/index.js";
+import {
+	normalizeToAnnotatedAllowedType,
+	createSchemaUpgrade,
+	AnnotatedAllowedTypesInternal,
 } from "../core/index.js";
-import { normalizeToAnnotatedAllowedType, createSchemaUpgrade } from "../core/index.js";
 import type {
+	AllowedTypesFullFromMixedUnsafe,
+	AnnotatedAllowedTypeUnsafe,
 	ArrayNodeCustomizableSchemaUnsafe,
 	MapNodeCustomizableSchemaUnsafe,
 	System_Unsafe,
 	TreeRecordNodeUnsafe,
+	UnannotateAllowedTypeUnsafe,
+	Unenforced,
 } from "./typesUnsafe.js";
 import type { SimpleObjectNodeSchema } from "../simpleSchema.js";
 import { SchemaFactoryBeta } from "./schemaFactoryBeta.js";
@@ -53,7 +62,6 @@ import type {
 } from "../fieldSchema.js";
 import type { LeafSchema } from "../leafNodeSchema.js";
 import type { SimpleLeafNodeSchema } from "../simpleSchema.js";
-import type { UnannotateImplicitAllowedTypes } from "../core/index.js";
 import type { FieldSchemaAlphaUnsafe } from "./typesUnsafe.js";
 /* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import/no-duplicates */
 
@@ -94,24 +102,79 @@ export interface SchemaStaticsAlpha {
 	 *
 	 * TODO: AB#45711: Update the docs above when recursive type support is added.
 	 */
-	staged: <const T extends LazyItem<TreeNodeSchema>>(
+	readonly staged: <const T extends LazyItem<TreeNodeSchema>>(
 		t: T | AnnotatedAllowedType<T>,
 	) => AnnotatedAllowedType<T>;
+
+	/**
+	 * Normalize information about a set of {@link AllowedTypes} into an {@link AllowedTypesFull}.
+	 * @remarks
+	 * This can take in {@link AnnotatedAllowedType} to preserve their annotations.
+	 */
+	readonly types: <
+		const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[],
+	>(
+		t: T,
+		metadata?: AllowedTypesMetadata,
+	) => AllowedTypesFullFromMixed<T>;
+
+	/**
+	 * {@link SchemaStaticsAlpha.staged} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStaticsAlpha.staged} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 */
+	stagedRecursive: <
+		const T extends Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>,
+	>(
+		t: T,
+	) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>;
+
+	/**
+	 * {@link SchemaStaticsAlpha.types} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStaticsAlpha.types} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+	 * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+	 * @privateRemarks
+	 * If all inputs (at least recursive ones) were required to be annotated, this could be typed more strongly.
+	 * In that case it could use `T extends readonly (AnnotatedAllowedTypeUnsafe | LazyItem<System_Unsafe.TreeNodeSchemaUnsafe>)[]`.
+	 */
+	readonly typesRecursive: <
+		const T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[],
+	>(
+		t: T,
+		metadata?: AllowedTypesMetadata,
+	) => AllowedTypesFullFromMixedUnsafe<T>;
 }
 
+const staged = <const T extends LazyItem<TreeNodeSchema>>(
+	t: T | AnnotatedAllowedType<T>,
+): AnnotatedAllowedType<T> => {
+	const annotatedType = normalizeToAnnotatedAllowedType(t);
+	return {
+		type: annotatedType.type,
+		metadata: {
+			...annotatedType.metadata,
+			stagedSchemaUpgrade: createSchemaUpgrade(),
+		},
+	};
+};
+
+const types = <const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]>(
+	t: T,
+	metadata: AllowedTypesMetadata = {},
+): AllowedTypesFullFromMixed<T> => {
+	return AnnotatedAllowedTypesInternal.createMixed<T>(t, metadata);
+};
+
 const schemaStaticsAlpha: SchemaStaticsAlpha = {
-	staged: <const T extends LazyItem<TreeNodeSchema>>(
-		t: T | AnnotatedAllowedType<T>,
-	): AnnotatedAllowedType<T> => {
-		const annotatedType = normalizeToAnnotatedAllowedType(t);
-		return {
-			type: annotatedType.type,
-			metadata: {
-				...annotatedType.metadata,
-				stagedSchemaUpgrade: createSchemaUpgrade(),
-			},
-		};
-	},
+	staged,
+	types,
+
+	stagedRecursive: staged as SchemaStaticsAlpha["stagedRecursive"],
+	typesRecursive: types as unknown as SchemaStaticsAlpha["typesRecursive"],
 };
 
 /**
@@ -136,12 +199,12 @@ export class SchemaFactoryAlpha<
 	 */
 	public objectAlpha<
 		const Name extends TName,
-		const T extends RestrictiveStringRecord<ImplicitAnnotatedFieldSchema>,
+		const T extends RestrictiveStringRecord<ImplicitFieldSchema>,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,
 		fields: T,
-		options?: SchemaFactoryObjectOptions<TCustomMetadata>,
+		options?: ObjectSchemaOptionsAlpha<TCustomMetadata>,
 	): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> & {
 		/**
 		 * Typing checking workaround: not for for actual use.
@@ -176,7 +239,7 @@ export class SchemaFactoryAlpha<
 	>(
 		name: Name,
 		t: T,
-		options?: SchemaFactoryObjectOptions<TCustomMetadata>,
+		options?: ObjectSchemaOptionsAlpha<TCustomMetadata>,
 	): TreeNodeSchemaClass<
 		ScopedSchemaName<TScope, Name>,
 		NodeKind.Object,
@@ -287,6 +350,36 @@ export class SchemaFactoryAlpha<
 	 */
 	public staged = schemaStaticsAlpha.staged;
 
+	/**
+	 * {@inheritDoc SchemaStaticsAlpha.stagedRecursive}
+	 */
+	public static stagedRecursive = schemaStaticsAlpha.stagedRecursive;
+
+	/**
+	 * {@inheritDoc SchemaStaticsAlpha.stagedRecursive}
+	 */
+	public stagedRecursive = schemaStaticsAlpha.stagedRecursive;
+
+	/**
+	 * {@inheritDoc SchemaStaticsAlpha.types}
+	 */
+	public static types = schemaStaticsAlpha.types;
+
+	/**
+	 * {@inheritDoc SchemaStaticsAlpha.types}
+	 */
+	public types = schemaStaticsAlpha.types;
+
+	/**
+	 * {@inheritDoc SchemaStaticsAlpha.typesRecursive}
+	 */
+	public static typesRecursive = schemaStaticsAlpha.typesRecursive;
+
+	/**
+	 * {@inheritDoc SchemaStaticsAlpha.typesRecursive}
+	 */
+	public typesRecursive = schemaStaticsAlpha.typesRecursive;
+
 	/**
 	 * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
 	 *
@@ -303,7 +396,7 @@ export class SchemaFactoryAlpha<
 	 */
 	public mapAlpha<
 		Name extends TName,
-		const T extends ImplicitAnnotatedAllowedTypes,
+		const T extends ImplicitAllowedTypes,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,
@@ -354,7 +447,7 @@ export class SchemaFactoryAlpha<
 	 */
 	public arrayAlpha<
 		const Name extends TName,
-		const T extends ImplicitAnnotatedAllowedTypes,
+		const T extends ImplicitAllowedTypes,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,
@@ -372,7 +465,7 @@ export class SchemaFactoryAlpha<
 	}
 
 	/**
-	 * {@inheritDoc SchemaFactory.objectRecursive}
+	 * {@link SchemaFactory.arrayRecursive} but with support for some alpha features.
 	 */
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	public override arrayRecursive<
@@ -405,7 +498,7 @@ export class SchemaFactoryAlpha<
 	 */
 	public recordAlpha<
 		const Name extends TName,
-		const T extends ImplicitAnnotatedAllowedTypes,
+		const T extends ImplicitAllowedTypes,
 		const TCustomMetadata = unknown,
 	>(
 		name: Name,

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

@@ -14,15 +14,20 @@ import type {
 } from "../core/index.js";
 
 import {
+	objectSchema,
 	recordSchema,
+	type InsertableObjectFromSchemaRecord,
 	type RecordNodeInsertableData,
+	type TreeObjectNode,
 	type TreeRecordNode,
 } from "../node-kinds/index.js";
 import {
+	defaultSchemaFactoryObjectOptions,
 	SchemaFactory,
 	scoped,
 	structuralName,
 	type NodeSchemaOptions,
+	type ObjectSchemaOptions,
 	type ScopedSchemaName,
 } from "./schemaFactory.js";
 import type { System_Unsafe, TreeRecordNodeUnsafe } from "./typesUnsafe.js";
@@ -34,9 +39,11 @@ import type {
 	FieldSchemaAlpha,
 	FieldPropsAlpha,
 	FieldKind,
+	ImplicitFieldSchema,
 } from "../fieldSchema.js";
 import type { LeafSchema } from "../leafNodeSchema.js";
 import type { SimpleLeafNodeSchema } from "../simpleSchema.js";
+import type { RestrictiveStringRecord } from "../../util/index.js";
 /* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import/no-duplicates */
 
 /**
@@ -57,7 +64,73 @@ export class SchemaFactoryBeta<
 	public scopedFactory<const T extends TName, TNameInner extends number | string = string>(
 		name: T,
 	): SchemaFactoryBeta<ScopedSchemaName<TScope, T>, TNameInner> {
-		return new SchemaFactoryBeta(scoped(this, name));
+		return new SchemaFactoryBeta(scoped<TScope, TName, T>(this, name));
+	}
+
+	/**
+	 * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.
+	 *
+	 * @param name - Unique identifier for this schema within this factory's scope.
+	 * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.
+	 * @param options - Additional options for the schema.
+	 */
+	public override object<
+		const Name extends TName,
+		const T extends RestrictiveStringRecord<ImplicitFieldSchema>,
+		const TCustomMetadata = unknown,
+	>(
+		name: Name,
+		fields: T,
+		options?: ObjectSchemaOptions<TCustomMetadata>,
+	): TreeNodeSchemaClass<
+		ScopedSchemaName<TScope, Name>,
+		NodeKind.Object,
+		TreeObjectNode<T, ScopedSchemaName<TScope, Name>>,
+		object & InsertableObjectFromSchemaRecord<T>,
+		true,
+		T
+	> {
+		return objectSchema(
+			scoped<TScope, TName, Name>(this, name),
+			fields,
+			true,
+			options?.allowUnknownOptionalFields ??
+				defaultSchemaFactoryObjectOptions.allowUnknownOptionalFields,
+			options?.metadata,
+		);
+	}
+
+	public override objectRecursive<
+		const Name extends TName,
+		const T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,
+		const TCustomMetadata = unknown,
+	>(
+		name: Name,
+		t: T,
+		options?: ObjectSchemaOptions<TCustomMetadata>,
+	): TreeNodeSchemaClass<
+		ScopedSchemaName<TScope, Name>,
+		NodeKind.Object,
+		System_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,
+		object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,
+		false,
+		T
+	> {
+		type TScopedName = ScopedSchemaName<TScope, Name>;
+		return this.object(
+			name,
+			t as T & RestrictiveStringRecord<ImplicitFieldSchema>,
+			options,
+		) as unknown as TreeNodeSchemaClass<
+			TScopedName,
+			NodeKind.Object,
+			System_Unsafe.TreeObjectNodeUnsafe<T, TScopedName>,
+			object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,
+			false,
+			T,
+			never,
+			TCustomMetadata
+		>;
 	}
 
 	/**
@@ -113,6 +186,7 @@ export class SchemaFactoryBeta<
 		/* Info */ T,
 		/* TConstructorExtra */ undefined
 	>;
+
 	/**
 	 * Define (and add to this library) a {@link TreeNodeSchemaClass} for a {@link (TreeRecordNode:interface)}.
 	 *
@@ -149,6 +223,7 @@ export class SchemaFactoryBeta<
 		/* Info */ T,
 		/* TConstructorExtra */ undefined
 	>;
+
 	/**
 	 * {@link SchemaFactoryBeta.record} implementation.
 	 *

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

@@ -4,11 +4,7 @@
  */
 
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
-import type {
-	ImplicitAllowedTypes,
-	ImplicitAnnotatedAllowedTypes,
-	UnannotateImplicitAllowedTypes,
-} from "../core/index.js";
+import type { ImplicitAllowedTypes } from "../core/index.js";
 import { FieldKind, getDefaultProvider, createFieldSchema } from "../fieldSchema.js";
 import type {
 	FieldProps,
@@ -165,60 +161,6 @@ export interface SchemaStatics {
 
 const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => []);
 
-// The following overloads for optional and required are used to get around the fact that
-// the compiler can't infer that UnannotateImplicitAllowedTypes<T> is equal to T when T is known to extend ImplicitAllowedTypes
-
-// #region Overloads for optional and required
-function optional<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
-	t: T,
-	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
-): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;
-
-function optional<
-	const T extends ImplicitAnnotatedAllowedTypes,
-	const TCustomMetadata = unknown,
->(
-	t: T,
-	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
-): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
-
-function optional<
-	const T extends ImplicitAnnotatedAllowedTypes,
-	const TCustomMetadata = unknown,
->(
-	t: T,
-	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
-): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {
-	return createFieldSchema(FieldKind.Optional, t, {
-		defaultProvider: defaultOptionalProvider,
-		...props,
-	});
-}
-
-function required<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
-	t: T,
-	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
-): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;
-
-function required<
-	const T extends ImplicitAnnotatedAllowedTypes,
-	const TCustomMetadata = unknown,
->(
-	t: T,
-	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
-): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
-
-function required<
-	const T extends ImplicitAnnotatedAllowedTypes,
-	const TCustomMetadata = unknown,
->(
-	t: T,
-	props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
-): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {
-	return createFieldSchema(FieldKind.Required, t, props);
-}
-// #endregion
-
 /**
  * Implementation of {@link SchemaStatics}.
  * @remarks
@@ -233,9 +175,22 @@ export const schemaStaticsStable = {
 	handle: handleSchema,
 	leaves: [stringSchema, numberSchema, booleanSchema, nullSchema, handleSchema],
 
-	optional,
+	optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
+		t: T,
+		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
+	): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata> => {
+		return createFieldSchema(FieldKind.Optional, t, {
+			defaultProvider: defaultOptionalProvider,
+			...props,
+		});
+	},
 
-	required,
+	required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(
+		t: T,
+		props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">,
+	): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata> => {
+		return createFieldSchema(FieldKind.Required, t, props);
+	},
 
 	optionalRecursive: <
 		const T extends System_Unsafe.ImplicitAllowedTypesUnsafe,
@@ -273,6 +228,9 @@ export const schemaStatics = {
 	},
 } as const;
 
+/**
+ * {@link Unenforced} version of {@link createFieldSchema}.
+ */
 function createFieldSchemaUnsafe<
 	Kind extends FieldKind,
 	Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,

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

@@ -13,11 +13,7 @@ import {
 } from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
 import type { SchemaUpgrade } from "../core/index.js";
-import {
-	normalizeFieldSchema,
-	type ImplicitAnnotatedFieldSchema,
-	type ImplicitFieldSchema,
-} from "../fieldSchema.js";
+import { normalizeFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.js";
 import { toStoredSchema } from "../toStoredSchema.js";
 import { TreeViewConfigurationAlpha } from "./configuration.js";
 
@@ -57,7 +53,7 @@ import type { SchemaCompatibilityStatus } from "./tree.js";
  * @alpha
  */
 export function extractPersistedSchema(
-	schema: ImplicitAnnotatedFieldSchema,
+	schema: ImplicitFieldSchema,
 	oldestCompatibleClient: FluidClientVersion,
 	includeStaged: (upgrade: SchemaUpgrade) => boolean,
 ): JsonCompatible {

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

@@ -412,7 +412,7 @@ export interface SchemaCompatibilityStatus {
 	 * Note that other content in the stored schema that does not impact document compatibility, like {@link NodeSchemaOptionsAlpha.persistedMetadata}, does not affect this field.
 	 *
 	 * For the computation of this equivalence, {@link SchemaStaticsAlpha.staged | staged} schemas are not included.
-	 * If there are any unknown optional fields, even if allowed by {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields}, `isEquivalent` will be false.
+	 * If there are any unknown optional fields, even if allowed by {@link ObjectSchemaOptions.allowUnknownOptionalFields}, `isEquivalent` will be false.
 	 */
 	readonly isEquivalent: boolean;
 
@@ -423,7 +423,7 @@ export interface SchemaCompatibilityStatus {
 	 * If the view schema does not opt into supporting any additional cases, then `canView` is only true when `isEquivalent` is also true.
 	 * The view schema can however opt into supporting additional cases, and thus can also view documents with stored schema which would be equivalent, except for the following discrepancies:
 	 *
-	 * - An object node with {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields} to set to true that has additional optional fields in the stored schema beyond those mentioned in its view schema.
+	 * - An object node with {@link ObjectSchemaOptions.allowUnknownOptionalFields} to set to true that has additional optional fields in the stored schema beyond those mentioned in its view schema.
 	 *
 	 * - An additional type allowed at a location in the stored schema where it is {@link SchemaStaticsAlpha.staged | staged} in the view schema.
 	 *
@@ -451,7 +451,7 @@ export interface SchemaCompatibilityStatus {
 	 * @remarks
 	 * When true, it is valid to call {@link TreeView.upgradeSchema} (though if the stored schema is already an exact match, this is a no-op).
 	 *
-	 * When adding optional fields to schema which previously were marked with {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields}
+	 * When adding optional fields to schema which previously were marked with {@link ObjectSchemaOptions.allowUnknownOptionalFields}
 	 * the schema upgrade (assuming no other changes are included) will allow the previous version to view.
 	 * Even this case must still must be done with caution however as only clients with the newly added field will be able to do future upgrades.
 	 * Thus if a version of an application is shipped that adds an unknown optional field, all future versions should include it, even if its no longer used,