@fluidframework/tree 2.61.0-355934 → 2.61.0-356132

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/tree",
-  "version": "2.61.0-355934",
+  "version": "2.61.0-356132",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -101,17 +101,17 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "2.61.0-355934",
-    "@fluidframework/container-runtime": "2.61.0-355934",
-    "@fluidframework/core-interfaces": "2.61.0-355934",
-    "@fluidframework/core-utils": "2.61.0-355934",
-    "@fluidframework/datastore-definitions": "2.61.0-355934",
-    "@fluidframework/driver-definitions": "2.61.0-355934",
-    "@fluidframework/id-compressor": "2.61.0-355934",
-    "@fluidframework/runtime-definitions": "2.61.0-355934",
-    "@fluidframework/runtime-utils": "2.61.0-355934",
-    "@fluidframework/shared-object-base": "2.61.0-355934",
-    "@fluidframework/telemetry-utils": "2.61.0-355934",
+    "@fluid-internal/client-utils": "2.61.0-356132",
+    "@fluidframework/container-runtime": "2.61.0-356132",
+    "@fluidframework/core-interfaces": "2.61.0-356132",
+    "@fluidframework/core-utils": "2.61.0-356132",
+    "@fluidframework/datastore-definitions": "2.61.0-356132",
+    "@fluidframework/driver-definitions": "2.61.0-356132",
+    "@fluidframework/id-compressor": "2.61.0-356132",
+    "@fluidframework/runtime-definitions": "2.61.0-356132",
+    "@fluidframework/runtime-utils": "2.61.0-356132",
+    "@fluidframework/shared-object-base": "2.61.0-356132",
+    "@fluidframework/telemetry-utils": "2.61.0-356132",
     "@sinclair/typebox": "^0.34.13",
     "@tylerbu/sorted-btree-es6": "^1.8.0",
     "@types/ungap__structured-clone": "^1.2.0",
@@ -121,19 +121,19 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "2.61.0-355934",
-    "@fluid-private/stochastic-test-utils": "2.61.0-355934",
-    "@fluid-private/test-dds-utils": "2.61.0-355934",
-    "@fluid-private/test-drivers": "2.61.0-355934",
+    "@fluid-internal/mocha-test-setup": "2.61.0-356132",
+    "@fluid-private/stochastic-test-utils": "2.61.0-356132",
+    "@fluid-private/test-dds-utils": "2.61.0-356132",
+    "@fluid-private/test-drivers": "2.61.0-356132",
     "@fluid-tools/benchmark": "^0.51.0",
     "@fluid-tools/build-cli": "^0.58.3",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.58.3",
-    "@fluidframework/container-definitions": "2.61.0-355934",
-    "@fluidframework/container-loader": "2.61.0-355934",
+    "@fluidframework/container-definitions": "2.61.0-356132",
+    "@fluidframework/container-loader": "2.61.0-356132",
     "@fluidframework/eslint-config-fluid": "^6.0.0",
-    "@fluidframework/test-runtime-utils": "2.61.0-355934",
-    "@fluidframework/test-utils": "2.61.0-355934",
+    "@fluidframework/test-runtime-utils": "2.61.0-356132",
+    "@fluidframework/test-utils": "2.61.0-356132",
     "@fluidframework/tree-previous": "npm:@fluidframework/tree@2.60.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/diff": "^3.5.1",
@@ -227,7 +227,7 @@
     "test:customBenchmarks:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:customBenchmarks",
     "test:memory": "mocha --perfMode --config ./src/test/memory/.mocharc.cjs",
     "test:memory-profiling:report": "mocha --config ./src/test/memory/.mocharc.cjs",
-    "test:mocha": "npm run test:mocha:esm && echo skipping cjs to avoid overhead - npm run test:mocha:cjs",
+    "test:mocha": "echo skipping non-smoke cjs to avoid overhead && npm run test:mocha:cjs -- --fgrep @Smoke && npm run test:mocha:esm",
     "test:mocha:cjs": "cross-env MOCHA_SPEC=dist/test mocha",
     "test:mocha:esm": "mocha",
     "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",

