@fluidframework/tree 2.10.0 → 2.12.0

package/src/shared-tree-core/branch.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 TelemetryEventBatcher, measure } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -21,83 +21,37 @@ import {
 	tagRollbackInverse,
 	type RebaseStatsWithDuration,
 } from "../core/index.js";
-import { createEmitter, type Listenable } from "../events/index.js";
+import type { Listenable } from "@fluidframework/core-interfaces";
+import { createEmitter } from "@fluid-internal/client-utils";
 
-import { TransactionStack } from "./transactionStack.js";
-import { fail } from "../util/index.js";
+import { hasSome, defineLazyCachedProperty } from "../util/index.js";
 
 /**
- * Describes a change to a `SharedTreeBranch`. Various operations can mutate the head of the branch;
- * this change format describes each in terms of the "removed commits" (all commits which were present
- * on the branch before the operation but are no longer present after) and the "new commits" (all
- * commits which are present on the branch after the operation that were not present before). Each of
- * the following event types also provides a `change` which contains the net change to the branch
- * (or is undefined if there was no net change):
+ * Describes a change to a `SharedTreeBranch`. Each of the following event types provides a `change` which contains the net change to the branch (or is undefined if there was no net change):
  * * Append - when one or more commits are appended to the head of the branch, for example via
  * a change applied by the branch's editor, or as a result of merging another branch into this one
- * * Remove - when one or more commits are removed from the head of the branch. This occurs
- * when a transaction is aborted and all commits pending in that transaction are removed.
- * * Replace - when an operation simultaneously removes and appends commits. For example, when this
- * branch is rebased and some commits are removed and replaced with rebased versions, or when a
- * transaction completes and all pending commits are replaced with a single squash commit.
+ * * Remove - when one or more commits are removed from the head of the branch.
+ * * Rebase - when a rebase operation adds commits from another branch and replaces existing commits with their rebased versions.
  */
 export type SharedTreeBranchChange<TChange> =
 	| {
 			type: "append";
 			kind: CommitKind;
 			change: TaggedChange<TChange>;
-			newCommits: readonly GraphCommit<TChange>[];
+			/** The commits appended to the head of the branch by this operation */
+			newCommits: readonly [GraphCommit<TChange>, ...GraphCommit<TChange>[]];
 	  }
 	| {
 			type: "remove";
-			change: TaggedChange<TChange> | undefined;
-			removedCommits: readonly GraphCommit<TChange>[];
+			change: TaggedChange<TChange>;
+			/** The commits removed from the head of the branch by this operation */
+			removedCommits: readonly [GraphCommit<TChange>, ...GraphCommit<TChange>[]];
 	  }
 	| {
-			type: "replace";
+			type: "rebase";
 			change: TaggedChange<TChange> | undefined;
-			removedCommits: readonly GraphCommit<TChange>[];
-			newCommits: readonly GraphCommit<TChange>[];
 	  };
 
-/**
- * Returns the operation that caused the given {@link SharedTreeBranchChange}.
- */
-export function getChangeReplaceType(
-	change: SharedTreeBranchChange<unknown> & { type: "replace" },
-): "transactionCommit" | "rebase" {
-	// The "replace" variant of the change event is emitted by two operations: committing a transaction and doing a rebase.
-	// Committing a transaction will always remove one or more commits (the commits that were squashed),
-	// and will add exactly one new commit (the squash commit).
-	if (change.removedCommits.length === 0 || change.newCommits.length !== 1) {
-		return "rebase";
-	}
-
-	// There is only one case in which a rebase both removes commits and adds exactly one new commit.
-	// This occurs when there is exactly one divergent, but equivalent, commit on each branch:
-	//
-	// A ─ B (branch X)	  -- rebase Y onto X -->   A ─ B (branch X)
-	// └─ B' (branch Y)                                └─ (branch Y)
-	//
-	// B' is removed and replaced by B because both have the same revision.
-	assert(
-		change.removedCommits[0] !== undefined,
-		0x9e4 /* This wont run due to the length check above */,
-	);
-	assert(
-		change.newCommits[0] !== undefined,
-		0x9e5 /* This wont run because a replace operation always has new commits */,
-	);
-	if (
-		change.removedCommits.length === 1 &&
-		change.removedCommits[0].revision === change.newCommits[0].revision
-	) {
-		return "rebase";
-	}
-
-	return "transactionCommit";
-}
-
 /**
  * The events emitted by a `SharedTreeBranch`
  */
