@fluidframework/tree 2.4.0 → 2.5.0

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

@@ -3,10 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import type { InternalTreeNode, Unhydrated } from "./types.js";
+import type { TreeLeafValue } from "../schemaTypes.js";
+import type { InternalTreeNode, TreeNode, Unhydrated } from "./types.js";
 
 /**
- * Schema for a tree node.
+ * Schema for a {@link TreeNode} or {@link TreeLeafValue}.
+ *
  * @typeParam Name - The full (including scope) name/identifier for the schema.
  * @typeParam Kind - Which kind of node this schema is for.
  * @typeParam TNode - API for nodes that use this schema.
@@ -14,17 +16,21 @@ import type { InternalTreeNode, Unhydrated } from "./types.js";
  * @typeParam Info - Data used when defining this schema.
  * @remarks
  * Captures the schema both as runtime data and compile time type information.
+ * Use {@link SchemaFactory} to define schema.
+ * Use `Tree.schema(value)` to lookup the schema for a {@link TreeNode} or {@link TreeLeafValue}.
  * @sealed @public
  */
 export type TreeNodeSchema<
 	Name extends string = string,
 	Kind extends NodeKind = NodeKind,
-	TNode = unknown,
+	TNode extends TreeNode | TreeLeafValue = TreeNode | TreeLeafValue,
 	TBuild = never,
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
 > =
-	| TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>
+	| (TNode extends TreeNode
+			? TreeNodeSchemaClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>
+			: never)
 	| TreeNodeSchemaNonClass<Name, Kind, TNode, TBuild, ImplicitlyConstructable, Info>;
 
 /**
@@ -35,16 +41,30 @@ export type TreeNodeSchema<
  * Non-class based schema can have issues with recursive types due to https://github.com/microsoft/TypeScript/issues/55832.
  * @system @sealed @public
  */
-export interface TreeNodeSchemaNonClass<
-	out Name extends string = string,
-	out Kind extends NodeKind = NodeKind,
-	out TNode = unknown,
-	in TInsertable = never,
-	out ImplicitlyConstructable extends boolean = boolean,
-	out Info = unknown,
-> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {
-	create(data: TInsertable): TNode;
-}
+export type TreeNodeSchemaNonClass<
+	Name extends string = string,
+	Kind extends NodeKind = NodeKind,
+	TNode extends TreeNode | TreeLeafValue = TreeNode | TreeLeafValue,
+	TInsertable = never,
+	ImplicitlyConstructable extends boolean = boolean,
+	Info = unknown,
+	TConstructorExtra = never,
+> = TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info, TInsertable> &
+	(undefined extends TConstructorExtra
+		? {
+				/**
+				 * Constructs an {@link Unhydrated} node with this schema.
+				 * @sealed
+				 */
+				create(data?: TInsertable | TConstructorExtra): TNode;
+			}
+		: {
+				/**
+				 * Constructs an {@link Unhydrated} node with this schema.
+				 * @sealed
+				 */
+				create(data: TInsertable | TConstructorExtra): TNode;
+			});
 
 /**
  * Tree node schema which is implemented using a class.
@@ -91,23 +111,40 @@ export interface TreeNodeSchemaNonClass<
  * ```
  * @sealed @public
  */
