Support recursive annotated and staged types (microsoft#25199)

## Description

Add support for recursive annotated and staged types.

Author: CraigMacomber

.changeset/quiet-hairs-lay.md

@@ -0,0 +1,8 @@
+---
+"fluid-framework": minor
+"@fluidframework/tree": minor
+"__section": tree
+---
+Add SchemaFactoryAlpha.typesRecursive and SchemaFactoryAlpha.stagedRecursive
+
+With these new APIs, it is now possible to [`stage`](https://fluidframework.com/docs/api/fluid-framework/schemafactoryalpha-class#staged-property) changes to recursive types.

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

@@ -33,6 +33,12 @@ export type AllowedTypesFullEvaluated = AllowedTypesFull<readonly AnnotatedAllow
 // @alpha @sealed
 export type AllowedTypesFullFromMixed<T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]> = UnannotateAllowedTypesList<T> & AnnotatedAllowedTypes<AnnotateAllowedTypesList<T>>;
 
+// @alpha @sealed @system
+export type AllowedTypesFullFromMixedUnsafe<T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[]> = UnannotateAllowedTypesListUnsafe<T> & AnnotatedAllowedTypes<AnnotateAllowedTypesListUnsafe<T>>;
+
+// @alpha @sealed @system
+export type AllowedTypesFullUnsafe<T extends readonly AnnotatedAllowedTypeUnsafe[] = readonly AnnotatedAllowedTypeUnsafe[]> = AnnotatedAllowedTypes<T> & UnannotateAllowedTypesListUnsafe<T>;
+
 // @alpha @input
 export interface AllowedTypesMetadata {
     readonly custom?: unknown;
@@ -46,6 +52,11 @@ export type AnnotateAllowedTypesList<T extends readonly (AnnotatedAllowedType |
     [I in keyof T]: T[I] extends AnnotatedAllowedType<unknown> ? T[I] : AnnotatedAllowedType<T[I]>;
 };
 
+// @alpha @sealed @system
+export type AnnotateAllowedTypesListUnsafe<T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[]> = {
+    [I in keyof T]: T[I] extends AnnotatedAllowedTypeUnsafe ? T[I] : AnnotatedAllowedTypeUnsafe<T[I]>;
+};
+
 // @alpha @sealed
 export interface AnnotatedAllowedType<T = LazyItem<TreeNodeSchema>> {
     readonly metadata: AllowedTypeMetadata;
@@ -61,6 +72,14 @@ export interface AnnotatedAllowedTypes<T = readonly AnnotatedAllowedType[]> exte
     readonly types: T;
 }
 
+// @alpha @sealed @system
+export interface AnnotatedAllowedTypesUnsafe extends AnnotatedAllowedTypes<LazyItem<System_Unsafe.TreeNodeSchemaUnsafe>> {
+}
+
+// @alpha @sealed @system
+export interface AnnotatedAllowedTypeUnsafe<T = Unenforced<LazyItem<TreeNodeSchema>>> extends AnnotatedAllowedType<T> {
+}
+
 // @public @system
 type ApplyKind<T, Kind extends FieldKind> = {
     [FieldKind.Required]: T;
@@ -896,8 +915,12 @@ export class SchemaFactoryAlpha<out TScope extends string | undefined = string |
     scopedFactoryAlpha<const T extends TName, TNameInner extends number | string = string>(name: T): SchemaFactoryAlpha<ScopedSchemaName<TScope, T>, TNameInner>;
     static staged: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>;
     staged: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>;
+    static stagedRecursive: <const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>;
+    stagedRecursive: <const T extends unknown>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>;
     static types: <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>;
     types: <const T extends readonly (LazyItem<TreeNodeSchema> | AnnotatedAllowedType<LazyItem<TreeNodeSchema>>)[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixed<T>;
+    static typesRecursive: <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T>;
+    typesRecursive: <const T extends readonly unknown[]>(t: T, metadata?: AllowedTypesMetadata | undefined) => AllowedTypesFullFromMixedUnsafe<T>;
 }
 
 // @beta
@@ -936,7 +959,9 @@ export interface SchemaStatics {
 // @alpha @sealed @system
 export interface SchemaStaticsAlpha {
     readonly staged: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>;
+    stagedRecursive: <const T extends Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>>(t: T) => AnnotatedAllowedTypeUnsafe<UnannotateAllowedTypeUnsafe<T>>;
     readonly types: <const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]>(t: T, metadata?: AllowedTypesMetadata) => AllowedTypesFullFromMixed<T>;
+    readonly typesRecursive: <const T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[]>(t: T, metadata?: AllowedTypesMetadata) => AllowedTypesFullFromMixedUnsafe<T>;
 }
 
 // @alpha @sealed
@@ -1615,6 +1640,16 @@ export type UnannotateAllowedTypesList<T extends readonly (AnnotatedAllowedType
     [I in keyof T]: T[I] extends AnnotatedAllowedType<infer X> ? X : T[I];
 };
 
+// @alpha @sealed @system
+export type UnannotateAllowedTypesListUnsafe<T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[]> = {
+    readonly [I in keyof T]: T[I] extends {
+        type: infer X;
+    } ? X : T[I];
+};
+
+// @alpha @sealed @system
+export type UnannotateAllowedTypeUnsafe<T extends Unenforced<AnnotatedAllowedTypeUnsafe | LazyItem<System_Unsafe.TreeNodeSchemaUnsafe>>> = T extends AnnotatedAllowedTypeUnsafe<infer X> ? X : T;
+
 // @public
 export type Unenforced<_DesiredExtendsConstraint> = unknown;
 

packages/dds/tree/src/index.ts

@@ -137,6 +137,13 @@ export {
 	type ArrayNodeCustomizableSchemaUnsafe,
 	type MapNodeCustomizableSchemaUnsafe,
 	type TreeRecordNodeUnsafe,
+	type UnannotateAllowedTypeUnsafe,
+	type AnnotatedAllowedTypeUnsafe,
+	type AnnotatedAllowedTypesUnsafe,
+	type AllowedTypesFullUnsafe,
+	type AllowedTypesFullFromMixedUnsafe,
+	type UnannotateAllowedTypesListUnsafe,
+	type AnnotateAllowedTypesListUnsafe,
 	// System types (not in Internal types for various reasons, like doc links or cannot be named errors).
 	type typeSchemaSymbol,
 	type TreeNodeSchemaNonClass,

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

@@ -90,6 +90,13 @@ export type {
 	MapNodeCustomizableSchemaUnsafe,
 	System_Unsafe,
 	TreeRecordNodeUnsafe,
+	UnannotateAllowedTypeUnsafe,
+	AnnotatedAllowedTypeUnsafe,
+	AnnotatedAllowedTypesUnsafe,
+	AllowedTypesFullUnsafe,
+	AllowedTypesFullFromMixedUnsafe,
+	UnannotateAllowedTypesListUnsafe,
+	AnnotateAllowedTypesListUnsafe,
 } from "./typesUnsafe.js";
 
 export {

packages/dds/tree/src/simple-tree/api/schemaFactoryAlpha.ts

@@ -40,10 +40,14 @@ import {
 	AnnotatedAllowedTypesInternal,
 } 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";
@@ -113,28 +117,64 @@ export interface SchemaStaticsAlpha {
 		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,
 
-	types: <const T extends readonly (AnnotatedAllowedType | LazyItem<TreeNodeSchema>)[]>(
-		t: T,
-		metadata: AllowedTypesMetadata = {},
-	): AllowedTypesFullFromMixed<T> => {
-		return AnnotatedAllowedTypesInternal.createMixed<T>(t, metadata);
-	},
+	stagedRecursive: staged as SchemaStaticsAlpha["stagedRecursive"],
+	typesRecursive: types as unknown as SchemaStaticsAlpha["typesRecursive"],
 };
 
 /**
@@ -310,6 +350,16 @@ 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}
 	 */
@@ -320,6 +370,16 @@ export class SchemaFactoryAlpha<
 	 */
 	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}.
 	 *
@@ -405,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<

packages/dds/tree/src/simple-tree/api/schemaStatics.ts

@@ -228,6 +228,9 @@ export const schemaStatics = {
 	},
 } as const;
 
+/**
+ * {@link Unenforced} version of {@link createFieldSchema}.
+ */
 function createFieldSchemaUnsafe<
 	Kind extends FieldKind,
 	Types extends System_Unsafe.ImplicitAllowedTypesUnsafe,

packages/dds/tree/src/simple-tree/api/typesUnsafe.ts

@@ -29,6 +29,8 @@ import type {
 	TreeLeafValue,
 	FlexListToUnion,
 	LazyItem,
+	AnnotatedAllowedType,
+	AnnotatedAllowedTypes,
 } from "../core/index.js";
 import type { TreeArrayNode } from "../node-kinds/index.js";
 import type { SimpleArrayNodeSchema, SimpleMapNodeSchema } from "../simpleSchema.js";
@@ -543,3 +545,82 @@ export interface TreeRecordNodeUnsafe<
 		[string, System_Unsafe.TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>]
 	>;
 }
+
+/**
+ * {@link Unenforced} utility to remove {@link AnnotatedAllowedTypeUnsafe} wrappers.
+ * @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.
+ * @sealed
+ * @alpha
+ * @system
+ */
+export type UnannotateAllowedTypeUnsafe<
+	T extends Unenforced<
+		AnnotatedAllowedTypeUnsafe | LazyItem<System_Unsafe.TreeNodeSchemaUnsafe>
+	>,
+> = T extends AnnotatedAllowedTypeUnsafe<infer X> ? X : T;
+
+/**
+ * {@link Unenforced} version of {@link AnnotatedAllowedType}.
+ * @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 AnnotatedAllowedTypeUnsafe<T = Unenforced<LazyItem<TreeNodeSchema>>>
+	extends AnnotatedAllowedType<T> {}
+
+/**
+ * {@link Unenforced} version of {@link AnnotatedAllowedTypes}.
+ * @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 AnnotatedAllowedTypesUnsafe
+	extends AnnotatedAllowedTypes<LazyItem<System_Unsafe.TreeNodeSchemaUnsafe>> {}
+
+/**
+ * {@link Unenforced} version of {@link AllowedTypesFull}.
+ * @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 type AllowedTypesFullUnsafe<
+	T extends readonly AnnotatedAllowedTypeUnsafe[] = readonly AnnotatedAllowedTypeUnsafe[],
+> = AnnotatedAllowedTypes<T> & UnannotateAllowedTypesListUnsafe<T>;
+
+/**
+ * {@link Unenforced} version of {@link AllowedTypesFullFromMixed}.
+ * @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 type AllowedTypesFullFromMixedUnsafe<
+	T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[],
+> = UnannotateAllowedTypesListUnsafe<T> &
+	AnnotatedAllowedTypes<AnnotateAllowedTypesListUnsafe<T>>;
+
+/**
+ * {@link Unenforced} version of {@link UnannotateAllowedTypesList}.
+ * @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 type UnannotateAllowedTypesListUnsafe<
+	T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[],
+> = {
+	readonly [I in keyof T]: T[I] extends { type: infer X } ? X : T[I];
+};
+
+/**
+ * {@link Unenforced} version of {@link AnnotateAllowedTypesList}.
+ * @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 type AnnotateAllowedTypesListUnsafe<
+	T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[],
+> = {
+	[I in keyof T]: T[I] extends AnnotatedAllowedTypeUnsafe
+		? T[I]
+		: AnnotatedAllowedTypeUnsafe<T[I]>;
+};

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

@@ -127,6 +127,13 @@ export {
 	type ArrayNodeCustomizableSchemaUnsafe,
 	type MapNodeCustomizableSchemaUnsafe,
 	type TreeRecordNodeUnsafe,
+	type UnannotateAllowedTypeUnsafe,
+	type AnnotatedAllowedTypeUnsafe,
+	type AnnotatedAllowedTypesUnsafe,
+	type AllowedTypesFullUnsafe,
+	type AllowedTypesFullFromMixedUnsafe,
+	type UnannotateAllowedTypesListUnsafe,
+	type AnnotateAllowedTypesListUnsafe,
 	type TreeViewAlpha,
 	type TreeBranch,
 	type TreeBranchEvents,