@fluidframework/tree 2.80.0 → 2.81.0

package/src/shared-tree/treeCheckout.ts

@@ -3,14 +3,17 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
-import type { IFluidHandle, Listenable } from "@fluidframework/core-interfaces/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
+import type { IDisposable } from "@fluidframework/core-interfaces";
+import type { IFluidHandle, Listenable } from "@fluidframework/core-interfaces/internal";
+import { assert, unreachableCase, fail } from "@fluidframework/core-utils/internal";
 import type { IIdCompressor, SessionId } from "@fluidframework/id-compressor";
+import { isStableId } from "@fluidframework/id-compressor/internal";
 import {
 	UsageError,
 	type ITelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
+
 import {
 	FluidClientVersion,
 	FormatValidatorNoOp,
@@ -54,6 +57,8 @@ import {
 	type ChangeMetadata,
 	type ChangeEncodingContext,
 	type ReadOnlyDetachedFieldIndex,
+	makeAnonChange,
+	type TaggedChange,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -74,18 +79,6 @@ import {
 	type SharedTreeBranchChange,
 	type Transactor,
 } from "../shared-tree-core/index.js";
-import {
-	Breakable,
-	disposeSymbol,
-	getOrCreate,
-	type JsonCompatibleReadOnly,
-	type WithBreakable,
-} from "../util/index.js";
-
-import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamily.js";
-import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
-import type { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
-import type { IDisposable } from "@fluidframework/core-interfaces";
 import {
 	type ImplicitFieldSchema,
 	type ReadSchema,
@@ -100,8 +93,20 @@ import {
 	type CustomTreeValue,
 	type CustomTreeNode,
 } from "../simple-tree/index.js";
+import {
+	Breakable,
+	disposeSymbol,
+	getOrCreate,
+	hasSome,
+	type JsonCompatibleReadOnly,
+	type WithBreakable,
+} from "../util/index.js";
+
 import { getCheckout, SchematizingSimpleTreeView } from "./schematizingTreeView.js";
-import { isStableId } from "@fluidframework/id-compressor/internal";
+import { SharedTreeChangeEnricher } from "./sharedTreeChangeEnricher.js";
+import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamily.js";
+import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
+import type { ISharedTreeEditor, SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 
 /**
  * Events for {@link ITreeCheckout}.
@@ -132,8 +137,6 @@ export interface CheckoutEvents {
 	 * can use to filter on changes they care about e.g. local vs remote changes.
 	 *
 	 * @param data - information about the change
-	 * @param getRevertible - a function provided that allows users to get a revertible for the change. If not provided,
-	 * this change is not revertible.
 	 */
 	changed(data: ChangeMetadata, getRevertible?: RevertibleAlphaFactory): void;
 
@@ -566,6 +569,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 							change: encodedChange,
 						} satisfies SerializedChange;
 					},
+					getRevertible: (onDisposed) => getRevertible?.(onDisposed),
 				};
 
 				this.#events.emit("changed", metadata, getRevertible);
@@ -591,7 +595,9 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		this.#events.emit("afterBatch");
 		this.editLock.unlock();
 		if (event.type === "append") {
-			event.newCommits.forEach((commit) => this.validateCommit(commit));
+			for (const commit of event.newCommits) {
+				this.validateCommit(commit);
+			}
 		}
 	};
 
@@ -653,7 +659,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		// When the branch is trimmed, we can garbage collect any repair data whose latest relevant revision is one of the
 		// trimmed revisions.
 		this.withCombinedVisitor((visitor) => {
-			revisions.forEach((revision) => {
+			for (const revision of revisions) {
 				// get all the roots last created or used by the revision
 				const roots = this._removedRoots.getRootsLastTouchedByRevision(revision);
 
@@ -663,7 +669,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 				}
 
 				this._removedRoots.deleteRootsLastTouchedByRevision(revision);
-			});
+			}
 		});
 	};
 
