@fluidframework/tree 2.90.0-378676 → 2.90.0

package/src/shared-tree/sharedTreeEditBuilder.ts

@@ -4,22 +4,14 @@
  */
 
 import type {
-	ChangeAtomId,
 	ChangeFamilyEditor,
-	EditorOptions,
 	RevisionTag,
 	TaggedChange,
-	TreeChunk,
 	TreeStoredSchema,
 } from "../core/index.js";
 import {
-	DefaultIdBasedDataEditor,
-	LocationBasedDataEditor,
-	type DetachedRootIds,
-	type DetachedRootLocation,
-	type DetachedRootsLocation,
-	type Locator,
-	type DataEditor,
+	DefaultEditBuilder,
+	type IDefaultEditBuilder,
 	type ModularChangeFamily,
 } from "../feature-libraries/index.js";
 
@@ -41,16 +33,7 @@ export interface ISchemaEditor {
 /**
  * SharedTree editor for transactional tree data and schema changes.
  */
-export interface IIdBasedSharedTreeEditor
-	extends DataEditor<TreeChunk, ChangeAtomId, DetachedRootIds> {
-	/**
-	 * Editor for schema changes.
-	 */
-	schema: ISchemaEditor;
-}
-
-export interface ILocationBasedSharedTreeEditor
-	extends DataEditor<TreeChunk, DetachedRootLocation, DetachedRootsLocation> {
+export interface ISharedTreeEditor extends IDefaultEditBuilder {
 	/**
 	 * Editor for schema changes.
 	 */
@@ -58,12 +41,12 @@ export interface ILocationBasedSharedTreeEditor
 }
 
 /**
- * Implementation of {@link DataEditor} based on the default set of supported field kinds.
+ * Implementation of {@link IDefaultEditBuilder} based on the default set of supported field kinds.
  * @sealed
  */
-export class IdBasedSharedTreeEditBuilder
-	extends DefaultIdBasedDataEditor
-	implements ChangeFamilyEditor, IIdBasedSharedTreeEditor
+export class SharedTreeEditBuilder
+	extends DefaultEditBuilder
+	implements ChangeFamilyEditor, ISharedTreeEditor
 {
 	public readonly schema: ISchemaEditor;
 
@@ -71,7 +54,6 @@ export class IdBasedSharedTreeEditBuilder
 		modularChangeFamily: ModularChangeFamily,
 		mintRevisionTag: () => RevisionTag,
 		private readonly changeReceiver: (change: TaggedChange<SharedTreeChange>) => void,
-		options?: EditorOptions,
 	) {
 		super(
 			modularChangeFamily,
@@ -81,13 +63,12 @@ export class IdBasedSharedTreeEditBuilder
 					...taggedChange,
 					change: { changes: [{ type: "data", innerChange: taggedChange.change }] },
 				}),
-			options,
 			modularChangeFamily.codecOptions,
 		);
 
 		this.schema = {
 			setStoredSchema: (oldSchema, newSchema) => {
-				changeReceiver({
+				this.changeReceiver({
 					revision: mintRevisionTag(),
 					change: {
 						changes: [
@@ -105,19 +86,3 @@ export class IdBasedSharedTreeEditBuilder
 		};
 	}
 }
-
-export class LocationBasedSharedTreeEditBuilder
-	extends LocationBasedDataEditor
-	implements ILocationBasedSharedTreeEditor
-{
-	public readonly schema: ISchemaEditor;
-
-	public constructor(
-		idBasedEditor: IIdBasedSharedTreeEditor,
-		locator: Locator,
-		options: EditorOptions,
-	) {
-		super(idBasedEditor, locator, options);
-		this.schema = idBasedEditor.schema;
-	}
-}

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>(