@@ -125,34 +79,6 @@ export interface SharedTreeBranchEvents<TEditor extends ChangeFamilyEditor, TCha
 	 * Fired after this branch is disposed
 	 */
 	dispose(): void;
-
-	/**
-	 * Fired after a new transaction is started.
-	 * @param isOuterTransaction - true iff the transaction being started is the outermost transaction
-	 * as opposed to a nested transaction.
-	 */
-	transactionStarted(isOuterTransaction: boolean): void;
-
-	/**
-	 * Fired after the current transaction is aborted.
-	 * @param isOuterTransaction - true iff the transaction being aborted is the outermost transaction
-	 * as opposed to a nested transaction.
-	 */
-	transactionAborted(isOuterTransaction: boolean): void;
-
-	/**
-	 * Fired after the current transaction is completely rolled back.
-	 * @param isOuterTransaction - true iff the transaction being aborted is the outermost transaction
-	 * as opposed to a nested transaction.
-	 */
-	transactionRolledBack(isOuterTransaction: boolean): void;
-
-	/**
-	 * Fired after the current transaction is committed.
-	 * @param isOuterTransaction - true iff the transaction being committed is the outermost transaction
-	 * as opposed to a nested transaction.
-	 */
-	transactionCommitted(isOuterTransaction: boolean): void;
 }
 
 /**
@@ -179,30 +105,6 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 	readonly #events = createEmitter<SharedTreeBranchEvents<TEditor, TChange>>();
 	public readonly events: Listenable<SharedTreeBranchEvents<TEditor, TChange>> = this.#events;
 	public readonly editor: TEditor;
-	private readonly transactions = new TransactionStack();
-	/**
-	 * After pushing a starting revision to the transaction stack, this branch might be rebased
-	 * over commits which are children of that starting revision. When the transaction is committed,
-	 * those rebased-over commits should not be included in the transaction's squash commit, even though
-	 * they exist between the starting revision and the final commit within the transaction.
-	 *
-	 * Whenever `rebaseOnto` is called during a transaction, this map is augmented with an entry from the
-	 * original merge-base to the new merge-base.
-	 *
-	 * This state need only be retained for the lifetime of the transaction.
-	 *
-	 * TODO: This strategy might need to be revisited when adding better support for async transactions.
-	 * Since:
-	 *
-	 * 1. Transactionality is guaranteed primarily by squashing at commit time
-	 * 2. Branches may be rebased with an ongoing transaction
-	 *
-	 * a rebase operation might invalidate only a portion of a transaction's commits, thus defeating the
-	 * purpose of transactionality.
-	 *
-	 * AB#6483 and children items track this work.
-	 */
-	private readonly initialTransactionRevToRebasedRev = new Map<RevisionTag, RevisionTag>();
 	private disposed = false;
 	private readonly unsubscribeBranchTrimmer?: () => void;
 	/**
@@ -230,45 +132,42 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 	}
 
 	/**
-	 * Sets the head of this branch. Emits no change events.
+	 * Sets the head of this branch.
+	 * @remarks This is a "manual override" of sorts, for when the branch needs to be set to a certain state without going through the usual flow of edits.
+	 * This might be necessary as a performance optimization, or to prevent parts of the system updating incorrectly (this method emits no change events!).
 	 */
 	public setHead(head: GraphCommit<TChange>): void {
 		this.assertNotDisposed();
-		assert(!this.isTransacting(), 0x685 /* Cannot set head during a transaction */);
 		this.head = head;
 	}
 
 	/**
 	 * Apply a change to this branch.
-	 * @param taggedChange - the change to apply
+	 * @param change - the change to apply
 	 * @param kind - the kind of change to apply
 	 * @returns the change that was applied and the new head commit of the branch
 	 */
