@fluidframework/tree 2.71.0 → 2.72.0

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

@@ -25,35 +25,21 @@ import type { ImplicitFieldSchema } from "../fieldSchema.js";
 import type { RestrictiveStringRecord } from "../../util/index.js";
 import type {
 	NodeKind,
-	TreeNodeSchema,
 	TreeNodeSchemaClass,
 	ImplicitAllowedTypes,
-	AnnotatedAllowedType,
-	LazyItem,
 	WithType,
-	AllowedTypesMetadata,
-	AllowedTypesFullFromMixed,
-} from "../core/index.js";
-import {
-	normalizeToAnnotatedAllowedType,
-	createSchemaUpgrade,
-	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";
 
 // These imports prevent a large number of type references in the API reports from showing up as *_2.
-/* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import/no-duplicates */
+/* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */
 import type {
 	FieldProps,
 	FieldSchemaAlpha,
@@ -63,119 +49,7 @@ import type {
 import type { LeafSchema } from "../leafNodeSchema.js";
 import type { SimpleLeafNodeSchema } from "../simpleSchema.js";
 import type { FieldSchemaAlphaUnsafe } from "./typesUnsafe.js";
-/* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import/no-duplicates */
-
-/**
- * Stateless APIs exposed via {@link SchemaFactoryAlpha} as both instance properties and as statics.
- * @remarks
- * See {@link SchemaStatics} for why this is useful.
- * @system @sealed @alpha
- */
-export interface SchemaStaticsAlpha {
-	/**
-	 * Declares a staged type in a set of {@link AllowedTypes}.
-	 *
-	 * @remarks
-	 * Staged allowed types add support for loading documents which may contain that type at the declared location.
-	 * This allows for an incremental rollout of a schema change to add a {@link TreeNodeSchema} to an {@link AllowedTypes} without breaking cross version collaboration.
-	 * A guide on this process can be found here: https://fluidframework.com/docs/data-structures/tree/schema-evolution/allowed-types-rollout
-	 *
-	 * Once enough clients have the type staged (and thus can read documents which allow it), documents can start being created and upgraded to allow the staged type.
-	 * This is done by deploying a new version of the app which removes the `staged` wrapper around the allowed type in the the schema definition.
-	 * This will also require {@link TreeView.upgradeSchema|upgrading the schema} for existing documents.
-	 *
-	 * Using a staged allowed type in a schema is just like using the schema as an allowed type with the following exceptions:
-	 *
-	 * 1. {@link TreeView.initialize} will omit the staged allowed type from the newly created stored schema.
-	 * 2. {@link TreeView.upgradeSchema} will omit the staged allowed type from the the upgraded stored schema.
-	 * 3. When evaluating {@link TreeView.compatibility}, it will be viewable even if the staged allowed type is not present in the stored schema's corresponding allowed types.
-	 * 4. Because of the above, it is possible to get errors when inserting content which uses the staged allowed type into a tree whose stored schema does not permit it.
-	 *
-	 * Currently, `staged` is not supported in the recursive type APIs: this is a known limitation which future versions of the API will address.
-	 *
-	 * @example
-	 * A full code example of the schema migration process can be found in our {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/src/test/simple-tree/api/stagedSchemaUpgrade.spec.ts | tests}.
-	 *
-	 * @privateRemarks
-	 * TODO:#44317 staged allowed types rely on schema validation of stored schema to output errors, these errors are not very
-	 * user friendly and should be improved, particularly in the case of staged allowed types
-	 *
-	 * TODO: AB#45711: Update the docs above when recursive type support is added.
-	 */
-	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,
-	types,
-
-	stagedRecursive: staged as SchemaStaticsAlpha["stagedRecursive"],
-	typesRecursive: types as unknown as SchemaStaticsAlpha["typesRecursive"],
-};
+/* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */
 
 /**
  * {@link SchemaFactory} with additional alpha APIs.
@@ -335,46 +209,6 @@ export class SchemaFactoryAlpha<
 	 */
 	public override readonly requiredRecursive = schemaStatics.requiredRecursive;
 
-	/**
-	 * {@inheritDoc SchemaStaticsAlpha.staged}
-	 */
-	public static staged = schemaStaticsAlpha.staged;
-
-	/**
-	 * {@inheritDoc SchemaStaticsAlpha.staged}
-	 */
-	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}.
 	 *

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

@@ -3,14 +3,21 @@
  * Licensed under the MIT License.
  */
 
-import type {
-	ImplicitAllowedTypes,
-	NodeKind,
-	TreeNodeSchema,
-	TreeNodeSchemaBoth,
-	TreeNodeSchemaClass,
-	TreeNodeSchemaNonClass,
-	WithType,
+import {
+	AnnotatedAllowedTypesInternal,
+	createSchemaUpgrade,
+	normalizeToAnnotatedAllowedType,
+	type AllowedTypesFullFromMixed,
+	type AllowedTypesMetadata,
+	type AnnotatedAllowedType,
+	type ImplicitAllowedTypes,
+	type LazyItem,
+	type NodeKind,
+	type TreeNodeSchema,
+	type TreeNodeSchemaBoth,
+	type TreeNodeSchemaClass,
+	type TreeNodeSchemaNonClass,
+	type WithType,
 } from "../core/index.js";
 
 import {
@@ -30,10 +37,17 @@ import {
 	type ObjectSchemaOptions,
 	type ScopedSchemaName,
 } from "./schemaFactory.js";
-import type { System_Unsafe, TreeRecordNodeUnsafe } from "./typesUnsafe.js";
+import type {
+	AllowedTypesFullFromMixedUnsafe,
+	AnnotatedAllowedTypeUnsafe,
+	System_Unsafe,
+	TreeRecordNodeUnsafe,
+	UnannotateAllowedTypeUnsafe,
+	Unenforced,
+} from "./typesUnsafe.js";
 
 // These imports prevent a large number of type references in the API reports from showing up as *_2.
-/* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import/no-duplicates */
+/* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */
 import type {
 	FieldProps,
 	FieldSchemaAlpha,
@@ -44,7 +58,119 @@ import type {
 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 */
+/* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */
+
+/**
+ * Stateless APIs exposed via {@link SchemaFactoryBeta} as both instance properties and as statics.
+ * @see {@link SchemaStatics} for why this is useful.
+ * @system @sealed @beta
+ */
+export interface SchemaStaticsBeta {
+	/**
+	 * Declares a staged type in a set of {@link AllowedTypes}.
+	 *
+	 * @remarks
+	 * Staged allowed types add support for loading documents which may contain that type at the declared location.
+	 * This allows for an incremental rollout of a schema change to add a {@link TreeNodeSchema} to an {@link AllowedTypes} without breaking cross version collaboration.
+	 * A guide on this process can be found here: https://fluidframework.com/docs/data-structures/tree/schema-evolution/allowed-types-rollout
+	 *
+	 * Once enough clients have the type staged (and thus can read documents which allow it), documents can start being created and upgraded to allow the staged type.
+	 * This is done by deploying a new version of the app which removes the `staged` wrapper around the allowed type in the the schema definition.
+	 * This will also require {@link TreeView.upgradeSchema|upgrading the schema} for existing documents.
+	 *
+	 * Using a staged allowed type in a schema is just like using the schema as an allowed type with the following exceptions:
+	 *
+	 * 1. {@link TreeView.initialize} will omit the staged allowed type from the newly created stored schema.
+	 * 2. {@link TreeView.upgradeSchema} will omit the staged allowed type from the the upgraded stored schema.
+	 * 3. When evaluating {@link TreeView.compatibility}, it will be viewable even if the staged allowed type is not present in the stored schema's corresponding allowed types.
+	 * 4. Because of the above, it is possible to get errors when inserting content which uses the staged allowed type into a tree whose stored schema does not permit it.
+	 *
+	 * For recursive schemas, use {@link SchemaStaticsBeta.stagedRecursive} instead.
+	 * It offers equivalent runtime behavior with relaxed compile-time typing for recursive type.
+	 *
+	 * @example
+	 * A full code example of the schema migration process can be found in our {@link https://github.com/microsoft/FluidFramework/blob/main/packages/dds/tree/src/test/simple-tree/api/stagedSchemaUpgrade.spec.ts | tests}.
+	 *
+	 * @privateRemarks
+	 * TODO:#44317 staged allowed types rely on schema validation of stored schema to output errors, these errors are not very
+	 * user friendly and should be improved, particularly in the case of staged allowed types
+	 *
+	 * TODO: AB#45711: Update the docs above when recursive type support is added.
+	 */
+	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 SchemaStaticsBeta.staged} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStaticsBeta.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 SchemaStaticsBeta.types} except tweaked to work better for recursive types.
+	 * Use with {@link ValidateRecursiveSchema} for improved type safety.
+	 * @remarks
+	 * This version of {@link SchemaStaticsBeta.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 schemaStaticsBeta: SchemaStaticsBeta = {
+	staged,
+	types,
+
+	stagedRecursive: staged as SchemaStaticsBeta["stagedRecursive"],
+	typesRecursive: types as unknown as SchemaStaticsBeta["typesRecursive"],
+};
 
 /**
  * {@link SchemaFactory} with additional beta APIs.
@@ -55,6 +181,46 @@ export class SchemaFactoryBeta<
 	out TScope extends string | undefined = string | undefined,
 	TName extends number | string = string,
 > extends SchemaFactory<TScope, TName> {
+	/**
+	 * {@inheritDoc SchemaStaticsBeta.staged}
+	 */
+	public static staged = schemaStaticsBeta.staged;
+
+	/**
+	 * {@inheritDoc SchemaStaticsBeta.staged}
+	 */
+	public staged = schemaStaticsBeta.staged;
+
+	/**
+	 * {@inheritDoc SchemaStaticsBeta.stagedRecursive}
+	 */
+	public static stagedRecursive = schemaStaticsBeta.stagedRecursive;
+
+	/**
+	 * {@inheritDoc SchemaStaticsBeta.stagedRecursive}
+	 */
+	public stagedRecursive = schemaStaticsBeta.stagedRecursive;
+
+	/**
+	 * {@inheritDoc SchemaStaticsBeta.types}
+	 */
+	public static types = schemaStaticsBeta.types;
+
+	/**
+	 * {@inheritDoc SchemaStaticsBeta.types}
+	 */
+	public types = schemaStaticsBeta.types;
+
+	/**
+	 * {@inheritDoc SchemaStaticsBeta.typesRecursive}
+	 */
+	public static typesRecursive = schemaStaticsBeta.typesRecursive;
+
+	/**
+	 * {@inheritDoc SchemaStaticsBeta.typesRecursive}
+	 */
+	public typesRecursive = schemaStaticsBeta.typesRecursive;
+
 	/**
 	 * Create a {@link SchemaFactory} with a {@link SchemaFactory.scope|scope} which is a combination of this factory's scope and the provided name.
 	 * @remarks
@@ -250,9 +416,9 @@ export class SchemaFactoryBeta<
 		/* Info */ T
 	> {
 		if (maybeAllowedTypes === undefined) {
-			const types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];
-			const fullName = structuralName("Record", types);
-			return this.getStructuralType(fullName, types, () =>
+			const nodeTypes = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];
+			const fullName = structuralName("Record", nodeTypes);
+			return this.getStructuralType(fullName, nodeTypes, () =>
 				this.namedRecord(
 					fullName,
 					nameOrAllowedTypes as T,

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

@@ -106,9 +106,12 @@ function generateNode(
 			for (const [key, field] of schema.fields) {
 				fields[key] = generateFieldSchema(field, context, field.storedKey);
 			}
-			// Here allowUnknownOptionalFields is implicitly defaulting. This is a subjective policy choice:
-			// users of this code are expected to handle what ever choice this code makes for cases like this.
-			return factory.objectAlpha(id, fields, { metadata: schema.metadata });
+			// Here allowUnknownOptionalFields is implicitly defaulting in the case where the input schema does not explicitly specify the value.
+			// This is a subjective policy choice: users of this code are expected to handle what ever choice this code makes for cases like this.
+			return factory.objectAlpha(id, fields, {
+				metadata: schema.metadata,
+				allowUnknownOptionalFields: schema.allowUnknownOptionalFields ?? false,
+			});
 		}
 		case NodeKind.Array:
 			return factory.arrayAlpha(id, generateAllowedTypes(schema.simpleAllowedTypes, context), {