@@ -1126,12 +1132,98 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	private validateCommit(commit: GraphCommit<SharedTreeChange>): void {
 		const validated = getOrCreate(this.#validatedCommits, commit, () => []);
 		if (validated !== true) {
-			validated.forEach((fn) => fn(commit));
+			for (const fn of validated) {
+				fn(commit);
+			}
 			this.#validatedCommits.set(commit, true);
 		}
 	}
 
 	// #endregion Commit Validation
+
+	// #region Enrichment
+
+	/**
+	 * Statistics about enrichment operations performed by this checkout.
+	 * Used for testing. May be used for telemetry in the future.
+	 * The performance cost of maintaining this information is negligible.
+	 */
+	private readonly enrichmentStats: {
+		batches: number;
+		diffs: number;
+		commitsEnriched: number;
+		refreshers: number;
+		forks: number;
+		applied: number;
+	} = { batches: 0, diffs: 0, commitsEnriched: 0, refreshers: 0, forks: 0, applied: 0 };
+
+	public resetEnrichmentStats(): void {
+		this.enrichmentStats.batches = 0;
+		this.enrichmentStats.diffs = 0;
+		this.enrichmentStats.commitsEnriched = 0;
+		this.enrichmentStats.refreshers = 0;
+		this.enrichmentStats.forks = 0;
+		this.enrichmentStats.applied = 0;
+	}
+
+	public getEnrichmentStats(): {
+		batches: number;
+		diffs: number;
+		commitsEnriched: number;
+		refreshers: number;
+		forks: number;
+		applied: number;
+	} {
+		return { ...this.enrichmentStats };
+	}
+
+	public enrich(
+		context: GraphCommit<SharedTreeChange>,
+		changes: readonly TaggedChange<SharedTreeChange>[],
+	): SharedTreeChange[] {
+		if (!hasSome(changes)) {
+			return [];
+		}
+		this.enrichmentStats.batches += 1;
+		const enricher = new SharedTreeChangeEnricher(
+			this.forest,
+			this._removedRoots,
+			this.storedSchema,
+			this.idCompressor,
+			() => (this.enrichmentStats.commitsEnriched += 1),
+			() => (this.enrichmentStats.refreshers += 1),
+			() => (this.enrichmentStats.forks += 1),
+			() => (this.enrichmentStats.applied += 1),
+		);
+		// This `lastCommitApplied` may be on the main branch or on a transaction branch.
+		// In either case, it is crucial that the state of the forest & detached field index reflects all changes up to and including this commit.
+		const lastCommitApplied = this.#transaction.activeBranch.getHead();
+		if (context !== lastCommitApplied) {
+			enricher.enqueueChange(() => {
+				this.enrichmentStats.diffs += 1;
+				const diff = diffHistories(
+					this.changeFamily.rebaser,
+					lastCommitApplied,
+					context,
+					this.mintRevisionTag,
+				);
+				return makeAnonChange(diff);
+			});
+		}
+		const enriched: SharedTreeChange[] = [];
+		for (const change of changes) {
+			enriched.push(enricher.enrich(change.change));
+			enricher.enqueueChange(change);
+		}
+		enricher[disposeSymbol]();
+		return enriched;
+	}
+
+	public get mainBranch(): SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange> {
+		return this.#transaction.branch;
+	}
+
+	// #endregion Enrichment
 }
 
 /**
@@ -1260,8 +1352,12 @@ function trackForksForDisposal(checkout: TreeCheckout): () => void {
 	let disposed = false;
 	return () => {
 		assert(!disposed, 0xaa9 /* Forks may only be disposed once */);
-		forks.forEach((fork) => fork.dispose());
-		onDisposeUnSubscribes.forEach((unsubscribe) => unsubscribe());
+		for (const fork of forks) {
+			fork.dispose();
+		}
+		for (const unsubscribe of onDisposeUnSubscribes) {
+			unsubscribe();
+		}
 		onForkUnSubscribe();
 		disposed = true;
 	};

package/src/shared-tree-core/branch.ts

