@fluidframework/tree 2.5.0-302463 → 2.10.0-304831

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

@@ -14,7 +14,7 @@ import {
 import type { Format } from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
 import type { ImplicitFieldSchema } from "../schemaTypes.js";
-import { toStoredSchema } from "../toFlexSchema.js";
+import { toStoredSchema } from "../toStoredSchema.js";
 import type { SchemaCompatibilityStatus } from "./tree.js";
 import { ViewSchema } from "./view.js";
 

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

@@ -13,13 +13,14 @@ import {
 	type ImplicitFieldSchema,
 	type InsertableField,
 	type InsertableTreeFieldFromImplicitField,
+	type ReadableField,
+	type ReadSchema,
 	type TreeFieldFromImplicitField,
-	type TreeLeafValue,
 	type UnsafeUnknownSchema,
 	FieldKind,
 } from "../schemaTypes.js";
-import { NodeKind, type TreeNode, type TreeNodeSchema } from "../core/index.js";
-import { toStoredSchema } from "../toFlexSchema.js";
+import { NodeKind, type TreeNodeSchema } from "../core/index.js";
+import { toStoredSchema } from "../toStoredSchema.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
 import { assert } from "@fluidframework/core-utils/internal";
 import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js";
@@ -29,6 +30,14 @@ import type { MakeNominal } from "../../util/index.js";
 import { walkFieldSchema } from "../walkFieldSchema.js";
 /**
  * A tree from which a {@link TreeView} can be created.
+ *
+ * @privateRemarks
+ * TODO:
+ * Add stored key versions of {@link TreeAlpha.(exportVerbose:2)}, {@link TreeAlpha.(exportConcise:2)} and {@link TreeAlpha.exportCompressed} here so tree content can be accessed without a view schema.
+ * Add exportSimpleSchema and exportJsonSchema methods (which should exactly match the concise format, and match the free functions for exporting view schema).
+ * Maybe rename "exportJsonSchema" to align on "concise" terminology.
+ * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).
+ * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).
  * @system @sealed @public
  */
 export interface ViewableTree {
@@ -48,7 +57,7 @@ export interface ViewableTree {
 	 * Only one schematized view may exist for a given ITree at a time.
 	 * If creating a second, the first must be disposed before calling `viewWith` again.
 	 *
-	 * @privateRemarks
+	 *
 	 * TODO: Provide a way to make a generic view schema for any document.
 	 * TODO: Support adapters for handling out-of-schema data.
 	 *
@@ -242,7 +251,7 @@ export class TreeViewConfiguration<
 		if (ambiguityErrors.length !== 0) {
 			// Duplicate errors are common since when two types conflict, both orders error:
 			const deduplicated = new Set(ambiguityErrors);
-			throw new UsageError(`Ambigious schema found:\n${[...deduplicated].join("\n")}`);
+			throw new UsageError(`Ambiguous schema found:\n${[...deduplicated].join("\n")}`);
 		}
 
 		// Eagerly perform this conversion to surface errors sooner.
@@ -350,6 +359,84 @@ export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): v
 	}
 }
 
