@fluidframework/tree 2.62.0 → 2.63.0-359286

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

@@ -9,6 +9,7 @@ import { brand } from "../../util/index.js";
 import {
 	Context,
 	getKernel,
+	getOrCreateNodeFromInnerNode,
 	isTreeNode,
 	UnhydratedContext,
 	type NodeKind,
@@ -17,7 +18,15 @@ import {
 	type WithType,
 } from "../core/index.js";
 import { getUnhydratedContext } from "../createContext.js";
-import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../fieldSchema.js";
+import type {
+	ImplicitFieldSchema,
+	InsertableTreeFieldFromImplicitField,
+	TreeFieldFromImplicitField,
+} from "../fieldSchema.js";
+import {
+	unhydratedFlexTreeFromInsertable,
+	type InsertableContent,
+} from "../unhydratedFlexTreeFromInsertable.js";
 
 import { createFromCursor } from "./create.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
@@ -159,6 +168,20 @@ export interface TreeBeta {
 	// 		replaceIdentifiers?: true;
 	// 	},
 	// ): TreeFieldFromImplicitField<TSchema>;
+
+	/**
+	 * Construct tree content that is compatible with the field defined by the provided `schema`.
+	 * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
+	 * @param data - The data used to construct the field content.
+	 * @remarks
+	 * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.
+	 * This function exists as a generalization that can be used in other cases as well,
+	 * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.
+	 */
+	create<const TSchema extends ImplicitFieldSchema>(
+		schema: TSchema,
+		data: InsertableTreeFieldFromImplicitField<TSchema>,
+	): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
 }
 
 /**
@@ -202,4 +225,16 @@ export const TreeBeta: TreeBeta = {
 			TreeFieldFromImplicitField<TSchema>
 		>;
 	},
+
+	create<const TSchema extends ImplicitFieldSchema>(
+		schema: TSchema,
+		data: InsertableTreeFieldFromImplicitField<TSchema>,
+	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
+		const mapTree = unhydratedFlexTreeFromInsertable(
+			data as InsertableContent | undefined,
+			schema,
+		);
+		const result = mapTree === undefined ? undefined : getOrCreateNodeFromInnerNode(mapTree);
+		return result as Unhydrated<TreeFieldFromImplicitField<TSchema>>;
+	},
 };

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

@@ -533,7 +533,7 @@ export interface MapNodeCustomizableSchemaUnsafe<
  * {@link Unenforced} version of {@link TreeRecordNode}.
  * @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
+ * @system @sealed @beta
  */
 export interface TreeRecordNodeUnsafe<
 	TAllowedTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe,

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

@@ -28,13 +28,14 @@ import { markEager } from "./flexList.js";
  *
  * 2. Explicit construction of {@link Unhydrated} nodes using either {@link TreeNodeSchemaClass} as a constructor or {@link TreeNodeSchemaNonClass|TreeNodeSchemaNonClass.create}.
  * Either way the {@link TreeNodeSchema} produced must be produced using a {@link SchemaFactory}.
+ * There are also higher level APIs which wrap these, including {@link (TreeBeta:interface).create}, {@link (TreeBeta:interface).clone},
+ * and import APIs like {@link (TreeAlpha:interface).importConcise}, {@link (TreeAlpha:interface).importVerbose}, and {@link (TreeAlpha:interface).importCompressed}.
  *
  * 3. Implicit construction: Several APIs which logically require an unhydrated TreeNode also allow passing in a value which could be used to explicitly construct the node instead.
- * These APIs internally call the constructor with the provided value, so it's really just a special case of the above option.
+ * These APIs internally call the constructor with the provided value (typically behaving like {@link (TreeAlpha:interface).create}), so it's really just a special case of the above option.
  * Note that when constructing nodes, sometimes implicit construction is not allowed
  * (either at runtime due to ambiguous types or at compile time due to TypeScript limitations):
  * in such cases, explicit construction must be used.
- *
  * @privateRemarks
  * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})
  * and some runtime enforcement of schema class policy (see the the validation in the constructor).

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

@@ -385,7 +385,7 @@ class KernelEventBuffer implements Listenable<KernelEvents> {
 	readonly #events = createEmitter<KernelEvents>();
 
 	#eventSource: Listenable<KernelEvents> & HasListeners<KernelEvents>;
-	#disposeSourceListeners: Map<keyof KernelEvents, Off> = new Map();
+	readonly #disposeSourceListeners: Map<keyof KernelEvents, Off> = new Map();
 
 	/**
 	 * Buffer of fields that have changed since events were paused.

package/src/simple-tree/node-kinds/record/recordNodeTypes.ts

@@ -28,7 +28,7 @@ import type { RestrictiveStringRecord } from "../../../util/index.js";
  * Therefore code assigning to these fields must explicitly construct nodes using the schema's constructor or create method,
  * or using some other method like {@link (TreeAlpha:interface).create}.
  *
- * @alpha
+ * @beta
  */
 export interface TreeRecordNode<
 	TAllowedTypes extends ImplicitAllowedTypes = ImplicitAllowedTypes,
@@ -44,7 +44,7 @@ export interface TreeRecordNode<
 
 /**
  * Content which can be used to construct a Record node, explicitly or implicitly.
- * @system @alpha
+ * @system @beta
  */
 export type RecordNodeInsertableData<T extends ImplicitAllowedTypes> = RestrictiveStringRecord<
 	InsertableTreeNodeFromImplicitAllowedTypes<T>

package/src/util/brand.ts

@@ -17,7 +17,7 @@ import type { Covariant } from "./typeCheck.js";
  * mismatched branded types will be:
  * `Type 'Name1' is not assignable to type 'Name2'.`
  *
- * These branded types are not opaque: A `Brand<A, B>` can still be used as a `B`.
+ * These branded types are not opaque: A `Brand<A, B>` can still be used as a `A`.
  */
 export type Brand<ValueType, Name> = ValueType & BrandedType<ValueType, Name>;