@fluidframework/tree 2.71.0 → 2.73.0

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

@@ -6,7 +6,6 @@
 import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.js";
 import type {
-	SimpleAllowedTypeAttributes,
 	SimpleArrayNodeSchema,
 	SimpleFieldSchema,
 	SimpleLeafNodeSchema,
@@ -32,7 +31,6 @@ import { LeafNodeSchema } from "../leafNodeSchema.js";
  *
  * @param schema - The schema to convert
  * @param copySchemaObjects - If true, TreeNodeSchema and FieldSchema are copied into plain JavaScript objects. Either way, custom metadata is referenced and not copied.
- * @param isViewSchema - If true (default), properties used by view schema but not part of stored schema (for example, `isStaged` on allowed types) are preserved in the output.
  *
  * @remarks
  * Given that the Schema types used in {@link ImplicitFieldSchema} already implement the {@link SimpleNodeSchema} interfaces, there are limited use-cases for this function.
@@ -47,7 +45,6 @@ import { LeafNodeSchema } from "../leafNodeSchema.js";
 export function toSimpleTreeSchema(
 	schema: ImplicitFieldSchema,
 	copySchemaObjects: boolean,
-	isViewSchema: boolean = true,
 ): SimpleTreeSchema {
 	const normalizedSchema = normalizeFieldSchema(schema);
 	const definitions = new Map<string, SimpleNodeSchema>();
@@ -62,9 +59,7 @@ export function toSimpleTreeSchema(
 					nodeSchema instanceof RecordNodeSchema,
 				0xb60 /* Invalid schema */,
 			);
-			const outSchema = copySchemaObjects
-				? copySimpleNodeSchema(nodeSchema, isViewSchema)
-				: nodeSchema;
+			const outSchema = copySchemaObjects ? copySimpleNodeSchema(nodeSchema) : nodeSchema;
 			definitions.set(nodeSchema.identifier, outSchema);
 		},
 	});