-export interface TreeNodeSchemaClass<
-	out Name extends string = string,
-	out Kind extends NodeKind = NodeKind,
-	out TNode = unknown,
-	in TInsertable = never,
-	out ImplicitlyConstructable extends boolean = boolean,
-	out Info = unknown,
-> extends TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info> {
-	/**
-	 * Constructs an {@link Unhydrated} node with this schema.
-	 * @remarks
-	 * This constructor is also used internally to construct hydrated nodes with a different parameter type.
-	 * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.
-	 * @sealed
-	 */
-	new (data: TInsertable | InternalTreeNode): Unhydrated<TNode>;
-}
+export type TreeNodeSchemaClass<
+	Name extends string = string,
+	Kind extends NodeKind = NodeKind,
+	TNode extends TreeNode = TreeNode,
+	TInsertable = never,
+	ImplicitlyConstructable extends boolean = boolean,
+	Info = unknown,
+	TConstructorExtra = never,
+> = TreeNodeSchemaCore<Name, Kind, ImplicitlyConstructable, Info, TInsertable> &
+	(undefined extends TConstructorExtra
+		? {
+				/**
+				 * Constructs an {@link Unhydrated} node with this schema.
+				 * @remarks
+				 * This constructor is also used internally to construct hydrated nodes with a different parameter type.
+				 * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.
+				 * @sealed
+				 */
+				// The approach suggested by the linter here is more concise, but ir break intellisense for the constructor.
+				// eslint-disable-next-line @typescript-eslint/prefer-function-type
+				new (data?: TInsertable | InternalTreeNode | TConstructorExtra): Unhydrated<TNode>;
+			}
+		: {
+				/**
+				 * Constructs an {@link Unhydrated} node with this schema.
+				 * @remarks
+				 * This constructor is also used internally to construct hydrated nodes with a different parameter type.
+				 * Therefore, overriding this constructor with different argument types is not type-safe and is not supported.
+				 * @sealed
+				 */
+				// The approach suggested by the linter here is more concise, but ir break intellisense for the constructor.
+				// eslint-disable-next-line @typescript-eslint/prefer-function-type
+				new (data: TInsertable | InternalTreeNode | TConstructorExtra): Unhydrated<TNode>;
+			});
 
 /**
  * Internal helper for utilities that return schema which can be used in class and non class formats depending on the API exposing it.
@@ -115,12 +152,29 @@ export interface TreeNodeSchemaClass<
 export type TreeNodeSchemaBoth<
 	Name extends string = string,
 	Kind extends NodeKind = NodeKind,
-	TNode = unknown,
+	TNode extends TreeNode = TreeNode,
 	TInsertable = never,
 	ImplicitlyConstructable extends boolean = boolean,
 	Info = unknown,
-> = TreeNodeSchemaClass<Name, Kind, TNode, TInsertable, ImplicitlyConstructable, Info> &
-	TreeNodeSchemaNonClass<Name, Kind, TNode, TInsertable, ImplicitlyConstructable, Info>;
+	TConstructorExtra = never,
+> = TreeNodeSchemaClass<
+	Name,
+	Kind,
+	TNode,
+	TInsertable,
+	ImplicitlyConstructable,
+	Info,
+	TConstructorExtra
+> &
+	TreeNodeSchemaNonClass<
+		Name,
+		Kind,
+		TNode,
+		TInsertable,
+		ImplicitlyConstructable,
+		Info,
+		TConstructorExtra
+	>;
 
 /**
  * Data common to all tree node schema.
@@ -133,6 +187,7 @@ export interface TreeNodeSchemaCore<
 	out Kind extends NodeKind,
 	out ImplicitlyConstructable extends boolean,
 	out Info = unknown,
+	out TInsertable = never,
 > {
 	/**
 	 * Unique (within a document's schema) identifier used to associate nodes with their schema.
@@ -188,6 +243,24 @@ export interface TreeNodeSchemaCore<
 	 * @system
 	 */
 	readonly childTypes: ReadonlySet<TreeNodeSchema>;
+
+	/**
+	 * Constructs an instance of this node type.
+	 * @remarks
+	 * Due to TypeScript limitations, the return type of this method can not be very specific.
+	 * For {@link TreeNodeSchemaClass} prefer using the constructor directly for better typing.
+	 * For {@link TreeNodeSchemaNonClass} use `create`.
+	 *
+	 * @privateRemarks
+	 * This method signature provides a way to infer `TInsertable` without relying on the constructor, and to construct nodes from schema of unknown kind.
+	 * This makes customizations of the constructor not impact the typing of insertable content, allowing customization of the constructor,
+	 * as long as doing so only adds additional supported cases.
+	 *
+	 * This cannot be required to return `TNode`:
+	 * doing so breaks sub-classing of schema since they don't overload this method with a more specific return type.
+	 * @sealed @system
+	 */
+	createFromInsertable(data: TInsertable): Unhydrated<TreeNode | TreeLeafValue>;
 }
 
 /**

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

@@ -15,6 +15,7 @@ import {
 	type FieldKindIdentifier,
 	type FieldUpPath,
 	forbiddenFieldKindIdentifier,
+	type ITreeCursorSynchronous,
 	type MapTree,
 	type SchemaPolicy,
 	type TreeNodeSchemaIdentifier,
@@ -39,6 +40,7 @@ import {
 	type FlexFieldKind,
 	FieldKinds,
 	type SequenceFieldEditBuilder,
+	cursorForMapTreeNode,
 } from "../../feature-libraries/index.js";
 import type { Context } from "./context.js";
 import { createEmitter, type Listenable } from "../../events/index.js";
@@ -168,6 +170,10 @@ export class UnhydratedFlexTreeNode implements UnhydratedFlexTreeNode {
 		return this.location;
 	}
 
+	public borrowCursor(): ITreeCursorSynchronous {
+		return cursorForMapTreeNode(this.mapTree);
+	}
+
 	public tryGetField(key: FieldKey): UnhydratedFlexTreeField | undefined {
 		const field = this.mapTree.fields.get(key);
 		// Only return the field if it is not empty, in order to fulfill the contract of `tryGetField`.

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

@@ -4,6 +4,7 @@
  */
 
 import type { NodeKind, TreeNodeSchemaClass } from "./treeNodeSchema.js";
