refactor(tree): Support pausing Tree events for table operations

packages/dds/tree/api-report/tree.alpha.api.md

@@ -757,6 +757,7 @@ export interface RunTransaction {
 
 // @alpha @input
 export interface RunTransactionParams {
+    readonly deferTreeEvents?: boolean;
     readonly preconditions?: readonly TransactionConstraint[];
 }
 

packages/dds/tree/src/core/tree/anchorSet.ts

@@ -684,6 +684,24 @@ export class AnchorSet implements AnchorLocator {
 		}
 	}
 
+	// #region TODO: document all of this
+
+	private eventsPaused: boolean = false;
+	private bufferedEvents: BufferedEvent[] = [];
+
+	public pauseEvents(): void {
+		this.eventsPaused = true;
+		this.bufferedEvents = [];
+	}
+
+	public resumeAndFlushEvents(): void {
+		this.eventsPaused = false;
+		flushBufferedEvents(this.bufferedEvents);
+		this.bufferedEvents = [];
+	}
+
+	// #endregion
+
 	/**
 	 * Provides a visitor that can be used to mutate this {@link AnchorSet}.
 	 *
@@ -768,33 +786,10 @@ export class AnchorSet implements AnchorLocator {
 				}
 				this.anchorSet.activeVisitor = undefined;
 
-				// Aggregate changedFields by node.
-				const eventsByNode: Map<PathNode, Set<FieldKey>> = new Map();
-				for (const { node, event, changedField } of this.bufferedEvents) {
-					if (event === "childrenChangedAfterBatch") {
-						const keys = getOrCreate(eventsByNode, node, () => new Set());
-						keys.add(
-							changedField ??
-								fail(0xb57 /* childrenChangedAfterBatch events should have a changedField */),
-						);
-					}
-				}
-
-				const alreadyEmitted = new Map<PathNode, (keyof AnchorEvents)[]>();
-				for (const { node, event } of this.bufferedEvents) {
-					const emittedEvents = getOrAddEmptyToMap(alreadyEmitted, node);
-					if (emittedEvents.includes(event)) {
-						continue;
-					}
-					emittedEvents.push(event);
-					if (event === "childrenChangedAfterBatch") {
-						const changedFields =
-							eventsByNode.get(node) ??
-							fail(0xaeb /* childrenChangedAfterBatch events should have changedFields */);
-						node.events.emit(event, { changedFields });
-					} else {
-						node.events.emit(event);
-					}
+				if (this.anchorSet.eventsPaused) {
+					this.anchorSet.bufferedEvents.push(...this.bufferedEvents);
+				} else {
+					flushBufferedEvents(this.bufferedEvents);
 				}
 			},
 			notifyChildrenChanging(): void {
@@ -945,6 +940,40 @@ export class AnchorSet implements AnchorLocator {
 	}
 }
 
+/**
+ * Flushes and emits any buffered events.
+ */
+function flushBufferedEvents(bufferedEvents: readonly BufferedEvent[]): void {
+	// Aggregate changedFields by node.
+	const eventsByNode: Map<PathNode, Set<FieldKey>> = new Map();
+	for (const { node, event, changedField } of bufferedEvents) {
+		if (event === "childrenChangedAfterBatch") {
+			const keys = getOrCreate(eventsByNode, node, () => new Set());
+			keys.add(
+				changedField ??
+					fail(0xb57 /* childrenChangedAfterBatch events should have a changedField */),
+			);
+		}
+	}
+
+	const alreadyEmitted = new Map<PathNode, (keyof AnchorEvents)[]>();
+	for (const { node, event } of bufferedEvents) {
+		const emittedEvents = getOrAddEmptyToMap(alreadyEmitted, node);
+		if (emittedEvents.includes(event)) {
+			continue;
+		}
+		emittedEvents.push(event);
+		if (event === "childrenChangedAfterBatch") {
+			const changedFields =
+				eventsByNode.get(node) ??
+				fail(0xaeb /* childrenChangedAfterBatch events should have changedFields */);
+			node.events.emit(event, { changedFields });
+		} else {
+			node.events.emit(event);
+		}
+	}
+}
+
 /**
  * Indicates the status of a `NodePath`.
  */

packages/dds/tree/src/shared-tree/schematizingTreeView.ts

@@ -229,16 +229,10 @@ export class SchematizingSimpleTreeView<
 		return this.flexTreeContext;
 	}
 
-	/**
-	 * {@inheritDoc @fluidframework/shared-tree#TreeViewAlpha.runTransaction}
-	 */
 	public runTransaction<TSuccessValue, TFailureValue>(
 		transaction: () => TransactionCallbackStatus<TSuccessValue, TFailureValue>,
 		params?: RunTransactionParams,
 	): TransactionResultExt<TSuccessValue, TFailureValue>;