+/**
+ * A collection of functionality associated with a (version-control-style) branch of a SharedTree.
+ * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork | creation of branches} and for those branches to later be {@link TreeBranch.merge | merged}.
+ *
+ * The `TreeBranch` for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.branch`.
+ *
+ * A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha | view with a schema}, use {@link TreeBranch.hasRootSchema | hasRootSchema()}.
+ *
+ * The branch associated directly with the {@link ITree | SharedTree} is the "main" branch, and all other branches fork (directly or transitively) from that main branch.
+ * @sealed @alpha
+ */
+export interface TreeBranch extends IDisposable {
+	/**
+	 * Events for the branch
+	 */
+	readonly events: Listenable<TreeBranchEvents>;
+
+	/**
+	 * Returns true if this branch has the given schema as its root schema.
+	 * @remarks This is a type guard which allows this branch to become strongly typed as a {@link TreeViewAlpha | view} of the given schema.
+	 *
+	 * To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types.
+	 * For example, a schema of `Foo | Bar` will not match a view schema of `Foo`, and likewise a schema of `Foo` will not match a view schema of `Foo | Bar`.
+	 * @example
+	 * ```typescript
+	 * if (branch.hasRootSchema(MySchema)) {
+	 *   const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>
+	 *   // ...
+	 * }
+	 * ```
+	 */
+	hasRootSchema<TSchema extends ImplicitFieldSchema>(
+		schema: TSchema,
+	): this is TreeViewAlpha<TSchema>;
+
+	/**
+	 * Fork a new branch off of this branch which is based off of this branch's current state.
+	 * @remarks Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. {@link TreeBranch.merge | merged} back into this branch.
+	 * The branch should be disposed when no longer needed, either {@link TreeBranch.dispose | explicitly} or {@link TreeBranch.merge | implicitly when merging} into another branch.
+	 */
+	fork(): TreeBranch;
+
+	/**
+	 * Apply all the new changes on the given branch to this branch.
+	 * @param branch - a branch which was created by a call to `branch()`.
+	 * @param disposeMerged - whether or not to dispose `branch` after the merge completes.
+	 * Defaults to true.
+	 * The {@link TreeBranch | main branch} cannot be disposed - attempting to do so will have no effect.
+	 * @remarks All ongoing transactions (if any) in `branch` will be committed before the merge.
+	 */
+	merge(branch: TreeBranch, disposeMerged?: boolean): void;
+
+	/**
+	 * Advance this branch forward such that all new changes on the target branch become part of this branch.
+	 * @param branch - The branch to rebase onto.
+	 * @remarks After rebasing, this branch will be "ahead" of the target branch, that is, its unique changes will have been recreated as if they happened after all changes on the target branch.
+	 * This method may only be called on branches produced via {@link TreeBranch.fork | branch} - attempting to rebase the main branch will throw.
+	 *
+	 * Rebasing long-lived branches is important to avoid consuming memory unnecessarily.
+	 * In particular, the SharedTree retains all sequenced changes made to the tree since the "most-behind" branch was created or last rebased.
+	 *
+	 * The {@link TreeBranch | main branch} cannot be rebased onto another branch - attempting to do so will throw an error.
+	 */
+	rebaseOnto(branch: TreeBranch): void;
+
+	/**
+	 * Dispose of this branch, cleaning up any resources associated with it.
+	 * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.
+	 * @remarks Branches can also be automatically disposed when {@link TreeBranch.merge | they are merged} into another branch.
+	 *
+	 * Disposing branches is important to avoid consuming memory unnecessarily.
+	 * In particular, the SharedTree retains all sequenced changes made to the tree since the "most-behind" branch was created or last {@link TreeBranch.rebaseOnto | rebased}.
+	 *
+	 * The {@link TreeBranch | main branch} cannot be disposed - attempting to do so will have no effect.
+	 */
+	dispose(error?: Error): void;
+}
+
 /**
  * An editable view of a (version control style) branch of a shared tree based on some schema.
  *
@@ -430,21 +517,22 @@ export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends ID
 
 /**
  * {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.
- * @alpha
+ * @sealed @alpha
  */
 export interface TreeViewAlpha<
 	in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