package/src/feature-libraries/flex-tree/flexTreeTypes.ts

@@ -151,6 +151,8 @@ export enum TreeStatus {
  *
  * @remarks
  * All editing is actually done via {@link FlexTreeField}s: the nodes are immutable other than that they contain mutable fields.
+ *
+ * All implementations should track read access in {@link currentObserver}'s observation methods as appropriate.
  */
 export interface FlexTreeNode extends FlexTreeEntity, MapTreeNodeViewGeneric<FlexTreeNode> {
 	readonly [flexTreeMarker]: FlexTreeEntityKind.Node;

package/src/feature-libraries/flex-tree/index.ts

@@ -42,3 +42,5 @@ export { getOrCreateHydratedFlexTreeNode } from "./lazyNode.js";
 export { getSchemaAndPolicy, indexForAt } from "./utilities.js";
 
 export { treeStatusFromAnchorCache } from "./utilities.js";
+
+export { currentObserver, withObservation, type Observer } from "./observer.js";

package/src/feature-libraries/flex-tree/lazyNode.ts

@@ -33,6 +33,7 @@ import {
 } from "./flexTreeTypes.js";
 import { LazyEntity } from "./lazyEntity.js";
 import { makeField } from "./lazyField.js";
+import { currentObserver } from "./observer.js";
 
 /**
  * Get or create a {@link HydratedFlexTreeNode} for the given context at node indicated by the cursor.
@@ -118,18 +119,23 @@ export class LazyTreeNode extends LazyEntity<Anchor> implements HydratedFlexTree
 	public readonly fields: Pick<Map<FieldKey, FlexTreeField>, typeof Symbol.iterator | "get"> =
 		{
 			get: (key: FieldKey): FlexTreeField | undefined => this.tryGetField(key),
-			[Symbol.iterator]: (): IterableIterator<[FieldKey, FlexTreeField]> =>
-				mapCursorFields(this.cursor, (cursor) => {
+			[Symbol.iterator]: (): IterableIterator<[FieldKey, FlexTreeField]> => {
+				currentObserver?.observeNodeFields(this);
+
+				return mapCursorFields(this.cursor, (cursor) => {
 					const key: FieldKey = cursor.getFieldKey();
 					const pair: [FieldKey, FlexTreeField] = [
 						key,
 						makeField(this.context, this.storedSchema.getFieldSchema(key).kind, cursor),
 					];
 					return pair;
-				}).values(),
+				}).values();
+			},
 		};
 
 	public tryGetField(fieldKey: FieldKey): FlexTreeField | undefined {
+		currentObserver?.observeNodeField(this, fieldKey);
+
 		const schema = this.storedSchema.getFieldSchema(fieldKey);
 		return inCursorField(this.cursor, fieldKey, (cursor) => {
 			if (cursor.getFieldLength() === 0) {
@@ -140,6 +146,8 @@ export class LazyTreeNode extends LazyEntity<Anchor> implements HydratedFlexTree
 	}
 
 	public getBoxed(key: FieldKey): FlexTreeField {
+		currentObserver?.observeNodeField(this, key);
+
 		const fieldSchema = this.storedSchema.getFieldSchema(key);
 		return inCursorField(this.cursor, key, (cursor) => {
 			return makeField(this.context, fieldSchema.kind, cursor);
@@ -157,6 +165,8 @@ export class LazyTreeNode extends LazyEntity<Anchor> implements HydratedFlexTree
 	}
 
 	public get parentField(): { readonly parent: FlexTreeField; readonly index: number } {
+		currentObserver?.observeParentOf(this);
+
 		const cursor = this.cursor;
 		const index = this.anchorNode.parentIndex;
 		assert(cursor.fieldIndex === index, 0x786 /* mismatched indexes */);

package/src/feature-libraries/flex-tree/observer.ts

@@ -0,0 +1,58 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { debugAssert } from "@fluidframework/core-utils/internal";
+import type { FlexTreeNode } from "./flexTreeTypes.js";
+import type { FieldKey } from "../../core/index.js";
+
+/*
+ * This file sets up a static observation tracking system.
+ *
+ * This library used to contain a more general variant of this which was deleted in https://github.com/microsoft/FluidFramework/pull/18659.
+ * This pattern somewhat resembles the approach in https://github.com/tc39/proposal-signals.
+ */
+
+/**
+ * An object informed about observation made to trees.
+ * @remarks
+ * See {@link withObservation} and {@link currentObserver}.
+ */
+export interface Observer {
+	observeNodeFields(node: FlexTreeNode): void;
+	observeNodeField(node: FlexTreeNode, key: FieldKey): void;
+	observeParentOf(node: FlexTreeNode): void;
+}
+/**
+ * The current observer, if any.
+ * @remarks
+ * Set via {@link setObserver} as used by {@link withObservation}.
+ */
+export let currentObserver: Observer | undefined;
+
+const observerStack: (Observer | undefined)[] = [];
+
+function setObserver(newObserver: Observer | undefined): void {
+	observerStack.push(newObserver);
+	currentObserver = newObserver;
+}
+
+function clearObserver(): void {
+	debugAssert(() => observerStack.length > 0 || "Empty Observer stack on clear");
+	const popped = observerStack.pop();
+	debugAssert(() => popped === currentObserver || "Mismatched observer stack");
+	currentObserver = observerStack[observerStack.length - 1];
+}
+
+/**
+ * For the duration of `f`, pushes `newObserver` onto the observer stack, making it the {@link currentObserver}.
+ */
+export function withObservation<T>(newObserver: Observer | undefined, f: () => T): T {
+	setObserver(newObserver);
+	try {
+		return f();
+	} finally {
+		clearObserver();
+	}
+}

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-355934";
+export const pkgVersion = "2.61.0-356132";

package/src/shared-tree/treeAlpha.ts

@@ -17,7 +17,7 @@ import type { IIdCompressor } from "@fluidframework/id-compressor";
 import {
 	asIndex,
 	getKernel,
-	type TreeNode,
+	TreeNode,
 	type Unhydrated,
 	TreeBeta,
 	tryGetSchema,
@@ -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,189 @@ export interface TreeAlpha {
 	children(
 		node: TreeNode,
 	): Iterable<[propertyKey: string | number, child: TreeNode | TreeLeafValue]>;
+
+	/**
+	 * Track observations of any TreeNode content.
+	 * @remarks
+	 * This subscribes to changes to any nodes content observed during `trackDuring`.
+	 *
+	 * Currently this does not support tracking parentage (see {@link (TreeAlpha:interface).trackObservationsOnce} for a version which does):
+	 * if accessing parentage during `trackDuring`, this will throw a usage error.
+	 *
+	 * This also does not track node status changes (e.g. whether a node is attached to a view or not).
+	 * The current behavior of checking status is unspecified: future versions may track it, error, or ignore it.
+	 *
+	 * Even after onInvalidation is called, these subscriptions remain active until `unsubscribe` is called.
+	 * See {@link (TreeAlpha:interface).trackObservationsOnce} for a version which automatically unsubscribes on the first invalidation.
+	 */
+	trackObservations<TResult>(
+		onInvalidation: () => void,
+		trackDuring: () => TResult,
+	): { result: TResult; unsubscribe: () => void };
+
+	/**
+	 * {@link (TreeAlpha:interface).trackObservations} except automatically unsubscribes when the first invalidation occurs.
+	 * @remarks
+	 * This also supports tracking parentage, unlike {@link (TreeAlpha:interface).trackObservations}, as long as the parent is not undefined.
+	 */
+	trackObservationsOnce<TResult>(
+		onInvalidation: () => void,
+		trackDuring: () => TResult,
+	): { result: TResult; unsubscribe: () => void };
+}
+
+/**
+ * Subscription to changes on a single node.
+ * @remarks
+ * Either tracks some set of fields, or all fields and can be updated to track more fields.
+ */
+class NodeSubscription {
+	/**
+	 * If undefined, subscribes to all keys.
+	 * Otherwise only subscribes to the keys in the set.
+	 */
+	private keys: Set<FieldKey> | undefined;
+	private readonly unsubscribe: () => void;
+	private constructor(
+		private 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);
+	}
+
+	/**
+	 * Create an {@link Observer} which subscribes to what was observed in {@link NodeSubscription}s.
+	 */
+	public static createObserver(
+		invalidate: () => void,
+		onlyOnce = false,
+	): { observer: Observer; unsubscribe: () => void } {
+		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 {
+				// Supporting parent tracking is more difficult that it might seem at first.
+				// There are two main complicating factors:
+				// 1. The parent may be undefined (the node is a root).
+				// 2. If tracking this by subscribing to the parent's changes, then which events are subscribed to needs to be updated after the parent changes.
+				//
+				// If not supporting the first case (undefined parents), the second case gets problematic since it would result in edits which take a node who's parent was observed,
+				// and un-parent it, could then throw a usage error.
+
+				if (!onlyOnce) {
+					// TODO: better APIS should be provided which make handling this case practical.
+					throw new UsageError("Observation tracking for parents is currently not supported.");
+				}
+
+				const parent = withObservation(undefined, () => node.parentField.parent);
+
+				if (parent.parent === undefined) {
+					// TODO: better APIS should be provided which make handling this case practical.
+					throw new UsageError(
+						"Observation tracking for parents is currently not supported when parent is undefined.",
+					);
+				}
+				observer.observeNodeField(parent.parent, parent.key);
+			},
+		};
+
+		let subscribed = true;
+
+		return {
+			observer,
+			unsubscribe: () => {
+				if (!subscribed) {
+					throw new UsageError("Already unsubscribed");
+				}
+				subscribed = false;
+				for (const subscription of subscriptions.values()) {
+					subscription.unsubscribe();
+				}
+			},
+		};
+	}
+}
+
+/**
+ * Handles both {@link (TreeAlpha:interface).trackObservations} and {@link (TreeAlpha:interface).trackObservationsOnce}.
+ */
+function trackObservations<TResult>(
+	onInvalidation: () => void,
+	trackDuring: () => TResult,
+	onlyOnce = false,
+): { result: TResult; unsubscribe: () => void } {
+	let observing = true;
+
+	const invalidate = (): void => {
+		if (observing) {
+			throw new UsageError("Cannot invalidate while tracking observations");
+		}
+		onInvalidation();
+	};
+
+	const { observer, unsubscribe } = NodeSubscription.createObserver(invalidate, onlyOnce);
+	const result = withObservation(observer, trackDuring);
+	observing = false;
+
+	return {
+		result,
+		unsubscribe,
+	};
 }
 
 /**
@@ -427,6 +614,30 @@ export interface TreeAlpha {
  * @alpha
  */
 export const TreeAlpha: TreeAlpha = {
+	trackObservations<TResult>(
+		onInvalidation: () => void,
+		trackDuring: () => TResult,
+	): { result: TResult; unsubscribe: () => void } {
+		return trackObservations(onInvalidation, trackDuring);
+	},
+
+	trackObservationsOnce<TResult>(
+		onInvalidation: () => void,
+		trackDuring: () => TResult,
+	): { result: TResult; unsubscribe: () => void } {
+		const result = trackObservations(
+			() => {
+				// trackObservations ensures no invalidation occurs while its running,
+				// so this callback can only run after trackObservations has returns and thus result is defined.
+				result.unsubscribe();
+				onInvalidation();
+			},
+			trackDuring,
+			true,
+		);
+		return result;
+	},
+
 	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);
 	}