@fluidframework/tree 2.60.0 → 2.61.0-355516

package/src/simple-tree/core/treeNodeKernel.ts

@@ -4,8 +4,13 @@
  */
 
 import { createEmitter } from "@fluid-internal/client-utils";
-import type { Listenable, Off } from "@fluidframework/core-interfaces";
-import { assert, Lazy, fail, debugAssert } from "@fluidframework/core-utils/internal";
+import type { HasListeners, Listenable, Off } from "@fluidframework/core-interfaces/internal";
+import {
+	assert,
+	fail,
+	debugAssert,
+	unreachableCase,
+} from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
@@ -13,6 +18,7 @@ import {
 	type AnchorEvents,
 	type AnchorNode,
 	type AnchorSet,
+	type FieldKey,
 	type TreeValue,
 	type UpPath,
 } from "../../core/index.js";
@@ -74,7 +80,6 @@ export function tryGetTreeNodeSchema(value: unknown): undefined | TreeNodeSchema
 
 /** The {@link HydrationState} of a {@link TreeNodeKernel} before the kernel is hydrated */
 interface UnhydratedState {
-	off: Off;
 	readonly innerNode: UnhydratedFlexTreeNode;
 }
 
@@ -126,7 +131,7 @@ export class TreeNodeKernel {
 	 * This means optimizations like skipping processing data in subtrees where no subtreeChanged events are subscribed to would be able to work,
 	 * since the kernel does not unconditionally subscribe to those events (like a design which simply forwards all events would).
 	 */
-	readonly #unhydratedEvents = new Lazy(createEmitter<KernelEvents>);
+	readonly #eventBuffer: KernelEventBuffer;
 
 	/**
 	 * Create a TreeNodeKernel which can be looked up with {@link getKernel}.
@@ -149,38 +154,21 @@ export class TreeNodeKernel {
 
 		if (innerNode instanceof UnhydratedFlexTreeNode) {
 			// Unhydrated case
+
 			debugAssert(() => innerNode.treeNode === undefined);
 			innerNode.treeNode = node;
-			// Register for change events from the unhydrated flex node.
-			// These will be fired if the unhydrated node is edited, and will also be forwarded later to the hydrated node.
+
 			this.#hydrationState = {
 				innerNode,
-				off: innerNode.events.on("childrenChangedAfterBatch", ({ changedFields }) => {
-					this.#unhydratedEvents.value.emit("childrenChangedAfterBatch", {
-						changedFields,
-					});
-
-					let unhydratedNode: UnhydratedFlexTreeNode | undefined = innerNode;
-					while (unhydratedNode !== undefined) {
-						const treeNode = unhydratedNode.treeNode;
-						if (treeNode !== undefined) {
-							const kernel = getKernel(treeNode);
-							kernel.#unhydratedEvents.value.emit("subtreeChangedAfterBatch");
-						}
-						const parentNode: FlexTreeNode | undefined =
-							unhydratedNode.parentField.parent.parent;
-						assert(
-							parentNode === undefined || parentNode instanceof UnhydratedFlexTreeNode,
-							0xb76 /* Unhydrated node's parent should be an unhydrated node */,
-						);
-						unhydratedNode = parentNode;
-					}
-				}),
 			};
+
+			this.#eventBuffer = new KernelEventBuffer(innerNode.events);
 		} else {
 			// Hydrated case
 			this.#hydrationState = this.createHydratedState(innerNode.anchorNode);
 			this.#hydrationState.innerNode = innerNode;
+
+			this.#eventBuffer = new KernelEventBuffer(innerNode.anchorNode.events);
 		}
 	}
 
