@fluidframework/tree 2.4.0-299707 → 2.4.0

package/src/packageVersion.ts

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

package/src/shared-tree/schematizingTreeView.ts

@@ -273,7 +273,7 @@ export class SchematizingSimpleTreeView<in out TRootSchema extends ImplicitField
 			this.view = view;
 			assert(
 				!this.checkout.forest.anchors.slots.has(SimpleContextSlot),
-				"extra simple tree context",
+				0xa47 /* extra simple tree context */,
 			);
 			this.checkout.forest.anchors.slots.set(
 				SimpleContextSlot,

package/src/shared-tree/sharedTree.ts

@@ -357,7 +357,7 @@ export function getBranch(view: TreeView<ImplicitFieldSchema>): TreeBranch;
 export function getBranch(treeOrView: ITree | TreeView<ImplicitFieldSchema>): TreeBranch {
 	assert(
 		treeOrView instanceof SharedTree || treeOrView instanceof SchematizingSimpleTreeView,
-		"Unsupported implementation",
+		0xa48 /* Unsupported implementation */,
 	);
 	const checkout: TreeCheckout = treeOrView.checkout;
 	// This cast is safe so long as TreeCheckout supports all the operations on the branch interface.

package/src/shared-tree-core/branch.ts

@@ -253,7 +253,7 @@ export class SharedTreeBranch<
 		this.assertNotDisposed();
 
 		const revisionTag = taggedChange.revision;
-		assert(revisionTag !== undefined, "Revision tag must be provided");
+		assert(revisionTag !== undefined, 0xa49 /* Revision tag must be provided */);
 
 		const newHead = mintCommit(this.head, {
 			revision: revisionTag,

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

@@ -80,15 +80,15 @@ export function customFromCursorInner<TChild, THandle>(
 		case booleanSchema.identifier:
 		case nullSchema.identifier:
 		case stringSchema.identifier:
-			assert(reader.value !== undefined, "out of schema: missing value");
-			assert(!isFluidHandle(reader.value), "out of schema: unexpected FluidHandle");
+			assert(reader.value !== undefined, 0xa50 /* out of schema: missing value */);
+			assert(!isFluidHandle(reader.value), 0xa51 /* out of schema: unexpected FluidHandle */);
 			return reader.value;
 		case handleSchema.identifier:
-			assert(reader.value !== undefined, "out of schema: missing value");
-			assert(isFluidHandle(reader.value), "out of schema: expected FluidHandle");
+			assert(reader.value !== undefined, 0xa52 /* out of schema: missing value */);
+			assert(isFluidHandle(reader.value), 0xa53 /* out of schema: expected FluidHandle */);
 			return options.valueConverter(reader.value);
 		default: {
-			assert(reader.value === undefined, "out of schema: unexpected value");
+			assert(reader.value === undefined, 0xa54 /* out of schema: unexpected value */);
 			if (nodeSchema.kind === NodeKind.Array) {
 				const fields = inCursorField(reader, EmptyKey, () =>
 					mapCursorField(reader, () => childHandler(reader, options, schema)),

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

@@ -3,8 +3,19 @@
  * Licensed under the MIT License.
  */
 
-import type { NodeKind, TreeChangeEvents, TreeNode, WithType } from "../core/index.js";
+import {
+	getKernel,
+	isTreeNode,
+	type NodeKind,
+	type TreeChangeEvents,
+	type TreeNode,
+	type Unhydrated,
+	type WithType,
+} from "../core/index.js";
+import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../schemaTypes.js";
 import { treeNodeApi } from "./treeNodeApi.js";
+import { createFromCursor, cursorFromInsertable } from "./create.js";
+import type { ITreeCursorSynchronous } from "../../core/index.js";
 
 /**
  * Data included for {@link TreeChangeEventsBeta.nodeChanged}.
@@ -82,7 +93,7 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>
  * Extensions to {@link Tree} which are not yet stable.
  * @sealed @beta
  */
-export const TreeBeta = {
+export const TreeBeta: {
 	/**
 	 * Register an event listener on the given node.
 	 * @param node - The node whose events should be subscribed to.
@@ -91,6 +102,26 @@ export const TreeBeta = {
 	 * @returns A callback function which will deregister the event.
 	 * This callback should be called only once.
 	 */
+	on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(
+		node: TNode,
+		eventName: K,
+		listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,
+	): () => void;
+
+	/**
+	 * Clones the persisted data associated with a node. Some key things to note:
+	 * - Local state, such as properties added to customized schema classes, will not be cloned. However, they will be
+	 * initialized to their default state just as if the node had been created via its constructor.
+	 * - Value node types (i.e., numbers, strings, booleans, nulls and Fluid handles) will be returned as is.
+	 * - The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.
+	 *
+	 * @param node - The node to clone.
+	 * @returns A new unhydrated node with the same persisted data as the original node.
+	 */
+	clone<TSchema extends ImplicitFieldSchema>(
+		node: TreeFieldFromImplicitField<TSchema>,
+	): TreeFieldFromImplicitField<TSchema>;
+} = {
 	on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(
 		node: TNode,
 		eventName: K,
@@ -98,4 +129,35 @@ export const TreeBeta = {
 	): () => void {
 		return treeNodeApi.on(node, eventName, listener);
 	},
-} as const;
+	clone<TSchema extends ImplicitFieldSchema>(
+		node: TreeFieldFromImplicitField<TSchema>,
+	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
+		/* The only non-TreeNode cases are {@link Value} (for an empty optional field) which can be returned as is. */
+		if (!isTreeNode(node)) {
+			return node;
+		}
+
+		const kernel = getKernel(node);
+		/*
+		 * For unhydrated nodes, we can create a cursor by calling `cursorFromInsertable` because the node
+		 * hasn't been inserted yet. We can then create a new node from the cursor.
+		 */
+		if (!kernel.isHydrated()) {
+			return createFromCursor(
+				kernel.schema,
+				cursorFromInsertable(kernel.schema, node),
+			) as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+		}
+
+		// For hydrated nodes, create a new cursor in the forest and then create a new node from the cursor.
+		const forest = kernel.context.flexContext.checkout.forest;
+		const cursor = forest.allocateCursor("tree.clone");
+		forest.moveCursorToPath(kernel.anchorNode, cursor);
+		const clonedNode = createFromCursor(
+			kernel.schema,
+			cursor as ITreeCursorSynchronous,
+		) as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+		cursor.free();
+		return clonedNode;
+	},
+};

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

@@ -29,7 +29,7 @@ export function getSimpleContextFromInnerNode(innerNode: InnerNode): Context {
 	}
 
 	const context = innerNode.anchorNode.anchorSet.slots.get(SimpleContextSlot);
-	assert(context !== undefined, "missing simple tree context");
+	assert(context !== undefined, 0xa55 /* missing simple tree context */);
 
 	return context;
 }

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

@@ -29,7 +29,7 @@ import { fail } from "../../util/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 { SimpleContextSlot, type Context } from "./context.js";
+import { SimpleContextSlot, type Context, type HydratedContext } from "./context.js";
 import { UnhydratedFlexTreeNode } from "./unhydratedFlexTree.js";
 
 const treeNodeToKernel = new WeakMap<TreeNode, TreeNodeKernel>();
@@ -267,6 +267,14 @@ export class TreeNodeKernel implements Listenable<KernelEvents> {
 		// TODO: go to the context and remove myself from withAnchors
 	}
 
+	public isHydrated(): this is { anchorNode: AnchorNode; context: HydratedContext } {
+		return isHydrated(this.#hydrationState);
+	}
+
+	public get anchorNode(): AnchorNode | undefined {
+		return isHydrated(this.#hydrationState) ? this.#hydrationState.anchorNode : undefined;
+	}
+
 	/**
 	 * Retrieves the flex node associated with the given target via {@link setInnerNode}.
 	 * @remarks
@@ -421,7 +429,7 @@ export function tryDisposeTreeNode(anchorNode: AnchorNode): void {
 export function getTreeNodeSchemaFromHydratedFlexNode(flexNode: FlexTreeNode): TreeNodeSchema {
 	assert(
 		flexNode.context.isHydrated(),
-		"getTreeNodeSchemaFromHydratedFlexNode only allows hydrated flex tree nodes",
+		0xa56 /* getTreeNodeSchemaFromHydratedFlexNode only allows hydrated flex tree nodes */,
 	);
 
 	const context =

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

@@ -445,7 +445,7 @@ class EagerMapTreeRequiredField
 		// This cannot use ?? since null is a legal value here.
 		assert(
 			super.content !== undefined,
-			"Expected EagerMapTree required field to have a value",
+			0xa57 /* Expected EagerMapTree required field to have a value */,
 		);
 		return super.content;
 	}

package/src/simple-tree/toFlexSchema.ts

@@ -98,7 +98,7 @@ export function getStoredSchema(schema: TreeNodeSchema): TreeNodeStoredSchema {
 	const kind = schema.kind;
 	switch (kind) {
 		case NodeKind.Leaf: {
-			assert(schema instanceof LeafNodeSchema, "invalid kind");
+			assert(schema instanceof LeafNodeSchema, 0xa4a /* invalid kind */);
 			return new LeafNodeStoredSchema(schema.info);
 		}
 		case NodeKind.Map: {
@@ -116,7 +116,7 @@ export function getStoredSchema(schema: TreeNodeSchema): TreeNodeStoredSchema {
 			return new ObjectNodeStoredSchema(fields);
 		}
 		case NodeKind.Object: {
-			assert(isObjectNodeSchema(schema), "invalid kind");
+			assert(isObjectNodeSchema(schema), 0xa4b /* invalid kind */);
 			const fields: Map<FieldKey, TreeFieldStoredSchema> = new Map();
 			for (const field of schema.flexKeyMap.values()) {
 				fields.set(field.storedKey, convertField(field.schema));