feat(tree): enablable allowed types

.changeset/curly-bikes-train.md

@@ -0,0 +1,26 @@
+---
+"fluid-framework": minor
+"@fluidframework/tree": minor
+"__section": feature
+---
+Adds enablable allowed types to SchemaFactoryAlpha
+
+This adds the `enablable` API to [`SchemaFactoryAlpha`](https://fluidframework.com/docs/api/fluid-framework/schemafactoryalpha-class).
+Enablables can be used for schema evolution to add members to an [`AllowedTypes`](https://fluidframework.com/docs/api/fluid-framework/allowedtypes-typealias) while supporting cross version collaboration.
+
+Enablables are allowed types that can be enabled by schema upgrades.
+Before being enabled, any attempt to insert or move a node to a location which requires the enablement for its type to be valid will throw an error.
+
+To add a new member to an `AllowedTypes`, add the type wrapped by `enablable`.
+For example, migrating an array which previously supported only numbers to support both numbers and strings would start by deploying a version of the app using `enablable`:
+```typescript
+schemaFactoryAlpha.arrayAlpha("TestArray", [schemaFactoryAlpha.number, schemaFactoryAlpha.enablable(schemaFactoryAlpha.string)]);
+```
+
+Once enough clients have this code update, it is safe to allow writing strings to the array.
+To enable writing strings to the array, a code change must be made to remove the enablable annotation:
+```typescript
+schemaFactoryAlpha.arrayAlpha("TestArray", [schemaFactoryAlpha.number, schemaFactoryAlpha.string]);
+```
+
+In the future, SharedTree may add an API that allows enablables to be enabled via a runtime schema upgrade so that the type can be more easily deployed using a configuration flag change rather than a code change.

packages/dds/tree/.vscode/settings.json

@@ -21,6 +21,7 @@
 		"covariantly",
 		"deprioritized",
 		"enablable",
+		"enablables",
 		"endregion",
 		"fluidframework",
 		"insertable",

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

@@ -18,6 +18,7 @@ export function adaptEnum<TScope extends string, const TEnum extends Record<stri
 // @alpha
 export interface AllowedTypeMetadata {
     readonly custom?: unknown;
+    readonly enablableSchemaUpgrade?: SchemaUpgrade;
 }
 
 // @public @system
@@ -421,17 +422,17 @@ export namespace JsonAsTree {
     }
     const // @system
     _APIExtractorWorkaroundObjectBase: TreeNodeSchemaClass<"com.fluidframework.json.object", NodeKind.Map, System_Unsafe.TreeMapNodeUnsafe<readonly [LeafSchema<"null", null>, LeafSchema<"number", number>, LeafSchema<"string", string>, LeafSchema<"boolean", boolean>, () => typeof JsonObject, () => typeof Array]> & WithType<"com.fluidframework.json.object", NodeKind.Map, unknown>, {
-        [Symbol.iterator](): Iterator<[string, string | number | JsonObject | Array | System_Unsafe.InsertableTypedNodeUnsafe<LeafSchema<"boolean", boolean>, LeafSchema<"boolean", boolean>> | null], any, undefined>;
+        [Symbol.iterator](): Iterator<[string, string | number | System_Unsafe.InsertableTypedNodeUnsafe<LeafSchema<"boolean", boolean>, LeafSchema<"boolean", boolean>> | JsonObject | Array | null], any, undefined>;
     } | {
-        readonly [x: string]: string | number | JsonObject | Array | System_Unsafe.InsertableTypedNodeUnsafe<LeafSchema<"boolean", boolean>, LeafSchema<"boolean", boolean>> | null;
+        readonly [x: string]: string | number | System_Unsafe.InsertableTypedNodeUnsafe<LeafSchema<"boolean", boolean>, LeafSchema<"boolean", boolean>> | JsonObject | Array | null;
     }, false, readonly [LeafSchema<"null", null>, LeafSchema<"number", number>, LeafSchema<"string", string>, LeafSchema<"boolean", boolean>, () => typeof JsonObject, () => typeof Array], undefined>;
     // (undocumented)
     export type Primitive = TreeNodeFromImplicitAllowedTypes<typeof Primitive>;
     // @system
     export type _RecursiveArrayWorkaroundJsonArray = FixRecursiveArraySchema<typeof Array>;
     const // @system
     _APIExtractorWorkaroundArrayBase: TreeNodeSchemaClass<"com.fluidframework.json.array", NodeKind.Array, System_Unsafe.TreeArrayNodeUnsafe<readonly [LeafSchema<"null", null>, LeafSchema<"number", number>, LeafSchema<"string", string>, LeafSchema<"boolean", boolean>, () => typeof JsonObject, () => typeof Array]> & WithType<"com.fluidframework.json.array", NodeKind.Array, unknown>, {
-        [Symbol.iterator](): Iterator<string | number | JsonObject | Array | System_Unsafe.InsertableTypedNodeUnsafe<LeafSchema<"boolean", boolean>, LeafSchema<"boolean", boolean>> | null, any, undefined>;
+        [Symbol.iterator](): Iterator<string | number | System_Unsafe.InsertableTypedNodeUnsafe<LeafSchema<"boolean", boolean>, LeafSchema<"boolean", boolean>> | JsonObject | Array | null, any, undefined>;
     }, false, readonly [LeafSchema<"null", null>, LeafSchema<"number", number>, LeafSchema<"string", string>, LeafSchema<"boolean", boolean>, () => typeof JsonObject, () => typeof Array], undefined>;
     // (undocumented)
     export type Tree = TreeNodeFromImplicitAllowedTypes<typeof Tree>;
@@ -760,6 +761,7 @@ export class SchemaFactory<out TScope extends string | undefined = string | unde
 export class SchemaFactoryAlpha<out TScope extends string | undefined = string | undefined, TName extends number | string = string> extends SchemaFactory<TScope, TName> {
     arrayAlpha<const Name extends TName, const T extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>): ArrayNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
     arrayRecursive<const Name extends TName, const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>): ArrayNodeCustomizableSchemaUnsafe<ScopedSchemaName<TScope, Name>, T, TCustomMetadata>;
+    enablable<const T extends TreeNodeSchema>(t: T | AnnotatedAllowedType<T>): AnnotatedAllowedType<T>;
     static readonly identifier: <const TCustomMetadata = unknown>(props?: Omit<FieldProps_2<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha_2<FieldKind_2.Identifier, LeafSchema_2<"string", string> & SimpleLeafNodeSchema_2, TCustomMetadata>;
     static readonly leaves: readonly [LeafSchema_2<"string", string> & SimpleLeafNodeSchema_2, LeafSchema_2<"number", number> & SimpleLeafNodeSchema_2, LeafSchema_2<"boolean", boolean> & SimpleLeafNodeSchema_2, LeafSchema_2<"null", null> & SimpleLeafNodeSchema_2, LeafSchema_2<"handle", IFluidHandle<unknown>> & SimpleLeafNodeSchema_2];
     mapAlpha<Name extends TName, const T extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptions<TCustomMetadata>): MapNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
@@ -805,6 +807,10 @@ export interface SchemaStatics {
     readonly string: LeafSchema<"string", string>;
 }
 
+// @alpha @sealed
+export class SchemaUpgrade {
+}
+
 // @alpha
 export interface SchemaValidationFunction<Schema extends TSchema> {
     check(data: unknown): data is Static<Schema>;

packages/dds/tree/src/index.ts

@@ -115,6 +115,7 @@ export {
 	type InternalTreeNode,
 	type WithType,
 	type NodeChangedData,
+	type SchemaUpgrade,
 	// Types not really intended for public use, but used in links.
 	// Can not be moved to internalTypes since doing so causes app code to throw errors like:
 	// Error: src/simple-tree/objectNode.ts:72:1 - (ae-unresolved-link) The @link reference could not be resolved: The package "@fluidframework/tree" does not have an export "TreeNodeApi"

packages/dds/tree/src/shared-tree/schematizingTreeView.ts

@@ -183,6 +183,8 @@ export class SchematizingSimpleTreeView<
 					policy: this.schemaPolicy,
 				},
 				this,
+				// this allows enablable allowed types to be loaded into a tree
+				true,
 			);
 
 			initialize(this.checkout, {
@@ -462,7 +464,7 @@ export class SchematizingSimpleTreeView<
 		const view = this.getView();
 		setField(
 			view.context.root,
-			this.rootFieldSchema,
+			normalizeFieldSchema(this.rootFieldSchema),
 			newRoot as InsertableContent | undefined,
 		);
 	}

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

@@ -90,11 +90,9 @@ export function cursorFromInsertable<
 ):
 	| ITreeCursorSynchronous
 	| (TSchema extends FieldSchema<FieldKind.Optional> ? undefined : never) {
-	const mapTree = mapTreeFromNodeData(
-		data as InsertableField<UnsafeUnknownSchema>,
-		schema,
+	const mapTree = mapTreeFromNodeData(data as InsertableField<UnsafeUnknownSchema>, schema, {
 		context,
-	);
+	});
 	if (mapTree === undefined) {
 		return undefined as TSchema extends FieldSchema<FieldKind.Optional> ? undefined : never;
 	}

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

@@ -10,16 +10,19 @@ import {
 	type SchemaFactoryObjectOptions,
 	type ScopedSchemaName,
 } from "./schemaFactory.js";
-import type {
-	ImplicitAllowedTypes,
-	ImplicitAnnotatedAllowedTypes,
-	ImplicitAnnotatedFieldSchema,
-	ImplicitFieldSchema,
-	NodeSchemaOptions,
+import {
+	createSchemaUpgrade,
+	normalizeToAnnotatedAllowedType,
+	type AnnotatedAllowedType,
+	type ImplicitAllowedTypes,
+	type ImplicitAnnotatedAllowedTypes,
+	type ImplicitAnnotatedFieldSchema,
+	type ImplicitFieldSchema,
+	type NodeSchemaOptions,
 } from "../schemaTypes.js";
 import { objectSchema } from "../objectNode.js";
 import type { RestrictiveStringRecord } from "../../util/index.js";
-import type { NodeKind, TreeNodeSchemaClass } from "../core/index.js";
+import type { NodeKind, TreeNodeSchema, TreeNodeSchemaClass } from "../core/index.js";
 import type {
 	ArrayNodeCustomizableSchemaUnsafe,
 	MapNodeCustomizableSchemaUnsafe,
@@ -51,6 +54,34 @@ export class SchemaFactoryAlpha<
 		) as ScopedSchemaName<TScope, Name>;
 	}
 
+	/**
+	 * Declares a type enablable in a set of {@link AllowedTypes}.
+	 *
+	 * @remarks
+	 * An allowed type that is enablable can be read from the document but cannot be written.
+	 * Enablables add support for reading a type which can be used for schema evolution to add members to
+	 * an {@link AllowedTypes} while supporting cross version collaboration.
+	 *
+	 * Once enough clients supporting reading the type, support for writing can be added by removing the use of
+	 * `enablable` from the schema definition.
+	 *
+	 * A future change will allow writing the type using a runtime schema upgrade so that the type can be enabled
+	 * using a configuration flag change rather than a code change.
+	 *
+	 */
+	public enablable<const T extends TreeNodeSchema>(
+		t: T | AnnotatedAllowedType<T>,
+	): AnnotatedAllowedType<T> {
+		const annotatedType = normalizeToAnnotatedAllowedType(t);
+		return {
+			type: annotatedType.type,
+			metadata: {
+				...annotatedType.metadata,
+				enablableSchemaUpgrade: createSchemaUpgrade(),
+			},
+		};
+	}
+
 	/**
 	 * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.
 	 *

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

@@ -826,15 +826,15 @@ type Insertable<T extends ImplicitAllowedTypes> = readonly (
 	| IterableTreeArrayContent<InsertableTreeNodeFromImplicitAllowedTypes<T>>
 )[];
 
-abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
+abstract class CustomArrayNodeBase<const T extends ImplicitAnnotatedAllowedTypes>
 	extends TreeNodeWithArrayFeatures<
-		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
-		TreeNodeFromImplicitAllowedTypes<T>
+		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<UnannotateImplicitAllowedTypes<T>>>,
+		TreeNodeFromImplicitAllowedTypes<UnannotateImplicitAllowedTypes<T>>
 	>
-	implements TreeArrayNode<T>
+	implements TreeArrayNode<UnannotateImplicitAllowedTypes<T>>
 {
 	// Indexing must be provided by subclass.
-	[k: number]: TreeNodeFromImplicitAllowedTypes<T>;
+	[k: number]: TreeNodeFromImplicitAllowedTypes<UnannotateImplicitAllowedTypes<T>>;
 
 	public static readonly kind = NodeKind.Array;
 
@@ -847,12 +847,16 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	>;
 
 	public constructor(
-		input?: Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>> | InternalTreeNode,
+		input?:
+			| Iterable<InsertableTreeNodeFromImplicitAllowedTypes<UnannotateImplicitAllowedTypes<T>>>
+			| InternalTreeNode,
 	) {
 		super(input ?? []);
 	}
 
-	#mapTreesFromFieldData(value: Insertable<T>): ExclusiveMapTree[] {
+	#mapTreesFromFieldData(
+		value: Insertable<UnannotateImplicitAllowedTypes<T>>,
+	): ExclusiveMapTree[] {
 		const sequenceField = getSequenceField(this);
 		const content = value as readonly (
 			| InsertableContent
@@ -884,7 +888,9 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		return fail(0xadb /* Proxy should intercept length */);
 	}
 