@@ -213,19 +201,8 @@ export class TreeNodeKernel {
 		this.#hydrationState = this.createHydratedState(anchorNode);
 		this.#hydrationState.offAnchorNode.add(() => anchors.forget(anchor));
 
-		// If needed, register forwarding emitters for events from before hydration
-		if (this.#unhydratedEvents.evaluated) {
-			const events = this.#unhydratedEvents.value;
-			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)),
-					);
-				}
-			}
-		}
+		// Lazily migrate existing event listeners to the anchor node
+		this.#eventBuffer.migrateEventSource(anchorNode.events);
 	}
 
 	private createHydratedState(anchorNode: AnchorNode): HydratedState {
@@ -267,10 +244,7 @@ export class TreeNodeKernel {
 	}
 
 	public get events(): Listenable<KernelEvents> {
-		// Retrieve the correct events object based on whether this node is pre or post hydration.
-		return isHydrated(this.#hydrationState)
-			? this.#hydrationState.anchorNode.events
-			: this.#unhydratedEvents.value;
+		return this.#eventBuffer;
 	}
 
 	public dispose(): void {
@@ -281,6 +255,7 @@ export class TreeNodeKernel {
 				off();
 			}
 		}
+		this.#eventBuffer.dispose();
 		// TODO: go to the context and remove myself from withAnchors
 	}
 
@@ -354,6 +329,229 @@ const kernelEvents = ["childrenChangedAfterBatch", "subtreeChangedAfterBatch"] a
 
 type KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;
 
+// #region TreeNodeEventBuffer
+
+/**
+ * Whether or not events from {@link TreeNodeKernel} should be buffered instead of emitted immediately.
+ */
+let bufferTreeEvents: boolean = false;
+
+/**
+ * Call the provided callback with {@link TreeNode}s' events paused until after the callback's completion.
+ *
+ * Events that would otherwise have been emitted immediately are merged and buffered until after the
+ * provided callback has been completed.
+ *
+ * @remarks
+ * Note: this should be used with caution. User application behaviors are implicitly coupled to event timing.
+ * Disrupting this timing can lead to unexpected behavior.
+ */
+export function withBufferedTreeEvents(callback: () => void): void {
+	if (bufferTreeEvents) {
+		// Already buffering - just run the callback
+		callback();
+	} else {
+		bufferTreeEvents = true;
+		try {
+			callback();
+		} finally {
+			bufferTreeEvents = false;
+			flushEventsEmitter.emit("flush");
+		}
+	}
+}
+
+/**
+ * Event emitter to notify subscribers when tree events buffered due to {@link withBufferedTreeEvents} should be flushed.
+ */
+const flushEventsEmitter = createEmitter<{
+	flush: () => void;
+}>();
+
+/**
+ * Event emitter for {@link TreeNodeKernel}, which optionally buffers events based on {@link bufferTreeEvents}.
+ * @remarks Listens to {@link flushEventsEmitter} to know when to flush any buffered events.
+ */
+class KernelEventBuffer implements Listenable<KernelEvents> {
+	#disposed: boolean = false;
+
+	/**
+	 * Listen to {@link flushEventsEmitter} to know when to flush buffered events.
+	 */
+	readonly #disposeOnFlushListener = flushEventsEmitter.on("flush", () => {
+		this.flush();
+	});
+
+	readonly #events = createEmitter<KernelEvents>();
+
+	#eventSource: Listenable<KernelEvents> & HasListeners<KernelEvents>;
+	#disposeSourceListeners: Map<keyof KernelEvents, Off> = new Map();
+
+	/**
+	 * Buffer of fields that have changed since events were paused.
+	 * When events are flushed, a single {@link AnchorEvents.childrenChangedAfterBatch} event will be emitted
+	 * containing the accumulated set of changed fields.
+	 */
+	readonly #childrenChangedBuffer: Set<FieldKey> = new Set();
+
+	/**
+	 * Whether or not the subtree has changed since events were paused.
+	 * When events are flushed, a single {@link AnchorEvents.subTreeChanged} event will be emitted if and only
+	 * if the subtree has changed.
+	 */
+	#subTreeChangedBuffer: boolean = false;
+
+	public constructor(
+		/**
+		 * Source of the kernel events.
+		 * Subscriptions will be created on-demand when listeners are added to this.events,
+		 * and those subscriptions will be cleaned up when all corresponding listeners have been removed.
+		 */
+		eventSource: Listenable<KernelEvents> & HasListeners<KernelEvents>,
+	) {
+		this.#eventSource = eventSource;
+	}
+
+	/**
+	 * Migrate this event buffer to a new event source.
+	 *
+	 * @remarks
+	 * Cleans up any existing event subscriptions from the old source.
+	 * Binds events to the new source for each event with active listeners.
+	 */
+	public migrateEventSource(
+		newSource: Listenable<KernelEvents> & HasListeners<KernelEvents>,
+	): void {
+		// Unsubscribe from the old source
+		this.#disposeSourceListeners.forEach((off) => off());
+		this.#disposeSourceListeners.clear();
+
+		this.#eventSource = newSource;
+
+		if (this.#events.hasListeners("childrenChangedAfterBatch")) {
+			const off = this.#eventSource.on("childrenChangedAfterBatch", ({ changedFields }) =>
+				this.#emit("childrenChangedAfterBatch", { changedFields }),
+			);
+			this.#disposeSourceListeners.set("childrenChangedAfterBatch", off);
+		}
+		if (this.#events.hasListeners("subtreeChangedAfterBatch")) {
+			const off = this.#eventSource.on("subtreeChangedAfterBatch", () =>
+				this.#emit("subtreeChangedAfterBatch"),
+			);
+			this.#disposeSourceListeners.set("subtreeChangedAfterBatch", off);
+		}
+	}
+
+	public on(eventName: keyof KernelEvents, listener: KernelEvents[typeof eventName]): Off {
+		// Lazily bind event listeners to the source.
+		// If we do not have any existing listeners for this event, then we need to bind to the source.
+		if (!this.#events.hasListeners(eventName)) {
+			assert(
+				!this.#disposeSourceListeners.has(eventName),
+				"Should not have a dispose function without listeners",
+			);
+
+			const off = this.#eventSource.on(eventName, (args) => this.#emit(eventName, args));
+			this.#disposeSourceListeners.set(eventName, off);
+		}
+
+		this.#events.on(eventName, listener);
+		return () => this.off(eventName, listener);
+	}
+
+	public off(eventName: keyof KernelEvents, listener: KernelEvents[typeof eventName]): void {
+		this.#events.off(eventName, listener);
+
+		// If there are no remaining listeners for the event, unbind from the source
+		if (!this.#events.hasListeners(eventName)) {
+			const off = this.#disposeSourceListeners.get(eventName);
+			off?.();
+			this.#disposeSourceListeners.delete(eventName);
+		}
+	}
+
+	#emit(
+		eventName: keyof KernelEvents,
+		arg?: {
+			changedFields: ReadonlySet<FieldKey>;
+		},
+	): void {
+		this.#assertNotDisposed();
+		switch (eventName) {
+			case "childrenChangedAfterBatch":
+				assert(arg !== undefined, "childrenChangedAfterBatch should have arg");
+				return this.#handleChildrenChangedAfterBatch(arg.changedFields);
+			case "subtreeChangedAfterBatch":
+				return this.#handleSubtreeChangedAfterBatch();
+			default:
+				unreachableCase(eventName);
+		}
+	}
+
+	#handleChildrenChangedAfterBatch(changedFields: ReadonlySet<FieldKey>): void {
+		if (bufferTreeEvents) {
+			for (const fieldKey of changedFields) {
+				this.#childrenChangedBuffer.add(fieldKey);
+			}
+		} else {
+			this.#events.emit("childrenChangedAfterBatch", { changedFields });
+		}
+	}
+
+	#handleSubtreeChangedAfterBatch(): void {
+		if (bufferTreeEvents) {
+			this.#subTreeChangedBuffer = true;
+		} else {
+			this.#events.emit("subtreeChangedAfterBatch");
+		}
+	}
+
+	/**
+	 * Flushes any events buffered due to {@link withBufferedTreeEvents}.
+	 */
+	public flush(): void {
+		this.#assertNotDisposed();
+
+		if (this.#childrenChangedBuffer.size > 0) {
+			this.#events.emit("childrenChangedAfterBatch", {
+				changedFields: this.#childrenChangedBuffer,
+			});
+			this.#childrenChangedBuffer.clear();
+		}
+
+		if (this.#subTreeChangedBuffer) {
+			this.#events.emit("subtreeChangedAfterBatch");
+			this.#subTreeChangedBuffer = false;
+		}
+	}
+
+	#assertNotDisposed(): void {
+		assert(!this.#disposed, "Event handler disposed.");
+	}
+
+	public dispose(): void {
+		if (this.#disposed) {
+			return;
+		}
+
+		assert(
+			this.#childrenChangedBuffer.size === 0 && !this.#subTreeChangedBuffer,
+			"Buffered kernel events should have been flushed before disposing.",
+		);
+
+		this.#disposeOnFlushListener();
+		this.#disposeSourceListeners.forEach((off) => off());
+		this.#disposeSourceListeners.clear();
+
+		this.#childrenChangedBuffer.clear();
+		this.#subTreeChangedBuffer = false;
+
+		this.#disposed = true;
+	}
+}
+
+// #endregion
+
 /**
  * For "cooked" nodes this is a HydratedFlexTreeNode thats a projection of forest content.
  * For {@link Unhydrated} nodes this is a UnhydratedFlexTreeNode.

package/src/simple-tree/core/unhydratedFlexTree.ts

@@ -4,7 +4,7 @@
  */
 
 import { createEmitter } from "@fluid-internal/client-utils";
