@fluidframework/tree 2.31.0 → 2.32.0

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

@@ -20,6 +20,7 @@ import type {
 } from "../../shared-tree/index.js";
 
 import {
+	type FieldSchemaAlpha,
 	type ImplicitFieldSchema,
 	type InsertableField,
 	type InsertableTreeFieldFromImplicitField,
@@ -29,6 +30,7 @@ import {
 	type UnsafeUnknownSchema,
 	FieldKind,
 	markSchemaMostDerived,
+	normalizeFieldSchema,
 } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import { toStoredSchema } from "../toStoredSchema.js";
@@ -38,7 +40,7 @@ import { getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
 import type { VerboseTree } from "./verboseTree.js";
-import type { SimpleTreeSchema } from "../simpleSchema.js";
+import type { SimpleNodeSchema, SimpleTreeSchema } from "../simpleSchema.js";
 import type {
 	RunTransactionParams,
 	TransactionCallbackStatus,
@@ -106,9 +108,7 @@ export interface ITree extends ViewableTree, IFluidLoadable {}
 
 /**
  * {@link ITree} extended with some alpha APIs.
- * @privateRemarks
- * TODO: Promote this to alpha.
- * @internal
+ * @sealed @alpha
  */
 export interface ITreeAlpha extends ITree {
 	/**
@@ -309,6 +309,53 @@ export class TreeViewConfiguration<
 	}
 }
 
+/**
+ * {@link TreeViewConfiguration} extended with some alpha APIs.
+ * @sealed @alpha
+ */
+export class TreeViewConfigurationAlpha<
+		const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
+	>
+	extends TreeViewConfiguration<TSchema>
+	implements TreeSchema
+{
+	/**
+	 * {@inheritDoc TreeSchema.root}
+	 */
+	public readonly root: FieldSchemaAlpha;
+	/**
+	 * {@inheritDoc TreeSchema.definitions}
+	 */
+	public readonly definitions: ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
+
+	public constructor(props: ITreeViewConfiguration<TSchema>) {
+		super(props);
+		this.root = normalizeFieldSchema(props.schema);
+		const definitions = new Map<string, SimpleNodeSchema & TreeNodeSchema>();
+		walkFieldSchema(props.schema, {
+			node: (schema) =>
+				definitions.set(schema.identifier, schema as SimpleNodeSchema & TreeNodeSchema),
+		});
+		this.definitions = definitions;
+	}
+}
+
+/**
+ * {@link TreeViewConfigurationAlpha}
+ * @sealed @alpha
+ */
+export interface TreeSchema extends SimpleTreeSchema {
+	/**
+	 * {@inheritDoc SimpleTreeSchema.root}
+	 */
+	readonly root: FieldSchemaAlpha;
+
+	/**
+	 * {@inheritDoc SimpleTreeSchema.definitions}
+	 */
+	readonly definitions: ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
+}
+
 /**
  * Pretty print a set of types for use in error messages.
  */

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

@@ -41,8 +41,9 @@ import {
 	customFromCursor,
 	replaceHandles,
 	type CustomTreeNode,
-	type EncodeOptions,
 	type HandleConverter,
+	type SchemalessParseOptions,
+	type TreeEncodingOptions,
 } from "./customTree.js";
 import { getUnhydratedContext } from "../createContext.js";
 
@@ -110,40 +111,14 @@ export interface VerboseTreeNode<THandle = IFluidHandle> {
 		  };
 }
 
-/**
- * Options for how to interpret a `VerboseTree` when schema information is available.
- * @alpha
- */
-export interface ParseOptions {
-	/**
-	 * If true, interpret the input keys of object nodes as stored keys.
-	 * If false, interpret them as property keys.
-	 * @defaultValue false.
-	 */
-	readonly useStoredKeys?: boolean;
-}
-
-/**
- * Options for how to interpret a `VerboseTree` without relying on schema.
- */
-export interface SchemalessParseOptions {
-	/**
-	 * Converts stored keys into whatever key the tree is using in its encoding.
-	 */
-	keyConverter?: {
-		parse(type: string, inputKey: string): FieldKey;
-		encode(type: string, key: FieldKey): string;
-	};
-}
-
 /**
  * Use info from `schema` to convert `options` to {@link SchemalessParseOptions}.
  */
 export function applySchemaToParserOptions(
 	schema: ImplicitFieldSchema,
-	options: ParseOptions,
+	options: TreeEncodingOptions,
 ): SchemalessParseOptions {
-	const config: Required<ParseOptions> = {
+	const config: Required<TreeEncodingOptions> = {
 		useStoredKeys: false,
 		...options,
 	};
@@ -305,9 +280,9 @@ function verboseTreeAdapter(options: SchemalessParseOptions): CursorAdapter<Verb
 export function verboseFromCursor(
 	reader: ITreeCursor,
 	rootSchema: ImplicitAllowedTypes,
-	options: EncodeOptions,
+	options: TreeEncodingOptions,
 ): VerboseTree {
-	const config: Required<EncodeOptions> = {
+	const config: Required<TreeEncodingOptions> = {
 		useStoredKeys: false,
 		...options,
 	};
@@ -319,7 +294,7 @@ export function verboseFromCursor(
 
 function verboseFromCursorInner(
 	reader: ITreeCursor,
-	options: Required<EncodeOptions>,
+	options: Required<TreeEncodingOptions>,
 	schema: ReadonlyMap<string, TreeNodeSchema>,
 ): VerboseTree {
 	const fields = customFromCursor(reader, options, schema, verboseFromCursorInner);

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

@@ -7,6 +7,7 @@ import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "../schemaTypes.js";
 import type {
 	SimpleArrayNodeSchema,
+	SimpleFieldSchema,
 	SimpleLeafNodeSchema,
 	SimpleMapNodeSchema,
 	SimpleNodeSchema,
@@ -59,10 +60,14 @@ export function toSimpleTreeSchema(
 	});
 
 	return {
-		kind: normalizedSchema.kind,
-		allowedTypesIdentifiers: normalizedSchema.allowedTypesIdentifiers,
+		root: copySchemaObjects
+			? ({
+					allowedTypesIdentifiers: normalizedSchema.allowedTypesIdentifiers,
+					kind: normalizedSchema.kind,
+					metadata: normalizedSchema.metadata,
+				} satisfies SimpleFieldSchema)
+			: normalizedSchema,
 		definitions,
-		metadata: normalizedSchema.metadata,
 	};
 }
 

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

@@ -19,7 +19,6 @@ import {
 	assertFlexTreeEntityNotFreed,
 	ContextSlot,
 	flexTreeSlot,
-	isFreedSymbol,
 	LazyEntity,
 	TreeStatus,
 	treeStatusFromAnchorCache,
@@ -155,15 +154,20 @@ export class TreeNodeKernel {
 						changedFields,
 					});
 
-					let n: UnhydratedFlexTreeNode | undefined = innerNode;
-					while (n !== undefined) {
-						const treeNode = unhydratedFlexTreeNodeToTreeNodeInternal.get(n);
+					let unhydratedNode: UnhydratedFlexTreeNode | undefined = innerNode;
+					while (unhydratedNode !== undefined) {
+						const treeNode = unhydratedFlexTreeNodeToTreeNodeInternal.get(unhydratedNode);
 						if (treeNode !== undefined) {
 							const kernel = getKernel(treeNode);
 							kernel.#unhydratedEvents.value.emit("subtreeChangedAfterBatch");
 						}
-						// This cast is safe because the parent (if it exists) of an unhydrated flex node is always another unhydrated flex node.
-						n = n.parentField.parent.parent as UnhydratedFlexTreeNode | undefined;
+						const parentNode: FlexTreeNode | undefined =
+							unhydratedNode.parentField.parent.parent;
+						assert(
+							parentNode === undefined || parentNode instanceof UnhydratedFlexTreeNode,
+							0xb76 /* Unhydrated node's parent should be an unhydrated node */,
+						);
+						unhydratedNode = parentNode;
 					}
 				}),
 			};
@@ -243,7 +247,7 @@ export class TreeNodeKernel {
 		const flex = this.#hydrationState.anchorNode.slots.get(flexTreeSlot);
 		if (flex !== undefined) {
 			assert(flex instanceof LazyEntity, 0x9b4 /* Unexpected flex node implementation */);
-			if (flex[isFreedSymbol]()) {
+			if (flex.isFreed()) {
 				return TreeStatus.Deleted;
 			}
 		}

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

@@ -150,11 +150,24 @@ export class UnhydratedFlexTreeNode implements UnhydratedFlexTreeNode {
 	public adoptBy(parent: UnhydratedFlexTreeField, index: number): void;
 	public adoptBy(parent: UnhydratedFlexTreeField | undefined, index?: number): void {
 		if (parent !== undefined) {
-			assert(
-				this.location === unparentedLocation,
-				0x98c /* Node may not be adopted if it already has a parent */,
-			);
 			assert(index !== undefined, 0xa08 /* Expected index */);
+			if (this.location !== unparentedLocation) {
+				throw new UsageError("A node may not be inserted if it's already in a tree");
+			}
+			let unhydratedNode: UnhydratedFlexTreeNode | undefined = parent.parent;
+			while (unhydratedNode !== undefined) {
+				if (unhydratedNode === this) {
+					throw new UsageError(
+						"A node may not be inserted into a location that is under itself",
+					);
+				}
+				const parentNode: FlexTreeNode | undefined = unhydratedNode.parentField.parent.parent;
+				assert(
+					parentNode === undefined || parentNode instanceof UnhydratedFlexTreeNode,
+					0xb77 /* Unhydrated node's parent should be an unhydrated node */,
+				);
+				unhydratedNode = parentNode;
+			}
 			this.location = { parent, index };
 		} else {
 			assert(

package/src/simple-tree/index.ts

@@ -31,6 +31,7 @@ export {
 	type ViewableTree,
 	type TreeViewEvents,
 	TreeViewConfiguration,
+	TreeViewConfigurationAlpha,
 	type ITreeViewConfiguration,
 	type SchemaCompatibilityStatus,
 	type ITreeConfigurationOptions,
@@ -70,11 +71,11 @@ export {
 	type JsonTreeSchema,
 	type JsonFieldSchema,
 	type JsonLeafSchemaType,
+	type TreeSchemaEncodingOptions,
 	getJsonSchema,
 	getSimpleSchema,
 	type VerboseTreeNode,
-	type EncodeOptions,
-	type ParseOptions,
+	type TreeEncodingOptions,
 	type VerboseTree,
 	extractPersistedSchema,
 	comparePersistedSchema,
@@ -138,6 +139,7 @@ export {
 	replaceVerboseTreeHandles,
 	type HandleConverter,
 	type FieldSchemaAlphaUnsafe,
+	type TreeSchema,
 } from "./api/index.js";
 export type {
 	SimpleTreeSchema,

package/src/simple-tree/simpleSchema.ts

@@ -180,22 +180,14 @@ export interface SimpleFieldSchema {
  * @alpha
  * @sealed
  */
-export interface SimpleTreeSchema extends SimpleFieldSchema {
+export interface SimpleTreeSchema {
 	/**
-	 * The kind of tree field representing the root of the tree.
+	 * The tree field representing the root of the tree.
 	 */
-	readonly kind: FieldKind;
-
-	/**
-	 * The types allowed under the tree root.
-	 *
-	 * @remarks Refers to the types by identifier.
-	 * Can be resolved via {@link SimpleTreeSchema.definitions}.
-	 */
-	readonly allowedTypesIdentifiers: ReadonlySet<string>;
+	readonly root: SimpleFieldSchema;
 
 	/**
-	 * The complete set of node schema definitions recursively referenced by the tree's {@link SimpleTreeSchema.allowedTypesIdentifiers}.
+	 * The complete set of node schema definitions recursively referenced by the tree's {@link SimpleTreeSchema.root}.
 	 *
 	 * @remarks the keys are the schemas' {@link TreeNodeSchemaCore.identifier | identifiers}.
 	 */