@fluidframework/tree 2.10.0 → 2.12.0

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

@@ -4,106 +4,110 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { type ChangeRebaser, type GraphCommit, replaceChange } from "../core/index.js";
+import {
+	type ChangeRebaser,
+	type GraphCommit,
+	replaceChange,
+	type RevisionTag,
+} from "../core/index.js";
 import type { ChangeEnricherReadonlyCheckout } from "./changeEnricher.js";
 import { TransactionEnricher } from "./transactionEnricher.js";
+import type { SharedTreeBranchChange } from "./branch.js";
 
 /**
  * Utility for enriching commits from a {@link Branch} before these commits are applied and submitted.
  */
 export class BranchCommitEnricher<TChange> {
-	private readonly transactionEnricher: TransactionEnricher<TChange>;
-	private readonly enricher: ChangeEnricherReadonlyCheckout<TChange>;
+	readonly #transactionEnricher: TransactionEnricher<TChange>;
+	readonly #enricher: ChangeEnricherReadonlyCheckout<TChange>;
 	/**
 	 * Maps each local commit to the corresponding enriched commit.
-	 * Entries are added when the commits are prepared (before being applied and submitted).
-	 * Entries are removed when the commits are retrieved for submission (after being applied).
-	 * It's possible an entry will linger in the map indefinitely if it is never retrieved for submission.
-	 * This would happen if applying a commit were to fail and the commit were not retrieved/purged after the failure.
+	 * @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}.
+	 * In the event that an entry is not explicitly removed, it will eventually be {@link WeakMap | dropped from memory} along with the associated commit.
 	 */
-	private readonly preparedCommits: Map<GraphCommit<TChange>, GraphCommit<TChange>> =
-		new Map();
+	readonly #preparedCommits: WeakMap<GraphCommit<TChange>, GraphCommit<TChange>> = new Map();
+
+	/**
+	 * 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?: (revision: RevisionTag) => TChange;
 
 	public constructor(
 		rebaser: ChangeRebaser<TChange>,
 		enricher: ChangeEnricherReadonlyCheckout<TChange>,
 	) {
-		this.enricher = enricher;
-		this.transactionEnricher = new TransactionEnricher(rebaser, this.enricher);
+		this.#enricher = enricher;
+		this.#transactionEnricher = new TransactionEnricher(rebaser, this.#enricher);
 	}
 
 	/**
-	 * @returns The number of commits that have been prepared but not yet retrieved.
+	 * Process the given change, preparing new commits for {@link BranchCommitEnricher.enrich | enrichment}.
+	 * @param change - The change to process.
+	 * @param isAttached - Whether or not the SharedTree is attached to the service.
 	 */
-	public get preparedCommitsCount(): number {
-		return this.preparedCommits.size;
-	}
+	public processChange(change: SharedTreeBranchChange<TChange>): void {
+		if (change.type === "append") {
+			for (const newCommit of change.newCommits) {
+				const newChange =
+					this.#getOuterTransactionChange?.(newCommit.revision) ??
+					this.#enricher.updateChangeEnrichments(newCommit.change, newCommit.revision);
 
-	public startNewTransaction(): void {
-		this.transactionEnricher.startNewTransaction();
-	}
+				this.#preparedCommits.set(newCommit, replaceChange(newCommit, newChange));
+			}
+		}
 
-	public commitCurrentTransaction(): void {
-		this.transactionEnricher.commitCurrentTransaction();
+		this.#getOuterTransactionChange = undefined;
 	}
 
-	public abortCurrentTransaction(): void {
-		this.transactionEnricher.abortCurrentTransaction();
+	/**
+	 * Retrieves the enriched version of the given commit.
+	 * @param commit - A commit {@link BranchCommitEnricher.processChange | processed during the most recent change}.
+	 * @remarks A commit can only be enriched once - subsequent calls to this method with the same commit will throw an error.
+	 */
+	public enrich(commit: GraphCommit<TChange>): GraphCommit<TChange> {
+		const prepared = this.#preparedCommits.get(commit);
+		assert(prepared !== undefined, 0x980 /* Unknown commit */);
+		this.#preparedCommits.delete(commit);
+		return prepared;
 	}
 
 	/**
-	 * Adds a commit to the enricher.
-	 * @param commit - A commit that is part of a transaction.
+	 * 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 ingestTransactionCommit(commit: GraphCommit<TChange>): void {
-		// We do not submit ops for changes that are part of a transaction.
-		// But we need to enrich the commits that will be sent if the transaction is committed.
-		this.transactionEnricher.addTransactionStep(commit);
+	public startTransaction(): void {
+		this.#transactionEnricher.startTransaction();
 	}
 
 	/**
-	 * Prepares an enriched commit for later submission (see {@link BranchCommitEnricher.getPreparedCommit}).
-	 * @param commit - The commit to prepare an enriched version of.
-	 * @param concludesOuterTransaction - Whether the commit concludes an outer transaction.
-	 *
-	 * Each call to this method must be followed by a call to {@link BranchCommitEnricher.getPreparedCommit} or
-	 * {@link BranchCommitEnricher.purgePreparedCommits}. Failing to do so will result in a memory leak.
+	 * Commit the current transaction.
+	 * @remarks This should be called _before_ the corresponding transaction commit change is {@link BranchCommitEnricher.processChange | processed}.
 	 */
-	public prepareCommit(
-		commit: GraphCommit<TChange>,
-		concludesOuterTransaction: boolean,
-	): void {
-		let enrichedChange: TChange;
-		if (concludesOuterTransaction) {
-			assert(
-				this.transactionEnricher !== undefined,
-				0x97f /* Unexpected transaction commit without transaction steps */,
-			);
-			enrichedChange = this.transactionEnricher.getComposedChange(commit.revision);
-		} else {
-			enrichedChange = this.enricher.updateChangeEnrichments(commit.change, commit.revision);
-		}
-		this.preparedCommits.set(commit, replaceChange(commit, enrichedChange));
+	public commitTransaction(): void {
+		this.#getOuterTransactionChange = this.#transactionEnricher.commitTransaction();
 	}
 
 	/**
-	 * @param commit - A commit previously passed to {@link BranchCommitEnricher.prepareCommit}.
-	 * @returns The enriched commit corresponds to the given commit.
+	 * Notify the enricher that the current transaction has been aborted.
+	 * @remarks This will throw an error if there is no ongoing transaction.
 	 */
-	public getPreparedCommit(commit: GraphCommit<TChange>): GraphCommit<TChange> {
-		const prepared = this.preparedCommits.get(commit);
-		assert(prepared !== undefined, 0x980 /* Unknown commit */);
-		this.preparedCommits.delete(commit);
-		return prepared;
+	public abortTransaction(): void {
+		this.#transactionEnricher.abortTransaction();
 	}
 
 	/**
-	 * Purges all commits that have been prepared but not been retrieved.
-	 * This should be called to avoid memory leaks if the prepared commits are no longer needed.
-	 *
-	 * Does not affect ingested transaction commits.
+	 * 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 purgePreparedCommits(): void {
-		this.preparedCommits.clear();
+	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/defaultResubmitMachine.ts

@@ -5,7 +5,7 @@
 
 import { assert, oob } from "@fluidframework/core-utils/internal";
 import type { GraphCommit, TaggedChange } from "../core/index.js";
-import { disposeSymbol } from "../util/index.js";
+import { disposeSymbol, hasSome } from "../util/index.js";
 import type { ChangeEnricherReadonlyCheckout, ResubmitMachine } from "./index.js";
 
 /**
@@ -114,7 +114,8 @@ export class DefaultResubmitMachine<TChange> implements ResubmitMachine<TChange>
 			this.isInResubmitPhase,
 			0x982 /* No available commit to resubmit outside of resubmit phase */,
 		);
-		return this.resubmitQueue[0] ?? oob();
+		assert(hasSome(this.resubmitQueue), 0xa87 /* Expected resubmit queue to be non-empty */);
+		return this.resubmitQueue[0];
 	}
 
 	public get isInResubmitPhase(): boolean {

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

@@ -4,6 +4,7 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import { createEmitter } from "@fluid-internal/client-utils";
 import type { SessionId } from "@fluidframework/id-compressor";
 import { BTree } from "@tylerbu/sorted-btree-es6";
 
@@ -21,12 +22,7 @@ import {
 } from "../core/index.js";
 import { type Mutable, brand, fail, getOrCreate, mapIterable } from "../util/index.js";
 
-import {
-	SharedTreeBranch,
-	type BranchTrimmingEvents,
-	getChangeReplaceType,
-	onForkTransitive,
-} from "./branch.js";
+import { SharedTreeBranch, type BranchTrimmingEvents, onForkTransitive } from "./branch.js";
 import type {
 	Commit,
 	SeqNumber,
@@ -41,7 +37,6 @@ import {
 	minSequenceId,
 	sequenceIdComparator,
 } from "./sequenceIdUtils.js";
-import { createEmitter } from "../events/index.js";
 import {
 	TelemetryEventBatcher,
 	measure,
@@ -224,12 +219,12 @@ export class EditManager<
 		this.trackBranch(branch);
 		// Whenever the branch is rebased, update our record of its base trunk commit
 		const offBeforeRebase = branch.events.on("beforeChange", (args) => {
-			if (args.type === "replace" && getChangeReplaceType(args) === "rebase") {
+			if (args.type === "rebase") {
 				this.untrackBranch(branch);
 			}
 		});
 		const offAfterRebase = branch.events.on("afterChange", (args) => {
-			if (args.type === "replace" && getChangeReplaceType(args) === "rebase") {
+			if (args.type === "rebase") {
 				this.trackBranch(branch);
 				this.trimTrunk();
 			}

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

@@ -8,15 +8,25 @@ export {
 	SharedTreeBranch,
 	type SharedTreeBranchChange,
 	type SharedTreeBranchEvents,
-	getChangeReplaceType,
 } from "./branch.js";
 
+export {
+	TransactionResult,
+	type Transactor,
+	type TransactionEvents,
+	TransactionStack,
+	SquashingTransactionStack,
+	type OnPush,
+	type OnPop,
+} from "./transaction.js";
+
 export {
 	type ExplicitCoreCodecVersions,
 	SharedTreeCore,
 	type Summarizable,
 	type SummaryElementParser,
 	type SummaryElementStringifier,
+	type ClonableSchemaAndPolicy,
 } from "./sharedTreeCore.js";
 
 export type { ResubmitMachine } from "./resubmitMachine.js";
@@ -28,8 +38,6 @@ export {
 	NoOpChangeEnricher,
 } from "./changeEnricher.js";
 
-export { TransactionStack } from "./transactionStack.js";
-
 export { makeEditManagerCodec } from "./editManagerCodecs.js";
 export { EditManagerSummarizer } from "./editManagerSummarizer.js";
 export {

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob } from "@fluidframework/core-utils/internal";
+import { assert } from "@fluidframework/core-utils/internal";
 import type {
 	IChannelAttributes,
 	IFluidDataStoreRuntime,
@@ -45,7 +45,7 @@ import {
 	breakingClass,
 } from "../util/index.js";
 
-import { type SharedTreeBranch, getChangeReplaceType } from "./branch.js";
+import type { SharedTreeBranch } from "./branch.js";
 import { EditManager, minimumPossibleSequenceNumber } from "./editManager.js";
 import { makeEditManagerCodec } from "./editManagerCodecs.js";
 import type { SeqNumber } from "./editManagerFormat.js";
@@ -97,13 +97,6 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		return this.getLocalBranch().editor;
 	}
 
-	/**
-	 * Gets the revision at the head of the trunk.
-	 */
-	protected get trunkHeadRevision(): RevisionTag {
-		return this.editManager.getTrunkHead().revision;
-	}
-
 	/**
 	 * Used to encode/decode messages sent to/received from the Fluid runtime.
 	 *
@@ -183,60 +176,15 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			this.mintRevisionTag,
 			rebaseLogger,
 		);
-		this.editManager.localBranch.events.on("transactionStarted", () => {
-			this.commitEnricher.startNewTransaction();
-		});
-		this.editManager.localBranch.events.on("transactionAborted", () => {
-			this.commitEnricher.abortCurrentTransaction();
-		});
-		this.editManager.localBranch.events.on("transactionCommitted", () => {
-			this.commitEnricher.commitCurrentTransaction();
-		});
+
 		this.editManager.localBranch.events.on("beforeChange", (change) => {
-			// Ensure that any previously prepared commits that have not been sent are purged.
-			this.commitEnricher.purgePreparedCommits();
-			if (this.detachedRevision !== undefined) {
-				// Edits submitted before the first attach do not need enrichment because they will not be applied by peers.
-			} else if (change.type === "append") {
-				if (this.getLocalBranch().isTransacting()) {
-					for (const newCommit of change.newCommits) {
-						this.commitEnricher.ingestTransactionCommit(newCommit);
-					}
-				} else {
-					for (const newCommit of change.newCommits) {
-						this.commitEnricher.prepareCommit(newCommit, false);
-					}
-				}
-			} else if (
-				change.type === "replace" &&
-				getChangeReplaceType(change) === "transactionCommit" &&
-				!this.getLocalBranch().isTransacting()
-			) {
-				assert(
-					change.newCommits.length === 1,
-					0x983 /* Unexpected number of commits when committing transaction */,
-				);
-				this.commitEnricher.prepareCommit(change.newCommits[0] ?? oob(), true);
-			}
-		});
-		this.editManager.localBranch.events.on("afterChange", (change) => {
-			if (this.getLocalBranch().isTransacting()) {
-				// We do not submit ops for changes that are part of a transaction.
-				return;
+			if (this.detachedRevision === undefined) {
+				// Commit enrichment is only necessary for changes that will be submitted as ops, and changes issued while detached are not submitted.
+				this.commitEnricher.processChange(change);
 			}
-			if (
-				change.type === "append" ||
-				(change.type === "replace" && getChangeReplaceType(change) === "transactionCommit")
-			) {
-				if (this.detachedRevision !== undefined) {
-					for (const newCommit of change.newCommits) {
-						this.submitCommit(newCommit, this.schemaAndPolicy);
-					}
-				} else {
-					for (const newCommit of change.newCommits) {
-						const prepared = this.commitEnricher.getPreparedCommit(newCommit);
-						this.submitCommit(prepared, this.schemaAndPolicy);
-					}
+			if (change.type === "append") {
+				for (const commit of change.newCommits) {
+					this.submitCommit(commit, this.schemaAndPolicy, false);
 				}
 			}
 		});
@@ -309,6 +257,10 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	}
 
 	protected async loadCore(services: IChannelStorageService): Promise<void> {
+		assert(
+			this.editManager.localBranch.getHead() === this.editManager.getTrunkHead(),
+			"All local changes should be applied to the trunk before loading from summary",
+		);
 		const [editManagerSummarizer, ...summarizables] = this.summarizables;
 		const loadEditManager = this.loadSummarizable(editManagerSummarizer, services);
 		const loadSummarizables = summarizables.map(async (s) =>
@@ -353,22 +305,21 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	 * @returns the submitted commit. This is undefined if the underlying `SharedObject` is not attached,
 	 * and may differ from `commit` due to enrichments like detached tree refreshers.
 	 */
-
-	private submitCommit(
+	protected submitCommit(
 		commit: GraphCommit<TChange>,
 		schemaAndPolicy: ClonableSchemaAndPolicy,
-		isResubmit = false,
+		isResubmit: boolean,
 	): void {
-		assert(
-			// Edits should not be submitted until all transactions finish
-			!this.getLocalBranch().isTransacting() || isResubmit,
-			0x68b /* Unexpected edit submitted during transaction */,
-		);
 		assert(
 			this.isAttached() === (this.detachedRevision === undefined),
 			0x95a /* Detached revision should only be set when not attached */,
 		);
 
+		const enrichedCommit =
+			this.detachedRevision === undefined && !isResubmit
+				? this.commitEnricher.enrich(commit)
+				: commit;
+
 		// Edits submitted before the first attach are treated as sequenced because they will be included
 		// in the attach summary that is uploaded to the service.
 		// Until this attach workflow happens, this instance essentially behaves as a centralized data structure.
@@ -376,7 +327,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			const newRevision: SeqNumber = brand((this.detachedRevision as number) + 1);
 			this.detachedRevision = newRevision;
 			this.editManager.addSequencedChange(
-				{ ...commit, sessionId: this.editManager.localSessionId },
+				{ ...enrichedCommit, sessionId: this.editManager.localSessionId },
 				newRevision,
 				this.detachedRevision,
 			);
@@ -385,7 +336,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		}
 		const message = this.messageCodec.encode(
 			{
-				commit,
+				commit: enrichedCommit,
 				sessionId: this.editManager.localSessionId,
 			},
 			{
@@ -398,7 +349,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			schema: schemaAndPolicy.schema.clone(),
 			policy: schemaAndPolicy.policy,
 		});
-		this.resubmitMachine.onCommitSubmitted(commit);
+		this.resubmitMachine.onCommitSubmitted(enrichedCommit);
 	}
 
 	protected processCore(
@@ -421,9 +372,6 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		this.editManager.advanceMinimumSequenceNumber(brand(message.minimumSequenceNumber));
 	}
 
-	/**
-	 * @returns the head commit of the root local branch
-	 */
 	protected getLocalBranch(): SharedTreeBranch<TEditor, TChange> {
 		return this.editManager.localBranch;
 	}
@@ -469,10 +417,6 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	}
 
 	protected applyStashedOp(content: JsonCompatibleReadOnly): void {
-		assert(
-			!this.getLocalBranch().isTransacting(),
-			0x674 /* Unexpected transaction is open while applying stashed ops */,
-		);
 		// Empty context object is passed in, as our decode function is schema-agnostic.
 		const {
 			commit: { revision, change },