@fluidframework/tree 2.41.0 → 2.42.0

package/src/simple-tree/api/treeNodeApi.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob, fail } from "@fluidframework/core-utils/internal";
+import { assert, oob, fail, unreachableCase } from "@fluidframework/core-utils/internal";
 
 import { EmptyKey, rootFieldKey } from "../../core/index.js";
 import { type TreeStatus, isTreeValue, FieldKinds } from "../../feature-libraries/index.js";
@@ -34,17 +34,23 @@ import {
 	type TreeNode,
 	tryGetTreeNodeSchema,
 	getOrCreateNodeFromInnerNode,
-	UnhydratedFlexTreeNode,
 	typeSchemaSymbol,
 	getOrCreateInnerNode,
 } from "../core/index.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
-import { lazilyAllocateIdentifier, isObjectNodeSchema } from "../node-kinds/index.js";
+import { isObjectNodeSchema } from "../node-kinds/index.js";
+import { getTreeNodeForField } from "../getTreeNodeForField.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
- * * @remarks
- * This type should only be used via the public `Tree` export.
+ *
+ * @remarks
+ * With the exception of {@link TreeNodeApi.status}, these functions should not be called with nodes that have
+ * been {@link TreeStatus.Deleted | deleted}.
+ * To verify whether or not a node already has been deleted, use the {@link TreeNodeApi.status} function.
+ *
+ * This type should only be used via the public {@link (Tree:variable)} export.
+ *
  * @privateRemarks
  * Due to limitations of API-Extractor link resolution, this type can't be moved into internalTypes but should be considered just an implementation detail of the `Tree` export.
  *
