@fluidframework/tree 2.2.0 → 2.3.0-288113

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

@@ -4,9 +4,15 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { createEmitter, type Listenable, type Off } from "../../events/index.js";
-import type { TreeChangeEvents, TreeNode, Unhydrated } from "./types.js";
-import type { AnchorNode } from "../../core/index.js";
+import {
+	createEmitter,
+	type HasListeners,
+	type IEmitter,
+	type Listenable,
+	type Off,
+} from "../../events/index.js";
+import type { TreeNode, Unhydrated } from "./types.js";
+import type { AnchorEvents, AnchorNode } from "../../core/index.js";
 import {
 	flexTreeSlot,
 	isFreedSymbol,
@@ -60,12 +66,48 @@ export function tryGetTreeNodeSchema(value: unknown): undefined | TreeNodeSchema
  * The kernel has the same lifetime as the node and spans both its unhydrated and hydrated states.
  * When hydration occurs, the kernel is notified via the {@link TreeNodeKernel.hydrate | hydrate} method.
  */
-export class TreeNodeKernel implements Listenable<TreeChangeEvents> {
+export class TreeNodeKernel implements Listenable<KernelEvents> {
+	private disposed = false;
+
+	/**
+	 * Generation number which is incremented any time we have an edit on the node.
+	 * Used during iteration to make sure there has been no edits that were concurrently made.
+	 */
+	public generationNumber: number = 0;
+
 	#hydrated?: {
 		anchorNode: AnchorNode;
-		offAnchorNode: Off;
+		offAnchorNode: Set<Off>;
 	};
-	#events = createEmitter<TreeChangeEvents>();
+
+	/**
+	 * Events registered before hydration.
+	 * @remarks
+	 *
+	 */
+	#preHydrationEvents?: Listenable<KernelEvents> &
+		IEmitter<KernelEvents> &
+		HasListeners<KernelEvents>;
+
+	/**
+	 * Get the listener.
+	 * @remarks
+	 * If before hydration, allocates and uses `#preHydrationEvents`, otherwise the anchorNode.
+	 * This design avoids allocating `#preHydrationEvents` if unneeded.
+	 *
+	 * This design also avoids extra forwarding overhead for events from anchorNode and also
+	 * avoids registering for events that the are unneeded.
+	 * This means optimizations like skipping processing data in subtrees where no subtreeChanged events are subscribed to would be able to work,
+	 * since this code does not unconditionally subscribe to those events (like a design simply forwarding all events would).
+	 */
+	get #events(): Listenable<KernelEvents> {
+		if (this.#hydrated === undefined) {
+			this.#preHydrationEvents ??= createEmitter<KernelEvents>();
+			return this.#preHydrationEvents;
+		} else {
+			return this.#hydrated.anchorNode;
+		}
+	}
 
 	/**
 	 * Create a TreeNodeKernel which can be looked up with {@link getKernel}.
@@ -80,37 +122,50 @@ export class TreeNodeKernel implements Listenable<TreeChangeEvents> {
 		treeNodeToKernel.set(node, this);
 	}
 
+	/**
+	 * Transition from {@link Unhydrated} to hydrated.
+	 * @remarks
+	 * Happens at most once for any given node.
+	 */
 	public hydrate(anchorNode: AnchorNode): void {
-		const offChildrenChanged = anchorNode.on("childrenChangedAfterBatch", () => {
-			this.#events.emit("nodeChanged");
-		});
-
-		const offSubtreeChanged = anchorNode.on("subtreeChangedAfterBatch", () => {
-			this.#events.emit("treeChanged");
-		});
-
-		const offAfterDestroy = anchorNode.on("afterDestroy", () => this.dispose());
+		assert(!this.disposed, "cannot use a disposed node");
 
 		this.#hydrated = {
 			anchorNode,
-			offAnchorNode: () => {
-				offChildrenChanged();
-				offSubtreeChanged();
-				offAfterDestroy();
-			},
+			offAnchorNode: new Set([
+				anchorNode.on("afterDestroy", () => this.dispose()),
+				// TODO: this should be triggered on change even for unhydrated nodes.
+				anchorNode.on("childrenChanging", () => {
+					this.generationNumber += 1;
+				}),
+			]),
 		};
-	}
 