@@ -6,6 +6,10 @@
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { Listenable } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
+import type {
+	OpSpaceCompressedId,
+	SessionSpaceCompressedId,
+} from "@fluidframework/id-compressor";
 import { type TelemetryEventBatcher, measure } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -24,10 +28,6 @@ import {
 	type RebaseStatsWithDuration,
 } from "../core/index.js";
 import { hasSome, defineLazyCachedProperty } from "../util/index.js";
-import type {
-	OpSpaceCompressedId,
-	SessionSpaceCompressedId,
-} from "@fluidframework/id-compressor";
 
 export type BranchId = SessionSpaceCompressedId | "main";
 export type EncodedBranchId = OpSpaceCompressedId;
@@ -400,5 +400,9 @@ export function onForkTransitive<T extends { events: Listenable<{ fork(t: T): vo
 			onFork(fork);
 		}),
 	);
-	return () => offs.forEach((off) => off());
+	return () => {
+		for (const off of offs) {
+			off();
+		}
+	};
 }

package/src/shared-tree-core/branchCommitEnricher.ts

@@ -5,105 +5,53 @@
 
 import { assert } from "@fluidframework/core-utils/internal";
 
-import { type ChangeRebaser, type GraphCommit, replaceChange } from "../core/index.js";
+import type { GraphCommit } from "../core/index.js";
+import { hasSome } from "../util/index.js";
 
