@fluidframework/tree 2.117.0 → 2.118.0

package/src/shared-tree/schematizingTreeView.ts

@@ -10,7 +10,7 @@ import type {
 	Listenable,
 } from "@fluidframework/core-interfaces/internal";
 import { assert } from "@fluidframework/core-utils/internal";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { tagSchemaArtifacts, UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import { anchorSlot, rootFieldKey, type RevertToOptionsAlpha } from "../core/index.js";
 import {
@@ -27,7 +27,7 @@ import {
 } from "../feature-libraries/index.js";
 import {
 	type ImplicitFieldSchema,
-	type SchemaCompatibilityStatus,
+	type SchemaCompatibilityStatusBeta,
 	type TreeView,
 	type TreeViewEvents,
 	tryGetTreeNodeForField,
@@ -61,6 +61,8 @@ import {
 	type TreeBranchHistory,
 	type UntypedTreeViewAlpha,
 	type TreeSchema,
+	type SchemaUpgrade,
+	type StagedUpgradeStatus,
 } from "../simple-tree/index.js";
 import {
 	type Breakable,
@@ -79,6 +81,27 @@ import type { TreeCheckout } from "./treeCheckout.js";
  */
 export const ViewSlot = anchorSlot<TreeView<ImplicitFieldSchema>>();
 
+function throwIfSchemaIsIncompatible(compatibility: SchemaCompatibilityStatusBeta): void {
+	if (compatibility.canView) {
+		return;
+	}
+
+	const resolution = compatibility.canInitialize
+		? "The document is uninitialized; call TreeView.initialize() before reading or writing TreeView.root."
+		: compatibility.canUpgrade
+			? "The stored schema can be upgraded; call TreeView.upgradeSchema() before reading or writing TreeView.root."
+			: "The schemas cannot be upgraded automatically. Use a compatible view schema or explicitly migrate the document schema and data.";
+	throw new UsageError(
+		`TreeView.root is unavailable because the view schema is incompatible with the stored schema. ${resolution}`,
+		tagSchemaArtifacts({
+			schemaIncompatibilityDetails:
+				compatibility.discrepancies === undefined
+					? undefined
+					: JSON.stringify(compatibility.discrepancies),
+		}),
+	);
+}
+
 /**
  * Implementation of TreeView wrapping a FlexTreeView.
  */
@@ -95,9 +118,14 @@ export class SchematizingSimpleTreeView<
 	private flexTreeContext: Context | undefined;
 
 	/**
-	 * Undefined iff uninitialized or disposed.
+	 * Undefined if and only if uninitialized or disposed.
 	 */
-	private currentCompatibility: SchemaCompatibilityStatus | undefined;
+	private currentCompatibility: SchemaCompatibilityStatusBeta | undefined;
+	/**
+	 * Cached map of upgrade statuses, computed alongside compatibility.
+	 * @remarks Undefined if and only if uninitialized or disposed.
+	 */
+	private currentEnabledUpgrades: ReadonlyMap<SchemaUpgrade, StagedUpgradeStatus> | undefined;
 	public readonly events: Listenable<TreeViewEvents & TreeBranchEvents> &
 		IEmitter<TreeViewEvents & TreeBranchEvents> &
 		HasListeners<TreeViewEvents & TreeBranchEvents> = createEmitter();
@@ -155,9 +183,7 @@ export class SchematizingSimpleTreeView<
 		const stagedUpgradePolicy =
 			config instanceof TreeViewConfigurationAlpha ? config.stagedUpgradePolicy : undefined;
 		const configAlpha = new TreeViewConfigurationAlpha({
-			schema: config.schema,
-			enableSchemaValidation: config.enableSchemaValidation,
-			preventAmbiguity: config.preventAmbiguity,
+			...config,
 			stagedUpgradePolicy,
 		});
 		this.stagedUpgradePolicy = configAlpha.stagedUpgradePolicy;
@@ -170,7 +196,9 @@ export class SchematizingSimpleTreeView<
 			canUpgrade: true,
 			isEquivalent: false,
 			canInitialize: true,
+			discrepancies: undefined,
 		};
+		this.currentEnabledUpgrades = new Map();
 		this.update();
 
 		this.unregisterCallbacks.add(
@@ -270,7 +298,7 @@ export class SchematizingSimpleTreeView<
 	public upgradeSchema(): void {
 		this.ensureUndisposed();
 
-		const newSchema = toUpgradeSchema(this.viewSchema.root, this.stagedUpgradePolicy);
+		const newSchema = toUpgradeSchema(this.viewSchema.root, this.effectiveUpgradePolicy);
 		const storedSchema = this.checkout.storedSchema.clone();
 		if (!allowsRepoSuperset(defaultSchemaPolicy, storedSchema, newSchema)) {
 			throw new UsageError(
@@ -285,6 +313,35 @@ export class SchematizingSimpleTreeView<
 		this.runSchemaEdit(() => this.checkout.updateSchema(newSchema));
 	}
 
+	public isStagedUpgradeEnabled(upgrade: SchemaUpgrade): StagedUpgradeStatus {
+		if (!this.currentEnabledUpgrades) {
+			this.failDisposed();
+		}
+		return this.currentEnabledUpgrades.get(upgrade) ?? "disabled";
+	}
+
+	private get effectiveUpgradePolicy(): StagedSchemaUpgradePolicy {
+		const configuredPolicy = this.stagedUpgradePolicy;
+		if (configuredPolicy.includeAlreadyEnabledUpgrades === false) {
+			return configuredPolicy;
+		}
+		const enabledUpgrades = this.currentEnabledUpgrades;
+		assert(
+			enabledUpgrades !== undefined,
+			0xd3e /* Enabled upgrades must be available for an active view */,
+		);
+		if (enabledUpgrades.size === 0) {
+			return configuredPolicy;
+		}
+
+		return {
+			includeStaged: (upgrade) =>
+				configuredPolicy.includeStaged(upgrade) || enabledUpgrades.has(upgrade),
+			includeStagedOptional: (upgrade) =>
+				configuredPolicy.includeStagedOptional(upgrade) || enabledUpgrades.has(upgrade),
+		};
+	}
+
 	/**
 	 * Gets the flex-tree context. Throws when disposed or out of schema.
 	 */
@@ -442,12 +499,16 @@ export class SchematizingSimpleTreeView<
 		}
 	}
 
-	private computeCompatibility(): SchemaCompatibilityStatus {
-		const compatibility = checkSchemaCompatibility(
+	/**
+	 * Computes the current schema compatibility status and updates the cached enabled upgrades.
+	 */
+	private computeCompatibility(): SchemaCompatibilityStatusBeta {
+		const { enabledUpgrades, ...compatibility } = checkSchemaCompatibility(
 			this.viewSchema,
 			this.checkout.storedSchema,
 			this.stagedUpgradePolicy,
 		);
+		this.currentEnabledUpgrades = enabledUpgrades;
 		return {
 			...compatibility,
 			canInitialize: canInitialize(this.checkout),
@@ -486,7 +547,7 @@ export class SchematizingSimpleTreeView<
 		anchors.slots.delete(SimpleContextSlot);
 	}
 
-	public get compatibility(): SchemaCompatibilityStatus {
+	public get compatibility(): SchemaCompatibilityStatusBeta {
 		if (!this.currentCompatibility) {
 			this.failDisposed();
 		}
@@ -501,6 +562,7 @@ export class SchematizingSimpleTreeView<
 		}
 		this.checkout.forest.anchors.slots.delete(ViewSlot);
 		this.currentCompatibility = undefined;
+		this.currentEnabledUpgrades = undefined;
 		this.onDispose?.();
 		if (!this.checkout.isSharedBranch && !this.checkout.disposed) {
 			// All non-shared branches are 1:1 with views, so if a user manually disposes a view, we should also dispose the checkout/branch.
@@ -510,11 +572,7 @@ export class SchematizingSimpleTreeView<
 
 	private get flexRoot(): FlexTreeOptionalField | FlexTreeRequiredField {
 		this.breaker.use();
-		if (!this.compatibility.canView) {
-			throw new UsageError(
-				"Document is out of schema. Check TreeView.compatibility before accessing TreeView.root.",
-			);
-		}
+		throwIfSchemaIsIncompatible(this.compatibility);
 		const view = this.getFlexTreeContext();
 		assert(
 			view.root.is(FieldKinds.optional) ||
@@ -531,11 +589,7 @@ export class SchematizingSimpleTreeView<
 
 	public set root(newRoot: InsertableField<TRootSchema>) {
 		this.breaker.use();
-		if (!this.compatibility.canView) {
-			throw new UsageError(
-				"Document is out of schema. Check TreeView.compatibility before accessing TreeView.root.",
-			);
-		}
+		throwIfSchemaIsIncompatible(this.compatibility);
 		const view = this.getFlexTreeContext();
 		setField(
 			view.root,

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

@@ -158,22 +158,22 @@ export interface ITreeViewConfiguration<
 
 /**
  * Property-bag configuration for {@link TreeViewConfigurationAlpha} construction.
+ * @input
  * @alpha
  */
 export interface ITreeViewConfigurationAlpha<
 	TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
 > extends ITreeViewConfiguration<TSchema> {
 	/**
-	 * Policy for generating stored schema from the view schema.
+	 * Policy for generating stored schema from the view schema during staged schema upgrades.
 	 *
 	 * @remarks
-	 * If omitted or `undefined`, defaults to {@link StagedSchemaUpgradePolicyFactory.restrictive}
-	 * which does not enable any staged schema upgrades.
-	 *
 	 * If provided, this policy is used when generating stored schema to include in documents via
 	 * `initialize` / `upgradeSchema` as well as in {@link snapshotSchemaCompatibility} to validate
 	 * the compatibility of such documents.
 	 *
+	 * @defaultValue {@link StagedSchemaUpgradePolicyFactory.restrictive}
+	 *
 	 * @example Enabling specific staged upgrades
 	 * ```typescript
 	 * const config = new TreeViewConfigurationAlpha({

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

@@ -27,6 +27,7 @@ import {
 	NodeKind,
 	normalizeAndEvaluateAnnotatedAllowedTypes,
 	type AnnotatedAllowedType,
+	type SchemaUpgrade,
 	type TreeNodeSchema,
 } from "../core/index.js";
 import {
@@ -48,6 +49,25 @@ import type { TreeSchema } from "../treeSchema.js";
 
 import { tryStoredSchemaAsArray } from "./customTree.js";
 
+/**
+ * Collects upgrade location data during a schema walk.
+ * @remarks Called for each staged type or staged optional field encountered.
+ */
+export interface UpgradeLocationCollector {
+	/**
+	 * Record a staged allowed type location.
+	 * @param upgrade - The upgrade token guarding this type.
+	 * @param isEnabled - Whether this type is present in stored schema.
+	 */
+	allowedType(upgrade: SchemaUpgrade, isEnabled: boolean): void;
+	/**
+	 * Record a staged optional field location.
+	 * @param upgrade - The upgrade token guarding this field.
+	 * @param isEnabled - Whether the stored field is already optional.
+	 */
+	optionalField(upgrade: SchemaUpgrade, isEnabled: boolean): void;
+}
+
 /**
  * Discriminated union (keyed on `mismatch`) of discrepancies between a view and stored schema which
  * make it possible for content matching the stored schema to be incompatible with the view schema.
@@ -79,6 +99,11 @@ export interface FieldDiscrepancyLocation {
 	 * - the discrepancy is for 'all fields' of a map node
 	 */
 	readonly fieldKey: FieldKey | undefined;
+	/**
+	 * Whether the view field is a staged optional field.
+	 * Omitted when false.
+	 */
+	readonly viewIsStagedOptional?: true;
 }
 
 /**
@@ -94,6 +119,13 @@ export interface AllowedTypeDiscrepancy extends FieldDiscrepancyLocation {
 	 * (excluding {@link SchemaStaticsBeta.staged | staged} schema) which are not allowed in stored schema.
 	 */
 	readonly view: readonly AnnotatedAllowedType<TreeNodeSchema>[];
+	/**
+	 * Staged allowed types in the view schema which are not allowed in stored schema.
+	 *
+	 * @remarks
+	 * These types do not cause the discrepancy and are omitted when there are none.
+	 */
+	readonly stagedView?: readonly AnnotatedAllowedType<TreeNodeSchema>[];
 	/**
 	 * Allowed type identifiers in stored schema which are not allowed in view schema
 	 * (including the view schema's {@link SchemaStaticsBeta.staged | staged} schema).
@@ -174,15 +206,25 @@ function doesNodeKindMatchStoredNodeKind(
 
 /**
  * Finds and reports discrepancies between a view schema and a stored schema which make "canView" false.
+ *
+ * Optionally collects upgrade location information for staged schema upgrades during the same walk.
+ *
  * @remarks
  * See documentation on {@link Discrepancy} and its subtypes for details of possible discrepancies.
  */
 export function* getDiscrepanciesInAllowedContent(
 	view: TreeSchema,
 	stored: TreeStoredSchema,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<Discrepancy> {
 	// check root field discrepancies
-	yield* getFieldDiscrepancies(view.root, stored.rootFieldSchema, undefined, undefined);
+	yield* getFieldDiscrepancies(
+		view.root,
+		stored.rootFieldSchema,
+		undefined,
+		undefined,
+		upgradeCollector,
+	);
 
 	// Check all of the stored nodes, including their fields for discrepancies.
 	for (const [identifier, storedSchema] of stored.nodeSchema) {
@@ -190,7 +232,7 @@ export function* getDiscrepanciesInAllowedContent(
 
 		// if the view schema has a node that's also in the stored schema, check it.
 		if (viewSchema !== undefined) {
-			yield* getNodeDiscrepancies(identifier, viewSchema, storedSchema);
+			yield* getNodeDiscrepancies(identifier, viewSchema, storedSchema, upgradeCollector);
 		}
 		// Note that nodes that are missing in the view schema are only a problem if other stored schema nodes actually reference them which will produce its own discrepancy, so we can rely on that to produce any needed discrepancies.
 	}
@@ -200,6 +242,7 @@ function* getNodeDiscrepancies(
 	identifier: TreeNodeSchemaIdentifier,
 	view: TreeNodeSchema,
 	stored: TreeNodeStoredSchema,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<Discrepancy> {
 	if (!doesNodeKindMatchStoredNodeKind(view.kind, getStoredNodeSchemaType(stored))) {
 		yield {
@@ -221,6 +264,7 @@ function* getNodeDiscrepancies(
 				identifier,
 				view,
 				stored as ObjectNodeStoredSchema,
+				upgradeCollector,
 			);
 			break;
 		}
@@ -246,6 +290,8 @@ function* getNodeDiscrepancies(
 				arrayStoredSchema,
 				brand(view.identifier),
 				EmptyKey,
+				false,
+				upgradeCollector,
 			);
 
 			break;
@@ -261,6 +307,7 @@ function* getNodeDiscrepancies(
 				(stored as MapNodeStoredSchema).mapFields,
 				identifier,
 				undefined,
+				upgradeCollector,
 			);
 			break;
 		}
@@ -275,6 +322,7 @@ function* getNodeDiscrepancies(
 				(stored as MapNodeStoredSchema).mapFields,
 				identifier,
 				undefined,
+				upgradeCollector,
 			);
 			break;
 		}
@@ -308,7 +356,7 @@ function* getNodeDiscrepancies(
 export function findExtraAllowedTypes(
 	viewAllowedTypes: readonly AnnotatedAllowedType<TreeNodeSchema>[],
 	storedAllowedTypes: TreeTypeSet,
-): Pick<AllowedTypeDiscrepancy, "view" | "stored"> {
+): Pick<AllowedTypeDiscrepancy, "view" | "stagedView" | "stored"> {
 	const viewNodeSchemaIdentifiers = new Set(
 		viewAllowedTypes.map((value) => value.type.identifier),
 	);
@@ -322,10 +370,19 @@ export function findExtraAllowedTypes(
 			!storedAllowedTypes.has(brand(value.type.identifier)) &&
 			value.metadata.stagedSchemaUpgrade === undefined,
 	);
+	const stagedView = viewAllowedTypes.filter(
+		(value) =>
+			!storedAllowedTypes.has(brand(value.type.identifier)) &&
+			value.metadata.stagedSchemaUpgrade !== undefined,
+	);
 	const stored = [...storedAllowedTypes].filter(
 		(value) => !viewNodeSchemaIdentifiers.has(value),
 	);
-	return { view, stored };
+	return {
+		view,
+		...(stagedView.length === 0 ? {} : { stagedView }),
+		stored,
+	};
 }
 
 /**
@@ -346,16 +403,28 @@ function* getFieldDiscrepancies(
 	stored: TreeFieldStoredSchema,
 	identifier: TreeNodeSchemaIdentifier | undefined,
 	fieldKey: FieldKey | undefined,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<FieldDiscrepancy> {
 	assert(
 		view instanceof FieldSchemaAlpha,
 		0xbee /* all field schema should be FieldSchemaAlpha */,
 	);
+
+	// Collect staged-optional upgrade location if present.
+	if (upgradeCollector !== undefined && view.isStagedOptional !== false) {
+		upgradeCollector.optionalField(
+			view.isStagedOptional,
+			stored.kind === FieldKinds.optional.identifier,
+		);
+	}
+
 	yield* getAllowedTypeDiscrepancies(
 		view.allowedTypesFull.evaluate().types,
 		stored.types,
 		identifier,
 		fieldKey,
+		view.isStagedOptional !== false,
+		upgradeCollector,
 	);
 
 	const viewKind =
@@ -375,6 +444,7 @@ function* getFieldDiscrepancies(
 			mismatch: "fieldKind",
 			view: viewKind.identifier,
 			stored: stored.kind,
+			...(view.isStagedOptional === false ? {} : { viewIsStagedOptional: true }),
 		} satisfies FieldKindDiscrepancy;
 	}
 }
@@ -396,7 +466,21 @@ function* getAllowedTypeDiscrepancies(
 	stored: TreeTypeSet,
 	identifier: TreeNodeSchemaIdentifier | undefined,
 	fieldKey: FieldKey | undefined,
+	viewIsStagedOptional: boolean,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<FieldDiscrepancy> {
+	// Collect staged allowed type upgrade locations if present.
+	if (upgradeCollector !== undefined) {
+		for (const allowedType of view) {
+			if (allowedType.metadata.stagedSchemaUpgrade !== undefined) {
+				upgradeCollector.allowedType(
+					allowedType.metadata.stagedSchemaUpgrade,
+					stored.has(brand(allowedType.type.identifier)),
+				);
+			}
+		}
+	}
+
 	const discrepancies = findExtraAllowedTypes(view, stored);
 	if (discrepancies.view.length > 0 || discrepancies.stored.length > 0) {
 		yield {
@@ -404,6 +488,7 @@ function* getAllowedTypeDiscrepancies(
 			identifier,
 			fieldKey,
 			mismatch: "allowedTypes",
+			...(viewIsStagedOptional ? { viewIsStagedOptional: true } : {}),
 		} satisfies AllowedTypeDiscrepancy;
 	}
 }
@@ -424,6 +509,7 @@ function* computeObjectNodeDiscrepancies(
 	identifier: TreeNodeSchemaIdentifier,
 	view: ObjectNodeSchemaPrivate,
 	stored: ObjectNodeStoredSchema,
+	upgradeCollector?: UpgradeLocationCollector,
 ): Iterable<FieldDiscrepancy> {
 	/**
 	 * Similar to the logic used for tracking discrepancies between two node schemas, we will identify
@@ -453,9 +539,18 @@ function* computeObjectNodeDiscrepancies(
 				mismatch: "fieldKind",
 				view: viewKind.identifier,
 				stored: storedEmptyFieldSchema.kind,
+				...(fieldSchema instanceof FieldSchemaAlpha && fieldSchema.isStagedOptional !== false
+					? { viewIsStagedOptional: true }
+					: {}),
 			} satisfies FieldKindDiscrepancy;
 		} else {
-			yield* getFieldDiscrepancies(fieldSchema, storedSchema, identifier, fieldKey);
+			yield* getFieldDiscrepancies(
+				fieldSchema,
+				storedSchema,
+				identifier,
+				fieldKey,
+				upgradeCollector,
+			);
 		}
 	}
 

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

@@ -19,6 +19,8 @@ export type {
 	ViewableTree,
 	TreeViewEvents,
 	SchemaCompatibilityStatus,
+	SchemaCompatibilityStatusBeta,
+	SchemaDiscrepancy,
 	TreeViewAlpha,
 	TreeViewBeta,
 	UntypedTreeView,
@@ -105,7 +107,11 @@ export {
 export type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
 export { getJsonSchema } from "./getJsonSchema.js";
 export { getSimpleSchema } from "./getSimpleSchema.js";
-export { checkSchemaCompatibility } from "./schemaCompatibilityTester.js";
+export {
+	checkSchemaCompatibility,
+	getSchemaIncompatibilityDetails,
+} from "./schemaCompatibilityTester.js";
+export { type StagedUpgradeStatus } from "./schemaCompatibilityTester.js";
 export type {
 	Unenforced,
 	FieldSchemaAlphaUnsafe,