-> extends Omit<
-		TreeView<TSchema extends ImplicitFieldSchema ? TSchema : ImplicitFieldSchema>,
-		"root" | "initialize"
-	> {
-	get root(): TSchema extends ImplicitFieldSchema
-		? TreeFieldFromImplicitField<TSchema>
-		: TreeLeafValue | TreeNode;
+> extends Omit<TreeView<ReadSchema<TSchema>>, "root" | "initialize">,
+		TreeBranch {
+	get root(): ReadableField<TSchema>;
 
 	set root(newRoot: InsertableField<TSchema>);
 
+	readonly events: Listenable<TreeViewEvents & TreeBranchEvents>;
+
 	initialize(content: InsertableField<TSchema>): void;
+
+	// Override the base branch method to return a typed view rather than merely a branch.
+	fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>;
 }
 
 /**
@@ -514,7 +602,7 @@ export interface SchemaCompatibilityStatus {
 	 *
 	 * @remarks
 	 * It's not necessary to check this field before calling {@link TreeView.initialize} in most scenarios; application authors typically know from
-	 * context that they're in a flow which creates a new `SharedTree` and would like to initialize it.
+	 * branch that they're in a flow which creates a new `SharedTree` and would like to initialize it.
 	 */
 	readonly canInitialize: boolean;
 
@@ -523,6 +611,42 @@ export interface SchemaCompatibilityStatus {
 	// - details about the differences between the stored and view schema sufficient for implementing "safe mismatch" policies
 }
 
+/**
+ * Events for {@link TreeBranch}.
+ * @sealed @alpha
+ */
+export interface TreeBranchEvents {
+	/**
+	 * The stored schema for the document has changed.
+	 */
+	schemaChanged(): void;
+
+	/**
+	 * Fired when a change is made to the branch. Includes data about the change that is made which listeners
+	 * can use to filter on changes they care about (e.g. local vs. remote changes).
+	 *
+	 * @param data - information about the change
+	 * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,
+	 * this change is not revertible.
+	 */
+	changed(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+
+	/**
+	 * Fired when:
+	 * - a local commit is applied outside of a transaction
+	 * - a local transaction is committed
+	 *
+	 * The event is not fired when:
+	 * - a local commit is applied within a transaction
+	 * - a remote commit is applied
+	 *
+	 * @param data - information about the commit that was applied
+	 * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,
+	 * this commit is not revertible.
+	 */
+	commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+}
+
 /**
  * Events for {@link TreeView}.
  * @sealed @public
@@ -562,3 +686,13 @@ export interface TreeViewEvents {
 	 */
 	commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
 }
+
+/**
+ * Retrieve the {@link TreeViewAlpha | alpha API} for a {@link TreeView}.
+ * @alpha
+ */
+export function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(
+	view: TreeView<TSchema>,
+): TreeViewAlpha<TSchema> {
+	return view as TreeViewAlpha<TSchema>;
+}

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

@@ -12,14 +12,9 @@ import {
 	type Unhydrated,
 	type WithType,
 } from "../core/index.js";
-import type {
-	ImplicitFieldSchema,
-	TreeFieldFromImplicitField,
-	UnsafeUnknownSchema,
-} from "../schemaTypes.js";
 import { treeNodeApi } from "./treeNodeApi.js";
-import { createFromCursor, cursorFromInsertable } from "./create.js";
-import type { ITreeCursorSynchronous } from "../../core/index.js";
+import { createFromCursor } from "./create.js";
+import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../schemaTypes.js";
 
 /**
  * Data included for {@link TreeChangeEventsBeta.nodeChanged}.
@@ -113,18 +108,40 @@ export const TreeBeta: {
 	): () => void;
 
 	/**
-	 * Clones the persisted data associated with a node. Some key things to note:
+	 * Clones the persisted data associated with a node.
+	 *
+	 * @param node - The node to clone.
+	 * @returns A new unhydrated node with the same persisted data as the original node.
+	 * @remarks
+	 * 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>(
+	clone<const TSchema extends ImplicitFieldSchema>(
 		node: TreeFieldFromImplicitField<TSchema>,
 	): TreeFieldFromImplicitField<TSchema>;
+
+	// TODO: support more clone options
+	// /**
+	//  * Like {@link TreeBeta.create}, except deeply clones existing nodes.
+	//  * @remarks
+	//  * This only clones the persisted data associated with a node.
+	//  * Local state, such as properties added to customized schema classes, will not be cloned:
+	//  * they will be initialized however they end up after running the constructor, just like if a remote client had inserted the same nodes.
+	//  */
+	// clone<const TSchema extends ImplicitFieldSchema>(
+	// 	original: TreeFieldFromImplicitField<TSchema>,
+	// 	options?: {
+	// 		/**
+	// 		 * If set, all identifier's in the cloned tree (See {@link SchemaFactory.identifier}) will be replaced with new ones allocated using the default identifier allocation schema.
+	// 		 * Otherwise any identifiers will be preserved as is.
+	// 		 */
+	// 		replaceIdentifiers?: true;
+	// 	},
+	// ): TreeFieldFromImplicitField<TSchema>;
 } = {
 	on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(
 		node: TNode,
@@ -133,35 +150,18 @@ export const TreeBeta: {
 	): () => void {
 		return treeNodeApi.on(node, eventName, listener);
 	},
-	clone<TSchema extends ImplicitFieldSchema>(
+	clone<const 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. */
+		/** The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (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<UnsafeUnknownSchema>(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;
+		const cursor = kernel.getOrCreateInnerNode().borrowCursor();
+		return createFromCursor(kernel.schema, cursor) as Unhydrated<
+			TreeFieldFromImplicitField<TSchema>
+		>;
 	},
 };

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

@@ -23,7 +23,7 @@ import type {
 	TreeNodeSchema,
 	TreeNodeSchemaCore,
 } from "../core/index.js";
-import type { TreeArrayNodeBase } from "../arrayNode.js";
+import type { TreeArrayNode } from "../arrayNode.js";
 import type { FlexListToUnion, LazyItem } from "../flexList.js";
 
 /*
@@ -86,8 +86,7 @@ export type TreeNodeSchemaUnsafe<
 export interface TreeNodeSchemaClassUnsafe<
 	out Name extends string,
 	out Kind extends NodeKind,
-	// TODO: maybe this can be more specific (exclude leaves)
-	out TNode extends Unenforced<TreeNode | TreeLeafValue>,
+	out TNode extends Unenforced<TreeNode>,
 	in TInsertable,
 	out ImplicitlyConstructable extends boolean,
 	out Info,
@@ -239,7 +238,8 @@ export type NodeBuilderDataUnsafe<T extends Unenforced<TreeNodeSchema>> =
  * @system @sealed @public
  */
 export interface TreeArrayNodeUnsafe<TAllowedTypes extends Unenforced<ImplicitAllowedTypes>>
-	extends TreeArrayNodeBase<
+	extends TreeArrayNode<
+		TAllowedTypes,
 		TreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>,
 		InsertableTreeNodeFromImplicitAllowedTypesUnsafe<TAllowedTypes>
 	> {}

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

@@ -53,6 +53,7 @@ import { getUnhydratedContext } from "../createContext.js";
  * @privateRemarks
  * This can store all possible simple trees,
  * but it can not store all possible trees representable by our internal representations like FlexTree and JsonableTree.
+ * @alpha
  */
 export type VerboseTree<THandle = IFluidHandle> =
 	| VerboseTreeNode<THandle>
@@ -82,6 +83,7 @@ export type VerboseTree<THandle = IFluidHandle> =
  * Unlike `JsonableTree`, leaf nodes are not boxed into node objects, and instead have their schema inferred from the value.
  * Additionally, sequence fields can only occur on a node that has a single sequence field (with the empty key)
  * replicating the behavior of simple-tree ArrayNodes.
+ * @alpha
  */
 export interface VerboseTreeNode<THandle = IFluidHandle> {
 	/**
@@ -109,6 +111,7 @@ export interface VerboseTreeNode<THandle = IFluidHandle> {
 
 /**
  * Options for how to interpret a `VerboseTree<TCustom>` when schema information is available.
+ * @alpha
  */
 export interface ParseOptions<TCustom> {
 	/**

package/src/simple-tree/arrayNode.ts

@@ -46,6 +46,7 @@ import {
 } from "./core/index.js";
 import { TreeNodeValid, type MostDerivedData } from "./treeNodeValid.js";
 import { getUnhydratedContext } from "./createContext.js";
+import type { Unenforced } from "./api/index.js";
 
 /**
  * A covariant base type for {@link (TreeArrayNode:interface)}.
@@ -61,15 +62,25 @@ export interface ReadonlyArrayNode<out T = TreeNode | TreeLeafValue>
 		Awaited<TreeNode & WithType<string, NodeKind.Array>> {}
 
 /**
- * A generic array type, used to defined types like {@link (TreeArrayNode:interface)}.
+ * A {@link TreeNode} which implements 'readonly T[]' and the array mutation APIs.
  *
- * @privateRemarks
- * Inlining this into TreeArrayNode causes recursive array use to stop compiling.
+ * @typeParam TAllowedTypes - Schema for types which are allowed as members of this array.
+ * @typeParam T - Use Default: Do not specify. Type of values to read from the array.
+ * @typeParam TNew - Use Default: Do not specify. Type of values to write into the array.
+ * @typeParam TMoveFrom - Use Default: Do not specify. Type of node from which children can be moved into this array.
  *
- * @system @sealed @public
+ * @sealed @public
  */
-export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom = ReadonlyArrayNode>
-	extends ReadonlyArrayNode<T> {
+export interface TreeArrayNode<
+	TAllowedTypes extends Unenforced<ImplicitAllowedTypes> = ImplicitAllowedTypes,
+	out T = [TAllowedTypes] extends [ImplicitAllowedTypes]
+		? TreeNodeFromImplicitAllowedTypes<TAllowedTypes>
+		: TreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
+	in TNew = [TAllowedTypes] extends [ImplicitAllowedTypes]
+		? InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
+		: InsertableTreeNodeFromImplicitAllowedTypes<ImplicitAllowedTypes>,
+	in TMoveFrom = ReadonlyArrayNode,
+> extends ReadonlyArrayNode<T> {
 	/**
 	 * Inserts new item(s) at a specified location.
 	 * @param index - The index at which to insert `value`.
@@ -369,20 +380,6 @@ export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom = ReadonlyArrayN
 	values(): IterableIterator<T>;
 }
 
-/**
- * A {@link TreeNode} which implements 'readonly T[]' and the array mutation APIs.
- *
- * @typeParam TAllowedTypes - Schema for types which are allowed as members of this array.
- *
- * @sealed @public
- */
-export interface TreeArrayNode<
-	TAllowedTypes extends ImplicitAllowedTypes = ImplicitAllowedTypes,
-> extends TreeArrayNodeBase<
-		TreeNodeFromImplicitAllowedTypes<TAllowedTypes>,
-		InsertableTreeNodeFromImplicitAllowedTypes<TAllowedTypes>
-	> {}
-
 /**
  * A {@link TreeNode} which implements 'readonly T[]' and the array mutation APIs.
  * @public
@@ -816,9 +813,9 @@ abstract class CustomArrayNodeBase<const T extends ImplicitAllowedTypes>
 	>;
 
 	public constructor(
-		input: Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>> | InternalTreeNode,
+		input?: Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>> | InternalTreeNode,
 	) {
-		super(input);
+		super(input ?? []);
 	}
 
 	#mapTreesFromFieldData(value: Insertable<T>): ExclusiveMapTree[] {
@@ -1077,7 +1074,8 @@ export function arraySchema<
 		TreeArrayNode<T> & WithType<TName, NodeKind.Array>,
 		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 		ImplicitlyConstructable,
-		T
+		T,
+		undefined
 	>;
 
 	const lazyChildTypes = new Lazy(() => normalizeAllowedTypes(info));

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

@@ -31,7 +31,7 @@ export function getOrCreateNodeFromInnerNode(flexNode: InnerNode): TreeNode | Tr
 	const node = flexNode as unknown as InternalTreeNode;
 	// eslint-disable-next-line unicorn/prefer-ternary
 	if (typeof classSchema === "function") {
-		return new classSchema(node) as TreeNode;
+		return new classSchema(node);
 	} else {
 		return (classSchema as { create(data: FlexTreeNode): TreeValue }).create(flexNode);
 	}

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

@@ -28,7 +28,9 @@ export type TreeNodeSchema<
 	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>;
 
 /**
@@ -39,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 extends TreeNode | TreeLeafValue = TreeNode | TreeLeafValue,
-	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.
@@ -95,24 +111,40 @@ export interface TreeNodeSchemaNonClass<
  * ```
  * @sealed @public
  */
-export interface TreeNodeSchemaClass<
-	out Name extends string = string,
-	out Kind extends NodeKind = NodeKind,
-	// TODO: maybe this can be more specific (exclude leaves)
-	out TNode extends TreeNode | TreeLeafValue = TreeNode | TreeLeafValue,
-	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.
@@ -124,8 +156,25 @@ export type TreeNodeSchemaBoth<
 	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.
@@ -138,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.
@@ -193,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>;
 }
 
 /**