-import type { Listenable } from "@fluidframework/core-interfaces";
+import type { HasListeners, Listenable } from "@fluidframework/core-interfaces/internal";
 import { assert, oob, fail } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
@@ -60,7 +60,10 @@ import type { TreeNode } from "./treeNode.js";
 interface UnhydratedTreeSequenceFieldEditBuilder
 	extends SequenceFieldEditBuilder<FlexibleFieldContent, UnhydratedFlexTreeNode[]> {}
 
-type UnhydratedFlexTreeNodeEvents = Pick<AnchorEvents, "childrenChangedAfterBatch">;
+type UnhydratedFlexTreeNodeEvents = Pick<
+	AnchorEvents,
+	"childrenChangedAfterBatch" | "subtreeChangedAfterBatch"
+>;
 
 /** A node's parent field and its index in that field */
 type LocationInField = FlexTreeNode["parentField"];
@@ -96,7 +99,8 @@ export class UnhydratedFlexTreeNode
 	public readonly [flexTreeMarker] = FlexTreeEntityKind.Node as const;
 
 	private readonly _events = createEmitter<UnhydratedFlexTreeNodeEvents>();
-	public get events(): Listenable<UnhydratedFlexTreeNodeEvents> {
+	public get events(): Listenable<UnhydratedFlexTreeNodeEvents> &
+		HasListeners<UnhydratedFlexTreeNodeEvents> {
 		return this._events;
 	}
 
@@ -244,6 +248,25 @@ export class UnhydratedFlexTreeNode
 
 	public emitChangedEvent(key: FieldKey): void {
 		this._events.emit("childrenChangedAfterBatch", { changedFields: new Set([key]) });
+
+		// Also emit subtree changed event for this node and all ancestors.
+		this.#emitSubtreeChangedEvents();
+	}
+
+	/**
+	 * Emit subtree changed events for this node and all ancestors.
+	 */
+	#emitSubtreeChangedEvents(): void {
+		this._events.emit("subtreeChangedAfterBatch");
+
+		const parent = this.parentField.parent.parent;
+		assert(
+			parent === undefined || parent instanceof UnhydratedFlexTreeNode,
+			0xb76 /* Unhydrated node's parent should be an unhydrated node */,
+		);
+		if (parent !== undefined) {
+			parent.#emitSubtreeChangedEvents();
+		}
 	}
 }
 