-	/**
-	 * {@inheritDoc @fluidframework/shared-tree#TreeViewAlpha.runTransaction}
-	 */
 	public runTransaction(
 		transaction: () => VoidTransactionCallbackStatus | void,
 		params?: RunTransactionParams,
@@ -250,6 +244,8 @@ export class SchematizingSimpleTreeView<
 			| void,
 		params?: RunTransactionParams,
 	): TransactionResultExt<TSuccessValue, TFailureValue> | TransactionResult {
+		const { preconditions, deferTreeEvents } = params ?? {};
+
 		const addConstraints = (
 			constraintsOnRevert: boolean,
 			constraints: readonly TransactionConstraint[] = [],
@@ -259,8 +255,12 @@ export class SchematizingSimpleTreeView<
 
 		this.checkout.transaction.start();
 
+		if (deferTreeEvents === true) {
+			this.checkout.forest.anchors.pauseEvents();
+		}
+
 		// Validate preconditions before running the transaction callback.
-		addConstraints(false /* constraintsOnRevert */, params?.preconditions);
+		addConstraints(false /* constraintsOnRevert */, preconditions);
 		const transactionCallbackStatus = transaction();
 		const rollback = transactionCallbackStatus?.rollback;
 		const value = (
@@ -280,6 +280,10 @@ export class SchematizingSimpleTreeView<
 			transactionCallbackStatus?.preconditionsOnRevert,
 		);
 
+		if (deferTreeEvents === true) {
+			this.checkout.forest.anchors.resumeAndFlushEvents();
+		}
+
 		this.checkout.transaction.commit();
 		return value !== undefined
 			? { success: true, value: value as TSuccessValue }

packages/dds/tree/src/simple-tree/api/transactionTypes.ts

@@ -123,4 +123,11 @@ export interface RunTransactionParams {
 	 * this client and ignored by all other clients.
 	 */
 	readonly preconditions?: readonly TransactionConstraint[];
+
+	/**
+	 * Set to defer all tree event notifications until completion of the transaction.
+	 * @remarks TODO: note benefits and note potential pitfalls
+	 * @defaultValue `false`
+	 */
+	readonly deferTreeEvents?: boolean;
 }

packages/dds/tree/src/simple-tree/api/tree.ts

@@ -168,16 +168,17 @@ export interface TreeBranch extends IDisposable {
 
 	/**
 	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
+	 *
 	 * @param transaction - The function to run as the body of the transaction.
 	 * It should return a status object of {@link TransactionCallbackStatus | TransactionCallbackStatus } type.
 	 * It includes a "rollback" property which may be returned as true at any point during the transaction. This will
 	 * abort the transaction and discard any changes it made so far.
 	 * "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
 	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
-	 * @returns A result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:
 	 *
+	 * @returns A result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:
 	 * - A "success" flag indicating whether the transaction was successful or not.
-	 * - The success or failure value as returned by the transaction function.
+	 * - The success of failure value as returned by the transaction function.
 	 *
 	 * @remarks
 	 * This API will throw an error if the constraints are not met or something unexpected happens.
@@ -205,16 +206,17 @@ export interface TreeBranch extends IDisposable {
 	): TransactionResultExt<TSuccessValue, TFailureValue>;
 	/**
 	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
-	 * @param transaction - The function to run as the body of the transaction. It may return the following:
 	 *
+	 * @param transaction - The function to run as the body of the transaction. It may return the following:
 	 * - Nothing to indicate that the body of the transaction has successfully run.
 	 * - A status object of {@link VoidTransactionCallbackStatus | VoidTransactionCallbackStatus } type. It includes a "rollback" property which
 	 * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so
 	 * far. "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
 	 *
 	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
-	 * @returns A result object of {@link TransactionResult | TransactionResult} type. It includes a "success" flag indicating whether the
-	 * transaction was successful or not.
+	 *
+	 * @returns A result object of {@link TransactionResult | TransactionResult} type.
+	 * It includes a "success" flag indicating whether the transaction was successful or not.
 	 *
 	 * @remarks
 	 * This API will throw an error if the constraints are not met or something unexpected happens.

packages/dds/tree/src/simple-tree/core/treeNodeKernel.ts

@@ -219,9 +219,7 @@ export class TreeNodeKernel {
 			for (const eventName of kernelEvents) {
 				if (events.hasListeners(eventName)) {
 					this.#hydrationState.offAnchorNode.add(
-						// Argument is forwarded between matching events, so the type should be correct.
-						// eslint-disable-next-line @typescript-eslint/no-explicit-any
-						anchorNode.events.on(eventName, (arg: any) => events.emit(eventName, arg)),
+						anchorNode.events.on(eventName, (arg) => events.emit(eventName, arg)),
 					);
 				}
 			}