+import type { TreeNode } from "./types.js";
 
 /**
  * The type of a {@link TreeNode}.
@@ -87,5 +88,5 @@ export interface WithType<
 	/**
 	 * Type symbol, marking a type in a way to increase type safety via strong type checking.
 	 */
-	get [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind, unknown, never, boolean, TInfo>;
+	get [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind, TreeNode, never, boolean, TInfo>;
 }

package/src/simple-tree/createContext.ts

@@ -7,7 +7,7 @@ import { defaultSchemaPolicy } from "../feature-libraries/index.js";
 import { getOrCreate } from "../util/index.js";
 import { Context, UnhydratedContext } from "./core/index.js";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "./schemaTypes.js";
-import { toStoredSchema } from "./toFlexSchema.js";
+import { toStoredSchema } from "./toStoredSchema.js";
 
 const contextCache: WeakMap<ImplicitFieldSchema, Context> = new WeakMap();
 

package/src/simple-tree/index.ts

@@ -23,6 +23,7 @@ export {
 	HydratedContext,
 	SimpleContextSlot,
 	getOrCreateInnerNode,
+	getKernel,
 } from "./core/index.js";
 export {
 	type ITree,
@@ -40,7 +41,6 @@ export {
 	adaptEnum,
 	enumFromStrings,
 	singletonSchema,
-	typedObjectValues,
 	test_RecursiveObject,
 	test_RecursiveObject_base,
 	test_RecursiveObjectPojoMode,
@@ -92,6 +92,21 @@ export {
 	type NodeBuilderDataUnsafe,
 	type NodeFromSchemaUnsafe,
 	type ReadonlyMapInlined,
+	type TreeNodeSchemaClassUnsafe,
+	type TreeNodeSchemaUnsafe,
+	type AllowedTypesUnsafe,
+	type TreeNodeSchemaNonClassUnsafe,
+	type InsertableTreeNodeFromAllowedTypesUnsafe,
+	type TreeViewAlpha,
+	type TreeBranch,
+	type TreeBranchEvents,
+	tryGetSchema,
+	applySchemaToParserOptions,
+	cursorFromVerbose,
+	verboseFromCursor,
+	conciseFromCursor,
+	createFromCursor,
+	asTreeViewAlpha,
 } from "./api/index.js";
 export {
 	type NodeFromSchema,
@@ -111,8 +126,18 @@ export {
 	type DefaultProvider,
 	type FieldProps,
 	normalizeFieldSchema,
+	areFieldSchemaEqual,
+	areImplicitFieldSchemaEqual,
 	type ApplyKind,
 	type FieldSchemaMetadata,
+	type InsertableField,
+	type Insertable,
+	type UnsafeUnknownSchema,
+	type ApplyKindInput,
+	type InsertableTreeNodeFromAllowedTypes,
+	type Input,
+	type ReadableField,
+	type ReadSchema,
 } from "./schemaTypes.js";
 export {
 	getTreeNodeForField,
@@ -122,6 +147,7 @@ export {
 	TreeArrayNode,
 	IterableTreeArrayContent,
 	type TreeArrayNodeBase,
+	type ReadonlyArrayNode,
 } from "./arrayNode.js";
 export {
 	type FieldHasDefault,
@@ -131,8 +157,13 @@ export {
 	setField,
 } from "./objectNode.js";
 export type { TreeMapNode, MapNodeInsertableData } from "./mapNode.js";
-export { mapTreeFromNodeData, type InsertableContent } from "./toMapTree.js";
-export { toStoredSchema, getStoredSchema } from "./toFlexSchema.js";
+export {
+	mapTreeFromNodeData,
+	type InsertableContent,
+	type FactoryContent,
+	type FactoryContentObject,
+} from "./toMapTree.js";
+export { toStoredSchema, getStoredSchema } from "./toStoredSchema.js";
 export {
 	numberSchema,
 	stringSchema,

package/src/simple-tree/leafNodeSchema.ts

@@ -40,6 +40,10 @@ export class LeafNodeSchema<Name extends string, const T extends ValueSchema>
 		return data;
 	}
 
+	public createFromInsertable(data: TreeValue<T>): TreeValue<T> {
+		return data;
+	}
+
 	public constructor(name: Name, t: T) {
 		this.identifier = name;
 		this.info = t;
@@ -56,7 +60,8 @@ function makeLeaf<Name extends string, const T extends ValueSchema>(
 	`com.fluidframework.leaf.${Name}`,
 	NodeKind.Leaf,
 	TreeValue<T>,
-	TreeValue<T>
+	TreeValue<T>,
+	true
 > {
 	// Names in this domain follow https://en.wikipedia.org/wiki/Reverse_domain_name_notation
 	return new LeafNodeSchema(`com.fluidframework.leaf.${name}`, t);

package/src/simple-tree/mapNode.ts

@@ -33,6 +33,7 @@ import {
 	type Context,
 	UnhydratedFlexTreeNode,
 	getOrCreateInnerNode,
+	type InternalTreeNode,
 } from "./core/index.js";
 import {
 	mapTreeFromNodeData,
@@ -128,7 +129,10 @@ export interface TreeMapNode<T extends ImplicitAllowedTypes = ImplicitAllowedTyp
 	): void;
 }
 
-const handler: ProxyHandler<TreeMapNode> = {
+// TreeMapNode is invariant over schema type, so for this handler to work with all schema, the only possible type for the schema is `any`.
+// This is not ideal, but no alternatives are possible.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const handler: ProxyHandler<TreeMapNode<any>> = {
 	getPrototypeOf: () => {
 		return Map.prototype;
 	},
@@ -139,6 +143,10 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 > {
 	public static readonly kind = NodeKind.Map;
 
+	public constructor(input?: InternalTreeNode | MapNodeInsertableData<T> | undefined) {
+		super(input ?? []);
+	}
+
 	public [Symbol.iterator](): IterableIterator<[string, TreeNodeFromImplicitAllowedTypes<T>]> {
 		return this.entries();
 	}
@@ -177,7 +185,7 @@ abstract class CustomMapNodeBase<const T extends ImplicitAllowedTypes> extends T
 		const node = this.innerNode;
 		return node.keys();
 	}
-	public set(key: string, value: InsertableTreeNodeFromImplicitAllowedTypes<T>): TreeMapNode {
+	public set(key: string, value: InsertableTreeNodeFromImplicitAllowedTypes<T>): this {
 		const kernel = getKernel(this);
 		const node = this.innerNode;
 		const mapTree = mapTreeFromNodeData(
@@ -244,7 +252,7 @@ export function mapSchema<
 			flexNode: FlexTreeNode,
 		): TreeNodeValid<T2> {
 			if (useMapPrototype) {
-				return new Proxy<Schema>(instance as Schema, handler);
+				return new Proxy<Schema>(instance as Schema, handler as ProxyHandler<Schema>);
 			}
 			return instance;
 		}
@@ -290,7 +298,8 @@ export function mapSchema<
 		TreeMapNode<T> & WithType<TName, NodeKind.Map>,
 		MapNodeInsertableData<T>,
 		ImplicitlyConstructable,
-		T
+		T,
+		undefined
 	> = Schema;
 	return schemaErased;
 }

package/src/simple-tree/objectNode.ts

@@ -98,6 +98,8 @@ export type FieldHasDefault<T extends ImplicitFieldSchema> = T extends FieldSche
  *
  * 3. Union of 1 and 2.
  *
+ * @see {@link Input}
+ *
  * @privateRemarks TODO: consider separating these cases into different types.
  *
  * @system @public
@@ -107,13 +109,13 @@ export type InsertableObjectFromSchemaRecord<
 > = FlattenKeys<
 	{
 		readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<
-			T[Property] & string
+			T[Property & string]
 		>;
 	} & {
 		// Field does not have a known default, make it required:
-		readonly [Property in keyof T as FieldHasDefault<T[Property] & string> extends false
+		readonly [Property in keyof T as FieldHasDefault<T[Property & string]> extends false
 			? Property
-			: never]: InsertableTreeFieldFromImplicitField<T[Property] & string>;
+			: never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
 	}
 >;