@fluidframework/tree 2.41.0-338401 → 2.42.0

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 {
@@ -36,10 +36,11 @@ import {
 	numberSchema,
 	stringSchema,
 } from "../leafNodeSchema.js";
-import { isObjectNodeSchema } from "../objectNodeTypes.js";
+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/api/viewSchemaToSimpleSchema.ts

@@ -15,12 +15,10 @@ import type {
 	SimpleObjectNodeSchema,
 	SimpleTreeSchema,
 } from "../simpleSchema.js";
-import { ObjectNodeSchema } from "../objectNodeTypes.js";
 import { NodeKind } from "../core/index.js";
+import { ArrayNodeSchema, MapNodeSchema, ObjectNodeSchema } from "../node-kinds/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
-import { ArrayNodeSchema } from "../arrayNodeTypes.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
-import { MapNodeSchema } from "../mapNodeTypes.js";
 
 /**
  * Converts an {@link ImplicitFieldSchema} to a "simple" schema representation.

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

@@ -9,6 +9,7 @@ import type {
 	FlexTreeHydratedContext,
 } from "../../feature-libraries/index.js";
 import { brand } from "../../util/index.js";
+
 import type { TreeNodeSchema } from "./treeNodeSchema.js";
 import { walkAllowedTypes } from "./walkSchema.js";
 

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

@@ -4,13 +4,14 @@
  */
 
 import type { TreeValue } from "../../core/index.js";
+
+import type { TreeNode } from "./treeNode.js";
 import {
 	type InnerNode,
-	unhydratedFlexTreeNodeToTreeNode,
 	simpleTreeNodeSlot,
 	createTreeNodeFromInner,
+	splitInnerNodeType,
 } from "./treeNodeKernel.js";
-import type { TreeNode } from "./treeNode.js";
 import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
 
 /**
@@ -20,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/treeNode.ts

@@ -6,10 +6,10 @@
 import { assert } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
+import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
 import { NodeKind, type TreeNodeSchemaClass } from "./treeNodeSchema.js";
 // eslint-disable-next-line import/no-deprecated
 import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
-import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
 
 /**
  * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.

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

@@ -3,11 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { assert, Lazy, fail, debugAssert } from "@fluidframework/core-utils/internal";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { createEmitter } from "@fluid-internal/client-utils";
 import type { Listenable, Off } from "@fluidframework/core-interfaces";
-import type { InternalTreeNode, Unhydrated } from "./types.js";
+import { assert, Lazy, fail, debugAssert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
 import {
 	anchorSlot,
 	type AnchorEvents,
@@ -16,6 +16,9 @@ import {
 	type TreeValue,
 	type UpPath,
 } from "../../core/index.js";
+// TODO: decide how to deal with dependencies on flex-tree implementation.
+// eslint-disable-next-line import/no-internal-modules
+import { makeTree } from "../../feature-libraries/flex-tree/lazyNode.js";
 import {
 	assertFlexTreeEntityNotFreed,
 	ContextSlot,
@@ -24,14 +27,14 @@ import {
 	TreeStatus,
 	treeStatusFromAnchorCache,
 	type FlexTreeNode,
+	type HydratedFlexTreeNode,
 } from "../../feature-libraries/index.js";
-import type { TreeNodeSchema } from "./treeNodeSchema.js";
-// TODO: decide how to deal with dependencies on flex-tree implementation.
-// eslint-disable-next-line import/no-internal-modules
-import { makeTree } from "../../feature-libraries/flex-tree/lazyNode.js";
+
 import { SimpleContextSlot, type Context, type HydratedContext } from "./context.js";
-import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
 import type { TreeNode } from "./treeNode.js";
+import type { TreeNodeSchema } from "./treeNodeSchema.js";
+import type { InternalTreeNode, Unhydrated } from "./types.js";
+import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
 
 const treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();
 
@@ -141,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 = {
@@ -158,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");
@@ -176,6 +182,7 @@ export class TreeNodeKernel {
 		} else {
 			// Hydrated case
 			this.#hydrationState = this.createHydratedState(innerNode.anchorNode);
+			this.#hydrationState.innerNode = innerNode;
 		}
 	}
 
@@ -200,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 =
@@ -289,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(
 				() =>
@@ -308,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;
@@ -324,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);
 			}
 		}
 
@@ -340,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;
 	}
 }
@@ -363,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.
@@ -424,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;
 	}
@@ -435,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...

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

@@ -5,6 +5,7 @@
 
 import type { TreeLeafValue } from "../schemaTypes.js";
 import type { SimpleNodeSchemaBase } from "../simpleSchema.js";
+
 import type { TreeNode } from "./treeNode.js";
 import type { InternalTreeNode, Unhydrated } from "./types.js";
 

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

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/core-utils/internal";
 import type { ErasedType } from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils/internal";
 
 import { isFlexTreeNode, type FlexTreeNode } from "../../feature-libraries/index.js";