@@ -72,10 +67,7 @@ export function toSimpleTreeSchema(
 	return {
 		root: copySchemaObjects
 			? ({
-					simpleAllowedTypes: normalizeSimpleAllowedTypes(
-						normalizedSchema.simpleAllowedTypes,
-						isViewSchema,
-					),
+					simpleAllowedTypes: normalizedSchema.simpleAllowedTypes,
 					kind: normalizedSchema.kind,
 					metadata: normalizedSchema.metadata,
 					persistedMetadata: normalizedSchema.persistedMetadata,
@@ -85,36 +77,12 @@ export function toSimpleTreeSchema(
 	};
 }
 
-/**
- * Normalizes the {@link SimpleAllowedTypeAttributes} by either preserving or omitting view-specific schema properties.
- * @param simpleAllowedTypes - The simple allowed types to normalize.
- * @param isViewSchema - If true, properties used by view schema but not part of stored schema (for example, `isStaged` on allowed types) are preserved in the output.
- * @returns The normalized simple allowed types.
- */
-function normalizeSimpleAllowedTypes(
-	simpleAllowedTypes: ReadonlyMap<string, SimpleAllowedTypeAttributes>,
-	isViewSchema: boolean,
-): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
-	if (isViewSchema) {
-		return simpleAllowedTypes;
-	} else {
-		const normalized = new Map<string, SimpleAllowedTypeAttributes>();
-		for (const [identifier, attributes] of simpleAllowedTypes.entries()) {
-			normalized.set(identifier, { ...attributes, isStaged: undefined });
-		}
-		return normalized;
-	}
-}
-
 /**
  * Copies a {@link SimpleNodeSchema} into a new plain JavaScript object.
  *
  * @remarks Caches the result on the input schema for future calls.
  */
-function copySimpleNodeSchema(
-	schema: SimpleNodeSchema,
-	isViewSchema: boolean,
-): SimpleNodeSchema {
+export function copySimpleNodeSchema(schema: SimpleNodeSchema): SimpleNodeSchema {
 	const kind = schema.kind;
 	switch (kind) {
 		case NodeKind.Leaf:
@@ -122,9 +90,9 @@ function copySimpleNodeSchema(
 		case NodeKind.Array:
 		case NodeKind.Map:
 		case NodeKind.Record:
-			return copySimpleSchemaWithAllowedTypes(schema, isViewSchema);
+			return copySimpleSchemaWithAllowedTypes(schema);
 		case NodeKind.Object:
-			return copySimpleObjectSchema(schema, isViewSchema);
+			return copySimpleObjectSchema(schema);
 		default:
 			unreachableCase(kind);
 	}
@@ -141,36 +109,101 @@ function copySimpleLeafSchema(schema: SimpleLeafNodeSchema): SimpleLeafNodeSchem
 
 function copySimpleSchemaWithAllowedTypes(
 	schema: SimpleMapNodeSchema | SimpleArrayNodeSchema | SimpleRecordNodeSchema,
-	isViewSchema: boolean,
 ): SimpleMapNodeSchema | SimpleArrayNodeSchema | SimpleRecordNodeSchema {
 	return {
 		kind: schema.kind,
-		simpleAllowedTypes: normalizeSimpleAllowedTypes(schema.simpleAllowedTypes, isViewSchema),
+		simpleAllowedTypes: schema.simpleAllowedTypes,
 		metadata: schema.metadata,
 		persistedMetadata: schema.persistedMetadata,
 	};
 }
 
-function copySimpleObjectSchema(
-	schema: SimpleObjectNodeSchema,
-	isViewSchema: boolean,
-): SimpleObjectNodeSchema {
+function copySimpleObjectSchema(schema: SimpleObjectNodeSchema): SimpleObjectNodeSchema {
 	const fields: Map<string, SimpleObjectFieldSchema> = new Map();
 	for (const [propertyKey, field] of schema.fields) {
 		// field already is a SimpleObjectFieldSchema, but copy the subset of the properties needed by this interface to get a clean simple object.
-		fields.set(propertyKey, {
+		const simpleField = {
 			kind: field.kind,
-			simpleAllowedTypes: normalizeSimpleAllowedTypes(field.simpleAllowedTypes, isViewSchema),
+			simpleAllowedTypes: field.simpleAllowedTypes,
 			metadata: field.metadata,
 			persistedMetadata: field.persistedMetadata,
 			storedKey: field.storedKey,
-		});
+		};
+
+		fields.set(propertyKey, simpleField);
 	}
 
-	return {
+	const simpleObject = {
 		kind: NodeKind.Object,
 		fields,
 		metadata: schema.metadata,
 		persistedMetadata: schema.persistedMetadata,
+		allowUnknownOptionalFields: schema.allowUnknownOptionalFields,
+	} satisfies SimpleObjectNodeSchema;
+
+	return simpleObject;
+}
+
+/**
+ * Creates a copy of a SimpleTreeSchema without metadata fields. This is useful for comparing deserialized view schemas with in-memory schemas.
+ * metadata and persistedMetadata are not relevant for schema compatibility checks and are not serialized by the Simple Schema serializer.
+ * @see {@link simpleSchemaSerializer.ts} for the serialization logic.
+ *
+ * @param schema - The SimpleTreeSchema to remove fields from.
+ * @param fieldsToRemove - An object specifying which fields to remove.
+ * @returns A new SimpleTreeSchema without the specified fields.
+ */
+export function copySimpleTreeSchemaWithoutMetadata(
+	schema: SimpleTreeSchema,
+): SimpleTreeSchema {
+	const definitions = new Map<string, SimpleNodeSchema>();
+
+	for (const [identifier, nodeSchema] of schema.definitions.entries()) {
+		const kind = nodeSchema.kind;
+		switch (kind) {
+			case NodeKind.Array:
+			case NodeKind.Map:
+			case NodeKind.Record:
+			case NodeKind.Leaf: {
+				const outputNodeSchema = {
+					...nodeSchema,
+					metadata: {},
+					persistedMetadata: undefined,
+				};
+				definitions.set(identifier, outputNodeSchema);
+				break;
+			}
+			case NodeKind.Object: {
+				const outputFields = new Map<string, SimpleObjectFieldSchema>();
+				for (const [propertyKey, fieldSchema] of nodeSchema.fields.entries()) {
+					const outputField: SimpleObjectFieldSchema = {
+						...fieldSchema,
+						metadata: {},
+						persistedMetadata: undefined,
+					};
+					outputFields.set(propertyKey, outputField);
+				}
+				const outputNodeSchema = {
+					...nodeSchema,
+					metadata: {},
+					persistedMetadata: undefined,
+					fields: outputFields,
+				};
+				definitions.set(identifier, outputNodeSchema);
+				break;
+			}
+			default:
+				unreachableCase(kind);
+		}
+	}
+
+	return {
+		root: {
+			kind: schema.root.kind,
+			simpleAllowedTypes: schema.root.simpleAllowedTypes,
+			metadata: {},
+			persistedMetadata: undefined,
+		},
+		definitions,
 	};
 }

package/src/simple-tree/core/allowedTypes.ts

@@ -57,7 +57,7 @@ export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
 /**
  * Stores annotations for an individual allowed type.
  * @remarks
- * Create using APIs on {@link SchemaFactoryAlpha}, like {@link SchemaStaticsAlpha.staged}.
+ * Create using APIs on {@link SchemaStaticsBeta}, like {@link SchemaStaticsBeta.staged}.
  * @privateRemarks
  * Since this is sealed, users are not supposed to create instances of it directly.
  * Making it extend ErasedType could enforce that.
@@ -262,7 +262,7 @@ export class AnnotatedAllowedTypesInternal<
 		const simpleAllowedTypes = new Map<string, SimpleAllowedTypeAttributes>();
 		for (const type of annotatedAllowedTypes.evaluate().types) {
 			simpleAllowedTypes.set(type.type.identifier, {
-				isStaged: type.metadata.stagedSchemaUpgrade !== undefined,
+				isStaged: type.metadata.stagedSchemaUpgrade ?? false,
 			});
 		}
 		return simpleAllowedTypes;
@@ -412,7 +412,7 @@ export interface AllowedTypeMetadata {
 	readonly custom?: unknown;
 
 	/**
-	 * If defined, indicates that an allowed type is {@link SchemaStaticsAlpha.staged | staged}.
+	 * If defined, indicates that an allowed type is {@link SchemaStaticsBeta.staged | staged}.
 	 */
 	readonly stagedSchemaUpgrade?: SchemaUpgrade;
 }
@@ -425,7 +425,7 @@ export let createSchemaUpgrade: () => SchemaUpgrade;
 /**
  * Unique token used to upgrade schemas and determine if a particular upgrade has been completed.
  * @remarks
- * Create using {@link SchemaStaticsAlpha.staged}.
+ * Create using {@link SchemaStaticsBeta.staged}.
  * @privateRemarks
  * TODO:#38722 implement runtime schema upgrades.
  * Until then, the class purely behaves mostly as a placeholder.

package/src/simple-tree/core/index.ts

@@ -65,6 +65,7 @@ export {
 	createSchemaUpgrade,
 	AnnotatedAllowedTypesInternal,
 	normalizeAllowedTypesInternal,
+	SchemaUpgrade,
 } from "./allowedTypes.js";
 export type {
 	AnnotatedAllowedType,
@@ -80,7 +81,6 @@ export type {
 	AllowedTypeMetadata,
 	AnnotatedAllowedTypes,
 	AnnotateAllowedTypesList,
-	SchemaUpgrade,
 	AllowedTypesFullInternal,
 	AllowedTypesFull,
 	AllowedTypesFullFromMixed,
@@ -117,4 +117,6 @@ export {
 	type StoredSchemaGenerationOptions,
 	convertAllowedTypes,
 	allowedTypeFilter,
+	type StoredFromViewSchemaGenerationOptions,
+	ExpectStored,
 } from "./toStored.js";

package/src/simple-tree/core/toStored.ts

@@ -4,18 +4,15 @@
  */
 
 import { brand } from "../../util/index.js";
-import {
-	normalizeAndEvaluateAnnotatedAllowedTypes,
-	type AnnotatedAllowedType,
-	type ImplicitAllowedTypes,
-	type SchemaUpgrade,
-} from "./allowedTypes.js";
+import type { SchemaUpgrade } from "./allowedTypes.js";
 import type { TreeNodeSchemaIdentifier, TreeTypeSet } from "../../core/index.js";
+import type { SimpleAllowedTypeAttributes, SimpleAllowedTypes } from "../simpleSchema.js";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 /**
  * Options for generating a {@link TreeStoredSchema} from view schema.
  */
-export interface StoredSchemaGenerationOptions {
+export interface StoredFromViewSchemaGenerationOptions {
 	/**
 	 * Determines whether to include staged schema in the resulting stored schema.
 	 * @remarks
@@ -24,6 +21,16 @@ export interface StoredSchemaGenerationOptions {
 	includeStaged(upgrade: SchemaUpgrade): boolean;
 }
 
+/**
+ * Marker type indicating that the input schema is already a stored schema.
+ */
+export const ExpectStored = Symbol("ExpectStored");
+export type ExpectStored = typeof ExpectStored;
+
+export type StoredSchemaGenerationOptions =
+	| StoredFromViewSchemaGenerationOptions
+	| ExpectStored;
+
 /**
  * Filters an allowed type based on the provided options.
  * @param allowedType - The allowed type to filter.
@@ -31,30 +38,47 @@ export interface StoredSchemaGenerationOptions {
  * @returns Whether the allowed type passes the filter.
  */
 export function allowedTypeFilter(
-	allowedType: AnnotatedAllowedType,
+	data: SimpleAllowedTypeAttributes,
 	options: StoredSchemaGenerationOptions,
 ): boolean {
+	if (options === ExpectStored) {
+		if (data.isStaged !== undefined) {
+			throw new UsageError(
+				"Failed to covert view schema to stored schema. The simple schema provided was indicated to be a stored schema by the use of `ExpectStored`, but view schema specific content was encountered which requires a `StoredFromViewSchemaGenerationOptions` to process.",
+			);
+		}
+		return true;
+	}
+
+	if (data.isStaged === undefined) {
+		throw new UsageError(
+			"Failed to covert view schema to stored schema. The simple schema provided as the view schema was actually a stored schema. If this was intended, use `ExpectStored` for the `StoredSchemaGenerationOptions` to indicate the input is already a stored schema and only a format conversion is required.",
+		);
+	}
+
 	// If the allowed type is staged, only include it if the options allow it.
-	if (allowedType.metadata.stagedSchemaUpgrade !== undefined) {
-		return options.includeStaged(allowedType.metadata.stagedSchemaUpgrade);
+	if (data.isStaged === false) {
+		return true;
 	}
-	return true;
+
+	return options.includeStaged(data.isStaged);
 }
 
 /**
- * Converts an ImplicitAllowedTypes to a stored schema.
+ * Converts a {@link SimpleAllowedTypes} to a stored schema.
  * @param schema - The schema to convert.
  * @param options - The options to use for filtering.
  * @returns The converted stored schema.
  */
 export function convertAllowedTypes(
-	schema: ImplicitAllowedTypes,
+	schema: SimpleAllowedTypes,
 	options: StoredSchemaGenerationOptions,
 ): TreeTypeSet {
-	const filtered: TreeNodeSchemaIdentifier[] = normalizeAndEvaluateAnnotatedAllowedTypes(
-		schema,
-	)
-		.types.filter((allowedType) => allowedTypeFilter(allowedType, options))
-		.map((a) => brand(a.type.identifier));
+	const filtered: TreeNodeSchemaIdentifier[] = [];
+	for (const [type, data] of schema) {
+		if (allowedTypeFilter(data, options)) {
+			filtered.push(brand<TreeNodeSchemaIdentifier>(type));
+		}
+	}
 	return new Set(filtered);
 }

package/src/simple-tree/core/treeNode.ts

@@ -8,7 +8,7 @@ import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
 import { NodeKind, type TreeNodeSchemaClass } from "./treeNodeSchema.js";
-// eslint-disable-next-line import/no-deprecated
+// eslint-disable-next-line import-x/no-deprecated
 import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
 import { markEager } from "./flexList.js";
 
@@ -80,7 +80,7 @@ export abstract class TreeNode implements WithType {
 	 * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
 	 * @deprecated Use {@link typeSchemaSymbol} instead.
 	 */
-	// eslint-disable-next-line import/no-deprecated
+	// eslint-disable-next-line import-x/no-deprecated
 	public abstract get [typeNameSymbol](): string;
 
 	/**

package/src/simple-tree/core/treeNodeSchema.ts

@@ -12,10 +12,9 @@ import type { InternalTreeNode, Unhydrated } from "./types.js";
 import type { UnionToIntersection } from "../../util/index.js";
 import type { AllowedTypesFullEvaluated, AllowedTypesFull } from "./allowedTypes.js";
 import type { Context } from "./context.js";
-import type { FieldKey, NodeData, TreeNodeStoredSchema } from "../../core/index.js";
+import type { FieldKey, NodeData } from "../../core/index.js";
 import type { UnhydratedFlexTreeField } from "./unhydratedFlexTree.js";
 import type { FactoryContent } from "../unhydratedFlexTreeFromInsertable.js";
-import type { StoredSchemaGenerationOptions } from "./toStored.js";
 
 /**
  * Schema for a {@link TreeNode} or {@link TreeLeafValue}.
@@ -389,11 +388,6 @@ export interface TreeNodeSchemaPrivateData {
 	 * Idempotent initialization function that pre-caches data and can dereference lazy schema references.
 	 */
 	idempotentInitialize(): TreeNodeSchemaInitializedData;
-
-	/**
-	 * Converts a the schema into a {@link TreeNodeStoredSchema}.
-	 */
-	toStored(options: StoredSchemaGenerationOptions): TreeNodeStoredSchema;
 }
 
 /**

package/src/simple-tree/core/treeNodeValid.ts

@@ -260,7 +260,6 @@ export function isClassBasedSchema(
 export function createTreeNodeSchemaPrivateData(
 	schema: TreeNodeSchemaCore<string, NodeKind, boolean>,
 	childAllowedTypes: readonly AllowedTypesFull[],
-	toStored: TreeNodeSchemaPrivateData["toStored"],
 ): TreeNodeSchemaPrivateData {
 	const schemaValid = schemaAsTreeNodeValid(schema);
 	// Since this closes over the schema, ensure this schema is marked as most derived
@@ -270,7 +269,6 @@ export function createTreeNodeSchemaPrivateData(
 	return {
 		idempotentInitialize: () => schemaValid.oneTimeInitialize().oneTimeInitialized,
 		childAllowedTypes,
-		toStored,
 	};
 }
 

package/src/simple-tree/fieldSchema.ts

@@ -29,7 +29,7 @@ import type {
 	InsertableTreeNodeFromImplicitAllowedTypes,
 	AllowedTypesFull,
 } from "./core/index.js";
-import { normalizeAllowedTypes } from "./core/index.js";
+import { AnnotatedAllowedTypesInternal, normalizeAllowedTypes } from "./core/index.js";
 
 import type { SimpleAllowedTypeAttributes, SimpleFieldSchema } from "./simpleSchema.js";
 import type { UnsafeUnknownSchema } from "./unsafeUnknownSchema.js";
@@ -413,16 +413,7 @@ export class FieldSchemaAlpha<
 	}
 
 	public get simpleAllowedTypes(): ReadonlyMap<string, SimpleAllowedTypeAttributes> {
-		const types = this.allowedTypesFull.evaluate().types;
-		const info = new Map<string, SimpleAllowedTypeAttributes>();
-
-		for (const type of types) {
-			info.set(type.type.identifier, {
-				isStaged: type.metadata.stagedSchemaUpgrade !== undefined,
-			});
-		}
-
-		return info;
+		return AnnotatedAllowedTypesInternal.evaluateSimpleAllowedTypes(this.allowedTypesFull);
 	}
 
 	protected constructor(

package/src/simple-tree/index.ts

@@ -44,7 +44,7 @@ export {
 	type UnannotateAllowedTypesList,
 	type AllowedTypeMetadata,
 	type AnnotatedAllowedTypes,
-	type SchemaUpgrade,
+	SchemaUpgrade,
 	type LazyItem,
 	type FlexList,
 	type FlexListToUnion,
@@ -59,6 +59,8 @@ export {
 	type AllowedTypesFullFromMixed,
 	AnnotatedAllowedTypesInternal,
 	type NumberKeys,
+	ExpectStored,
+	createSchemaUpgrade,
 } from "./core/index.js";
 export { walkFieldSchema } from "./walkFieldSchema.js";
 export type { UnsafeUnknownSchema, Insertable } from "./unsafeUnknownSchema.js";
@@ -74,6 +76,7 @@ export {
 	type ITreeConfigurationOptions,
 	SchemaFactory,
 	SchemaFactoryBeta,
+	type SchemaStaticsBeta,
 	SchemaFactoryAlpha,
 	type ObjectSchemaOptionsAlpha,
 	type ObjectSchemaOptions,
@@ -180,7 +183,6 @@ export {
 	type TreeChangeEvents,
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
-	type SchemaStaticsAlpha,
 	KeyEncodingOptions,
 	type TreeParsingOptions,
 	incrementalSummaryHint,
@@ -280,3 +282,10 @@ export {
 	nullSchema,
 } from "./leafNodeSchema.js";
 export type { LeafSchema } from "./leafNodeSchema.js";
+export {
+	encodeSimpleSchema,
+	decodeSimpleSchema,
+	exportCompatibilitySchemaSnapshot,
+	importCompatibilitySchemaSnapshot,
+	checkCompatibility,
+} from "./api/index.js";

package/src/simple-tree/leafNodeSchema.ts

@@ -7,7 +7,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 
-import { LeafNodeStoredSchema, type TreeValue, ValueSchema } from "../core/index.js";
+import { type TreeValue, ValueSchema } from "../core/index.js";
 import {
 	type FlexTreeNode,
 	isFlexTreeNode,
@@ -64,7 +64,6 @@ export class LeafNodeSchema<Name extends string, const T extends ValueSchema>
 				): FlexContent => leafToFlexContent(data, this, allowedTypes),
 			})),
 		childAllowedTypes: [],
-		toStored: () => new LeafNodeStoredSchema(this.leafKind),
 	};
 	#initializedData: TreeNodeSchemaInitializedData | undefined;