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

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

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

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

@@ -66,6 +66,7 @@ import {
 
 import { canInitialize, initialize, initializerFromChunk } from "./schematizeTree.js";
 import type { ITreeCheckout, TreeCheckout } from "./treeCheckout.js";
+import { pauseTreeEvents } from "../simple-tree/index.js";
 
 /**
  * Creating multiple tree views from the same checkout is not supported. This slot is used to detect if one already
@@ -229,16 +230,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 +245,8 @@ export class SchematizingSimpleTreeView<
 			| void,
 		params?: RunTransactionParams,
 	): TransactionResultExt<TSuccessValue, TFailureValue> | TransactionResult {
+		const { preconditions } = params ?? {};
+
 		const addConstraints = (
 			constraintsOnRevert: boolean,
 			constraints: readonly TransactionConstraint[] = [],
@@ -260,7 +257,7 @@ export class SchematizingSimpleTreeView<
 		this.checkout.transaction.start();
 
 		// 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 = (

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

@@ -168,14 +168,15 @@ 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.
 	 *
@@ -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/index.ts

@@ -14,6 +14,7 @@ export {
 	treeNodeFromAnchor,
 	getSimpleNodeSchemaFromInnerNode,
 	SimpleContextSlot,
+	pauseTreeEvents,
 } from "./treeNodeKernel.js";
 export { type WithType, typeNameSymbol, typeSchemaSymbol } from "./withType.js";
 export {