@fluidframework/tree 2.4.0 → 2.5.0

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

@@ -13,8 +13,10 @@ import type {
 	InternalTreeNode,
 	NodeKind,
 	TreeNode,
+	TreeNodeSchema,
 	TreeNodeSchemaClass,
 } from "../core/index.js";
+import type { UnionToTuple } from "../../util/index.js";
 
 /*
  * This file does two things:
@@ -40,7 +42,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 	name: TName,
 ) {
 	class SingletonSchema extends factory.object(name, {}) {
-		public constructor(data?: InternalTreeNode) {
+		public constructor(data?: InternalTreeNode | Record<string, never>) {
 			super(data ?? {});
 		}
 		public get value(): TName {
@@ -48,7 +50,7 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 		}
 	}
 
-	type NodeType = TreeNode & { readonly value: TName };
+	type SingletonNodeType = TreeNode & { readonly value: TName };
 
 	// Returning SingletonSchema without a type conversion results in TypeScript generating something like `readonly "__#124291@#brand": unknown;`
 	// for the private brand field of TreeNode.
@@ -58,11 +60,12 @@ export function singletonSchema<TScope extends string, TName extends string | nu
 	const toReturn: TreeNodeSchemaClass<
 		ScopedSchemaName<TScope, TName>,
 		NodeKind.Object,
-		NodeType,
-		never,
-		true
-	> &
-		(new () => NodeType) = SingletonSchema;
+		SingletonNodeType,
+		Record<string, never>,
+		true,
+		Record<string, never>,
+		undefined
+	> = SingletonSchema;
 
 	return toReturn;
 }
@@ -84,15 +87,14 @@ export function singletonSchema<TScope extends string, TName extends string | nu
  * // Define the schema for each member of the enum using a nested scope to group them together.
  * const ModeNodes = adaptEnum(new SchemaFactory(`${schemaFactory.scope}.Mode`), Mode);
  * // Defined the types of the nodes which correspond to this the schema.
- * type ModeNodes = NodeFromSchema<(typeof ModeNodes)[keyof typeof ModeNodes]>;
+ * type ModeNodes = NodeFromSchema<(typeof ModeNodes.schema)[number]>;
  * // An example schema which has an enum as a child.
  * class Parent extends schemaFactory.object("Parent", {
- * 	// typedObjectValues extracts a list of all the fields of ModeNodes, which are the schema for each enum member.
- * 	// This means any member of the enum is allowed in this field.
- * 	mode: typedObjectValues(ModeNodes),
+ * 	// adaptEnum's return value has a ".schema" property can be use as an `AllowedTypes` array allowing any of the members of the enum.
+ * 	mode: ModeNodes.schema,
  * }) {}
  *
- * // Example usage of enum-based nodes, showing what type to use and that `.value` can be used to read out the enum value.
+ * // Example usage of enum based nodes, showing what type to use and that `.value` can be used to read out the enum value.
  * function getValue(node: ModeNodes): Mode {
  * 	return node.value;
  * }
@@ -131,35 +133,36 @@ export function adaptEnum<
 			typeof singletonSchema<TScope, TEnum[Property]>
 		>;
 	};
+
+	type SchemaArray = UnionToTuple<TOut[keyof TEnum]>;
+	const schemaArray: TreeNodeSchema[] = [];
+
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 	const factoryOut = <TValue extends Values>(value: TValue) => {
 		return new out[inverse.get(value) ?? fail("missing enum value")]() as NodeFromSchema<
 			ReturnType<typeof singletonSchema<TScope, TValue>>
 		>;
 	};
-	const out = factoryOut as typeof factoryOut & TOut;
+	const out = factoryOut as typeof factoryOut & TOut & { readonly schema: SchemaArray };
 	for (const [key, value] of Object.entries(members)) {
+		const schema = singletonSchema(factory, value);
+		schemaArray.push(schema);
 		Object.defineProperty(out, key, {
 			enumerable: true,
 			configurable: false,
 			writable: false,
-			value: singletonSchema(factory, value),
+			value: schema,
 		});
 	}
 
-	return out;
-}
+	Object.defineProperty(out, "schema", {
+		enumerable: true,
+		configurable: false,
+		writable: false,
+		value: schemaArray,
+	});
 
-/**
- * `Object.values`, but with more specific types.
- * @remarks
- * Useful with collections of schema, like those returned by {@link adaptEnum} or {@link enumFromStrings}.
- * @alpha
- */
-export function typedObjectValues<TKey extends string, TValues>(
-	object: Record<TKey, TValues>,
-): TValues[] {
-	return Object.values(object);
+	return out;
 }
 
 /**
@@ -171,44 +174,63 @@ export function typedObjectValues<TKey extends string, TValues>(
  * The produced nodes use the provided strings as their `name`, and don't store any data beyond that.
  * @example
  * ```typescript
+ * const schemaFactory = new SchemaFactory("com.myApp");
  * const Mode = enumFromStrings(schemaFactory, ["Fun", "Cool"]);
- * type Mode = NodeFromSchema<(typeof Mode)[keyof typeof Mode]>;
+ * type Mode = NodeFromSchema<(typeof Mode.schema)[number]>;
  * const nodeFromString: Mode = Mode("Fun");
  * const nodeFromSchema: Mode = new Mode.Fun();
- * const nameFromNode = nodeFromSchema.value;
  *
- * class Parent extends schemaFactory.object("Parent", { mode: typedObjectValues(Mode) }) {}
+ * // Schema nodes have a strongly typed `.value` property.
+ * const nameFromNode: "Fun" | "Cool" = nodeFromSchema.value;
+ *
+ * class Parent extends schemaFactory.object("Parent", { mode: Mode.schema }) {}
  * ```
  * @see {@link adaptEnum} for a similar function that works on enums instead of arrays of strings.
  * @alpha
  */
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-export function enumFromStrings<TScope extends string, const Members extends string>(
-	factory: SchemaFactory<TScope>,
-	members: readonly Members[],
-) {
+export function enumFromStrings<
+	TScope extends string,
+	const Members extends readonly string[],
+>(factory: SchemaFactory<TScope>, members: Members) {
 	const names = new Set(members);
 	if (names.size !== members.length) {
 		throw new UsageError("All members of enums must have distinct names");
 	}
 
-	type TOut = Record<Members, ReturnType<typeof singletonSchema<TScope, Members>>>;
+	type TOut = Record<
+		Members[number],
+		ReturnType<typeof singletonSchema<TScope, Members[number]>>
+	>;
 	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
-	const factoryOut = <TValue extends Members>(value: TValue) => {
+	const factoryOut = <TValue extends Members[number]>(value: TValue) => {
 		return new out[value]() as NodeFromSchema<
 			ReturnType<typeof singletonSchema<TScope, TValue>>
 		>;
 	};
-	const out = factoryOut as typeof factoryOut & TOut;
+
+	type SchemaArray = UnionToTuple<TOut[Members[number]]>;
+	const schemaArray: TreeNodeSchema[] = [];
+
+	const out = factoryOut as typeof factoryOut & TOut & { readonly schema: SchemaArray };
 	for (const name of members) {
+		const schema = singletonSchema(factory, name);
+		schemaArray.push(schema);
 		Object.defineProperty(out, name, {
 			enumerable: true,
 			configurable: false,
 			writable: false,
-			value: singletonSchema(factory, name),
+			value: schema,
 		});
 	}
 
+	Object.defineProperty(out, "schema", {
+		enumerable: true,
+		configurable: false,
+		writable: false,
+		value: schemaArray,
+	});
+
 	return out;
 }
 

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

@@ -120,6 +120,10 @@ export type ScopedSchemaName<
  * Typically this is just `string` but it is also possible to use `string` or `number` based enums if you prefer to identify your types that way.
  *
  * @remarks
+ * For details related to inputting data constrained by schema (including via assignment), and how non-exact schema types are handled in general refer to {@link Input}.
+ * For information about recursive schema support, see methods postfixed with "recursive" and {@link ValidateRecursiveSchema}.
+ * To apply schema defined with this factory to a tree, see {@link ViewableTree.viewWith} and {@link TreeViewConfiguration}.
+ *
  * All schema produced by this factory get a {@link TreeNodeSchemaCore.identifier|unique identifier} by combining the {@link SchemaFactory.scope} with the schema's `Name`.
  * The `Name` part may be explicitly provided as a parameter, or inferred as a structural combination of the provided types.
  * The APIs which use this second approach, structural naming, also deduplicate all equivalent calls.
@@ -337,7 +341,8 @@ export class SchemaFactory<
 		TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map>,
 		MapNodeInsertableData<T>,
 		true,
-		T
+		T,
+		undefined
 	>;
 
 	/**
@@ -359,7 +364,8 @@ export class SchemaFactory<
 		TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
 		MapNodeInsertableData<T>,
 		true,
-		T
+		T,
+		undefined
 	>;
 
 	/**
@@ -391,7 +397,8 @@ export class SchemaFactory<
 				TreeMapNode<T>,
 				MapNodeInsertableData<T>,
 				true,
-				T
+				T,
+				undefined
 			>;
 		}
 		// To actually have type safety, assign to the type this method should return before implicitly upcasting when returning.
@@ -401,7 +408,8 @@ export class SchemaFactory<
 			TreeMapNode<T>,
 			MapNodeInsertableData<T>,
 			true,
-			T
+			T,
+			undefined
 		> = this.namedMap(nameOrAllowedTypes as TName, allowedTypes, true, true);
 		return out;
 	}
@@ -426,7 +434,8 @@ export class SchemaFactory<
 		TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,
 		MapNodeInsertableData<T>,
 		ImplicitlyConstructable,
-		T
+		T,
+		undefined
 	> {
 		return mapSchema(
 			this.scoped(name),
@@ -478,7 +487,8 @@ export class SchemaFactory<
 		TreeArrayNode<T> & WithType<ScopedSchemaName<TScope, `Array<${string}>`>, NodeKind.Array>,
 		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 		true,
-		T
+		T,
+		undefined
 	>;
 
 	/**
@@ -502,7 +512,8 @@ export class SchemaFactory<
 		TreeArrayNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,
 		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 		true,
-		T
+		T,
+		undefined
 	>;
 
 	/**
@@ -531,7 +542,8 @@ export class SchemaFactory<
 				TreeArrayNode<T>,
 				Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 				true,
-				T
+				T,
+				undefined
 			>;
 		}
 		const out: TreeNodeSchemaBoth<
@@ -540,7 +552,8 @@ export class SchemaFactory<
 			TreeArrayNode<T>,
 			Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 			true,
-			T
+			T,
+			undefined
 		> = this.namedArray(nameOrAllowedTypes as TName, allowedTypes, true, true);
 		return out;
 	}
@@ -569,7 +582,8 @@ export class SchemaFactory<
 		TreeArrayNode<T> & WithType<ScopedSchemaName<TScope, string>, NodeKind.Array>,
 		Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,
 		ImplicitlyConstructable,
-		T
+		T,
+		undefined
 	> {
 		return arraySchema(this.scoped(name), allowedTypes, implicitlyConstructable, customizable);
 	}
@@ -743,7 +757,8 @@ export class SchemaFactory<
 				[Symbol.iterator](): Iterator<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>;
 			},
 			false,
-			T
+			T,
+			undefined
 		>;
 	}
 
@@ -789,7 +804,8 @@ export class SchemaFactory<
 			// Ideally this would be included, but doing so breaks recursive types.
 			// | RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,
 			false,
-			T
+			T,
+			undefined
 		>;
 	}
 }

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

@@ -97,7 +97,7 @@ function convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSch
 	});
 
 	const items: JsonFieldSchema =
-		allowedTypes.length === 1 ? allowedTypes[0] ?? oob() : { anyOf: allowedTypes };
+		allowedTypes.length === 1 ? (allowedTypes[0] ?? oob()) : { anyOf: allowedTypes };
 
 	return {
 		type: "array",
@@ -144,7 +144,7 @@ function convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNode
 
 		const output: Mutable<JsonFieldSchema> =
 			allowedTypes.length === 1
-				? allowedTypes[0] ?? oob()
+				? (allowedTypes[0] ?? oob())
 				: {
 						anyOf: allowedTypes,
 					};
@@ -180,7 +180,7 @@ function convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {
 		patternProperties: {
 			"^.*$":
 				allowedTypes.length === 1
-					? allowedTypes[0] ?? oob()
+					? (allowedTypes[0] ?? oob())
 					: {
 							anyOf: allowedTypes,
 						},

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

@@ -11,12 +11,16 @@ import type { Listenable } from "../../events/index.js";
 
 import {
 	type ImplicitFieldSchema,
+	type InsertableField,
 	type InsertableTreeFieldFromImplicitField,
+	type ReadableField,
+	type ReadSchema,
 	type TreeFieldFromImplicitField,
+	type UnsafeUnknownSchema,
 	FieldKind,
 } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
-import { toStoredSchema } from "../toFlexSchema.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";
@@ -26,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 {
@@ -45,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.
 	 *
@@ -190,8 +202,9 @@ export interface ITreeViewConfiguration<
  * Configuration for {@link ViewableTree.viewWith}.
  * @sealed @public
  */
-export class TreeViewConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema>
-	implements Required<ITreeViewConfiguration<TSchema>>
+export class TreeViewConfiguration<
+	const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
+> implements Required<ITreeViewConfiguration<TSchema>>
 {
 	protected _typeCheck!: MakeNominal;
 
@@ -238,7 +251,7 @@ export class TreeViewConfiguration<TSchema extends ImplicitFieldSchema = Implici
 		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.
@@ -346,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.
  *
@@ -363,7 +454,7 @@ export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): v
  * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.
  * @sealed @public
  */
-export interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposable {
+export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {
 	/**
 	 * The current root of the tree.
 	 *
@@ -424,6 +515,24 @@ export interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposab
 	readonly schema: TSchema;
 }
 
+/**
+ * {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.
+ * @sealed @alpha
+ */
+export interface TreeViewAlpha<
+	in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
+> extends Omit<TreeView<ReadSchema<TSchema>>, "root" | "initialize">,
+		Omit<TreeBranch, "events"> {
+	get root(): ReadableField<TSchema>;
+
+	set root(newRoot: InsertableField<TSchema>);
+
+	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>;
+}
+
 /**
  * Information about a view schema's compatibility with the document's stored schema.
  *
@@ -491,7 +600,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;
 
@@ -500,6 +609,32 @@ 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 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
@@ -539,3 +674,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>;
+}