@fluidframework/tree 2.33.2 → 2.40.0

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

@@ -3,9 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, fail } from "@fluidframework/core-utils/internal";
 import type { IFluidLoadable, IDisposable, Listenable } from "@fluidframework/core-interfaces";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type {
 	CommitMetadata,
@@ -19,28 +17,17 @@ import type {
 	TreeAlpha,
 } from "../../shared-tree/index.js";
 
-import {
-	type FieldSchemaAlpha,
-	type ImplicitFieldSchema,
-	type InsertableField,
-	type InsertableTreeFieldFromImplicitField,
-	type ReadableField,
-	type ReadSchema,
-	type TreeFieldFromImplicitField,
-	type UnsafeUnknownSchema,
-	FieldKind,
-	markSchemaMostDerived,
-	normalizeFieldSchema,
+import type {
+	ImplicitFieldSchema,
+	InsertableField,
+	InsertableTreeFieldFromImplicitField,
+	ReadableField,
+	ReadSchema,
+	TreeFieldFromImplicitField,
+	UnsafeUnknownSchema,
 } from "../schemaTypes.js";
-import { NodeKind, type TreeNodeSchema } from "../core/index.js";
-import { toStoredSchema } from "../toStoredSchema.js";
-import { LeafNodeSchema } from "../leafNodeSchema.js";
-import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js";
-import { getOrCreate } from "../../util/index.js";
-import type { MakeNominal } from "../../util/index.js";
-import { walkFieldSchema } from "../walkFieldSchema.js";
 import type { VerboseTree } from "./verboseTree.js";
-import type { SimpleNodeSchema, SimpleTreeSchema } from "../simpleSchema.js";
+import type { SimpleTreeSchema } from "../simpleSchema.js";
 import type {
 	RunTransactionParams,
 	TransactionCallbackStatus,
@@ -48,12 +35,14 @@ import type {
 	TransactionResultExt,
 	VoidTransactionCallbackStatus,
 } from "./transactionTypes.js";
+import type { TreeViewConfiguration } from "./configuration.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 stored key versions of {@link (TreeAlpha:interface).(exportVerbose:2)}, {@link (TreeAlpha:interface).(exportConcise:2)} and {@link (TreeAlpha:interface).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).
@@ -99,7 +88,7 @@ export interface ITree extends ViewableTree, IFluidLoadable {}
  */
 export interface ITreeAlpha extends ITree {
 	/**
-	 * Exports root in the same format as {@link TreeAlpha.(exportVerbose:1)} using stored keys.
+	 * Exports root in the same format as {@link (TreeAlpha:interface).(exportVerbose:1)} using stored keys.
 	 * @remarks
 	 * This is `undefined` if and only if the root field is empty (this can only happen if the root field is optional).
 	 */
@@ -113,336 +102,6 @@ export interface ITreeAlpha extends ITree {
 	exportSimpleSchema(): SimpleTreeSchema;
 }
 
-/**
- * Options when constructing a tree view.
- * @public
- */
-export interface ITreeConfigurationOptions {
-	/**
-	 * If `true`, the tree will validate new content against its stored schema at insertion time
-	 * and throw an error if the new content doesn't match the expected schema.
-	 *
-	 * @defaultValue `false`.
-	 *
-	 * @remarks Enabling schema validation has a performance penalty when inserting new content into the tree because
-	 * additional checks are done. Enable this option only in scenarios where you are ok with that operation being a
-	 * bit slower.
-	 */
-	enableSchemaValidation?: boolean;
-
-	/**
-	 * A flag used to opt into strict rules ensuring that the schema avoids cases which can make the type of nodes ambiguous when importing or exporting data.
-	 * @defaultValue `false`.
-	 *
-	 * @remarks
-	 * When this is true, it ensures that the compile time type safety for data when constructing nodes is sufficient to ensure that the runtime behavior will not give node data ambiguity errors.
-	 *
-	 * This ensures that the canonical JSON-like representation of all unions in the tree are lossless and unambiguous.
-	 * This canonical JSON-like representation consists of arrays, plain old JavaScript objects with string keys, booleans, numbers (excluding NaN, -0 and infinities), strings, null and {@link @fluidframework/core-interfaces#IFluidHandle}s.
-	 * It is compatible with the node creation APIs (such as schema class constructors) and is also compatible with JSON assuming any IFluidHandles get special handling (since they are not JSON compatible).
-	 * Currently these cases can cause ambiguity in a union:
-	 *
-	 * - More than one ArrayNode type: it's impossible to tell which array type is intended in the case of empty arrays (`[]`).
-	 *
-	 * - More than one MapNode type: it's impossible to tell which map type is intended in the case of an empty map (`{}`).
-	 *
-	 * - Both a MapNode and an ArrayNode: this case is not a problem for the canonical JSON representation, but is an issue when constructing from an Iterable, which is supported for both MapNode and ArrayNode.
-	 *
-	 * - Both a MapNode and an ObjectNode: when the input is valid for the ObjectNode, the current parser always considers it ambiguous with being a MapNode.
-	 *
-	 * - ObjectNodes which have fields (required or optional) which include all required fields of another ObjectNode: currently each ObjectNode is differentiated by the presence of its required fields.
-	 *
-	 * This check is conservative: some complex cases may error if the current simple algorithm cannot show no ambiguity is possible.
-	 * This check may become more permissive over time.
-	 *
-	 * @example Ambiguous schema (with `preventAmbiguity: false`), and how to disambiguate it using {@link Unhydrated} nodes:
-	 * ```typescript
-	 * const schemaFactory = new SchemaFactory("com.example");
-	 * class Feet extends schemaFactory.object("Feet", { length: schemaFactory.number }) {}
-	 * class Meters extends schemaFactory.object("Meters", { length: schemaFactory.number }) {}
-	 * const config = new TreeViewConfiguration({
-	 * 	// This combination of schema can lead to ambiguous cases and will error if `preventAmbiguity` is true.
-	 * 	schema: [Feet, Meters],
-	 * 	preventAmbiguity: false,
-	 * });
-	 * const view = tree.viewWith(config);
-	 * // This is invalid since it is ambiguous which type of node is being constructed:
-	 * // view.initialize({ length: 5 });
-	 * // To work, an explicit type can be provided by using an {@link Unhydrated} Node:
-	 * view.initialize(new Meters({ length: 5 }));
-	 * ```
-	 *
-	 * @example Schema disambiguated by adjusting field names, validated with `preventAmbiguity: true:`
-	 * ```typescript
-	 * const schemaFactory = new SchemaFactory("com.example");
-	 * class Feet extends schemaFactory.object("Feet", { length: schemaFactory.number }) {}
-	 * class Meters extends schemaFactory.object("Meters", {
-	 * 	// To avoid ambiguity when parsing unions of Feet and Meters, this renames the length field to "meters".
-	 * 	// To preserve compatibility with existing data from the ambiguous case,
-	 * 	// `{ key: "length" }` is set, so when persisted in the tree "length" is used as the field name.
-	 * 	meters: schemaFactory.required(schemaFactory.number, { key: "length" }),
-	 * }) {}
-	 * const config = new TreeViewConfiguration({
-	 * 	// This combination of schema is not ambiguous because `Feet` and `Meters` have different required keys.
-	 * 	schema: [Feet, Meters],
-	 * 	preventAmbiguity: true,
-	 * });
-	 * const view = tree.viewWith(config);
-	 * // This now works, since the field is sufficient to determine this is a `Meters` node.
-	 * view.initialize({ meters: 5 });
-	 * ```
-	 *
-	 * @privateRemarks
-	 * In the future, we can support lossless round tripping via the canonical JSON-like representation above when unambiguous.
-	 * This could be done via methods added to `Tree` to export and import such objects, which would give us a place to explicitly define the type of this representation.
-	 *
-	 * To make this more permissive in the future we can:
-	 *
-	 * - Make toMapTree more permissive (ex: allow disambiguation based on leaf type)
-	 * - Update this check to more tightly match toMapTree
-	 * - Add options to help schema authors disambiguate their types, such as "constant fields" which are not persisted, and always have a constant value.
-	 *
-	 * The above examples exist in executable form in this files tests, and should be updated there then copied back here.
-	 */
-	readonly preventAmbiguity?: boolean;
-}
-
-const defaultTreeConfigurationOptions: Required<ITreeConfigurationOptions> = {
-	enableSchemaValidation: false,
-	preventAmbiguity: false,
-};
-
-/**
- * Property-bag configuration for {@link TreeViewConfiguration} construction.
- * @public
- */
-export interface ITreeViewConfiguration<
-	TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
-> extends ITreeConfigurationOptions {
-	/**
-	 * The schema which the application wants to view the tree with.
-	 */
-	readonly schema: TSchema;
-}
-
-/**
- * Configuration for {@link ViewableTree.viewWith}.
- * @sealed @public
- */
-export class TreeViewConfiguration<
-	const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
-> implements Required<ITreeViewConfiguration<TSchema>>
-{
-	protected _typeCheck!: MakeNominal;
-
-	/**
-	 * {@inheritDoc ITreeViewConfiguration.schema}
-	 */
-	public readonly schema: TSchema;
-
-	/**
-	 * {@inheritDoc ITreeConfigurationOptions.enableSchemaValidation}
-	 */
-	public readonly enableSchemaValidation: boolean;
-
-	/**
-	 * {@inheritDoc ITreeConfigurationOptions.preventAmbiguity}
-	 */
-	public readonly preventAmbiguity: boolean;
-
-	/**
-	 * Construct a new {@link TreeViewConfiguration}.
-	 *
-	 * @param props - Property bag of configuration options.
-	 *
-	 * @remarks
-	 * Performing this construction deeply validates the provided schema.
-	 * This means that when this constructor is called, all {@link LazyItem} {@link TreeNodeSchema} references will be evaluated (using {@link evaluateLazySchema}).
-	 * This means that the declarations for all transitively reachable {@link TreeNodeSchema} must be available at this time.
-	 *
-	 * For example, a schema reachable from this configuration cannot reference this configuration during its declaration,
-	 * since this would be a cyclic dependency that will cause an error when constructing this configuration.
-	 */
-	public constructor(props: ITreeViewConfiguration<TSchema>) {
-		const config = { ...defaultTreeConfigurationOptions, ...props };
-		this.schema = config.schema;
-		this.enableSchemaValidation = config.enableSchemaValidation;
-		this.preventAmbiguity = config.preventAmbiguity;
-
-		// Ambiguity errors are lower priority to report than invalid schema errors, so collect these in an array and report them all at once.
-		const ambiguityErrors: string[] = [];
-
-		walkFieldSchema(config.schema, {
-			// Ensure all reachable schema are marked as most derived.
-			// This ensures if multiple schema extending the same schema factory generated class are present (or have been constructed, or get constructed in the future),
-			// an error is reported.
-
-			node: (schema) => markSchemaMostDerived(schema, true),
-			allowedTypes(types): void {
-				if (config.preventAmbiguity) {
-					checkUnion(types, ambiguityErrors);
-				}
-			},
-		});
-
-		if (ambiguityErrors.length !== 0) {
-			// Duplicate errors are common since when two types conflict, both orders error:
-			const deduplicated = new Set(ambiguityErrors);
-			throw new UsageError(`Ambiguous schema found:\n${[...deduplicated].join("\n")}`);
-		}
-
-		// Eagerly perform this conversion to surface errors sooner.
-		toStoredSchema(config.schema);
-	}
-}
-
-/**
- * {@link TreeViewConfiguration} extended with some alpha APIs.
- * @sealed @alpha
- */
-export class TreeViewConfigurationAlpha<
-		const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,
-	>
-	extends TreeViewConfiguration<TSchema>
-	implements TreeSchema
-{
-	/**
-	 * {@inheritDoc TreeSchema.root}
-	 */
-	public readonly root: FieldSchemaAlpha;
-	/**
-	 * {@inheritDoc TreeSchema.definitions}
-	 */
-	public readonly definitions: ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
-
-	public constructor(props: ITreeViewConfiguration<TSchema>) {
-		super(props);
-		this.root = normalizeFieldSchema(props.schema);
-		const definitions = new Map<string, SimpleNodeSchema & TreeNodeSchema>();
-		walkFieldSchema(props.schema, {
-			node: (schema) =>
-				definitions.set(schema.identifier, schema as SimpleNodeSchema & TreeNodeSchema),
-		});
-		this.definitions = definitions;
-	}
-}
-
-/**
- * {@link TreeViewConfigurationAlpha}
- * @sealed @alpha
- */
-export interface TreeSchema extends SimpleTreeSchema {
-	/**
-	 * {@inheritDoc SimpleTreeSchema.root}
-	 */
-	readonly root: FieldSchemaAlpha;
-
-	/**
-	 * {@inheritDoc SimpleTreeSchema.definitions}
-	 */
-	readonly definitions: ReadonlyMap<string, SimpleNodeSchema & TreeNodeSchema>;
-}
-
-/**
- * Pretty print a set of types for use in error messages.
- */
-function formatTypes(allowed: Iterable<TreeNodeSchema>): string {
-	// Use JSON.stringify to quote and escape identifiers.
-	// Don't just use a single array JSON.stringify since that omits spaces between items
-	return `[${Array.from(allowed, (s) => JSON.stringify(s.identifier)).join(", ")}]`;
-}
-
-/**
- * Detect cases documented in {@link ITreeConfigurationOptions.preventAmbiguity}.
- */
-export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): void {
-	const checked: Set<TreeNodeSchema> = new Set();
-	const maps: TreeNodeSchema[] = [];
-	const arrays: TreeNodeSchema[] = [];
-
-	const objects: ObjectNodeSchema[] = [];
-	// Map from key to schema using that key
-	const allObjectKeys: Map<string, Set<TreeNodeSchema>> = new Map();
-
-	for (const schema of union) {
-		if (checked.has(schema)) {
-			throw new UsageError(`Duplicate schema in allowed types: ${schema.identifier}`);
-		}
-		checked.add(schema);
-
-		if (schema instanceof LeafNodeSchema) {
-			// nothing to do
-		} else if (isObjectNodeSchema(schema)) {
-			objects.push(schema);
-			for (const key of schema.fields.keys()) {
-				getOrCreate(allObjectKeys, key, () => new Set()).add(schema);
-			}
-		} else if (schema.kind === NodeKind.Array) {
-			arrays.push(schema);
-		} else {
-			assert(schema.kind === NodeKind.Map, 0x9e7 /* invalid schema */);
-			maps.push(schema);
-		}
-	}
-
-	if (arrays.length > 1) {
-		errors.push(
-			`More than one kind of array allowed within union (${formatTypes(arrays)}). This would require type disambiguation which is not supported by arrays during import or export.`,
-		);
-	}
-
-	if (maps.length > 1) {
-		errors.push(
-			`More than one kind of map allowed within union (${formatTypes(maps)}). This would require type disambiguation which is not supported by maps during import or export.`,
-		);
-	}
-
-	if (maps.length > 0 && arrays.length > 0) {
-		errors.push(
-			`Both a map and an array allowed within union (${formatTypes([...arrays, ...maps])}). Both can be implicitly constructed from iterables like arrays, which are ambiguous when the array is empty.`,
-		);
-	}
-
-	if (objects.length > 0 && maps.length > 0) {
-		errors.push(
-			`Both a object and a map allowed within union (${formatTypes([...objects, ...maps])}). Both can be constructed from objects and can be ambiguous.`,
-		);
-	}
-
-	// Check for objects which fully overlap:
-	for (const schema of objects) {
-		// All objects which might be ambiguous relative to `schema`.
-		const possiblyAmbiguous = new Set(objects);
-
-		// A schema can't be ambiguous with itself
-		possiblyAmbiguous.delete(schema);
-
-		// For each field of schema, remove schema from possiblyAmbiguous that do not have that field
-		for (const [key, field] of schema.fields) {
-			if (field.kind === FieldKind.Required) {
-				const withKey = allObjectKeys.get(key) ?? fail(0xb35 /* missing schema */);
-				for (const candidate of possiblyAmbiguous) {
-					if (!withKey.has(candidate)) {
-						possiblyAmbiguous.delete(candidate);
-					}
-				}
-			}
-		}
-
-		if (possiblyAmbiguous.size > 0) {
-			// TODO: make this check more permissive.
-			// Allow using the type of the field to disambiguate, at least for leaf types.
-			// Add "constant" fields which can be used to disambiguate even more cases without adding persisted data: maybe make them optional in constructor?
-			// Consider separating unambiguous implicit construction format from constructor arguments at type level, allowing constructor to superset the implicit construction options (ex: optional constant fields).
-			// The policy here however must remain at least as conservative as shallowCompatibilityTest in src/simple-tree/toMapTree.ts.
-
-			errors.push(
-				`The required fields of ${JSON.stringify(schema.identifier)} are insufficient to differentiate it from the following types: ${formatTypes(possiblyAmbiguous)}. For objects to be considered unambiguous, each must have required fields that do not all occur on any other object in the union.`,
-			);
-		}
-	}
-}
-
 /**
  * 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}.
@@ -631,14 +290,18 @@ export interface TreeViewAlpha<
 	 * "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
 	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
 	 * @returns A result object of {@link TransactionResultExt | TransactionResultExt} type. It includes the following:
+	 *
 	 * - A "success" flag indicating whether the transaction was successful or not.
+	 *
 	 * - The success of failure value as returned by the transaction function.
 	 * @remarks
 	 * This API will throw an error if the constraints are not met or something unexpected happens.
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -646,9 +309,12 @@ export interface TreeViewAlpha<
 	 *
 	 * Nested transactions:
 	 * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
+	 *
 	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
+	 *
 	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
 	 * for the outermost transaction which includes all inner transactions.
+	 *
 	 * - Undo will undo the outermost transaction and all inner transactions.
 	 */
 	runTransaction<TSuccessValue, TFailureValue>(
@@ -658,10 +324,13 @@ export interface TreeViewAlpha<
 	/**
 	 * Run a transaction which applies one or more edits to the tree as a single atomic unit.
 	 * @param transaction - The function to run as the body of the transaction. It may return the following:
+	 *
 	 * - Nothing to indicate that the body of the transaction has successfully run.
+	 *
 	 * - A status object of {@link VoidTransactionCallbackStatus | VoidTransactionCallbackStatus } type. It includes a "rollback" property which
 	 * may be returned as true at any point during the transaction. This will abort the transaction and discard any changes it made so
 	 * far. "rollback" can be set to false or left undefined to indicate that the body of the transaction has successfully run.
+	 *
 	 * @param params - The optional parameters for the transaction. It includes the constraints that will be checked before the transaction begins.
 	 * @returns A result object of {@link TransactionResult | TransactionResult} type. It includes a "success" flag indicating whether the
 	 * transaction was successful or not.
@@ -670,7 +339,9 @@ export interface TreeViewAlpha<
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes (either from this client or from a remote client) can be interleaved with those changes.
 	 * Note that this is guaranteed by Fluid for any sequence of changes that are submitted synchronously, whether in a transaction or not.
 	 * However, using a transaction has the following additional consequences:
+	 *
 	 * - If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 *
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * Local change events will be emitted for each change as the transaction is being applied.
@@ -678,9 +349,12 @@ export interface TreeViewAlpha<
 	 *
 	 * Nested transactions:
 	 * This API can be called from within the transaction callback of another runTransaction call. That will have slightly different behavior:
+	 *
 	 * - If the inner transaction fails, only the inner transaction will be rolled back and the outer transaction will continue.
+	 *
 	 * - Constraints will apply to the outermost transaction. Constraints are applied per commit and there will be one commit generated
 	 * for the outermost transaction which includes all inner transactions.
+	 *
 	 * - Undo will undo the outermost transaction and all inner transactions.
 	 */
 	runTransaction(
@@ -704,7 +378,9 @@ export interface SchemaCompatibilityStatus {
 	 * exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.
 	 *
 	 * Examples which are expressible where this may occur include:
+	 *
 	 * - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)
+	 *
 	 * - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (ex: an object node type containing a required field with no allowed types)
 	 *
 	 * These cases are typically not interesting to applications.
@@ -782,11 +458,15 @@ export interface TreeBranchEvents extends Omit<TreeViewEvents, "commitApplied">
 
 	/**
 	 * 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
@@ -822,11 +502,15 @@ export interface TreeViewEvents {
 
 	/**
 	 * 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

package/src/simple-tree/api/{treeApiBeta.ts → treeBeta.ts}

@@ -7,7 +7,6 @@ import {
 	getKernel,
 	isTreeNode,
 	type NodeKind,
-	type TreeChangeEvents,
 	type TreeNode,
 	type Unhydrated,
 	type WithType,
@@ -15,6 +14,10 @@ import {
 import { treeNodeApi } from "./treeNodeApi.js";
 import { createFromCursor } from "./create.js";
 import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../schemaTypes.js";
+import type { TreeChangeEvents } from "./treeChangeEvents.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.
 
 /**
  * Data included for {@link TreeChangeEventsBeta.nodeChanged}.
@@ -89,10 +92,12 @@ export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>
 }
 
 /**
- * Extensions to {@link Tree} which are not yet stable.
- * @sealed @beta
+ * Extensions to {@link (Tree:interface)} which are not yet stable.
+ * @remarks
+ * Use via the {@link (TreeBeta:variable)} singleton.
+ * @system @sealed @beta
  */
-export const TreeBeta: {
+export interface TreeBeta {
 	/**
 	 * Register an event listener on the given node.
 	 * @param node - The node whose events should be subscribed to.
@@ -117,7 +122,9 @@ export const TreeBeta: {
 	 *
 	 * - 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.
 	 */
 	clone<const TSchema extends ImplicitFieldSchema>(
@@ -142,7 +149,14 @@ export const TreeBeta: {
 	// 		replaceIdentifiers?: true;
 	// 	},
 	// ): TreeFieldFromImplicitField<TSchema>;
-} = {
+}
+
+/**
+ * Extensions to {@link (Tree:variable)} which are not yet stable.
+ * @see {@link (TreeBeta:interface)}.
+ * @beta
+ */
+export const TreeBeta: TreeBeta = {
 	on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(
 		node: TNode,
 		eventName: K,
@@ -153,7 +167,7 @@ export const TreeBeta: {
 	clone<const TSchema extends ImplicitFieldSchema>(
 		node: TreeFieldFromImplicitField<TSchema>,
 	): Unhydrated<TreeFieldFromImplicitField<TSchema>> {
-		/** The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (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;
 		}

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

@@ -0,0 +1,84 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * A collection of events that can be emitted by a {@link TreeNode}.
+ *
+ * @privateRemarks
+ * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
+ * Probably have object node and map node specific APIs for this.
+ *
+ * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.
+ *
+ * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.
+ * Some ideas:
+ *
+ * - treeChanged, but with some subtrees/fields/paths excluded
+ * - helper to batch several nodeChanged calls to a treeChanged scope
+ * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)
+ * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.
+ * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)
+ * to allow efficiently searching for new content (and initial content) of a given type.
+ *
+ * @sealed @public
+ */
+export interface TreeChangeEvents {
+	/**
+	 * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.
+	 *
+	 * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).
+	 *
+	 * - Array nodes define a change as when an element is added, removed, moved or replaced.
+	 *
+	 * - Map nodes define a change as when an entry is added, updated, or removed.
+	 *
+	 * @param unstable - Future versions of this API (such as the one in beta on TreeBeta) may use this argument to provide additional data to the event.
+	 * users of this event should ensure that they do not provide a listener callback which has an optional parameter in this position, since unexpected data might get provided to it.
+	 * This parameter exists to capture this fact in the type system.
+	 * Using an inline lambda expression as the listener callback is a good pattern to avoid cases like this were arguments are added from breaking due to optional arguments.
+	 *
+	 * @remarks
+	 * This event is not emitted when:
+	 *
+	 * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
+	 * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the
+	 * array/map node as one of its properties.
+	 *
+	 * - The node is moved to a different location in the tree or removed from the tree.
+	 * In this case the event is emitted on the _parent_ node, not the node itself.
+	 *
+	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+	 * the client that made the original edit.
+	 *
+	 * When the event is emitted, the tree is guaranteed to be in-schema.
+	 *
+	 * @privateRemarks
+	 * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
+	 * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
+	 * node, or when the node has to be updated due to resolution of a merge conflict
+	 * (for example a previously applied local change might be undone, then reapplied differently or not at all).
+	 *
+	 * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).
+	 */
+	nodeChanged(unstable?: unknown): void;
+
+	/**
+	 * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
+	 * subtree rooted at it.
+	 *
+	 * @remarks
+	 * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.
+	 * In that case it is emitted on the _parent_ node, not the node itself.
+	 *
+	 * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties
+	 * of the node itself.
+	 *
+	 * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
+	 * the client that made the original edit.
+	 *
+	 * When it is emitted, the tree is guaranteed to be in-schema.
+	 */
+	treeChanged(): void;
+}

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

@@ -32,7 +32,6 @@ import {
 	type TreeNodeSchema,
 	NodeKind,
 	type TreeNode,
-	type TreeChangeEvents,
 	tryGetTreeNodeSchema,
 	getOrCreateNodeFromInnerNode,
 	UnhydratedFlexTreeNode,
@@ -40,6 +39,7 @@ import {
 	getOrCreateInnerNode,
 } from "../core/index.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
+import type { TreeChangeEvents } from "./treeChangeEvents.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.