@fluidframework/tree 2.61.0 → 2.62.0

package/src/shared-tree/sharedTree.ts

@@ -6,7 +6,7 @@
 import type { ErasedType, IFluidLoadable } from "@fluidframework/core-interfaces/internal";
 import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
+import type { IIdCompressor, StableId } from "@fluidframework/id-compressor";
 import type {
 	IChannelView,
 	IFluidSerializer,
@@ -20,8 +20,8 @@ import {
 import {
 	type CodecWriteOptions,
 	FluidClientVersion,
+	FormatValidatorNoOp,
 	type ICodecOptions,
-	noopValidator,
 } from "../codec/index.js";
 import {
 	type FieldKey,
@@ -33,7 +33,6 @@ import {
 	ObjectNodeStoredSchema,
 	RevisionTagCodec,
 	SchemaVersion,
-	type TaggedChange,
 	type TreeFieldStoredSchema,
 	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
@@ -62,8 +61,8 @@ import {
 // eslint-disable-next-line import/no-internal-modules
 import type { FormatV1 } from "../feature-libraries/schema-index/index.js";
 import {
+	type BranchId,
 	type ClonableSchemaAndPolicy,
-	DefaultResubmitMachine,
 	type ExplicitCoreCodecVersions,
 	SharedTreeCore,
 } from "../shared-tree-core/index.js";
@@ -189,6 +188,10 @@ const formatVersionToTopLevelCodecVersions = new Map<number, ExplicitCodecVersio
 		5,
 		{ forest: 1, schema: 2, detachedFieldIndex: 1, editManager: 4, message: 4, fieldBatch: 1 },
 	],
+	[
+		100, // SharedTreeFormatVersion.vSharedBranches
+		{ forest: 1, schema: 2, detachedFieldIndex: 1, editManager: 5, message: 5, fieldBatch: 1 },
+	],
 ]);
 
 function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
@@ -217,6 +220,8 @@ export class SharedTreeKernel
 		return this.checkout.storedSchema;
 	}
 
+	private readonly checkouts: Map<BranchId, TreeCheckout> = new Map();
+
 	/**
 	 * The app-facing API for SharedTree implemented by this Kernel.
 	 * @remarks
@@ -232,7 +237,7 @@ export class SharedTreeKernel
 		serializer: IFluidSerializer,
 		submitLocalMessage: (content: unknown, localOpMetadata?: unknown) => void,
 		lastSequenceNumber: () => number | undefined,
-		logger: ITelemetryLoggerExt | undefined,
+		private readonly logger: ITelemetryLoggerExt | undefined,
 		idCompressor: IIdCompressor,
 		optionsParam: SharedTreeOptionsInternal,
 	) {
@@ -319,16 +324,12 @@ export class SharedTreeKernel
 			idCompressor,
 			schema,
 			defaultSchemaPolicy,
-			new DefaultResubmitMachine(
-				(change: TaggedChange<SharedTreeChange>) =>
-					changeFamily.rebaser.invert(change, true, this.mintRevisionTag()),
-				changeEnricher,
-			),
+			undefined,
 			changeEnricher,
 		);
-		const localBranch = this.getLocalBranch();
+
 		this.checkout = createTreeCheckout(idCompressor, this.mintRevisionTag, revisionTagCodec, {
-			branch: localBranch,
+			branch: this.getLocalBranch(),
 			changeFamily,
 			schema,
 			forest,
@@ -340,39 +341,49 @@ export class SharedTreeKernel
 			disposeForksAfterTransaction: options.disposeForksAfterTransaction,
 		});
 
-		this.checkout.transaction.events.on("started", () => {
-			if (sharedObject.isAttached()) {
+		this.registerCheckout("main", this.checkout);
+
+		this.view = {
+			contentSnapshot: () => this.contentSnapshot(),
+			exportSimpleSchema: () => this.exportSimpleSchema(),
+			exportVerbose: () => this.exportVerbose(),
+			viewWith: this.viewWith.bind(this),
+			viewSharedBranchWith: this.viewBranchWith.bind(this),
+			createSharedBranch: this.createSharedBranch.bind(this),
+			getSharedBranchIds: this.getSharedBranchIds.bind(this),
+			kernel: this,
+		};
+	}
+
+	private registerCheckout(branchId: BranchId, checkout: TreeCheckout): void {
+		this.checkouts.set(branchId, checkout);
+		const enricher = this.getCommitEnricher(branchId);
+		checkout.transaction.events.on("started", () => {
+			if (this.sharedObject.isAttached()) {
 				// It is currently forbidden to attach during a transaction, so transaction state changes can be ignored until after attaching.
-				this.commitEnricher.startTransaction();
+				enricher.startTransaction();
 			}
 		});
-		this.checkout.transaction.events.on("aborting", () => {
-			if (sharedObject.isAttached()) {
+
+		checkout.transaction.events.on("aborting", () => {
+			if (this.sharedObject.isAttached()) {
 				// It is currently forbidden to attach during a transaction, so transaction state changes can be ignored until after attaching.
-				this.commitEnricher.abortTransaction();
+				enricher.abortTransaction();
 			}
 		});
-		this.checkout.transaction.events.on("committing", () => {
-			if (sharedObject.isAttached()) {
+		checkout.transaction.events.on("committing", () => {
+			if (this.sharedObject.isAttached()) {
 				// It is currently forbidden to attach during a transaction, so transaction state changes can be ignored until after attaching.
-				this.commitEnricher.commitTransaction();
+				enricher.commitTransaction();
 			}
 		});
-		this.checkout.events.on("beforeBatch", (event) => {
-			if (event.type === "append" && sharedObject.isAttached()) {
-				if (this.checkout.transaction.isInProgress()) {
-					this.commitEnricher.addTransactionCommits(event.newCommits);
+		checkout.events.on("beforeBatch", (event) => {
+			if (event.type === "append" && this.sharedObject.isAttached()) {
+				if (checkout.transaction.isInProgress()) {
+					enricher.addTransactionCommits(event.newCommits);
 				}
 			}
 		});
-
-		this.view = {
-			contentSnapshot: () => this.contentSnapshot(),
-			exportSimpleSchema: () => this.exportSimpleSchema(),
-			exportVerbose: () => this.exportVerbose(),
-			viewWith: this.viewWith.bind(this),
-			kernel: this,
-		};
 	}
 
 	public exportVerbose(): VerboseTree | undefined {
@@ -415,18 +426,56 @@ export class SharedTreeKernel
 			TreeView<ReadSchema<TRoot>>;
 	}
 
+	public viewBranchWith<TRoot extends ImplicitFieldSchema>(
+		branchId: string,
+		config: TreeViewConfiguration<TRoot>,
+	): TreeView<TRoot>;
+
+	public viewBranchWith<TRoot extends ImplicitFieldSchema | UnsafeUnknownSchema>(
+		branchId: string,
+		config: TreeViewConfiguration<ReadSchema<TRoot>>,
+	): SchematizingSimpleTreeView<TRoot> & TreeView<ReadSchema<TRoot>> {
+		const compressedId = this.idCompressor.tryRecompress(branchId as StableId);
+		if (compressedId === undefined) {
+			throw new UsageError(`No branch found with id: ${branchId}`);
+		}
+		return this.getCheckout(compressedId).viewWith(
+			config,
+		) as SchematizingSimpleTreeView<TRoot> & TreeView<ReadSchema<TRoot>>;
+	}
+
+	private getCheckout(branchId: BranchId): TreeCheckout {
+		return this.checkouts.get(branchId) ?? this.checkoutBranch(branchId);
+	}
+
+	private checkoutBranch(branchId: BranchId): TreeCheckout {
+		const checkout = this.checkout.branch();
+		checkout.switchBranch(this.getSharedBranch(branchId));
+		const enricher = new SharedTreeReadonlyChangeEnricher(
+			checkout.forest,
+			checkout.storedSchema,
+			checkout.removedRoots,
+		);
+
+		this.registerSharedBranchForEditing(branchId, enricher);
+		this.registerCheckout(branchId, checkout);
+		return checkout;
+	}
+
 	public override async loadCore(services: IChannelStorageService): Promise<void> {
 		await super.loadCore(services);
 		this.checkout.load();
 	}
 
 	public override didAttach(): void {
-		if (this.checkout.transaction.isInProgress()) {
-			// Attaching during a transaction is not currently supported.
-			// At least part of of the system is known to not handle this case correctly - commit enrichment - and there may be others.
-			throw new UsageError(
-				"Cannot attach while a transaction is in progress. Commit or abort the transaction before attaching.",
-			);
+		for (const checkout of this.checkouts.values()) {
+			if (checkout.transaction.isInProgress()) {
+				// Attaching during a transaction is not currently supported.
+				// At least part of of the system is known to not handle this case correctly - commit enrichment - and there may be others.
+				throw new UsageError(
+					"Cannot attach while a transaction is in progress. Commit or abort the transaction before attaching.",
+				);
+			}
 		}
 		super.didAttach();
 	}
@@ -436,31 +485,35 @@ export class SharedTreeKernel
 			SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>["applyStashedOp"]
 		>
 	): void {
-		assert(
-			!this.checkout.transaction.isInProgress(),
-			0x674 /* Unexpected transaction is open while applying stashed ops */,
-		);
+		for (const checkout of this.checkouts.values()) {
+			assert(
+				!checkout.transaction.isInProgress(),
+				0x674 /* Unexpected transaction is open while applying stashed ops */,
+			);
+		}
 		super.applyStashedOp(...args);
 	}
 
 	protected override submitCommit(
+		branchId: BranchId,
 		commit: GraphCommit<SharedTreeChange>,
 		schemaAndPolicy: ClonableSchemaAndPolicy,
 		isResubmit: boolean,
 	): void {
+		const checkout = this.getCheckout(branchId);
 		assert(
-			!this.checkout.transaction.isInProgress(),
+			!checkout.transaction.isInProgress(),
 			0xaa6 /* Cannot submit a commit while a transaction is in progress */,
 		);
 		if (isResubmit) {
-			return super.submitCommit(commit, schemaAndPolicy, isResubmit);
+			return super.submitCommit(branchId, commit, schemaAndPolicy, isResubmit);
 		}
 
 		// Refrain from submitting new commits until they are validated by the checkout.
 		// This is not a strict requirement for correctness in our system, but in the event that there is a bug when applying commits to the checkout
 		// that causes a crash (e.g. in the forest), this will at least prevent this client from sending the problematic commit to any other clients.
-		this.checkout.onCommitValid(commit, () =>
-			super.submitCommit(commit, schemaAndPolicy, isResubmit),
+		checkout.onCommitValid(commit, () =>
+			super.submitCommit(branchId, commit, schemaAndPolicy, isResubmit),
 		);
 	}
 
@@ -561,6 +614,11 @@ export const SharedTreeFormatVersion = {
 	 * Requires \@fluidframework/tree \>= 2.0.0.
 	 */
 	v5: 5,
+
+	/**
+	 * For testing purposes only.
+	 */
+	vSharedBranches: 100,
 } as const;
 
 /**
@@ -577,13 +635,19 @@ export const SharedTreeFormatVersion = {
  */
 export type SharedTreeFormatVersion = typeof SharedTreeFormatVersion;
 
+/**
+ * Configuration options for SharedTree.
+ * @beta @input
+ */
+export type SharedTreeOptionsBeta = ForestOptions;
+
 /**
  * Configuration options for SharedTree.
  * @alpha @input
  */
 export type SharedTreeOptions = Partial<CodecWriteOptions> &
 	Partial<SharedTreeFormatOptions> &
-	ForestOptions;
+	SharedTreeOptionsBeta;
 
 export interface SharedTreeOptionsInternal
 	extends Omit<SharedTreeOptions, "treeEncodeType">,
@@ -661,7 +725,7 @@ export interface ForestType extends ErasedType<"ForestType"> {}
  * A simple implementation with minimal complexity and moderate debuggability, validation and performance.
  * @privateRemarks
  * The "ObjectForest" forest type.
- * @alpha
+ * @beta
  */
 export const ForestTypeReference = toForestType(
 	(breaker: Breakable, schema: TreeStoredSchemaSubscription, idCompressor: IIdCompressor) =>
@@ -675,7 +739,7 @@ export const ForestTypeReference = toForestType(
  * Uses an internal representation optimized for size designed to scale to larger datasets with reduced overhead.
  * @privateRemarks
  * The "ChunkedForest" forest type.
- * @alpha
+ * @beta
  */
 export const ForestTypeOptimized = toForestType(
 	(breaker: Breakable, schema: TreeStoredSchemaSubscription, idCompressor: IIdCompressor) =>
@@ -689,7 +753,7 @@ export const ForestTypeOptimized = toForestType(
  * May be asymptotically slower than {@link ForestTypeReference}, and may perform very badly with larger data sizes.
  * @privateRemarks
  * The "ObjectForest" forest type with expensive asserts for debugging.
- * @alpha
+ * @beta
  */
 export const ForestTypeExpensiveDebug = toForestType(
 	(breaker: Breakable, schema: TreeStoredSchemaSubscription) =>
@@ -719,7 +783,7 @@ export function buildConfiguredForest(
 }
 
 export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
-	jsonValidator: noopValidator,
+	jsonValidator: FormatValidatorNoOp,
 	oldestCompatibleClient: FluidClientVersion.v2_0,
 	forest: ForestTypeReference,
 	treeEncodeType: TreeCompressionStrategy.Compressed,

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,15 +55,16 @@ import {
 	convertField,
 	toUnhydratedSchema,
 	type TreeParsingOptions,
+	type NodeChangedData,
 } from "../simple-tree/index.js";
 import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js";
 import {
 	FluidClientVersion,
-	noopValidator,
 	type ICodecOptions,
 	type CodecWriteOptions,
+	FormatValidatorNoOp,
 } 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,283 @@ 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.
+	 *
+	 * These subscriptions remain active until `unsubscribe` is called: `onInvalidation` may be called multiple times.
+	 * See {@link (TreeAlpha:interface).trackObservationsOnce} for a version which automatically unsubscribes on the first invalidation.
+	 * @privateRemarks
+	 * This version, while more general than {@link (TreeAlpha:interface).trackObservationsOnce}, might be unnecessary.
+	 * Maybe this should be removed and only `trackObservationsOnce` kept.
+	 * Reevaluate this before stabilizing.
+	 */
+	trackObservations<TResult>(
+		onInvalidation: () => void,
+		trackDuring: () => TResult,
+	): ObservationResults<TResult>;
+
+	/**
+	 * {@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.
+	 *
+	 * @example Simple cached value invalidation
+	 * ```typescript
+	 * // Compute and cache this "foo" value, and clear the cache when the fields read in the callback to compute it change.
+	 * cachedFoo ??= TreeAlpha.trackObservationsOnce(
+	 * 	() => {
+	 * 		cachedFoo = undefined;
+	 * 	},
+	 * 	() => nodeA.someChild.bar + nodeB.someChild.baz,
+	 * ).result;
+	 * ```
+	 *
+	 * That is equivalent to doing the following:
+	 * ```typescript
+	 * if (cachedFoo === undefined) {
+	 * 	cachedFoo = nodeA.someChild.bar + nodeB.someChild.baz;
+	 * 	const invalidate = (): void => {
+	 * 		cachedFoo = undefined;
+	 * 		for (const u of unsubscribe) {
+	 * 			u();
+	 * 		}
+	 * 	};
+	 * 	const unsubscribe: (() => void)[] = [
+	 * 		TreeBeta.on(nodeA, "nodeChanged", (data) => {
+	 * 			if (data.changedProperties.has("someChild")) {
+	 * 				invalidate();
+	 * 			}
+	 * 		}),
+	 * 		TreeBeta.on(nodeB, "nodeChanged", (data) => {
+	 * 			if (data.changedProperties.has("someChild")) {
+	 * 				invalidate();
+	 * 			}
+	 * 		}),
+	 * 		TreeBeta.on(nodeA.someChild, "nodeChanged", (data) => {
+	 * 			if (data.changedProperties.has("bar")) {
+	 * 				invalidate();
+	 * 			}
+	 * 		}),
+	 * 		TreeBeta.on(nodeB.someChild, "nodeChanged", (data) => {
+	 * 			if (data.changedProperties.has("baz")) {
+	 * 				invalidate();
+	 * 			}
+	 * 		}),
+	 * 	];
+	 * }
+	 * ```
+	 * @example Cached derived schema property
+	 * ```typescript
+	 * const factory = new SchemaFactory("com.example");
+	 * class Vector extends factory.object("Vector", {
+	 * 	x: SchemaFactory.number,
+	 * 	y: SchemaFactory.number,
+	 * }) {
+	 * 	#length: number | undefined = undefined;
+	 * 	public length(): number {
+	 * 		if (this.#length === undefined) {
+	 * 			const result = TreeAlpha.trackObservationsOnce(
+	 * 				() => {
+	 * 					this.#length = undefined;
+	 * 				},
+	 * 				() => Math.hypot(this.x, this.y),
+	 * 			);
+	 * 			this.#length = result.result;
+	 * 		}
+	 * 		return this.#length;
+	 * 	}
+	 * }
+	 * const vec = new Vector({ x: 3, y: 4 });
+	 * assert.equal(vec.length(), 5);
+	 * vec.x = 0;
+	 * assert.equal(vec.length(), 4);
+	 * ```
+	 */
+	trackObservationsOnce<TResult>(
+		onInvalidation: () => void,
+		trackDuring: () => TResult,
+	): ObservationResults<TResult>;
+}
+
+/**
+ * Results from an operation with tracked observations.
+ * @remarks
+ * Results from {@link (TreeAlpha:interface).trackObservations} or {@link (TreeAlpha:interface).trackObservationsOnce}.
+ * @sealed @alpha
+ */
+export interface ObservationResults<TResult> {
+	/**
+	 * The result of the operation which had its observations tracked.
+	 */
+	readonly result: TResult;
+
+	/**
+	 * Call to unsubscribe from further invalidations.
+	 */
+	readonly 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, 0xc54 /* 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: edits which un-parent a node could error due to being unable to update the event subscription.
+				// For now this is mitigated by only supporting one of tracking (non-undefined) parents or maintaining event subscriptions across edits.
+
+				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,
+): ObservationResults<TResult> {
+	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 +708,30 @@ export interface TreeAlpha {
  * @alpha
  */
 export const TreeAlpha: TreeAlpha = {
+	trackObservations<TResult>(
+		onInvalidation: () => void,
+		trackDuring: () => TResult,
+	): ObservationResults<TResult> {
+		return trackObservations(onInvalidation, trackDuring);
+	},
+
+	trackObservationsOnce<TResult>(
+		onInvalidation: () => void,
+		trackDuring: () => TResult,
+	): ObservationResults<TResult> {
+		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()) {
@@ -523,7 +828,7 @@ export const TreeAlpha: TreeAlpha = {
 	): JsonCompatible<IFluidHandle> {
 		const schema = tryGetSchema(node) ?? fail(0xacf /* invalid input */);
 		const format = fluidVersionToFieldBatchCodecWriteVersion(options.oldestCompatibleClient);
-		const codec = makeFieldBatchCodec({ jsonValidator: noopValidator }, format);
+		const codec = makeFieldBatchCodec({ jsonValidator: FormatValidatorNoOp }, format);
 		const cursor = borrowFieldCursorFromTreeNodeOrValue(node);
 		const batch: FieldBatch = [cursor];
 		// If none provided, create a compressor which will not compress anything.