@fluidframework/tree 2.83.0 → 2.90.0

package/src/index.ts

@@ -12,6 +12,8 @@ export {
 	type LocalChangeMetadata,
 	type RemoteChangeMetadata,
 	type ChangeMetadata,
+	type LabelTree,
+	type TransactionLabels,
 	type RevertibleFactory,
 	type RevertibleAlphaFactory,
 	type RevertibleAlpha,
@@ -53,7 +55,6 @@ export {
 	TreeStatus,
 	TreeCompressionStrategy,
 	type TreeIndex,
-	type TreeIndexKey,
 	type TreeIndexNodes,
 	type IncrementalEncodingPolicy,
 } from "./feature-libraries/index.js";
@@ -160,13 +161,13 @@ export {
 	type ValidateRecursiveSchema,
 	type FixRecursiveArraySchema,
 	// Index APIs
-	type SimpleTreeIndex,
 	type IdentifierIndex,
-	createSimpleTreeIndex,
+	createTreeIndex,
 	createIdentifierIndex,
 	type DirtyTreeStatus,
 	trackDirtyNodes,
 	type DirtyTreeMap,
+	type TreeIndexKey,
 	// experimental @alpha APIs:
 	adaptEnum,
 	enumFromStrings,
@@ -305,6 +306,8 @@ export {
 	type SnapshotSchemaCompatibilityOptions,
 	type ArrayPlaceAnchor,
 	createArrayInsertionAnchor,
+	type WithValue,
+	type TreeContextAlpha,
 } from "./simple-tree/index.js";
 export {
 	SharedTree,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/tree";
-export const pkgVersion = "2.83.0";
+export const pkgVersion = "2.90.0";

package/src/shared-tree/independentView.ts

@@ -23,7 +23,7 @@ import {
 } from "../core/index.js";
 import {
 	createNodeIdentifierManager,
-	makeFieldBatchCodec,
+	fieldBatchCodecBuilder,
 	makeSchemaCodec,
 	type FieldBatchEncodingContext,
 	defaultSchemaPolicy,
@@ -236,14 +236,14 @@ export function createIndependentTreeAlpha<const TSchema extends ImplicitFieldSc
 	});
 
 	if (options?.content !== undefined) {
-		// Any version can be passed down to `makeSchemaCodec` and `makeFieldBatchCodec` here.
+		// Any version can be passed down to `makeSchemaCodec` and `fieldBatchCodecBuilder.build` here.
 		// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not `minVersionForCollab`.
 		const writeOptions: CodecWriteOptions = {
 			...options,
 			minVersionForCollab: FluidClientVersion.v2_0,
 		};
 		const schemaCodec = makeSchemaCodec(writeOptions, SchemaFormatVersion.v1);
-		const fieldBatchCodec = makeFieldBatchCodec(writeOptions);
+		const fieldBatchCodec = fieldBatchCodecBuilder.build(writeOptions);
 		const newSchema = schemaCodec.decode(options.content.schema as Format);
 
 		const context: FieldBatchEncodingContext = {

package/src/shared-tree/schematizingTreeView.ts

@@ -166,6 +166,10 @@ export class SchematizingSimpleTreeView<
 		);
 	}
 
+	public isBranch(): this is TreeBranchAlpha {
+		return true;
+	}
+
 	public applyChange(change: JsonCompatibleReadOnly): void {
 		this.checkout.applySerializedChange(change);
 	}
@@ -328,8 +332,13 @@ export class SchematizingSimpleTreeView<
 	private mountTransaction(params: RunTransactionParams | undefined, isAsync: boolean): void {
 		this.ensureUndisposed();
 		const { checkout } = this;
-
-		checkout.transaction.start(isAsync);
+		if (isAsync && checkout.transaction.size > 0) {
+			throw new UsageError(
+				"An asynchronous transaction cannot be started while another transaction is already in progress.",
+			);
+		}
+		checkout.pushLabelFrame(params?.label);
+		checkout.transaction.start();
 
 		// Validate preconditions before running the transaction callback.
 		addConstraintsToTransaction(
@@ -344,7 +353,7 @@ export class SchematizingSimpleTreeView<
 			| TransactionCallbackStatus<TSuccessValue, TFailureValue>
 			| VoidTransactionCallbackStatus
 			| void,
-		params?: RunTransactionParams,
+		params: RunTransactionParams | undefined,
 	): TransactionResultExt<TSuccessValue, TFailureValue> | TransactionResult {
 		this.ensureUndisposed();
 		const { checkout } = this;
@@ -354,6 +363,7 @@ export class SchematizingSimpleTreeView<
 		)?.value;
 
 		if (rollback === true) {
+			checkout.popLabelFrame(true);
 			checkout.transaction.abort();
 			return value === undefined
 				? { success: false }
@@ -367,6 +377,7 @@ export class SchematizingSimpleTreeView<
 			transactionCallbackStatus?.preconditionsOnRevert,
 		);
 
+		checkout.popLabelFrame(false);
 		checkout.runWithTransactionLabel(() => {
 			checkout.transaction.commit();
 		}, params?.label);
@@ -611,17 +622,11 @@ export function addConstraintsToTransaction(
 	constraints: readonly TransactionConstraintAlpha[] = [],
 ): void {
 	for (const constraint of constraints) {
+		assertValidConstraint(constraint, constraintsOnRevert);
 		const constraintType = constraint.type;
 		switch (constraintType) {
 			case "nodeInDocument": {
 				const node = getInnerNode(constraint.node);
-				const nodeStatus = getKernel(constraint.node).getStatus();
-				if (nodeStatus !== TreeStatus.InDocument) {
-					const revertText = constraintsOnRevert ? " on revert" : "";
-					throw new UsageError(
-						`Attempted to add a "nodeInDocument" constraint${revertText}, but the node is not currently in the document. Node status: ${nodeStatus}`,
-					);
-				}
 				assert(node.isHydrated(), 0xbc2 /* In document node must be hydrated. */);
 				if (constraintsOnRevert) {
 					checkout.editor.addNodeExistsConstraintOnRevert(node.anchorNode);
@@ -644,3 +649,31 @@ export function addConstraintsToTransaction(
 		}
 	}
 }
+
+/**
+ * Throws if the given {@link TransactionConstraintAlpha | transaction constraint} is not currently satisfied.
+ */
+export function assertValidConstraint(
+	constraint: TransactionConstraintAlpha,
+	onRevert: boolean,
+): void {
+	switch (constraint.type) {
+		case "nodeInDocument": {
+			const nodeStatus = getKernel(constraint.node).getStatus();
+			if (nodeStatus !== TreeStatus.InDocument) {
+				const revertText = onRevert ? " on revert" : "";
+				throw new UsageError(
+					`Attempted to add a "nodeInDocument" constraint${revertText}, but the node is not currently in the document. Node status: ${nodeStatus}`,
+				);
+			}
+			break;
+		}
+		case "noChange": {
+			// This constraint is always satisfied at the time of checking, since it just requires that no changes have been made since the transaction callback returned.
+			break;
+		}
+		default: {
+			unreachableCase(constraint);
+		}
+	}
+}

package/src/shared-tree/sharedTree.ts

@@ -56,10 +56,9 @@ import {
 	buildForest,
 	defaultIncrementalEncodingPolicy,
 	defaultSchemaPolicy,
-	getCodecTreeForFieldBatchFormat,
-	getCodecTreeForForestFormat,
+	fieldBatchCodecBuilder,
+	forestCodecBuilder,
 	jsonableTreeFromFieldCursor,
-	makeFieldBatchCodec,
 	makeMitigatedChangeFamily,
 	makeSchemaCodec,
 	makeTreeChunker,
@@ -241,7 +240,7 @@ export class SharedTreeKernel
 			schemaCodec,
 			options.minVersionForCollab,
 		);
-		const fieldBatchCodec = makeFieldBatchCodec(options);
+		const fieldBatchCodec = fieldBatchCodecBuilder.build(options);
 
 		const encoderContext = {
 			schema: {
@@ -255,7 +254,6 @@ export class SharedTreeKernel
 		const forestSummarizer = new ForestSummarizer(
 			forest,
 			revisionTagCodec,
-			fieldBatchCodec,
 			encoderContext,
 			options,
 			idCompressor,
@@ -420,7 +418,7 @@ export class SharedTreeKernel
 
 	public override didAttach(): void {
 		for (const checkout of this.checkouts.values()) {
-			if (checkout.transaction.isInProgress()) {
+			if (checkout.transaction.size > 0) {
 				// 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(
@@ -438,7 +436,7 @@ export class SharedTreeKernel
 	): void {
 		for (const checkout of this.checkouts.values()) {
 			assert(
-				!checkout.transaction.isInProgress(),
+				checkout.transaction.size === 0,
 				0x674 /* Unexpected transaction is open while applying stashed ops */,
 			);
 		}
@@ -453,7 +451,7 @@ export class SharedTreeKernel
 	): void {
 		const checkout = this.getCheckout(branchId);
 		assert(
-			!checkout.transaction.isInProgress(),
+			checkout.transaction.size === 0,
 			0xaa6 /* Cannot submit a commit while a transaction is in progress */,
 		);
 		if (isResubmit) {
@@ -596,12 +594,12 @@ export function getCodecTreeForSharedTreeFormat(
 	clientVersion: MinimumVersionForCollab,
 ): CodecTree {
 	const children: CodecTree[] = [];
-	children.push(getCodecTreeForForestFormat(clientVersion));
+	children.push(forestCodecBuilder.getCodecTree(clientVersion));
 	children.push(schemaCodecBuilder.getCodecTree(clientVersion));
 	children.push(detachedFieldIndexCodecBuilder.getCodecTree(clientVersion));
 	children.push(getCodecTreeForEditManagerFormat(clientVersion));
 	children.push(getCodecTreeForMessageFormat(clientVersion));
-	children.push(getCodecTreeForFieldBatchFormat(clientVersion));
+	children.push(fieldBatchCodecBuilder.getCodecTree(clientVersion));
 	return {
 		name: "SharedTree",
 		version: undefined, // SharedTree does not have a version of its own.

package/src/shared-tree/tree.ts

@@ -467,7 +467,7 @@ function runTransactionInCheckout<TResult>(
 	transaction: () => TResult | typeof rollback,
 	preconditions: readonly TransactionConstraint[],
 ): TResult | typeof rollback {
-	checkout.transaction.start(false);
+	checkout.transaction.start();
 	addConstraintsToTransaction(checkout, false, preconditions);
 
 	let result: ReturnType<typeof transaction>;

package/src/shared-tree/treeAlpha.ts

@@ -26,7 +26,7 @@ import {
 	cursorForMapTreeField,
 	defaultSchemaPolicy,
 	isTreeValue,
-	makeFieldBatchCodec,
+	fieldBatchCodecBuilder,
 	mapTreeFromCursor,
 	TreeCompressionStrategy,
 	type FieldBatch,
@@ -80,6 +80,7 @@ import {
 	exportConcise,
 	borrowCursorFromTreeNodeOrValue,
 	contentSchemaSymbol,
+	type TreeContextAlpha,
 	type TreeNodeSchema,
 	getUnhydratedContext,
 	type TreeBranchAlpha,
@@ -88,6 +89,7 @@ import { brand, extractFromOpaque, type JsonCompatible } from "../util/index.js"
 
 import { independentInitializedView, type ViewContent } from "./independentView.js";
 import { SchematizingSimpleTreeView, ViewSlot } from "./schematizingTreeView.js";
+import { UnhydratedTreeContext } from "./unhydratedTreeContext.js";
 
 const identifier: TreeIdentifierUtils = (node: TreeNode): string | undefined => {
 	return getIdentifierFromNode(node, "uncompressed");
@@ -237,9 +239,17 @@ export interface TreeAlpha {
 	 *
 	 * This does not fork a new branch, but rather retrieves the _existing_ branch for the node.
 	 * To create a new branch, use e.g. {@link TreeBranch.fork | `myBranch.fork()`}.
+	 *
+	 * @deprecated To obtain a {@link TreeBranchAlpha | branch }, use `TreeAlpha.context(node)` to obtain a {@link TreeContextAlpha | context} and then check {@link TreeContextAlpha.isBranch | isBranch()}.
 	 */
 	branch(node: TreeNode): TreeBranchAlpha | undefined;
 
+	/**
+	 * Retrieve the {@link TreeContextAlpha | context} for the given node.
+	 * @param node - The node to query
+	 */
+	context(node: TreeNode): TreeContextAlpha;
+
 	/**
 	 * Construct tree content that is compatible with the field defined by the provided `schema`.
 	 * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
@@ -587,9 +597,10 @@ export interface ObservationResults<TResult> {
 class NodeSubscription {
 	/**
 	 * If undefined, subscribes to all keys.
+	 * If "deep", subscribes to all changes in the subtree.
 	 * Otherwise only subscribes to the keys in the set.
 	 */
-	private keys: Set<FieldKey> | undefined;
+	private keys: Set<FieldKey> | undefined | "deep";
 	private readonly unsubscribe: () => void;
 	private constructor(
 		private readonly onInvalidation: () => void,
@@ -600,6 +611,9 @@ class NodeSubscription {
 		assert(node instanceof TreeNode, 0xc54 /* Unexpected leaf value */);
 
 		const handler = (data: NodeChangedData): void => {
+			if (this.keys === "deep") {
+				return;
+			}
 			if (this.keys === undefined || data.changedProperties === undefined) {
 				this.onInvalidation();
 			} else {
@@ -620,7 +634,18 @@ class NodeSubscription {
 				}
 			}
 		};
-		this.unsubscribe = TreeBeta.on(node, "nodeChanged", handler);
+
+		// TODO:Performance: It would be better to defer subscribing to events so that this can subscribe to the correct one instead of both.
+		const shallow = TreeBeta.on(node, "nodeChanged", handler);
+		const deep = TreeBeta.on(node, "treeChanged", () => {
+			if (this.keys === "deep") {
+				this.onInvalidation();
+			}
+		});
+		this.unsubscribe = () => {
+			shallow();
+			deep();
+		};
 	}
 
 	/**
@@ -632,18 +657,39 @@ class NodeSubscription {
 	): { observer: Observer; unsubscribe: () => void } {
 		const subscriptions = new Map<FlexTreeNode, NodeSubscription>();
 		const observer: Observer = {
+			observeNodeDeep(flexNode: FlexTreeNode): void {
+				if (flexNode.value !== undefined) {
+					// Leaf value: the set of fields (and thus their content) is always empty, and cannot change, so no need to subscribe.
+					return;
+				}
+
+				const subscription = subscriptions.get(flexNode);
+				if (subscription === undefined) {
+					const newSubscription = new NodeSubscription(invalidate, flexNode);
+					newSubscription.keys = "deep";
+					subscriptions.set(flexNode, newSubscription);
+				} else {
+					// Already subscribed to this node.
+					subscription.keys = "deep"; // Now subscribed to subtree changes (deep observation).
+				}
+			},
 			observeNodeFields(flexNode: FlexTreeNode): void {
 				if (flexNode.value !== undefined) {
-					// Leaf value, nothing to observe.
+					// Leaf value: the set of fields is always empty, and cannot change, so no need to subscribe.
 					return;
 				}
+
+				// Subscribe to any change to any field to ensure that any change which empties or fills a field will invalidate.
+				// This could be more targeted by detecting specifically edits which change the emptiness of fields if desired.
 				const subscription = subscriptions.get(flexNode);
 				if (subscription === undefined) {
 					const newSubscription = new NodeSubscription(invalidate, flexNode);
 					subscriptions.set(flexNode, newSubscription);
 				} else {
 					// Already subscribed to this node.
-					subscription.keys = undefined; // Now subscribed to all keys.
+					if (subscription.keys instanceof Set) {
+						subscription.keys = undefined; // Now subscribed to all keys.
+					}
 				}
 			},
 			observeNodeField(flexNode: FlexTreeNode, key: FieldKey): void {
@@ -657,10 +703,12 @@ class NodeSubscription {
 					newSubscription.keys = new Set([key]);
 					subscriptions.set(flexNode, newSubscription);
 				} else {
-					// 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);
+					// Already subscribed to this node: if not subscribed to all keys or "deep", subscribe to this one.
+					if (subscription.keys instanceof Set) {
+						// 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);
+					}
 				}
 			},
 			observeParentOf(node: FlexTreeNode): void {
@@ -763,6 +811,10 @@ export const TreeAlpha: TreeAlpha = {
 		return result;
 	},
 
+	context(node: TreeNode): TreeContextAlpha {
+		return this.branch(node) ?? UnhydratedTreeContext.instance;
+	},
+
 	branch(node: TreeNode): TreeBranchAlpha | undefined {
 		const kernel = getKernel(node);
 		if (!kernel.isHydrated()) {
@@ -852,7 +904,7 @@ export const TreeAlpha: TreeAlpha = {
 		options: { idCompressor?: IIdCompressor } & Pick<CodecWriteOptions, "minVersionForCollab">,
 	): JsonCompatible<IFluidHandle> {
 		const schema = tryGetSchema(node) ?? fail(0xacf /* invalid input */);
-		const codec = makeFieldBatchCodec({
+		const codec = fieldBatchCodecBuilder.build({
 			jsonValidator: FormatValidatorNoOp,
 			minVersionForCollab: options.minVersionForCollab,
 		});
@@ -874,7 +926,8 @@ export const TreeAlpha: TreeAlpha = {
 			schema: { schema: storedSchema, policy: defaultSchemaPolicy },
 		};
 		const result = codec.encode(batch, context);
-		return result;
+		// TODO: codecs should better track which ones can contain handles, and which cannot. When done properly, casts like this can be removed.
+		return result as JsonCompatible<IFluidHandle>;
 	},
 
 	importCompressed<const TSchema extends ImplicitFieldSchema>(