-	public apply(
-		taggedChange: TaggedChange<TChange>,
-		kind: CommitKind = CommitKind.Default,
-	): [change: TChange, newCommit: GraphCommit<TChange>] {
+	public apply(change: TaggedChange<TChange>, kind: CommitKind = CommitKind.Default): void {
 		this.assertNotDisposed();
 
-		const revisionTag = taggedChange.revision;
+		const revisionTag = change.revision;
 		assert(revisionTag !== undefined, 0xa49 /* Revision tag must be provided */);
 
 		const newHead = mintCommit(this.head, {
 			revision: revisionTag,
-			change: taggedChange.change,
+			change: change.change,
 		});
 
 		const changeEvent = {
 			type: "append",
 			kind,
-			change: taggedChange,
+			change,
 			newCommits: [newHead],
 		} as const;
 
 		this.#events.emit("beforeChange", changeEvent);
 		this.head = newHead;
 		this.#events.emit("afterChange", changeEvent);
-		return [taggedChange.change, newHead];
 	}
 
 	/**
@@ -278,147 +177,6 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 		return this.head;
 	}
 
-	/**
-	 * Begin a transaction on this branch. If the transaction is committed via {@link commitTransaction},
-	 * all commits made since this call will be squashed into a single head commit.
-	 */
-	public startTransaction(): void {
-		this.assertNotDisposed();
-		const forks = new Set<SharedTreeBranch<TEditor, TChange>>();
-		const onDisposeUnSubscribes: (() => void)[] = [];
-		const onForkUnSubscribe = onForkTransitive(this, (fork) => {
-			forks.add(fork);
-			onDisposeUnSubscribes.push(fork.events.on("dispose", () => forks.delete(fork)));
-		});
-		this.transactions.push(this.head.revision, () => {
-			forks.forEach((fork) => fork.dispose());
-			onDisposeUnSubscribes.forEach((unsubscribe) => unsubscribe());
-			onForkUnSubscribe();
-		});
-		this.editor.enterTransaction();
-		this.#events.emit("transactionStarted", this.transactions.size === 1);
-	}
-
-	/**
-	 * Commit the current transaction. There must be a transaction in progress that was begun via {@link startTransaction}.
-	 * If there are commits in the current transaction, they will be squashed into a new single head commit.
-	 * @returns the commits that were squashed and the new squash commit if a squash occurred, otherwise `undefined`.
-	 * @remarks If the transaction had no changes applied during its lifetime, then no squash occurs (i.e. this method is a no-op).
-	 * Even if the transaction contained only one change, it will still be replaced with an (equivalent) squash change.
-	 */
-	public commitTransaction():
-		| [squashedCommits: GraphCommit<TChange>[], newCommit: GraphCommit<TChange>]
-		| undefined {
-		this.assertNotDisposed();
-		const [startCommit, commits] = this.popTransaction();
-		this.editor.exitTransaction();
-
-		this.#events.emit("transactionCommitted", this.transactions.size === 0);
-		if (commits.length === 0) {
-			return undefined;
-		}
-
-		// Squash the changes and make the squash commit the new head of this branch
-		const squashedChange = this.changeFamily.rebaser.compose(commits);
-		const revision = this.mintRevisionTag();
-
-		const newHead = mintCommit(startCommit, {
-			revision,
-			change: this.changeFamily.rebaser.changeRevision(squashedChange, revision),
-		});
-
-		const changeEvent = {
-			type: "replace",
-			change: undefined,
-			removedCommits: commits,
-			newCommits: [newHead],
-		} as const;
-
-		this.#events.emit("beforeChange", changeEvent);
-		this.head = newHead;
-		this.#events.emit("afterChange", changeEvent);
-		return [commits, newHead];
-	}
-
-	/**
-	 * Cancel the current transaction. There must be a transaction in progress that was begun via
-	 * {@link startTransaction}. All commits made during the transaction will be removed.
-	 * @returns the change to this branch resulting in the removal of the commits, and a list of the
-	 * commits that were removed.
-	 */
-	public abortTransaction(): [
-		change: TChange | undefined,
-		abortedCommits: GraphCommit<TChange>[],
-	] {
-		this.assertNotDisposed();
-		const [startCommit, commits] = this.popTransaction();
-		this.editor.exitTransaction();
-
-		this.#events.emit("transactionAborted", this.transactions.size === 0);
-		if (commits.length === 0) {
-			this.#events.emit("transactionRolledBack", this.transactions.size === 0);
-			return [undefined, []];
-		}
-
-		const inverses: TaggedChange<TChange>[] = [];
-		for (let i = commits.length - 1; i >= 0; i--) {
-			const revision = this.mintRevisionTag();
-			const commit =
-				commits[i] ?? fail("This wont run because we are iterating through commits");
-			const inverse = this.changeFamily.rebaser.changeRevision(
-				this.changeFamily.rebaser.invert(commit, true, revision),
-				revision,
-				commit.revision,
-			);
-
-			inverses.push(tagRollbackInverse(inverse, revision, commit.revision));
-		}
-		const change =
-			inverses.length > 0 ? this.changeFamily.rebaser.compose(inverses) : undefined;
-
-		const changeEvent = {
-			type: "remove",
-			change: change === undefined ? undefined : makeAnonChange(change),
-			removedCommits: commits,
-		} as const;
-
-		this.#events.emit("beforeChange", changeEvent);
-		this.head = startCommit;
-		this.#events.emit("afterChange", changeEvent);
-		this.#events.emit("transactionRolledBack", this.transactions.size === 0);
-		return [change, commits];
-	}
-
-	/**
-	 * True iff this branch is in the middle of a transaction that was begin via {@link startTransaction}
-	 */
-	public isTransacting(): boolean {
-		return this.transactions.size !== 0;
-	}
-
-	private popTransaction(): [GraphCommit<TChange>, GraphCommit<TChange>[]] {
-		const { startRevision: startRevisionOriginal } = this.transactions.pop();
-		let startRevision = startRevisionOriginal;
-		while (this.initialTransactionRevToRebasedRev.has(startRevision)) {
-			startRevision = this.initialTransactionRevToRebasedRev.get(startRevision) ?? oob();
-		}
-
-		if (!this.isTransacting()) {
-			this.initialTransactionRevToRebasedRev.clear();
-		}
-
-		const commits: GraphCommit<TChange>[] = [];
-		const startCommit = findAncestor(
-			[this.head, commits],
-			(c) => c.revision === startRevision,
-		);
-		assert(
-			startCommit !== undefined,
-			0x593 /* Expected branch to be ahead of transaction start revision */,
-		);
-		return [startCommit, commits];
-	}
-
 	/**
 	 * Spawn a new branch that is based off of the current state of this branch.
 	 * @param commit - The commit to base the new branch off of. Defaults to the head of this branch.
@@ -448,31 +206,23 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 	public rebaseOnto(
 		branch: SharedTreeBranch<TEditor, TChange>,
 		upTo = branch.getHead(),
-	): BranchRebaseResult<TChange> | undefined {
+	): void {
 		this.assertNotDisposed();
 
 		// Rebase this branch onto the given branch
 		const rebaseResult = this.rebaseBranch(this, branch, upTo);
 		if (rebaseResult === undefined) {
-			return undefined;
+			return;
 		}
 
 		// The net change to this branch is provided by the `rebaseBranch` API
 		const { newSourceHead, commits } = rebaseResult;
 		const { deletedSourceCommits, targetCommits, sourceCommits } = commits;
+		assert(hasSome(targetCommits), 0xa83 /* Expected commit(s) for a non no-op rebase */);
 
 		const newCommits = targetCommits.concat(sourceCommits);