-	public dehydrate(): void {
-		this.#hydrated?.offAnchorNode?.();
-		this.#hydrated = undefined;
+		// If needed, register forwarding emitters for events from before hydration
+		if (this.#preHydrationEvents !== undefined) {
+			for (const eventName of kernelEvents) {
+				if (this.#preHydrationEvents.hasListeners(eventName)) {
+					this.#hydrated.offAnchorNode.add(
+						// Argument is forwarded between matching events, so the type should be correct.
+						// eslint-disable-next-line @typescript-eslint/no-explicit-any
+						anchorNode.on(eventName, (arg: any) =>
+							this.#preHydrationEvents?.emit(eventName, arg),
+						),
+					);
+				}
+			}
+		}
 	}
 
 	public isHydrated(): boolean {
+		assert(!this.disposed, "cannot use a disposed node");
 		return this.#hydrated !== undefined;
 	}
 
 	public getStatus(): TreeStatus {
+		if (this.disposed) {
+			return TreeStatus.Deleted;
+		}
 		if (this.#hydrated?.anchorNode === undefined) {
 			return TreeStatus.New;
 		}
@@ -127,15 +182,19 @@ export class TreeNodeKernel implements Listenable<TreeChangeEvents> {
 		return treeStatusFromAnchorCache(this.#hydrated.anchorNode);
 	}
 
-	public on<K extends keyof TreeChangeEvents>(
-		eventName: K,
-		listener: TreeChangeEvents[K],
-	): Off {
+	public on<K extends keyof KernelEvents>(eventName: K, listener: KernelEvents[K]): Off {
 		return this.#events.on(eventName, listener);
 	}
 
 	public dispose(): void {
-		this.dehydrate();
+		this.disposed = true;
+		for (const off of this.#hydrated?.offAnchorNode ?? []) {
+			off();
+		}
 		// TODO: go to the context and remove myself from withAnchors
 	}
 }
+
+const kernelEvents = ["childrenChangedAfterBatch", "subtreeChangedAfterBatch"] as const;
+
+type KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;

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

@@ -24,9 +24,27 @@ import { isFlexTreeNode, type FlexTreeNode } from "../../feature-libraries/index
  */
 export type Unhydrated<T> = T;
 
+/**
+ * Data included for {@link TreeChangeEvents.nodeChanged}.
+ * @public
+ */
+export interface NodeChangedData {
+	/**
+	 * When the node changed is an object or Map node, this lists all the properties which changed.
+	 * @remarks
+	 * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
+	 */
+	readonly changedProperties?: ReadonlySet<string>;
+}
+
 /**
  * A collection of events that can be emitted by a {@link TreeNode}.
  *
+ * @remarks
+ * Currently events can be subscribed to for {@link Unhydrated} nodes, however no events will be triggered for the nodes until after they are hydrated.
+ * This is considered a known issue, and should be fixed in future versions.
+ * Do not rely on the fact that editing unhydrated nodes does not trigger their events.
+ *
  * @privateRemarks
  * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
  * Probably have object node and map node specific APIs for this.
@@ -45,17 +63,15 @@ export type Unhydrated<T> = T;
  *
  * @sealed @public
  */
-export interface TreeChangeEvents {
+export interface TreeChangeEvents<TNode = TreeNode> {
 	/**
-	 * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a
-	 * change is:
+	 * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.
 	 *
-	 * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
-	 * to something else, including `undefined`).
+	 * - Object nodes define a change as the value of one of its properties changing (i.e., the property's value is set, including when set to undefined).
 	 *
-	 * - For an array node, when an element is added, removed, or moved.
+	 * - Array node define a change as when an element is added, removed, moved or replaced.
 	 *
-	 * - For a map node, when an entry is added, updated, or removed.
+	 * - Map nodes define a change as when an entry is added, updated, or removed.
 	 *
 	 * @remarks
 	 * This event is not emitted when:
@@ -70,15 +86,23 @@ export interface TreeChangeEvents {
 	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
 	 * the client that made the original edit.
 	 *
-	 * When it is emitted, the tree is guaranteed to be in-schema.
+	 * When the event is emitted, the tree is guaranteed to be in-schema.
 	 *
 	 * @privateRemarks
 	 * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
 	 * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
 	 * node, or when the node has to be updated due to resolution of a merge conflict
 	 * (for example a previously applied local change might be undone, then reapplied differently or not at all).
+	 *
+	 * TODO: defined and document event ordering (ex: bottom up, with nodeChanged before treeCHange on each level).
 	 */
-	nodeChanged(): void;
+	nodeChanged(
+		data: NodeChangedData &
+			// For object and Map nodes, make properties specific to them required instead of optional:
+			(TNode extends WithType<string, NodeKind.Map | NodeKind.Object>
+				? Required<Pick<NodeChangedData, "changedProperties">>
+				: unknown),
+	): void;
 
 	/**
 	 * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
@@ -99,6 +123,8 @@ export interface TreeChangeEvents {
 	treeChanged(): void;
 }
 
+export type IsListener2<TListener> = TListener extends (...args: any[]) => void ? true : false;
+
 /**
  * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
  *

package/src/simple-tree/index.ts

@@ -19,6 +19,7 @@ export {
 	type Unhydrated,
 	type InternalTreeNode,
 	isTreeNode,
+	type NodeChangedData,
 } from "./core/index.js";
 export {
 	type ITree,