@fluidframework/tree 2.63.0-359461 → 2.63.0-359962

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

@@ -3,8 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import type { TreeFieldStoredSchema } from "../../core/index.js";
-import { defaultSchemaPolicy, FieldKinds } from "../../feature-libraries/index.js";
+import type { ITreeCursorSynchronous, TreeFieldStoredSchema } from "../../core/index.js";
+import {
+	defaultSchemaPolicy,
+	FieldKinds,
+	isTreeValue,
+} from "../../feature-libraries/index.js";
 import { brand } from "../../util/index.js";
 import {
 	Context,
@@ -13,6 +17,7 @@ import {
 	isTreeNode,
 	UnhydratedContext,
 	type NodeKind,
+	type TreeLeafValue,
 	type TreeNode,
 	type Unhydrated,
 	type WithType,
@@ -29,8 +34,12 @@ import {
 } from "../unhydratedFlexTreeFromInsertable.js";
 
 import { createFromCursor } from "./create.js";
+import { conciseFromCursor, type ConciseTree } from "./conciseTree.js";
+import type { TreeEncodingOptions } from "./customTree.js";
+import { cursorFromVerbose } from "./verboseTree.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
 import { treeNodeApi } from "./treeNodeApi.js";
+import type { InsertableField, UnsafeUnknownSchema } from "../unsafeUnknownSchema.js";
 
 // Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,
 // and where most of the actual implementation is for much of it.
@@ -128,6 +137,39 @@ export interface TreeBeta {
 		listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,
 	): () => void;
 
+	/**
+	 * A less type-safe version of {@link (TreeAlpha:interface).create}, suitable for importing data.
+	 * @remarks
+	 * Due to {@link ConciseTree} relying on type inference from the data, its use is somewhat limited.
+	 * This does not support {@link ConciseTree|ConciseTrees} with customized handle encodings or using persisted keys.
+	 * Use "compressed" or "verbose" formats for more flexibility.
+	 *
+	 * When using this function,
+	 * it is recommend to ensure your schema is unambiguous with {@link ITreeConfigurationOptions.preventAmbiguity}.
+	 * If the schema is ambiguous, consider using {@link (TreeAlpha:interface).create} and {@link Unhydrated} nodes where needed,
+	 * or using {@link (TreeAlpha:interface).(importVerbose:1)} and specify all types.
+	 *
+	 * Documented (and thus recoverable) error handling/reporting for this is not yet implemented,
+	 * but for now most invalid inputs will throw a recoverable error.
+	 */
+	importConcise<const TSchema extends ImplicitFieldSchema>(
+		schema: TSchema,
+		data: ConciseTree | undefined,
+	): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+
+	/**
+	 * Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}.
+	 */
+	exportConcise(node: TreeNode | TreeLeafValue, options?: TreeEncodingOptions): ConciseTree;
+
+	/**
+	 * Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}, allowing undefined.
+	 */
+	exportConcise(
+		node: TreeNode | TreeLeafValue | undefined,
+		options?: TreeEncodingOptions,
+	): ConciseTree | undefined;
+
 	/**
 	 * Clones the persisted data associated with a node.
 	 *
@@ -143,7 +185,7 @@ export interface TreeBeta {
 	 *
 	 * - The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.
 	 *
-	 * - If the node (or any node in its subtree) contains {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields|unknown optional fields},
+	 * - If the node (or any node in its subtree) contains {@link ObjectSchemaOptions.allowUnknownOptionalFields|unknown optional fields},
 	 * those fields will be cloned just like the known fields.
 	 */
 	clone<const TSchema extends ImplicitFieldSchema>(
@@ -184,6 +226,93 @@ export interface TreeBeta {
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 }
 
+/**
+ * Borrow a cursor from a node.
+ * @remarks
+ * The cursor must be put back to its original location before the node is used again.
+ */
+export function borrowCursorFromTreeNodeOrValue(
+	node: TreeNode | TreeLeafValue,
+): ITreeCursorSynchronous {
+	if (isTreeValue(node)) {
+		return cursorFromVerbose(node, {});
+	}
+	const kernel = getKernel(node);
+	const cursor = kernel.getInnerNode().borrowCursor();
+	return cursor;
+}
+
+/**
+ * {@inheritDoc (TreeBeta:interface).importConcise}
+ */
+export function importConcise<TSchema extends ImplicitFieldSchema>(
+	schema: TSchema & ImplicitFieldSchema,
+	data: ConciseTree | undefined,
+): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+/**
+ * {@inheritDoc (TreeAlpha:interface).importConcise}
+ */
+export function importConcise<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(
+	schema: UnsafeUnknownSchema extends TSchema
+		? ImplicitFieldSchema
+		: TSchema & ImplicitFieldSchema,
+	data: ConciseTree | undefined,
+): Unhydrated<
+	TSchema extends ImplicitFieldSchema
+		? TreeFieldFromImplicitField<TSchema>
+		: TreeNode | TreeLeafValue | undefined
+>;
+export function importConcise<TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(
+	schema: UnsafeUnknownSchema extends TSchema
+		? ImplicitFieldSchema
+		: TSchema & ImplicitFieldSchema,
+	data: ConciseTree | undefined,
+): Unhydrated<
+	TSchema extends ImplicitFieldSchema
+		? TreeFieldFromImplicitField<TSchema>
+		: TreeNode | TreeLeafValue | undefined
+> {
+	// Create the tree content from insertable data
+	const mapTree = unhydratedFlexTreeFromInsertable(
+		data as InsertableField<UnsafeUnknownSchema>,
+		schema,
+	);
+	const result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);
+	return result as Unhydrated<
+		TSchema extends ImplicitFieldSchema
+			? TreeFieldFromImplicitField<TSchema>
+			: TreeNode | TreeLeafValue | undefined
+	>;
+}
+
+/**
+ * {@inheritDoc (TreeBeta:interface).(exportConcise:1)}
+ */
+export function exportConcise(
+	node: TreeNode | TreeLeafValue,
+	options?: TreeEncodingOptions,
+): ConciseTree;
+/**
+ * {@inheritDoc (TreeBeta:interface).(exportConcise:2)}
+ */
+export function exportConcise(
+	node: TreeNode | TreeLeafValue | undefined,
+	options?: TreeEncodingOptions,
+): ConciseTree | undefined;
+export function exportConcise(
+	node: TreeNode | TreeLeafValue | undefined,
+	options?: TreeEncodingOptions,
+): ConciseTree | undefined {
+	if (!isTreeNode(node)) {
+		return node;
+	}
+	const config: TreeEncodingOptions = { ...options };
+
+	const kernel = getKernel(node);
+	const cursor = borrowCursorFromTreeNodeOrValue(node);
+	return conciseFromCursor(cursor, kernel.context, config);
+}
+
 /**
  * Extensions to {@link (Tree:variable)} which are not yet stable.
  * @see {@link (TreeBeta:interface)}.
@@ -197,6 +326,10 @@ export const TreeBeta: TreeBeta = {
 	): () => void {
 		return treeNodeApi.on(node, eventName, listener);
 	},
+
+	importConcise,
+	exportConcise,
+
 	clone<const TSchema extends ImplicitFieldSchema>(
 		node: TreeFieldFromImplicitField<TSchema>,
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
@@ -206,7 +339,7 @@ export const TreeBeta: TreeBeta = {
 		}
 
 		const kernel = getKernel(node);
-		const cursor = kernel.getOrCreateInnerNode().borrowCursor();
+		const cursor = kernel.getInnerNode().borrowCursor();
 
 		// To handle when the node transitively contains unknown optional fields,
 		// derive the context from the source node's stored schema which has stored schema for any such fields and their contents.

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

@@ -28,7 +28,7 @@ import {
 	tryGetTreeNodeSchema,
 	getOrCreateNodeFromInnerNode,
 	typeSchemaSymbol,
-	getOrCreateInnerNode,
+	getInnerNode,
 	type TreeLeafValue,
 	type ImplicitAllowedTypes,
 	type TreeNodeFromImplicitAllowedTypes,
@@ -141,7 +141,7 @@ export interface TreeNodeApi {
  */
 export const treeNodeApi: TreeNodeApi = {
 	parent(node: TreeNode): TreeNode | undefined {
-		const editNode = getOrCreateInnerNode(node).parentField.parent.parent;
+		const editNode = getInnerNode(node).parentField.parent.parent;
 		if (editNode === undefined) {
 			return undefined;
 		}
@@ -222,7 +222,7 @@ export const treeNodeApi: TreeNodeApi = {
 		if (actualSchema === undefined) {
 			return false;
 		}
-		return normalizeAllowedTypes(schema).has(actualSchema);
+		return normalizeAllowedTypes(schema).evaluateSet().has(actualSchema);
 	},
 	schema(node: TreeNode | TreeLeafValue): TreeNodeSchema {
 		return tryGetSchema(node) ?? fail(0xb37 /* Not a tree node */);
@@ -306,7 +306,7 @@ export function getIdentifierFromNode(
 		return undefined;
 	}
 
-	const flexNode = getOrCreateInnerNode(node);
+	const flexNode = getInnerNode(node);
 	const identifierFieldKeys = schema.identifierFieldKeys;
 
 	switch (identifierFieldKeys.length) {
@@ -361,7 +361,7 @@ export function getIdentifierFromNode(
 export function getStoredKey(node: TreeNode): string | number {
 	// Note: the flex domain strictly works with "stored keys", and knows nothing about the developer-facing
 	// "property keys".
-	const parentField = getOrCreateInnerNode(node).parentField;
+	const parentField = getInnerNode(node).parentField;
 	if (parentField.parent.schema === FieldKinds.sequence.identifier) {
 		// The parent of `node` is an array node
 		assert(

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

@@ -29,6 +29,8 @@ import type {
 	TreeLeafValue,
 	FlexListToUnion,
 	LazyItem,
+	AnnotatedAllowedType,
+	AnnotatedAllowedTypes,
 } from "../core/index.js";
 import type { TreeArrayNode } from "../node-kinds/index.js";
 import type { SimpleArrayNodeSchema, SimpleMapNodeSchema } from "../simpleSchema.js";
@@ -543,3 +545,82 @@ export interface TreeRecordNodeUnsafe<
 		[string, System_Unsafe.TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>]
 	>;
 }
+
+/**
+ * {@link Unenforced} utility to remove {@link AnnotatedAllowedTypeUnsafe} wrappers.
+ * @remarks
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @sealed
+ * @alpha
+ * @system
+ */
+export type UnannotateAllowedTypeUnsafe<
+	T extends Unenforced<
+		AnnotatedAllowedTypeUnsafe | LazyItem<System_Unsafe.TreeNodeSchemaUnsafe>
+	>,
+> = T extends AnnotatedAllowedTypeUnsafe<infer X> ? X : T;
+
+/**
+ * {@link Unenforced} version of {@link AnnotatedAllowedType}.
+ * @remarks
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @sealed @alpha
+ */
+export interface AnnotatedAllowedTypeUnsafe<T = Unenforced<LazyItem<TreeNodeSchema>>>
+	extends AnnotatedAllowedType<T> {}
+
+/**
+ * {@link Unenforced} version of {@link AnnotatedAllowedTypes}.
+ * @remarks
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @sealed @alpha
+ */
+export interface AnnotatedAllowedTypesUnsafe
+	extends AnnotatedAllowedTypes<LazyItem<System_Unsafe.TreeNodeSchemaUnsafe>> {}
+
+/**
+ * {@link Unenforced} version of {@link AllowedTypesFull}.
+ * @remarks
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @sealed @alpha
+ */
+export type AllowedTypesFullUnsafe<
+	T extends readonly AnnotatedAllowedTypeUnsafe[] = readonly AnnotatedAllowedTypeUnsafe[],
+> = AnnotatedAllowedTypes<T> & UnannotateAllowedTypesListUnsafe<T>;
+
+/**
+ * {@link Unenforced} version of {@link AllowedTypesFullFromMixed}.
+ * @remarks
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @sealed @alpha
+ */
+export type AllowedTypesFullFromMixedUnsafe<
+	T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[],
+> = UnannotateAllowedTypesListUnsafe<T> &
+	AnnotatedAllowedTypes<AnnotateAllowedTypesListUnsafe<T>>;
+
+/**
+ * {@link Unenforced} version of {@link UnannotateAllowedTypesList}.
+ * @remarks
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @sealed @alpha
+ */
+export type UnannotateAllowedTypesListUnsafe<
+	T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[],
+> = {
+	readonly [I in keyof T]: T[I] extends { type: infer X } ? X : T[I];
+};
+
+/**
+ * {@link Unenforced} version of {@link AnnotateAllowedTypesList}.
+ * @remarks
+ * Do not use this type directly: it's only needed in the implementation of generic logic which define recursive schema, not when using recursive schema.
+ * @system @sealed @alpha
+ */
+export type AnnotateAllowedTypesListUnsafe<
+	T extends readonly Unenforced<AnnotatedAllowedType | LazyItem<TreeNodeSchema>>[],
+> = {
+	[I in keyof T]: T[I] extends AnnotatedAllowedTypeUnsafe
+		? T[I]
+		: AnnotatedAllowedTypeUnsafe<T[I]>;
+};

package/src/simple-tree/core/TreeNodeBinding.md

@@ -8,9 +8,7 @@ Here is an example:
 function addPoint(curve: Curve, x: number, y: number): Point {
 	const point = new Point({ x: 3, y: 3 });
 	curve.points.insertAtEnd(point);
-	// After insertion, `point` can be queried:
-	assert(point.x === 3);
-	// In fact, `point` is the same simple-tree node object that you would get from reading it off of its new parent in the tree:
+	// `point` is the same simple-tree node object that you would get from reading it off of its new parent in the tree:
 	assert(point === curve.points[curve.points.length - 1]);
 	// So, to read the content that was just inserted, the original object can be used and there is no need to read via the parent:
 	return point;
@@ -22,83 +20,29 @@ function addPoint(curve: Curve, x: number, y: number): Point {
 
 This feature is supported by doing some bookkeeping to ensure that the simple-tree objects,
 flex tree nodes and anchor nodes in the tree get associated and disassociated at the right times.
-There are three states that a node simple-tree node can be in: "raw", "marinated" and "cooked".
+There are three states that a node simple-tree node can be in: "Unhydrated", "hydrating" and "Hydrated".
 
-Note from the public API perspective, `Unhydrated` nodes are "raw", and hydrated nodes are either "marinated" or "cooked".
+### Unhydrated Nodes
 
-### Raw Proxies
-
-A newly created simple-tree node, a.k.a. a **raw** simple-tree node. A raw simple-tree node is produced by invoking the schema-provided constructor for a node:
-
-```ts
-const rawPoint = new Point({ x: 3, y: 3 });
-```
-
-Such a simple-tree node will be raw until it is inserted into the tree and becomes "marinated" (see below).
-As raw nodes can be read or mutated.
-
-### Marinated Proxies
-
-Proxies become **marinated** as soon as they are inserted into the tree.
-
-This happens whether proxies are inserted directly, as the root of the content subtree...
+A newly created simple-tree node, a.k.a. an **unhydrated** simple-tree node. An unhydrated simple-tree node is produced by invoking the schema-provided constructor for a node:
 
 ```ts
-// Upon insertion, `rawPoint` transitions from "raw" to the next state, "marinated"
-app.graph.curves[0].insertAtEnd(rawPoint);
+const unhydratedPoint = new Point({ x: 3, y: 3 });
 ```
 
-...or proxies are inserted indirectly, making up some arbitrary portion of the content subtree.
+Such a simple-tree node will be unhydrated until it is inserted into the tree and becomes "hydrated" (see below).
+Unhydrated nodes can be read or mutated just like hydrated ones.
 
-```ts
-// Upon insertion, `rawPoint` transitions from "raw" to the next state, "marinated"
-app.graph = {
-	curves: [
-		[new Point({ x: 10, y: 10 }), new Point({ x: 20, y: 20 })],
-		[new Point({ x: 2, y: 2 }), rawPoint, new Point({ x: 4, y: 4 })],
-	],
-};
-```
+### Hydrating Nodes
 
-A marinated simple-tree node, by definition, is bound bi-directionally to an `AnchorNode`.
-When insertion occurs, an `AnchorNode` will be created (if not already present) for the location of the new content.
-The simple-tree node for that content will then be mapped to the `AnchorNode` (via its kernel) and the `AnchorNode` will be mapped to the simple-tree node.
-Note that the `AnchorNode` may not yet have a `FlexTreeNode` associated with it - that happens when the node becomes "cooked" (see below).
+Between insertion edit and the change callback which updates the node to "Hydrated" (see [prepareForInsertion.ts](../prepareForInsertion.ts)),
+the node is in a poorly defined "hydrating" state and should not be interacted with.
 
-### Cooked Proxies
+### Hydrated Nodes
 
-A simple-tree node is fully cooked when it finally associates itself with a `FlexTreeNode`.
-This happens lazily on demand, if/when a marinated simple-tree node is read or mutated (by the local client).
+A simple-tree node is fully hydrated when it is associated with a `HydratedFlexTreeNode`.
 
 ```ts
-const point = new Point({ x: 3, y: 3 }); // `point` is raw
-curves.points.insertAtEnd(point); // `point` becomes marinated
-const x = point.x; // `point` becomes cooked in order to support the read of `x`
+const point = new Point({ x: 3, y: 3 }); // `point` is unhydrated
+curves.points.insertAtEnd(point); // `point` becomes hydrated
 ```
-
-This laziness prevents the simple-tree node tree from generating unnecessary `FlexTreeNodes`.
-
-Cooking a marinated simple-tree node works as follows:
-
-1. Get the `AnchorNode` associated with the marinated simple-tree node.
-2. Get or create a `FlexTreeNode` for the anchor.
-3. This will cause the `FlexTreeNode` to be generated which corresponds to the simple-tree node.
-
-### Mappings
-
-```mermaid
-graph LR;
-    AnchorNode(AnchorNode)<-->|Cooked and sometimes when Marinated|FlexTreeNode(FlexTreeNode)
-    AnchorNode<--->|Marinated or Cooked|TreeNode(TreeNode)-.->|Raw|RawTreeNode(RawTreeNode)
-    linkStyle 0 stroke:#0f0
-    linkStyle 1 stroke:#00f
-    linkStyle 2 stroke:#f00
-```
-
-Note that it is possible for the `Cooked` mappings between an `AnchorNode` and a `FlexTreeNode` to exist regardless of whether there is also a simple-tree node yet created for that node.
-In that case, when that simple-tree node is created it will immediately be given its `Marinated` mappings and therefore already be cooked.
-
-`RawTreeNode`s, which implement the `FlexTreeNode` interface (or at least, as of 2024-03-21, pretend to), are substitutes for the true `FlexTreeNode`s that don't yet exist for a raw node.
-The `Raw` mapping is removed when a simple-tree node is marinated, and the `RawTreeNode` is forgotten.
-
-See [proxyBinding.ts](./proxyBinding.ts) for more details.