@fluidframework/tree 2.117.0 → 3.0.0

package/src/index.ts

@@ -27,38 +27,6 @@ export {
 	type RevertToOptionsAlpha,
 } from "./core/index.js";
 
-import type {
-	Listeners as EventListeners,
-	IsListener as EventIsListener,
-	Listenable as EventListenable,
-	Off as EventOff,
-} from "@fluidframework/core-interfaces";
-
-/**
- * {@inheritdoc @fluidframework/core-interfaces#Listeners}
- * @public
- * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
- */
-export type Listeners<T extends object> = EventListeners<T>;
-/**
- * {@inheritdoc @fluidframework/core-interfaces#IsListener}
- * @public
- * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
- */
-export type IsListener<T> = EventIsListener<T>;
-/**
- * {@inheritdoc @fluidframework/core-interfaces#Listenable}
- * @public
- * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
- */
-export type Listenable<T extends object> = EventListenable<T>;
-/**
- * {@inheritdoc @fluidframework/core-interfaces#Off}
- * @public
- * @deprecated Deprecated in `@fluidframework/tree`. Consider importing from `fluid-framework` or `@fluidframework/core-interfaces` instead.
- */
-export type Off = EventOff;
-
 export {
 	TreeStatus,
 	TreeCompressionStrategy,
@@ -74,6 +42,7 @@ export {
 	type ForestType,
 	type SharedTreeFormatOptions,
 	Tree,
+	TreeBeta,
 	type RunTransaction,
 	type ForestOptions,
 	independentInitializedView,
@@ -81,11 +50,13 @@ export {
 	TreeAlpha,
 	type ObservationResults,
 	type TreeIdentifierUtils,
+	createIndependentTreeViewAlpha,
 	independentView,
 	type IndependentViewOptions,
 	type IndependentViewTelemetryOptions,
-	createIndependentTreeBeta,
 	createIndependentTreeAlpha,
+	createIndependentTreeBeta,
+	createIndependentTreeView,
 	type CreateIndependentTreeAlphaOptions,
 	ForestTypeOptimized,
 	ForestTypeExpensiveDebug,
@@ -137,6 +108,8 @@ export {
 	type TreeNodeFromImplicitAllowedTypes,
 	type TreeNodeSchemaClass,
 	type SchemaCompatibilityStatus,
+	type SchemaCompatibilityStatusBeta,
+	type SchemaDiscrepancy,
 	type FieldProps,
 	type FieldPropsAlpha,
 	normalizeFieldSchema,
@@ -149,7 +122,6 @@ export {
 	type ArrayNodeTreeChangedDeltaOp,
 	type ArrayNodeTreeChangedRetainOp,
 	type NodeChangedData,
-	type NodeChangedDataAlpha,
 	type NodeChangedDataDelta,
 	type NodeChangedDataProperties,
 	type NodeChangedDataTreeDelta,
@@ -198,6 +170,7 @@ export {
 	singletonSchema,
 	type UnsafeUnknownSchema,
 	type TreeViewAlpha,
+	type StagedUpgradeStatus,
 	type TreeViewBeta,
 	type InsertableField,
 	type Insertable,
@@ -221,9 +194,7 @@ export {
 	type InsertableObjectFromSchemaRecordAlpha,
 	type FieldHasDefaultAlpha,
 	// Beta APIs
-	TreeBeta,
 	type TreeChangeEventsBeta,
-	type TreeChangeEventsAlpha,
 	// Other
 	type VerboseTreeNode,
 	type TreeEncodingOptions,
@@ -278,9 +249,9 @@ export {
 	type TreeBranchAlpha,
 	type UntypedTreeViewAlpha,
 	type TreeBranchEvents,
-	asTreeViewAlpha,
 	type TreeBranchCommitMetadata,
 	type TreeBranchHistory,
+	type TreeContextBeta,
 	type NodeSchemaOptions,
 	type NodeSchemaOptionsAlpha,
 	type NodeSchemaMetadata,
@@ -400,7 +371,7 @@ export type {
 } from "./util/index.js";
 export { cloneWithReplacements } from "./util/index.js";
 
-import * as InternalTypes from "./internalTypes.js";
+import type * as InternalTypes from "./internalTypes.js";
 /**
  * Contains types used by the API, but which serve mechanical purposes and do not represent semantic concepts.
  * They are used internally to implement API aspects, but are not intended for use by external consumers.
@@ -412,7 +383,7 @@ import * as InternalTypes from "./internalTypes.js";
  * support level tag is recognized by flub entrypoint generation.
  */
 // eslint-disable-next-line unicorn/prefer-export-from -- fixing requires `export * as` (breaks API-Extractor)
-export { InternalTypes };
+export type { InternalTypes };
 
 // Internal/System types:
 // These would be put in `internalTypes` except doing so tends to cause errors like:

package/src/internalTypes.ts

@@ -15,7 +15,7 @@ export type {
 	FieldHasDefault,
 	ScopedSchemaName,
 	DefaultProvider,
-	typeNameSymbol,
+	schemaIdentifierBrand,
 	InsertableObjectFromSchemaRecord,
 } from "./simple-tree/index.js";
 export type { FlexList, FlexListToUnion, ExtractItemType } from "./simple-tree/index.js";

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.117.0";
+export const pkgVersion = "3.0.0";

package/src/shared-tree/history.ts

@@ -4,12 +4,16 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
+import type { IIdCompressor, SessionSpaceCompressedId } from "@fluidframework/id-compressor";
 
 import type { GraphCommit, CustomMetadataTree } from "../core/index.js";
 import { flattenCustomMetadata } from "../core/index.js";
 import { BranchCommitCounter, type SharedTreeBranch } from "../shared-tree-core/index.js";
-import type { TreeBranchCommitMetadata, TreeBranchHistory } from "../simple-tree/index.js";
+import type {
+	CommitRevision,
+	TreeBranchCommitMetadata,
+	TreeBranchHistory,
+} from "../simple-tree/index.js";
 import type { JsonCompatibleReadOnlyObject } from "../util/index.js";
 
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
@@ -19,10 +23,17 @@ import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
  * A lazily constructed implementation of {@link TreeBranchCommitMetadata} that wraps a {@link GraphCommit}.
  */
 class LazyTreeBranchCommitMetadata implements TreeBranchCommitMetadata {
-	public readonly revision: string;
+	/**
+	 * Holds a copy of data that may become inaccessible when the commit is trimmed.
+	 */
+	private readonly snapshot: {
+		readonly revision: SessionSpaceCompressedId;
+		readonly parent: GraphCommit<SharedTreeChange> | undefined;
+		readonly customMetadata: CustomMetadataTree | undefined;
+	};
 	private parentCache?: {
-		readonly prior: GraphCommit<SharedTreeChange>;
-		readonly cached: TreeBranchCommitMetadata;
+		readonly prior: GraphCommit<SharedTreeChange> | undefined;
+		readonly cached: TreeBranchCommitMetadata | undefined;
 	};
 
 	public constructor(
@@ -31,30 +42,41 @@ class LazyTreeBranchCommitMetadata implements TreeBranchCommitMetadata {
 	) {
 		assert(
 			commit.revision !== "root",
-			0xd34 /* Cannot construct metadata for the root commit */,
+			0xd33 /* Cannot construct metadata for the root commit */,
 		);
-		this.revision = idCompressor.decompress(commit.revision);
+		this.snapshot = {
+			revision: commit.revision,
+			parent: commit.parent,
+			customMetadata: commit.customMetadata,
+		};
+	}
+
+	public get revision(): CommitRevision {
+		return this.idCompressor.decompress(this.snapshot.revision);
 	}
 
 	public get custom(): JsonCompatibleReadOnlyObject | undefined {
-		return flattenCustomMetadata(this.commit.customMetadata);
+		return flattenCustomMetadata(this.snapshot.customMetadata);
 	}
 
 	public get customTree(): CustomMetadataTree | undefined {
-		return this.commit.customMetadata;
+		return this.snapshot.customMetadata;
 	}
 
 	public getParent(): TreeBranchCommitMetadata | undefined {
-		// The parent of the commit may change over time due to trunk trimming.
-		if (this.commit.parent !== this.parentCache?.prior) {
-			const { parent } = this.commit;
-			this.parentCache =
-				parent === undefined || parent.revision === "root"
-					? undefined
-					: {
-							prior: parent,
-							cached: new LazyTreeBranchCommitMetadata(parent, this.idCompressor),
-						};
+		if (this.commit.wasTrimmed) {
+			delete this.parentCache;
+			return undefined;
+		}
+		const parent = this.snapshot.parent;
+		if (parent !== this.parentCache?.prior) {
+			this.parentCache = {
+				prior: parent,
+				cached:
+					parent === undefined || parent.wasTrimmed
+						? undefined
+						: new LazyTreeBranchCommitMetadata(parent, this.idCompressor),
+			};
 		}
 		return this.parentCache?.cached;
 	}

package/src/shared-tree/independentView.ts

@@ -29,6 +29,7 @@ import type {
 	TreeViewConfiguration,
 	ImplicitFieldSchema,
 	TreeViewAlpha,
+	TreeViewBeta,
 	ITreeAlpha,
 	ViewableTree,
 	TreeView,
@@ -68,7 +69,7 @@ export interface IndependentViewTelemetryOptions {
 }
 
 /**
- * {@link independentView} options.
+ * {@link createIndependentTreeViewAlpha} options.
  * @alpha @input
  */
 export interface IndependentViewOptions
@@ -114,18 +115,54 @@ export type CreateIndependentTreeAlphaOptions = ForestOptions &
  * Create an uninitialized {@link TreeView} that is not tied to any {@link ITree} instance.
  *
  * @remarks
- * Such a view can never experience collaboration or be persisted to to a Fluid Container.
+ * Such a view can never experience collaboration or be persisted to a Fluid Container.
  *
  * This can be useful for testing, as well as use-cases like working on local files instead of documents stored in some Fluid service.
+ *
+ * @param config - The configuration for the tree view.
+ * @param options - Options for the independent tree view.
+ * @returns An uninitialized, non-collaborative tree view.
  * @alpha
  */
-export function independentView<const TSchema extends ImplicitFieldSchema>(
+export function createIndependentTreeViewAlpha<const TSchema extends ImplicitFieldSchema>(
 	config: TreeViewConfiguration<TSchema>,
 	options?: IndependentViewOptions,
 ): TreeViewAlpha<TSchema> {
 	return createIndependentTreeAlpha(options).viewWith(config) as TreeViewAlpha<TSchema>;
 }
 
+/**
+ * {@inheritDoc createIndependentTreeViewAlpha}
+ * @deprecated Use {@link createIndependentTreeViewAlpha} instead.
+ * @alpha
+ */
+export function independentView<const TSchema extends ImplicitFieldSchema>(
+	config: TreeViewConfiguration<TSchema>,
+	options?: IndependentViewOptions,
+): TreeViewAlpha<TSchema> {
+	return createIndependentTreeViewAlpha(config, options);
+}
+
+/**
+ * Creates an uninitialized tree view that is not tied to any {@link ITree} instance.
+ *
+ * @remarks
+ * Such a view can never experience collaboration or be persisted to a Fluid Container.
+ *
+ * This can be useful for testing and for use cases such as working on local files instead of documents stored in a Fluid service.
+ *
+ * @param config - The configuration for the tree view.
+ * @param options - Options for the independent tree's forest.
+ * @returns An uninitialized, non-collaborative tree view.
+ * @beta
+ */
+export function createIndependentTreeView<const TSchema extends ImplicitFieldSchema>(
+	config: TreeViewConfiguration<TSchema>,
+	options?: ForestOptions,
+): TreeViewBeta<TSchema> {
+	return createIndependentTreeBeta(options).viewWith(config) as TreeViewBeta<TSchema>;
+}
+
 /**
  * Create an initialized {@link TreeView} that is not tied to any {@link ITree} instance.
  *

package/src/shared-tree/index.ts

@@ -48,6 +48,8 @@ export { minimize } from "./transactionMinimize.js";
 export { Tree } from "./tree.js";
 export type { RunTransaction } from "./tree.js";
 
+export { TreeBeta } from "./treeBeta.js";
+
 export {
 	TreeAlpha,
 	type TreeIdentifierUtils,
@@ -57,11 +59,13 @@ export {
 export {
 	independentInitializedView,
 	type ViewContent,
+	createIndependentTreeViewAlpha,
 	independentView,
 	type IndependentViewOptions,
 	type IndependentViewTelemetryOptions,
-	createIndependentTreeBeta,
 	createIndependentTreeAlpha,
+	createIndependentTreeBeta,
+	createIndependentTreeView,
 	type CreateIndependentTreeAlphaOptions,
 } from "./independentView.js";
 

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,8 +27,8 @@ import {
 } from "../feature-libraries/index.js";
 import {
 	type ImplicitFieldSchema,
-	type SchemaCompatibilityStatus,
-	type TreeView,
+	type SchemaCompatibilityStatusBeta,
+	type TreeContextAlpha,
 	type TreeViewEvents,
 	tryGetTreeNodeForField,
 	setField,
@@ -61,6 +61,8 @@ import {
 	type TreeBranchHistory,
 	type UntypedTreeViewAlpha,
 	type TreeSchema,
+	type SchemaUpgrade,
+	type StagedUpgradeStatus,
 } from "../simple-tree/index.js";
 import {
 	type Breakable,
@@ -77,7 +79,28 @@ import type { TreeCheckout } from "./treeCheckout.js";
  * Creating multiple tree views from the same checkout is not supported. This slot is used to detect if one already
  * exists and error if creating a second.
  */
-export const ViewSlot = anchorSlot<TreeView<ImplicitFieldSchema>>();
+export const ViewSlot = anchorSlot<TreeContextAlpha>();
+
+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/shared-tree/sharedTree.ts

@@ -14,6 +14,7 @@ import type {
 	SharedKernel,
 } from "@fluidframework/shared-object-base/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { lt } from "semver-ts";
 
 import {
 	type CodecTree,
@@ -213,7 +214,7 @@ export class SharedTreeKernel
 			...defaultSharedTreeOptions,
 			...optionsParam,
 		};
-		if (options.minVersionForCollab < FluidClientVersion.v2_0) {
+		if (lt(options.minVersionForCollab, FluidClientVersion.v2_0)) {
 			throw new UsageError("SharedTree requires minVersionForCollab of at least 2.0.0");
 		}
 		const schema = new TreeStoredSchemaRepository();

package/src/shared-tree/transactionMinimize.ts

@@ -5,14 +5,21 @@
 
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import { minimizeModularChangeset } from "../feature-libraries/index.js";
+import {
+	buildForest,
+	fieldKinds,
+	minimizeModularChangeset,
+} from "../feature-libraries/index.js";
 import { ChangeProcessorApplicability } from "../shared-tree-core/index.js";
 import type { TransactionPostProcessor } from "../simple-tree/index.js";
 
-import { mapDataChanges } from "./sharedTreeChangeFamily.js";
+import {
+	mapDataChanges,
+	type SharedTreeChangeProcessingContext,
+} from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import { createTransactionPostProcessor } from "./transactionPostProcessor.js";
-import type { SharedTreeChangeProcessingContext } from "./sharedTreeChangeFamily.js";
+import { Breakable } from "../util/index.js";
 
 /**
  * "Minimizes" a {@link SharedTreeChange} so that it contains no extraneous
@@ -40,7 +47,9 @@ function minimizeSharedTreeChange(
 		);
 	}
 	return mapDataChanges(change, (dataChange) =>
-		minimizeModularChangeset(dataChange, context.modularChangeFamily),
+		minimizeModularChangeset(dataChange, fieldKinds, () =>
+			buildForest(new Breakable("minimizeSharedTreeChange")),
+		),
 	);
 }