package/src/simple-tree/index.ts

@@ -56,6 +56,7 @@ export {
 	walkAllowedTypes,
 	type SchemaVisitor,
 	type SimpleNodeSchemaBase,
+	withBufferedTreeEvents,
 } from "./core/index.js";
 export { walkFieldSchema } from "./walkFieldSchema.js";
 export type { UnsafeUnknownSchema, Insertable } from "./unsafeUnknownSchema.js";
@@ -164,6 +165,7 @@ export {
 	type SchemaStaticsAlpha,
 	KeyEncodingOptions,
 	type TreeParsingOptions,
+	type SchemaFactory_base,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,

package/src/simple-tree/node-kinds/array/arrayNode.ts

@@ -49,6 +49,7 @@ import {
 	type FlexContent,
 	type TreeNodeSchemaPrivateData,
 	convertAllowedTypes,
+	withBufferedTreeEvents,
 } from "../../core/index.js";
 import {
 	type FactoryContent,
@@ -1080,17 +1081,24 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 				);
 			}
 
-			if (sourceField !== destinationField || destinationGap < sourceStart) {
-				destinationField.editor.insert(
-					destinationGap,
-					sourceField.editor.remove(sourceStart, movedCount),
-				);
-			} else if (destinationGap > sourceStart + movedCount) {
-				destinationField.editor.insert(
-					destinationGap - movedCount,
-					sourceField.editor.remove(sourceStart, movedCount),
-				);
-			}
+			// We implement move here via subsequent `remove` and `insert`.
+			// This is strictly an implementation detail and should not be observable by the user.
+			// TODO:AB#47457: Implement proper move support for unhydrated trees.
+			// As a temporary mitigation, we will pause tree events until both edits have been completed.
+			// That way, users will only see a single change event for the array instead of 2.
+			withBufferedTreeEvents(() => {
+				if (sourceField !== destinationField || destinationGap < sourceStart) {
+					destinationField.editor.insert(
+						destinationGap,
+						sourceField.editor.remove(sourceStart, movedCount),
+					);
+				} else if (destinationGap > sourceStart + movedCount) {
+					destinationField.editor.insert(
+						destinationGap - movedCount,
+						sourceField.editor.remove(sourceStart, movedCount),
+					);
+				}
+			});
 		} else {
 			if (!sourceField.context.isHydrated()) {
 				throw new UsageError(

package/src/tableSchema.ts

@@ -29,6 +29,7 @@ import {
 	type UnannotateImplicitFieldSchema,
 	isArrayNodeSchema,
 	type InsertableField,
+	withBufferedTreeEvents,
 } from "./simple-tree/index.js";
 
 // Future improvement TODOs:
@@ -891,16 +892,21 @@ export namespace System_TableSchema {
 			private _applyEditsInBatch(applyEdits: () => void): void {
 				const branch = TreeAlpha.branch(this);
 
-				if (branch === undefined) {
-					// If this node does not have a corresponding branch, then it is unhydrated.
-					// I.e., it is not part of a collaborative session yet.
-					// Therefore, we don't need to run the edits as a transaction.
-					applyEdits();
-				} else {
-					branch.runTransaction(() => {
+				// Ensure events are paused until all of the edits are applied.
+				// This ensures that the user sees the corresponding table-level edit as atomic,
+				// and ensures they are not spammed with intermediate events.
+				withBufferedTreeEvents(() => {
+					if (branch === undefined) {
+						// If this node does not have a corresponding branch, then it is unhydrated.
+						// I.e., it is not part of a collaborative session yet.
+						// Therefore, we don't need to run the edits as a transaction.
 						applyEdits();
-					});
-				}
+					} else {
+						branch.runTransaction(() => {
+							applyEdits();
+						});
+					}
+				});
 			}
 
 			/**

package/src/util/breakable.ts

@@ -31,9 +31,17 @@ export class Breakable {
 	 */
 	public use(): void {
 		if (this.brokenBy !== undefined) {
-			throw new UsageError(
+			const error = new UsageError(
 				`Invalid use of ${this.name} after it was put into an invalid state by another error.\nOriginal Error:\n${this.brokenBy}`,
 			);
+
+			// This "cause" field is added in ES2022, but using if even without that built in support, it is still helpful.
+			// See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
+			// TODO: remove this cast when targeting ES2022 lib or later.
+			(error as { cause?: unknown }).cause =
+				(this.brokenBy as { cause?: unknown }).cause ?? this.brokenBy;
+
+			throw error;
 		}
 	}