-import type { SharedTreeBranchChange } from "./branch.js";
-import type { ChangeEnricherReadonlyCheckout } from "./changeEnricher.js";
-import { TransactionEnricher } from "./transactionEnricher.js";
+import type { ChangeEnricher } from "./changeEnricher.js";
 
 /**
  * Utility for enriching commits from a {@link Branch} before these commits are applied and submitted.
  */
 export class BranchCommitEnricher<TChange> {
-	readonly #transactionEnricher: TransactionEnricher<TChange>;
-	readonly #enricher: ChangeEnricherReadonlyCheckout<TChange>;
 	/**
-	 * Maps each local commit to the corresponding enriched commit.
+	 * Maps each local commit to the corresponding enriched change.
 	 * @remarks
-	 * Entries are added when the commits are {@link BranchCommitEnricher.processChange | processed during a change}.
-	 * Each entry is removed when it is {@link BranchCommitEnricher.enrich | retrieved}.
+	 * Entries are added when the commits are {@link BranchCommitEnricher.prepareChanges | prepared}.
+	 * Each entry is removed when it is {@link BranchCommitEnricher.retrieveChange | retrieved}.
 	 * In the event that an entry is not explicitly removed, it will eventually be {@link WeakMap | dropped from memory} along with the associated commit.
 	 */
-	readonly #preparedCommits: WeakMap<GraphCommit<TChange>, GraphCommit<TChange>> = new Map();
+	private readonly prepared: WeakMap<GraphCommit<TChange>, TChange> = new WeakMap();
 
-	/**
-	 * If defined, a top-level transaction has been {@link BranchCommitEnricher.commitTransaction | committed} since the last {@link BranchCommitEnricher.processChange | change has been processed}.
-	 * Calling this function will compute the composition of that transaction's commits.
-	 * @remarks This function will be reset to undefined after each {@link BranchCommitEnricher.processChange | change is processed}.
-	 */
-	#getOuterTransactionChange?: () => TChange;
-
-	public constructor(
-		rebaser: ChangeRebaser<TChange>,
-		enricher: ChangeEnricherReadonlyCheckout<TChange>,
-	) {
-		this.#enricher = enricher;
-		this.#transactionEnricher = new TransactionEnricher(rebaser, this.#enricher);
-	}
+	public constructor(private readonly enricher: ChangeEnricher<TChange>) {}
 
 	/**
-	 * Process the given change, preparing new commits for {@link BranchCommitEnricher.enrich | enrichment}.
-	 * @param change - The change to process.
+	 * Process the given commits for later {@link BranchCommitEnricher.retrieveChange | retrieval}.
+	 * @param commits - The commits to prepare.
 	 */
-	public processChange(change: SharedTreeBranchChange<TChange>): void {
-		if (change.type === "append") {
-			for (const newCommit of change.newCommits) {
-				const newChange =
-					this.#getOuterTransactionChange?.() ??
-					this.#enricher.updateChangeEnrichments(newCommit.change, newCommit.revision);
-
-				this.#preparedCommits.set(newCommit, replaceChange(newCommit, newChange));
+	public prepareChanges(commits: readonly GraphCommit<TChange>[]): void {
+		if (hasSome(commits)) {
+			const startingState = commits[0].parent;
+			assert(startingState !== undefined, 0xcc1 /* New commits must have a parent. */);
+			const enrichedCommits = this.enricher.enrich(startingState, commits);
+			for (const [index, commit] of commits.entries()) {
+				const enrichedCommit = enrichedCommits[index];
+				assert(enrichedCommit !== undefined, 0xcc2 /* Missing enriched commit. */);
+				this.prepared.set(commit, enrichedCommit);
 			}
 		}
-
-		this.#getOuterTransactionChange = undefined;
 	}
 
 	/**
-	 * Retrieves the enriched version of the given commit.
-	 * @param commit - A commit {@link BranchCommitEnricher.processChange | processed during the most recent change}.
+	 * Retrieves the enriched change for the given commit.
+	 * @param commit - A commit that was already {@link BranchCommitEnricher.prepareChanges | prepared}.
 	 * @remarks A commit can only be enriched once - subsequent calls to this method with the same commit will throw an error.
+	 * @returns The enriched change corresponding to the given `commit`.
 	 */
-	public enrich(commit: GraphCommit<TChange>): GraphCommit<TChange> {
-		const prepared = this.#preparedCommits.get(commit);
+	public retrieveChange(commit: GraphCommit<TChange>): TChange {
+		const prepared = this.prepared.get(commit);
 		assert(prepared !== undefined, 0x980 /* Unknown commit */);
-		this.#preparedCommits.delete(commit);
+		this.prepared.delete(commit);
 		return prepared;
 	}
-
-	/**
-	 * Notify the enricher that a new transaction has started.
-	 * @remarks This may be called multiple times without calling {@link BranchCommitEnricher.commitTransaction | commitTransaction}, producing "nested transactions".
-	 */
-	public startTransaction(): void {
-		this.#transactionEnricher.startTransaction();
-	}
-
-	/**
-	 * Commit the current transaction.
-	 * @remarks This should be called _before_ the corresponding transaction commit change is {@link BranchCommitEnricher.processChange | processed}.
-	 */
-	public commitTransaction(): void {
-		this.#getOuterTransactionChange = this.#transactionEnricher.commitTransaction();
-	}
-
-	/**
-	 * Notify the enricher that the current transaction has been aborted.
-	 * @remarks This will throw an error if there is no ongoing transaction.
-	 */
-	public abortTransaction(): void {
-		this.#transactionEnricher.abortTransaction();
-	}
-
-	/**
-	 * Add new transaction commits to the current transaction.
-	 * @param newCommits - The new commits to add.
-	 * @remarks This will throw an error if there is no ongoing transaction.
-	 */
-	public addTransactionCommits(newCommits: Iterable<GraphCommit<TChange>>): void {
-		assert(this.#transactionEnricher.isTransacting(), 0xa97 /* Not in transaction */);
-		for (const commit of newCommits) {
-			this.#transactionEnricher.addTransactionStep(commit);
-		}
-	}
 }

package/src/shared-tree-core/branchIdCodec.ts

@@ -8,6 +8,7 @@ import type {
 	OpSpaceCompressedId,
 	SessionId,
 } from "@fluidframework/id-compressor";
+
 import type { BranchId } from "./branch.js";
 
 export function encodeBranchId(

package/src/shared-tree-core/changeEnricher.ts

@@ -3,61 +3,17 @@
  * Licensed under the MIT License.
  */
 
-import type { RevisionTag } from "../core/index.js";
-import { disposeSymbol } from "../util/index.js";
+import type { GraphCommit, TaggedChange } from "../core/index.js";
 
 /**
- * A checkout that can be used by {@link SharedTreeCore} or {@link DefaultResubmitMachine} to enrich changes with refreshers.
- *
- * This is similar to a {@link TreeCheckout} in that it represents the state of the tree at a specific revision.
- * But unlike a `TreeCheckout`...
- * - It is not backed by a branch because the `CommitEnricher` that owns it controls which revision it should represent.
- * - The host application has no knowledge of it, so applying changes to it has no impact on the application.
- * - It need not maintain any state or indexes that do not play a role in enriching changes.
- *
- * See implementations for examples.
+ * Allows change to be enriched by using a {@link ChangeEnricherCheckout}.
  */
-export interface ChangeEnricherReadonlyCheckout<TChange> {
+export interface ChangeEnricher<TChange> {
 	/**
-	 * Updates the set of refreshers on a change.
-	 * @param change - the change to enrich. Not mutated.
-	 * @param revision - the revision associated with the change.
-	 * @returns the enriched change. Possibly the same as the one passed in.
+	 * Runs a batch of change enrichments.
+	 * @param context - The branch head after which the `changes` would apply.
+	 * @param changes - The changes to be enriched.
+	 * @returns The enriched changes.
 	 */
-	updateChangeEnrichments(change: TChange, revision: RevisionTag): TChange;
-
-	/**
-	 * Forks the checkout, creating a new checkout that represents the same state but can be mutated.
-	 */
-	fork(): ChangeEnricherMutableCheckout<TChange>;
-}
-
-/**
- * A {@link ChangeEnricherReadonlyCheckout} whose state can be controlled by a {@link CommitEnricher}.
- */
-export interface ChangeEnricherMutableCheckout<TChange>
-	extends ChangeEnricherReadonlyCheckout<TChange> {
-	/**
-	 * Applies a change to the tip state.
-	 * @param change - the change to apply. Not mutated.
-	 * @param revision - the revision associated with the change.
-	 * Can be undefined when the applied change is a rollback.
-	 */
-	applyTipChange(change: TChange, revision?: RevisionTag): void;
-
-	/**
-	 * Disposes of the enricher.
-	 */
-	[disposeSymbol](): void;
-}
-
-export class NoOpChangeEnricher<TChange> implements ChangeEnricherMutableCheckout<TChange> {
-	public applyTipChange(change: TChange, revision?: RevisionTag | undefined): void {}
-	public updateChangeEnrichments(change: TChange, revision: RevisionTag): TChange {
-		return change;
-	}
-	public fork(): ChangeEnricherMutableCheckout<TChange> {
-		return new NoOpChangeEnricher();
-	}
-	public [disposeSymbol](): void {}
+	enrich(context: GraphCommit<TChange>, changes: readonly TaggedChange<TChange>[]): TChange[];
 }

package/src/shared-tree-core/defaultResubmitMachine.ts

@@ -3,12 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { assert, fail, oob } from "@fluidframework/core-utils/internal";
+import { assert, fail } from "@fluidframework/core-utils/internal";
 
-import type { GraphCommit, RevisionTag, TaggedChange } from "../core/index.js";
-import { disposeSymbol } from "../util/index.js";
+import type { GraphCommit, RevisionTag } from "../core/index.js";
+import { hasSome } from "../util/index.js";
 
-import type { ChangeEnricherReadonlyCheckout } from "./changeEnricher.js";
+import type { ChangeEnricher } from "./changeEnricher.js";
 import type { ResubmitMachine } from "./resubmitMachine.js";
 
 interface PendingChange<TChange> {
@@ -32,15 +32,11 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 	private currentEnrichment: number = 0;
 
 	public constructor(
-		/**
-		 * A function that can create a rollback for a given change.
-		 */
-		private readonly makeRollback: (change: TaggedChange<TChange>) => TChange,
 		/**
 		 * Change enricher that represent the tip of the top-level local branch (i.e., the branch on which in-flight
 		 * commits are applied and automatically rebased).
 		 */
-		private readonly tip: ChangeEnricherReadonlyCheckout<TChange>,
+		private readonly enricher: ChangeEnricher<TChange>,
 	) {}
 
 	public onCommitSubmitted(commit: GraphCommit<TChange>): void {
@@ -67,54 +63,46 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 			return;
 		}
 
-		const localCommits = getLocalCommits();
-		assert(
-			localCommits[0]?.revision === revision,
-			0xc79 /* Expected local commits to start with specified revision */,
-		);
+		const newCommits = getLocalCommits();
 
-		// Some in-flight commits have stale enrichments, so we recompute them.
-		const checkout = this.tip.fork();
-
-		// Roll back the checkout to the state before the oldest commit
-		for (let iCommit = localCommits.length - 1; iCommit >= 0; iCommit -= 1) {
-			const commit = localCommits[iCommit] ?? oob();
-			const rollback = this.makeRollback(commit);
-			// WARNING: it's not currently possible to roll back past a schema change (see AB#7265).
-			// Either we have to make it possible to do so, or this logic will have to change to work
-			// forwards from an earlier fork instead of backwards.
-			checkout.applyTipChange(rollback);
-		}
-
-		// Update the enrichments of the stale commits.
-		for (const [iCommit, commit] of localCommits.entries()) {
-			const current = this.getPendingChange(commit.revision);
+		const staleChanges: {
+			readonly pending: PendingChange<TChange>;
+			readonly newCommit: GraphCommit<TChange>;
+		}[] = [];
+		for (const newCommit of newCommits) {
+			const pending = this.getPendingChange(newCommit.revision);
 			assert(
-				current !== undefined,
+				pending !== undefined,
 				0xbda /* there must be an inflight commit for each resubmit commit */,
 			);
-
-			if (current.lastEnrichment < this.currentEnrichment) {
-				const enrichedChange = checkout.updateChangeEnrichments(
-					commit.change,
-					commit.revision,
-				);
-				const enrichedCommit = { ...commit, change: enrichedChange };
-
-				// Optimization: only apply the enriched change if the next commit also needs enrichment.
-				const nextCommit = localCommits[iCommit + 1];
-				if (
-					nextCommit !== undefined &&
-					this.getPendingChange(nextCommit.revision).lastEnrichment < this.currentEnrichment
-				) {
-					checkout.applyTipChange(enrichedChange, commit.revision);
-				}
-
-				current.commit = enrichedCommit;
-				current.lastEnrichment = this.currentEnrichment;
+			const isStale = pending.lastEnrichment < this.currentEnrichment;
+			if (isStale) {
+				staleChanges.push({ pending, newCommit });
+			} else {
+				// We have reached a commit with a valid enrichment. Later commits must also be valid.
+				break;
 			}
 		}
-		checkout[disposeSymbol]();
+
+		assert(
+			hasSome(staleChanges) && staleChanges[0].newCommit.revision === revision,
+			0xc79 /* Expected local commits to start with specified revision */,
+		);
+
+		const startingState = staleChanges[0].newCommit.parent;
+		assert(startingState !== undefined, 0xcc3 /* New commits must have a parent. */);
+		// Some in-flight commits have stale enrichments, so we recompute them.
+		const enriched = this.enricher.enrich(
+			startingState,
+			newCommits.slice(0, staleChanges.length),
+		);
+		for (const [index, { pending, newCommit }] of staleChanges.entries()) {
+			const enrichedChange = enriched[index];
+			assert(enrichedChange !== undefined, 0xcc4 /* Missing enriched commit. */);
+			const enrichedCommit = { ...newCommit, change: enrichedChange };
+			pending.commit = enrichedCommit;
+			pending.lastEnrichment = this.currentEnrichment;
+		}
 	}
 
 	public getEnrichedCommit(