@fluidframework/tree 2.61.0-355656 → 2.61.0-355781

package/src/feature-libraries/index.ts

@@ -171,6 +171,9 @@ export {
 	type FlexTreeHydratedContextMinimal,
 	type HydratedFlexTreeNode,
 	getOrCreateHydratedFlexTreeNode,
+	currentObserver,
+	withObservation,
+	type Observer,
 } from "./flex-tree/index.js";
 
 export {

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.61.0-355656";
+export const pkgVersion = "2.61.0-355781";

package/src/shared-tree/treeAlpha.ts

@@ -17,13 +17,13 @@ import type { IIdCompressor } from "@fluidframework/id-compressor";
 import {
 	asIndex,
 	getKernel,
-	type TreeNode,
 	type Unhydrated,
 	TreeBeta,
 	tryGetSchema,
 	createFromCursor,
 	FieldKind,
 	normalizeFieldSchema,
+	TreeNode,
 	type ImplicitFieldSchema,
 	type InsertableField,
 	type TreeFieldFromImplicitField,
@@ -55,6 +55,7 @@ import {
 	convertField,
 	toUnhydratedSchema,
 	type TreeParsingOptions,
+	type NodeChangedData,
 } from "../simple-tree/index.js";
 import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import {
@@ -63,7 +64,7 @@ import {
 	type ICodecOptions,
 	type CodecWriteOptions,
 } from "../codec/index.js";
-import { EmptyKey, type ITreeCursorSynchronous } from "../core/index.js";
+import { EmptyKey, type FieldKey, type ITreeCursorSynchronous } from "../core/index.js";
 import {
 	cursorForMapTreeField,
 	defaultSchemaPolicy,
@@ -76,6 +77,9 @@ import {
 	fluidVersionToFieldBatchCodecWriteVersion,
 	type LocalNodeIdentifier,
 	type FlexTreeSequenceField,
+	type FlexTreeNode,
+	type Observer,
+	withObservation,
 } from "../feature-libraries/index.js";
 import { independentInitializedView, type ViewContent } from "./independentView.js";
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
@@ -419,6 +423,54 @@ export interface TreeAlpha {
 	children(
 		node: TreeNode,
 	): Iterable<[propertyKey: string | number, child: TreeNode | TreeLeafValue]>;
+
+	/**
+	 * Track observations of any TreeNode content.
+	 */
+	trackObservations<TResult>(
+		onInvalidation: () => void,
+		trackDuring: () => TResult,
+	): { result: TResult; unsubscribe: () => void };
+}
+
+class NodeSubscription {
+	/**
+	 * If undefined, subscribes to all keys.
+	 * Otherwise only subscribes to the keys in the set.
+	 */
+	public keys: Set<FieldKey> | undefined;
+	public readonly unsubscribe: () => void;
+	public constructor(
+		public readonly onInvalidation: () => void,
+		flexNode: FlexTreeNode,
+	) {
+		// TODO:Performance: It is possible to optimize this to not use the public TreeNode API.
+		const node = getOrCreateNodeFromInnerNode(flexNode);
+		assert(node instanceof TreeNode, "Unexpected leaf value");
+
+		const handler = (data: NodeChangedData): void => {
+			if (this.keys === undefined || data.changedProperties === undefined) {
+				this.onInvalidation();
+			} else {
+				let keyMap: ReadonlyMap<FieldKey, string> | undefined;
+				const schema = treeNodeApi.schema(node);
+				if (isObjectNodeSchema(schema)) {
+					keyMap = schema.storedKeyToPropertyKey;
+				}
+				// TODO:Performance: Ideally this would use Set.prototype.isDisjointFrom when available.
+				for (const flexKey of this.keys) {
+					// TODO:Performance: doing everything at the flex tree layer could avoid this translation
+					const key = keyMap?.get(flexKey) ?? flexKey;
+
+					if (data.changedProperties.has(key)) {
+						this.onInvalidation();
+						return;
+					}
+				}
+			}
+		};
+		this.unsubscribe = TreeBeta.on(node, "nodeChanged", handler);
+	}
 }
 
 /**
@@ -427,6 +479,77 @@ export interface TreeAlpha {
  * @alpha
  */
 export const TreeAlpha: TreeAlpha = {
+	trackObservations<TResult>(
+		onInvalidation: () => void,
+		trackDuring: () => TResult,
+	): { result: TResult; unsubscribe: () => void } {
+		let observing = true;
+
+		const invalidate = (): void => {
+			if (observing) {
+				throw new UsageError("Cannot invalidate while tracking observations");
+			}
+			onInvalidation();
+		};
+
+		const subscriptions = new Map<FlexTreeNode, NodeSubscription>();
+		const observer: Observer = {
+			observeNodeFields(flexNode: FlexTreeNode): void {
+				if (flexNode.value !== undefined) {
+					// Leaf value, nothing to observe.
+					return;
+				}
+				const subscription = subscriptions.get(flexNode);
+				if (subscription !== undefined) {
+					// Already subscribed to this node.
+					subscription.keys = undefined; // Now subscribed to all keys.
+				} else {
+					const newSubscription = new NodeSubscription(invalidate, flexNode);
+					subscriptions.set(flexNode, newSubscription);
+				}
+			},
+			observeNodeField(flexNode: FlexTreeNode, key: FieldKey): void {
+				if (flexNode.value !== undefined) {
+					// Leaf value, nothing to observe.
+					return;
+				}
+				const subscription = subscriptions.get(flexNode);
+				if (subscription !== undefined) {
+					// Already subscribed to this node: if not subscribed to all keys, subscribe to this one.
+					// TODO:Performance: due to how JavaScript set ordering works,
+					// it might be faster to check `has` and only add if not present in case the same field is viewed many times.
+					subscription.keys?.add(key);
+				} else {
+					const newSubscription = new NodeSubscription(invalidate, flexNode);
+					newSubscription.keys = new Set([key]);
+					subscriptions.set(flexNode, newSubscription);
+				}
+			},
+			observeParentOf(node: FlexTreeNode): void {
+				throw new UsageError("Observation tracking for parents is currently not supported.");
+				// This is conservatively correct, but could be optimized.
+				// observer.observeNodeContent(parent);
+			},
+		};
+		const result = withObservation(observer, trackDuring);
+		observing = false;
+
+		let subscribed = true;
+
+		return {
+			result,
+			unsubscribe: () => {
+				if (!subscribed) {
+					throw new UsageError("Already unsubscribed");
+				}
+				subscribed = false;
+				for (const subscription of subscriptions.values()) {
+					subscription.unsubscribe();
+				}
+			},
+		};
+	},
+
 	branch(node: TreeNode): TreeBranch | undefined {
 		const kernel = getKernel(node);
 		if (!kernel.isHydrated()) {

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

@@ -50,6 +50,7 @@ import {
 	type HydratedFlexTreeNode,
 	cursorForMapTreeField,
 	type MinimalFieldMap,
+	currentObserver,
 } from "../../feature-libraries/index.js";
 import { brand, filterIterable, getOrCreate, mapIterable } from "../../util/index.js";
 
@@ -144,8 +145,10 @@ export class UnhydratedFlexTreeNode
 	 */
 	public readonly fields: MinimalFieldMap<UnhydratedFlexTreeField> = {
 		get: (key: FieldKey): UnhydratedFlexTreeField | undefined => this.tryGetField(key),
-		[Symbol.iterator]: (): IterableIterator<[FieldKey, UnhydratedFlexTreeField]> =>
-			filterIterable(this.fieldsAll, ([, field]) => field.length > 0),
+		[Symbol.iterator]: (): IterableIterator<[FieldKey, UnhydratedFlexTreeField]> => {
+			currentObserver?.observeNodeFields(this);
+			return filterIterable(this.fieldsAll, ([, field]) => field.length > 0);
+		},
 	};
 
 	public [Symbol.iterator](): IterableIterator<UnhydratedFlexTreeField> {
@@ -218,6 +221,7 @@ export class UnhydratedFlexTreeNode
 	 * @remarks If this node is unparented, this method will return the special {@link unparentedLocation} as the parent.
 	 */
 	public get parentField(): LocationInField {
+		currentObserver?.observeParentOf(this);
 		return this.location;
 	}
 
@@ -226,6 +230,8 @@ export class UnhydratedFlexTreeNode
 	}
 
 	public tryGetField(key: FieldKey): UnhydratedFlexTreeField | undefined {
+		currentObserver?.observeNodeField(this, key);
+
 		const field = this.fieldsAll.get(key);
 		// Only return the field if it is not empty, in order to fulfill the contract of `tryGetField`.
 		if (field !== undefined && field.length > 0) {
@@ -235,6 +241,9 @@ export class UnhydratedFlexTreeNode
 
 	public getBoxed(key: string): UnhydratedFlexTreeField {
 		const fieldKey: FieldKey = brand(key);
+
+		currentObserver?.observeNodeField(this, fieldKey);
+
 		return this.getOrCreateField(fieldKey);
 	}