@fluidframework/tree 2.116.1 → 2.118.0

package/src/shared-tree/schematizingTreeView.ts

@@ -10,9 +10,9 @@ 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 } from "../core/index.js";
+import { anchorSlot, rootFieldKey, type RevertToOptionsAlpha } from "../core/index.js";
 import {
 	type NodeIdentifierManager,
 	defaultSchemaPolicy,
@@ -27,7 +27,7 @@ import {
 } from "../feature-libraries/index.js";
 import {
 	type ImplicitFieldSchema,
-	type SchemaCompatibilityStatus,
+	type SchemaCompatibilityStatusBeta,
 	type TreeView,
 	type TreeViewEvents,
 	tryGetTreeNodeForField,
@@ -58,8 +58,11 @@ import {
 	TreeViewConfigurationAlpha,
 	toInitialSchema,
 	toUpgradeSchema,
-	type TreeBranchAlpha,
+	type TreeBranchHistory,
+	type UntypedTreeViewAlpha,
 	type TreeSchema,
+	type SchemaUpgrade,
+	type StagedUpgradeStatus,
 } from "../simple-tree/index.js";
 import {
 	type Breakable,
@@ -78,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.
  */
@@ -94,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();
@@ -154,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;
@@ -169,7 +196,9 @@ export class SchematizingSimpleTreeView<
 			canUpgrade: true,
 			isEquivalent: false,
 			canInitialize: true,
+			discrepancies: undefined,
 		};
+		this.currentEnabledUpgrades = new Map();
 		this.update();
 
 		this.unregisterCallbacks.add(
@@ -180,7 +209,11 @@ export class SchematizingSimpleTreeView<
 		);
 	}
 
-	public isBranch(): this is TreeBranchAlpha {
+	public isBranch(): this is UntypedTreeViewAlpha {
+		return this.isView();
+	}
+
+	public isView(): this is UntypedTreeViewAlpha {
 		return true;
 	}
 
@@ -265,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(
@@ -280,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.
 	 */
@@ -437,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),
@@ -481,7 +547,7 @@ export class SchematizingSimpleTreeView<
 		anchors.slots.delete(SimpleContextSlot);
 	}
 
-	public get compatibility(): SchemaCompatibilityStatus {
+	public get compatibility(): SchemaCompatibilityStatusBeta {
 		if (!this.currentCompatibility) {
 			this.failDisposed();
 		}
@@ -496,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.
@@ -505,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) ||
@@ -526,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,
@@ -542,28 +601,40 @@ export class SchematizingSimpleTreeView<
 
 	// #region Branching
 
-	public fork(): ReturnType<TreeBranchAlpha["fork"]> &
+	public fork(): ReturnType<UntypedTreeViewAlpha["fork"]> &
 		SchematizingSimpleTreeView<TRootSchema> {
 		return this.checkout.fork().viewWith(this.config);
 	}
 
-	public merge(context: TreeBranchAlpha, disposeMerged = true): void {
+	public rewindTo(revision: string): void {
+		this.checkout.rewindTo(revision);
+	}
+
+	public revertTo(revision: string, options?: RevertToOptionsAlpha): void {
+		this.checkout.revertTo(revision, options);
+	}
+
+	public merge(context: UntypedTreeViewAlpha, disposeMerged = true): void {
 		this.checkout.merge(context, disposeMerged);
 	}
 
-	public rebaseOnto(context: TreeBranchAlpha): void {
+	public rebaseOnto(context: UntypedTreeViewAlpha): void {
 		this.checkout.rebaseOnto(context);
 	}
 
-	public isMissingEditsFrom(context: TreeBranchAlpha): boolean {
+	public isMissingEditsFrom(context: UntypedTreeViewAlpha): boolean {
 		return this.checkout.isMissingEditsFrom(context);
 	}
 
 	public computeNetChangeIfRebasedOnto(
-		context: TreeBranchAlpha,
+		context: UntypedTreeViewAlpha,
 	): JsonCompatibleReadOnly | undefined {
 		return this.checkout.computeNetChangeIfRebasedOnto(context);
 	}
 
 	// #endregion Branching
+
+	public get branchHistory(): TreeBranchHistory {
+		return this.checkout.branchHistory;
+	}
 }

package/src/shared-tree/sharedTree.ts

@@ -524,6 +524,7 @@ export const changeFormatVersionForEditManager = DependentFormatVersion.fromPair
 	[EditManagerFormatVersion.v4, SharedTreeChangeFormatVersion.v4],
 	[EditManagerFormatVersion.vSharedBranches, SharedTreeChangeFormatVersion.v4],
 	[EditManagerFormatVersion.v6, SharedTreeChangeFormatVersion.v5],
+	[EditManagerFormatVersion.v7, SharedTreeChangeFormatVersion.v5],
 ]);
 
 /**
@@ -540,6 +541,7 @@ export const changeFormatVersionForMessage = DependentFormatVersion.fromPairs<
 	[MessageFormatVersion.v4, SharedTreeChangeFormatVersion.v4],
 	[MessageFormatVersion.vSharedBranches, SharedTreeChangeFormatVersion.v4],
 	[MessageFormatVersion.v6, SharedTreeChangeFormatVersion.v5],
+	[MessageFormatVersion.v7, SharedTreeChangeFormatVersion.v5],
 ]);
 
 function getCodecTreeForEditManagerFormat(
@@ -659,8 +661,9 @@ export interface SharedTreeOptions
 	 * @remarks
 	 * By default, SharedTree evicts trunk commits once all peers have acknowledged them (i.e. once they
 	 * are outside the collaboration window), and they are not otherwise retained (e.g. by revertibles or
-	 * local branches), to bound memory usage. Enabling this flag retains the full trunk history for the
-	 * lifetime of the client, which increases memory usage over time and should be used with care.
+	 * local branches), to bound memory usage and document size.
+	 * As long as this flag is enabled, trunk commits are retained - this increases memory usage and document size
+	 * over time and should be used with care.
 	 */
 	readonly retainHistory?: boolean;
 

package/src/shared-tree/tree.ts

@@ -58,7 +58,7 @@ export const Tree: Tree = {
 	...treeNodeApi,
 
 	// Note: the implementation details of `createRunTransaction` are deprecated.
-	// We have introduced replacement `@alpha` APIs on `TreeBranch`, but until they are `@public`, we can't reasonably deprecated this.
+	// We have introduced replacement `@alpha` APIs on `UntypedTreeView`, but until they are `@public`, we can't reasonably deprecated this.
 	// Once they have been promoted to public, we can deprecate this API.
 	runTransaction: createRunTransaction(),
 

package/src/shared-tree/treeAlpha.ts

@@ -58,7 +58,7 @@ import {
 	type TreeEncodingOptions,
 	type VerboseTree,
 	extractPersistedSchema,
-	type TreeBranch,
+	type UntypedTreeView,
 	TreeViewConfigurationAlpha,
 	getStoredKey,
 	getPropertyKeyFromStoredKey,
@@ -84,7 +84,6 @@ import {
 	type TreeContextAlpha,
 	type TreeNodeSchema,
 	getUnhydratedContext,
-	type TreeBranchAlpha,
 } from "../simple-tree/index.js";
 import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 
@@ -96,22 +95,22 @@ const identifier: TreeIdentifierUtils = (node: TreeNode): string | undefined =>
 	return getIdentifierFromNode(node, "uncompressed");
 };
 
-identifier.shorten = (branch: TreeBranch, nodeIdentifier: string): number | undefined => {
+identifier.shorten = (view: UntypedTreeView, nodeIdentifier: string): number | undefined => {
 	assert(
-		branch instanceof SchematizingSimpleTreeView,
+		view instanceof SchematizingSimpleTreeView,
 		0xcac /* Unexpected branch implementation */,
 	);
-	const { nodeKeyManager } = branch;
+	const { nodeKeyManager } = view;
 	const localNodeKey = nodeKeyManager.tryLocalizeNodeIdentifier(nodeIdentifier);
 	return localNodeKey === undefined ? undefined : extractFromOpaque(localNodeKey);
 };
 
-identifier.lengthen = (branch: TreeBranch, nodeIdentifier: number): string => {
+identifier.lengthen = (view: UntypedTreeView, nodeIdentifier: number): string => {
 	assert(
-		branch instanceof SchematizingSimpleTreeView,
+		view instanceof SchematizingSimpleTreeView,
 		0xcad /* Unexpected branch implementation */,
 	);
-	const { nodeKeyManager } = branch;
+	const { nodeKeyManager } = view;
 	const local = brand<LocalNodeIdentifier>(nodeIdentifier as SessionSpaceCompressedId);
 	return nodeKeyManager.stabilizeNodeIdentifier(local);
 };
@@ -121,8 +120,8 @@ identifier.getShort = (node: TreeNode): number | undefined => {
 	return typeof shortIdentifier === "number" ? shortIdentifier : undefined;
 };
 
-identifier.create = (branch: TreeBranch): string => {
-	const nodeKeyManager = (branch as SchematizingSimpleTreeView<ImplicitFieldSchema>)
+identifier.create = (view: UntypedTreeView): string => {
+	const nodeKeyManager = (view as SchematizingSimpleTreeView<ImplicitFieldSchema>)
 		.nodeKeyManager;
 	return nodeKeyManager.stabilizeNodeIdentifier(nodeKeyManager.generateLocalNodeIdentifier());
 };
@@ -154,7 +153,7 @@ export interface TreeIdentifierUtils {
 	(node: TreeNode): string | undefined;
 
 	/**
-	 * Returns the shortened identifier as a number given a UUID known by the id compressor on the branch.
+	 * Returns the shortened identifier as a number given a UUID known by the id compressor on the view.
 	 * @remarks
 	 * If the given string is not a valid identifier and/or was not generated by the SharedTree, this will return `undefined`.
 	 *
@@ -163,10 +162,10 @@ export interface TreeIdentifierUtils {
 	 * This method is the inverse of {@link TreeIdentifierUtils.lengthen}.
 	 * If you shorten an identifier and then immediately pass it to {@link TreeIdentifierUtils.lengthen}, you will get the original string back.
 	 *
-	 * @param branch - The branch (and/or view) of the SharedTree that will perform the compression.
+	 * @param view - The view of the SharedTree that will perform the compression.
 	 * @param nodeIdentifier - the stable identifier to be shortened.
 	 */
-	shorten(branch: TreeBranch, nodeIdentifier: string): number | undefined;
+	shorten(view: UntypedTreeView, nodeIdentifier: string): number | undefined;
 
 	/**
 	 * Returns the stable id as a string if the identifier is decompressible and known by the id compressor.
@@ -176,10 +175,10 @@ export interface TreeIdentifierUtils {
 	 * This method is the inverse of {@link TreeIdentifierUtils.shorten}.
 	 * If you lengthen an identifier and then immediately pass it to {@link TreeIdentifierUtils.shorten}, you will get the original short identifier back.
 	 *
-	 * @param branch - The branch (and/or view) of the SharedTree that will perform the decompression.
+	 * @param view - The view of the SharedTree that will perform the decompression.
 	 * @param nodeIdentifier - The local identifier to be lengthened.
 	 */
-	lengthen(branch: TreeBranch, nodeIdentifier: number): string;
+	lengthen(view: UntypedTreeView, nodeIdentifier: number): string;
 
 	/**
 	 * Returns the {@link TreeIdentifierUtils.shorten | shortened} form of the identifier {@link SchemaFactory.identifier | identifier} for the given node.
@@ -206,9 +205,9 @@ export interface TreeIdentifierUtils {
 	 * @remarks
 	 * The returned UUID string can be {@link TreeIdentifierUtils.shorten | shortened} for high-performance scenarios.
 	 *
-	 * @param branch - The branch (and/or view) of the SharedTree that will generate and manage the identifier.
+	 * @param view - The view of the SharedTree that will generate and manage the identifier.
 	 */
-	create(branch: TreeBranch): string;
+	create(view: UntypedTreeView): string;
 }
 
 /**
@@ -253,19 +252,6 @@ export interface TreeAlpha {
 		listener: NoInfer<TreeChangeEventsAlpha<TNode>[K]>,
 	): () => void;
 
-	/**
-	 * Retrieve the {@link TreeBranch | branch}, if any, for the given node.
-	 * @param node - The node to query
-	 * @remarks If the node has already been inserted into the tree, this will return the branch associated with that node's {@link TreeView | view}.
-	 * Otherwise, it will return `undefined` (because the node has not yet been inserted and is therefore not part of a branch or view).
-	 *
-	 * This does not fork a new branch, but rather retrieves the _existing_ branch for the node.
-	 * To create a new branch, use e.g. {@link TreeBranch.fork | `myBranch.fork()`}.
-	 *
-	 * @deprecated To obtain a {@link TreeBranchAlpha | branch }, use `TreeAlpha.context(node)` to obtain a {@link TreeContextAlpha | context} and then check {@link TreeContextAlpha.isBranch | isBranch()}.
-	 */
-	branch(node: TreeNode): TreeBranchAlpha | undefined;
-
 	/**
 	 * Retrieve the {@link TreeContextAlpha | context} for the given node.
 	 * @param node - The node to query
@@ -842,13 +828,9 @@ export const TreeAlpha: TreeAlpha = {
 	},
 
 	context(node: TreeNode): TreeContextAlpha {
-		return this.branch(node) ?? UnhydratedTreeContext.instance;
-	},
-
-	branch(node: TreeNode): TreeBranchAlpha | undefined {
 		const kernel = getKernel(node);
 		if (!kernel.isHydrated()) {
-			return undefined;
+			return UnhydratedTreeContext.instance;
 		}
 		const view = kernel.anchorNode.anchorSet.slots.get(ViewSlot);
 		assert(