-	public [Symbol.iterator](): IterableIterator<TreeNodeFromImplicitAllowedTypes<T>> {
+	public [Symbol.iterator](): IterableIterator<
+		TreeNodeFromImplicitAllowedTypes<UnannotateImplicitAllowedTypes<T>>
+	> {
 		return this.values();
 	}
 
@@ -896,28 +902,33 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	}
 
 	public at(
-		this: TreeArrayNode<T>,
+		this: TreeArrayNode<UnannotateImplicitAllowedTypes<T>>,
 		index: number,
-	): TreeNodeFromImplicitAllowedTypes<T> | undefined {
+	): TreeNodeFromImplicitAllowedTypes<UnannotateImplicitAllowedTypes<T>> | undefined {
 		const field = getSequenceField(this);
 		const val = field.boxedAt(index);
 
 		if (val === undefined) {
 			return val;
 		}
 
-		return getOrCreateNodeFromInnerNode(val) as TreeNodeFromImplicitAllowedTypes<T>;
+		return getOrCreateNodeFromInnerNode(val) as TreeNodeFromImplicitAllowedTypes<
+			UnannotateImplicitAllowedTypes<T>
+		>;
 	}
-	public insertAt(index: number, ...value: Insertable<T>): void {
+	public insertAt(
+		index: number,
+		...value: Insertable<UnannotateImplicitAllowedTypes<T>>
+	): void {
 		const field = getSequenceField(this);
 		validateIndex(index, field, "insertAt", true);
 		const content = this.#mapTreesFromFieldData(value);
 		field.editor.insert(index, content);
 	}
-	public insertAtStart(...value: Insertable<T>): void {
+	public insertAtStart(...value: Insertable<UnannotateImplicitAllowedTypes<T>>): void {
 		this.insertAt(0, ...value);
 	}
-	public insertAtEnd(...value: Insertable<T>): void {
+	public insertAtEnd(...value: Insertable<UnannotateImplicitAllowedTypes<T>>): void {
 		this.insertAt(this.length, ...value);
 	}
 	public removeAt(index: number): void {
@@ -1057,12 +1068,14 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 		}
 	}
 
-	public values(): IterableIterator<TreeNodeFromImplicitAllowedTypes<T>> {
+	public values(): IterableIterator<
+		TreeNodeFromImplicitAllowedTypes<UnannotateImplicitAllowedTypes<T>>
+	> {
 		return this.generateValues(getKernel(this).generationNumber);
 	}
 	private *generateValues(
 		initialLastUpdatedStamp: number,
-	): Generator<TreeNodeFromImplicitAllowedTypes<T>> {
+	): Generator<TreeNodeFromImplicitAllowedTypes<UnannotateImplicitAllowedTypes<T>>> {
 		const kernel = getKernel(this);
 		if (initialLastUpdatedStamp !== kernel.generationNumber) {
 			throw new UsageError(`Concurrent editing and iteration is not allowed.`);
@@ -1113,7 +1126,7 @@ export function arraySchema<
 
 	// This class returns a proxy from its constructor to handle numeric indexing.
 	// Alternatively it could extend a normal class which gets tons of numeric properties added.
-	class Schema extends CustomArrayNodeBase<UnannotateImplicitAllowedTypes<T>> {
+	class Schema extends CustomArrayNodeBase<T> {
 		public static override prepareInstance<T2>(
 			this: typeof TreeNodeValid<T2>,
 			instance: TreeNodeValid<T2>,
@@ -1200,8 +1213,8 @@ export function arraySchema<
 			return Schema.constructorCached?.constructor as unknown as Output;
 		}
 
-		protected get simpleSchema(): UnannotateImplicitAllowedTypes<T> {
-			return unannotatedTypes;
+		protected get simpleSchema(): T {
+			return info;
 		}
 		protected get allowedTypes(): ReadonlySet<TreeNodeSchema> {
 			return lazyChildTypes.value;

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

@@ -158,6 +158,7 @@ export {
 	type AllowedTypes,
 	type AllowedTypeMetadata,
 	type AllowedTypesMetadata,
+	type SchemaUpgrade,
 	FieldKind,
 	FieldSchema,
 	type FieldSchemaAlpha,

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

@@ -273,7 +273,10 @@ export function mapSchema<
 		): UnhydratedFlexTreeNode {
 			return UnhydratedFlexTreeNode.getOrCreate(
 				unhydratedContext,
-				mapTreeFromNodeData(input as FactoryContent, this as unknown as ImplicitAllowedTypes),
+				mapTreeFromNodeData(
+					input as FactoryContent,
+					this as unknown as ImplicitAnnotatedAllowedTypes,
+				),
 			);
 		}