-		if (this.isTransacting()) {
-			const firstCommit = targetCommits[0] ?? oob();
-			const lastCommit = targetCommits[targetCommits.length - 1] ?? oob();
-			const src = firstCommit.parent?.revision;
-			const dst = lastCommit.revision;
-			if (src !== undefined && dst !== undefined) {
-				this.initialTransactionRevToRebasedRev.set(src, dst);
-			}
-		}
 		const changeEvent = {
-			type: "replace",
+			type: "rebase",
 			get change() {
 				const change = rebaseResult.sourceChange;
 				return change === undefined ? undefined : makeAnonChange(change);
@@ -484,7 +234,48 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 		this.#events.emit("beforeChange", changeEvent);
 		this.head = newSourceHead;
 		this.#events.emit("afterChange", changeEvent);
-		return rebaseResult;
+	}
+
+	/**
+	 * Remove a range of commits from this branch.
+	 * @param commit - All commits after (but not including) this commit will be removed.
+	 * @returns The net change to this branch and the commits that were removed from this branch.
+	 */
+	public removeAfter(commit: GraphCommit<TChange>): void {
+		if (commit === this.head) {
+			return;
+		}
+
+		const removedCommits: GraphCommit<TChange>[] = [];
+		const inverses: TaggedChange<TChange>[] = [];
+		findAncestor([this.head, removedCommits], (c) => {
+			// TODO: Pull this side effect out if/when more diverse ancestry walking helpers are available
+			if (c !== commit) {
+				const revision = this.mintRevisionTag();
+				const inverse = this.changeFamily.rebaser.changeRevision(
+					this.changeFamily.rebaser.invert(c, true, revision),
+					revision,
+					c.revision,
+				);
+
+				inverses.push(tagRollbackInverse(inverse, revision, c.revision));
+				return false;
+			}
+
+			return true;
+		});
+		assert(hasSome(removedCommits), 0xa84 /* Commit must be in the branch's ancestry */);
+
+		const change = makeAnonChange(this.changeFamily.rebaser.compose(inverses));
+		const changeEvent = {
+			type: "remove",
+			change,
+			removedCommits,
+		} as const;
+
+		this.#events.emit("beforeChange", changeEvent);
+		this.head = commit;
+		this.#events.emit("afterChange", changeEvent);
 	}
 
 	/**
@@ -494,15 +285,9 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 	 * @returns the net change to this branch and the commits that were added to this branch by the merge,
 	 * or undefined if nothing changed
 	 */
-	public merge(
-		branch: SharedTreeBranch<TEditor, TChange>,
-	): [change: TChange, newCommits: GraphCommit<TChange>[]] | undefined {
+	public merge(branch: SharedTreeBranch<TEditor, TChange>): void {
 		this.assertNotDisposed();
 		branch.assertNotDisposed();
-		assert(
-			!branch.isTransacting(),
-			0x597 /* Branch may not be merged while transaction is in progress */,
-		);
 
 		if (branch === this) {
 			return undefined;
@@ -516,21 +301,21 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 
 		// Compute the net change to this branch
 		const sourceCommits = rebaseResult.commits.sourceCommits;
-		const change = this.changeFamily.rebaser.compose(sourceCommits);
-		const taggedChange = makeAnonChange(change);
-		const changeEvent = {
-			type: "append",
-			kind: CommitKind.Default,
-			get change(): TaggedChange<TChange> {
-				return taggedChange;
-			},
-			newCommits: sourceCommits,
-		} as const;
+		assert(hasSome(sourceCommits), 0xa86 /* Expected source commits in non no-op merge */);
+		const { rebaser } = this.changeFamily;
+		const changeEvent = defineLazyCachedProperty(
+			{
+				type: "append",
+				kind: CommitKind.Default,
+				newCommits: sourceCommits,
+			} as const,
+			"change",
+			() => makeAnonChange(rebaser.compose(sourceCommits)),
+		);
 
 		this.#events.emit("beforeChange", changeEvent);
 		this.head = rebaseResult.newSourceHead;
 		this.#events.emit("afterChange", changeEvent);
-		return [change, sourceCommits];
 	}
 
 	/** Rebase `branchHead` onto `onto`, but return undefined if nothing changed */
@@ -576,10 +361,6 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
 			return;
 		}
 
-		while (this.isTransacting()) {
-			this.abortTransaction();
-		}
-
 		this.unsubscribeBranchTrimmer?.();
 
 		this.disposed = true;
@@ -600,8 +381,7 @@ export class SharedTreeBranch<TEditor extends ChangeFamilyEditor, TChange> {
  * The deregister function has undefined behavior if called more than once.
  */
 // Branches are invariant over TChange
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function onForkTransitive<T extends SharedTreeBranch<ChangeFamilyEditor, any>>(
+export function onForkTransitive<T extends { events: Listenable<{ fork(t: T): void }> }>(
 	branch: T,
 	onFork: (fork: T) => void,
 ): () => void {