@@ -75,14 +81,19 @@ export interface TreeNodeApi {
 
 	/**
 	 * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).
+	 *
+	 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.
 	 */
 	parent(node: TreeNode): TreeNode | undefined;
 
 	/**
 	 * The key of the given node under its parent.
+	 *
 	 * @remarks
 	 * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).
 	 * Otherwise, this returns the key of the field that it is under (a `string`).
+	 *
+	 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.
 	 */
 	key(node: TreeNode): string | number;
 
@@ -126,7 +137,7 @@ export interface TreeNodeApi {
 }
 
 /**
- * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
+ * {@inheritDoc TreeNodeApi}
  */
 export const treeNodeApi: TreeNodeApi = {
 	parent(node: TreeNode): TreeNode | undefined {
@@ -303,29 +314,39 @@ export function getIdentifierFromNode(
 			return undefined;
 		case 1: {
 			const key = identifierFieldKeys[0] ?? oob();
-			const identifier = flexNode.tryGetField(key)?.boxedAt(0);
-			if (flexNode instanceof UnhydratedFlexTreeNode) {
-				if (identifier === undefined) {
-					return lazilyAllocateIdentifier(flexNode, key);
-				}
-				return identifier.value as string;
-			}
-			assert(
-				identifier?.context.isHydrated() === true,
-				0xa27 /* Expected hydrated identifier */,
-			);
-			const identifierValue = identifier.value as string;
+			const identifierField = flexNode.tryGetField(key);
+			assert(identifierField !== undefined, 0xbb5 /* missing identifier field */);
+			const identifierValue = getTreeNodeForField(identifierField);
+			assert(typeof identifierValue === "string", 0xbb6 /* identifier not a string */);
 
-			if (compression === "preferCompressed") {
-				const localNodeKey =
-					identifier.context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
-				return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;
-			} else if (compression === "compressed") {
-				const localNodeKey =
-					identifier.context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
-				return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : undefined;
+			const context = flexNode.context;
+			switch (compression) {
+				case "preferCompressed": {
+					if (context.isHydrated()) {
+						const localNodeKey =
+							context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
+						return localNodeKey !== undefined
+							? extractFromOpaque(localNodeKey)
+							: identifierValue;
+					} else {
+						return identifierValue;
+					}
+				}
+				case "compressed": {
+					if (context.isHydrated()) {
+						const localNodeKey =
+							context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
+						return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : undefined;
+					} else {
+						return undefined;
+					}
+				}
+				case "uncompressed": {
+					return identifierValue;
+				}
+				default:
+					unreachableCase(compression);
 			}
-			return identifierValue;
 		}
 		default:
 			throw new UsageError(

package/src/simple-tree/api/verboseTree.ts

@@ -6,6 +6,7 @@
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
 import { assert, fail } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import {
 	aboveRootPlaceholder,
@@ -14,7 +15,6 @@ import {
 	type FieldKey,
 	type ITreeCursor,
 	type ITreeCursorSynchronous,
-	type TreeNodeSchemaIdentifier,
 } from "../../core/index.js";
 import { brand } from "../../util/index.js";
 import type {
@@ -40,6 +40,7 @@ import { isObjectNodeSchema } from "../node-kinds/index.js";
 import {
 	customFromCursor,
 	replaceHandles,
+	unknownTypeError,
 	type CustomTreeNode,
 	type HandleConverter,
 	type SchemalessParseOptions,
@@ -153,12 +154,14 @@ export function applySchemaToParserOptions(
 						return key;
 					},
 					parse: (type, inputKey): FieldKey => {
-						const simpleNodeSchema =
-							context.schema.get(brand(type)) ?? fail(0xb3a /* missing schema */);
+						const simpleNodeSchema = context.schema.get(brand(type)) ?? unknownTypeError(type);
 						if (isObjectNodeSchema(simpleNodeSchema)) {
-							const info =
-								simpleNodeSchema.flexKeyMap.get(inputKey) ??
-								fail(0xb3b /* missing field info */);
+							const info = simpleNodeSchema.flexKeyMap.get(inputKey);
+							if (info === undefined) {
+								throw new UsageError(
+									`Failed to parse VerboseTree due to unexpected key ${JSON.stringify(inputKey)} on type ${JSON.stringify(type)}.`,
+								);
+							}
 							return info.storedKey;
 						}
 						return brand(inputKey);
@@ -203,19 +206,19 @@ function verboseTreeAdapter(options: SchemalessParseOptions): CursorAdapter<Verb
 		type: (node: VerboseTree) => {
 			switch (typeof node) {
 				case "number":
-					return numberSchema.identifier as TreeNodeSchemaIdentifier;
+					return brand(numberSchema.identifier);
 				case "string":
-					return stringSchema.identifier as TreeNodeSchemaIdentifier;
+					return brand(stringSchema.identifier);
 				case "boolean":
-					return booleanSchema.identifier as TreeNodeSchemaIdentifier;
+					return brand(booleanSchema.identifier);
 				default:
 					if (node === null) {
-						return nullSchema.identifier as TreeNodeSchemaIdentifier;
+						return brand(nullSchema.identifier);
 					}
 					if (isFluidHandle(node)) {
-						return handleSchema.identifier as TreeNodeSchemaIdentifier;
+						return brand(handleSchema.identifier);
 					}
-					return node.type as TreeNodeSchemaIdentifier;
+					return brand(node.type);
 			}
 		},
 		keysFromNode: (node: VerboseTree): readonly FieldKey[] => {

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

@@ -8,9 +8,9 @@ import type { TreeValue } from "../../core/index.js";
 import type { TreeNode } from "./treeNode.js";
 import {
 	type InnerNode,
-	unhydratedFlexTreeNodeToTreeNode,
 	simpleTreeNodeSlot,
 	createTreeNodeFromInner,
+	splitInnerNodeType,
 } from "./treeNodeKernel.js";
 import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
 
@@ -21,9 +21,11 @@ import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
  * This supports both hydrated and unhydrated nodes.
  */
 export function getOrCreateNodeFromInnerNode(flexNode: InnerNode): TreeNode | TreeValue {
+	splitInnerNodeType(flexNode);
+
 	const cached =
 		flexNode instanceof UnhydratedFlexTreeNode
-			? unhydratedFlexTreeNodeToTreeNode.get(flexNode)
+			? flexNode.treeNode
 			: flexNode.anchorNode.slots.get(simpleTreeNodeSlot);
 
 	if (cached !== undefined) {

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

@@ -10,7 +10,6 @@ export {
 	tryGetTreeNodeSchema,
 	type InnerNode,
 	tryDisposeTreeNode,
-	unhydratedFlexTreeNodeToTreeNode,
 	getOrCreateInnerNode,
 	treeNodeFromAnchor,
 	getSimpleNodeSchemaFromInnerNode,
@@ -38,7 +37,7 @@ export { Context, HydratedContext, SimpleContextSlot } from "./context.js";
 export { getOrCreateNodeFromInnerNode } from "./getOrCreateNode.js";
 export {
 	UnhydratedFlexTreeNode,
-	UnhydratedTreeSequenceField,
-	tryUnhydratedFlexTreeNode,
+	UnhydratedSequenceField,
 	UnhydratedContext,
+	createField,
 } from "./unhydratedFlexTree.js";

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

@@ -27,6 +27,7 @@ import {
 	TreeStatus,
 	treeStatusFromAnchorCache,
 	type FlexTreeNode,
+	type HydratedFlexTreeNode,
 } from "../../feature-libraries/index.js";
 
 import { SimpleContextSlot, type Context, type HydratedContext } from "./context.js";
@@ -143,12 +144,15 @@ export class TreeNodeKernel {
 		innerNode: InnerNode,
 		private readonly initialContext: Context,
 	) {
+		splitInnerNodeType(innerNode);
+
 		assert(!treeNodeToKernel.has(node), 0xa1a /* only one kernel per node can be made */);
 		treeNodeToKernel.set(node, this);
 
 		if (innerNode instanceof UnhydratedFlexTreeNode) {
 			// Unhydrated case
-			unhydratedFlexTreeNodeToTreeNodeInternal.set(innerNode, node);
+			debugAssert(() => innerNode.treeNode === undefined);
+			innerNode.treeNode = node;
 			// Register for change events from the unhydrated flex node.
 			// These will be fired if the unhydrated node is edited, and will also be forwarded later to the hydrated node.
 			this.#hydrationState = {
@@ -160,7 +164,7 @@ export class TreeNodeKernel {
 
 					let unhydratedNode: UnhydratedFlexTreeNode | undefined = innerNode;
 					while (unhydratedNode !== undefined) {
-						const treeNode = unhydratedFlexTreeNodeToTreeNodeInternal.get(unhydratedNode);
+						const treeNode = unhydratedNode.treeNode;
 						if (treeNode !== undefined) {
 							const kernel = getKernel(treeNode);
 							kernel.#unhydratedEvents.value.emit("subtreeChangedAfterBatch");
@@ -178,6 +182,7 @@ export class TreeNodeKernel {
 		} else {
 			// Hydrated case
 			this.#hydrationState = this.createHydratedState(innerNode.anchorNode);
+			this.#hydrationState.innerNode = innerNode;
 		}
 	}
 
@@ -202,7 +207,6 @@ export class TreeNodeKernel {
 	public hydrate(anchors: AnchorSet, path: UpPath): void {
 		assert(!this.disposed, 0xa2a /* cannot hydrate a disposed node */);
 		assert(!isHydrated(this.#hydrationState), 0xa2b /* hydration should only happen once */);
-		unhydratedFlexTreeNodeToTreeNodeInternal.delete(this.#hydrationState.innerNode);
 
 		const anchor = anchors.track(path);
 		const anchorNode =
@@ -291,16 +295,16 @@ export class TreeNodeKernel {
 	}
 
 	/**
-	 * Retrieves the flex node associated with the given target via {@link setInnerNode}.
+	 * Retrieves the flex node associated with the given target.
 	 * @remarks
 	 * For {@link Unhydrated} nodes, this returns the MapTreeNode.
 	 *
 	 * For hydrated nodes it returns a FlexTreeNode backed by the forest.
 	 * Note that for "marinated" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.
 	 *
-	 * If `allowDeleted` is false, this will throw a UsageError if the node is deleted.
+	 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been deleted.
 	 */
-	public getOrCreateInnerNode(allowDeleted = false): InnerNode {
+	public getOrCreateInnerNode(): InnerNode {
 		if (!isHydrated(this.#hydrationState)) {
 			debugAssert(
 				() =>
@@ -310,6 +314,10 @@ export class TreeNodeKernel {
 			return this.#hydrationState.innerNode; // Unhydrated case
 		}
 
+		if (this.disposed) {
+			throw new UsageError("Cannot access a deleted node.");
+		}
+
 		if (this.#hydrationState.innerNode === undefined) {
 			// Marinated case -> cooked
 			const anchorNode = this.#hydrationState.anchorNode;
@@ -326,15 +334,7 @@ export class TreeNodeKernel {
 				context.checkout.forest.moveCursorToPath(anchorNode, cursor);
 				this.#hydrationState.innerNode = makeTree(context, cursor);
 				cursor.free();
-				if (!allowDeleted) {
-					assertFlexTreeEntityNotFreed(this.#hydrationState.innerNode);
-				}
-			}
-		}
-
-		if (!allowDeleted) {
-			if (this.#hydrationState.innerNode.context.isDisposed()) {
-				throw new UsageError("Cannot access a Deleted node.");
+				assertFlexTreeEntityNotFreed(this.#hydrationState.innerNode);
 			}
 		}
 
@@ -342,20 +342,12 @@ export class TreeNodeKernel {
 	}
 
 	/**
-	 * Retrieves the InnerNode associated with the given target via {@link setInnerNode}, if any.
-	 * @remarks
-	 * If `target` is an unhydrated node, returns its UnhydratedFlexTreeNode.
-	 * If `target` is a cooked node (or marinated but a FlexTreeNode exists) returns the FlexTreeNode.
-	 * If the target is a marinated node with no FlexTreeNode for its anchor, returns undefined.
+	 * Retrieves the {@link UnhydratedFlexTreeNode} if unhydrated. otherwise undefined.
 	 */
-	public tryGetInnerNode(): InnerNode | undefined {
+	public getInnerNodeIfUnhydrated(): UnhydratedFlexTreeNode | undefined {
 		if (isHydrated(this.#hydrationState)) {
-			return (
-				this.#hydrationState.innerNode ??
-				this.#hydrationState.anchorNode.slots.get(flexTreeSlot)
-			);
+			return undefined;
 		}
-
 		return this.#hydrationState.innerNode;
 	}
 }
@@ -365,34 +357,24 @@ const kernelEvents = ["childrenChangedAfterBatch", "subtreeChangedAfterBatch"] a
 type KernelEvents = Pick<AnchorEvents, (typeof kernelEvents)[number]>;
 
 /**
- * For "cooked" nodes this is a FlexTreeNode thats a projection of forest content.
- * For {@link Unhydrated} nodes this is a MapTreeNode.
- * For "marinated" nodes, some code (ex: getOrCreateInnerNode) returns the FlexTreeNode thats a projection of forest content, and some code (ex: tryGetInnerNode) returns undefined.
- *
- * @remarks
- * Currently MapTreeNode extends FlexTreeNode, and most code which can work with either just uses FlexTreeNode.
- * TODO: Code should be migrating toward using this type to distinguish to two use-cases.
+ * For "cooked" nodes this is a HydratedFlexTreeNode thats a projection of forest content.
+ * For {@link Unhydrated} nodes this is a UnhydratedFlexTreeNode.
  *
- * TODO: The inconsistent handling of "marinated" cases should be cleaned up.
- * Maybe getOrCreateInnerNode should cook marinated nodes so they have a proper InnerNode?
+ * For "marinated" nodes, some code (ex: getOrCreateInnerNode) returns the FlexTreeNode thats a projection of forest content, and some code (ex: tryGetInnerNode) returns undefined.
  */
-export type InnerNode = FlexTreeNode | UnhydratedFlexTreeNode;
+export type InnerNode = FlexTreeNode;
 
 /**
- * Associates a given {@link UnhydratedFlexTreeNode} with a {@link TreeNode}.
- */
-const unhydratedFlexTreeNodeToTreeNodeInternal = new WeakMap<
-	UnhydratedFlexTreeNode,
-	TreeNode
->();
-/**
- * Retrieves the {@link TreeNode} associated with the given {@link UnhydratedFlexTreeNode} if any.
+ * Narrows innerNode to either {@link UnhydratedFlexTreeNode} or {@link HydratedFlexTreeNode}.
  */
-export const unhydratedFlexTreeNodeToTreeNode =
-	unhydratedFlexTreeNodeToTreeNodeInternal as Pick<
-		WeakMap<UnhydratedFlexTreeNode, TreeNode>,
-		"get"
-	>;
+export function splitInnerNodeType(
+	innerNode: InnerNode,
+): asserts innerNode is UnhydratedFlexTreeNode | HydratedFlexTreeNode {
+	assert(
+		innerNode instanceof UnhydratedFlexTreeNode || innerNode.isHydrated(),
+		"Invalid inner node type",
+	);
+}
 
 /**
  * An anchor slot which associates an anchor with its corresponding {@link TreeNode}, if there is one.
@@ -426,6 +408,7 @@ export function getSimpleNodeSchemaFromInnerNode(innerNode: InnerNode): TreeNode
  * Gets the {@link Context} for the {@link InnerNode}.
  */
 export function getSimpleContextFromInnerNode(innerNode: InnerNode): Context {
+	splitInnerNodeType(innerNode);
 	if (innerNode instanceof UnhydratedFlexTreeNode) {
 		return innerNode.simpleContext;
 	}
@@ -437,24 +420,24 @@ export function getSimpleContextFromInnerNode(innerNode: InnerNode): Context {
 }
 
 /**
- * Retrieves the flex node associated with the given target via {@link setInnerNode}.
+ * Retrieves the flex node associated with the given target.
  * @remarks
  * For {@link Unhydrated} nodes, this returns the MapTreeNode.
  *
  * For hydrated nodes it returns a FlexTreeNode backed by the forest.
  * Note that for "marinated" nodes, this FlexTreeNode exists and returns it: it does not return the MapTreeNode which is the current InnerNode.
  *
- * If `allowDeleted` is false, this will throw a UsageError if the node is deleted.
+ * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been deleted.
  */
-export function getOrCreateInnerNode(treeNode: TreeNode, allowDeleted = false): InnerNode {
+export function getOrCreateInnerNode(treeNode: TreeNode): InnerNode {
 	const kernel = getKernel(treeNode);
-	return kernel.getOrCreateInnerNode(allowDeleted);
+	return kernel.getOrCreateInnerNode();
 }
 
 /**
  * Gets a flex node from an anchor node
  */
-function flexNodeFromAnchor(anchorNode: AnchorNode): FlexTreeNode {
+function flexNodeFromAnchor(anchorNode: AnchorNode): HydratedFlexTreeNode {
 	const flexNode = anchorNode.slots.get(flexTreeSlot);
 	if (flexNode !== undefined) {
 		return flexNode; // If it does have a flex node, return it...