@fluidframework/tree 2.118.0 → 3.0.0

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

@@ -62,7 +62,7 @@ import type { VerboseTree } from "./verboseTree.js";
  * 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).
+ * Make sure users of createIndependentTreeViewAlpha 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 {
@@ -160,7 +160,92 @@ export interface ITreeAlpha extends ITree {
  * See {@link UntypedTreeViewAlpha} for additional APIs that are in an earlier stage of development.
  * @sealed @beta
  */
-export interface UntypedTreeView extends IDisposable {
+export interface UntypedTreeView extends IDisposable, TreeContextBeta {
+	runTransaction<TValue>(
+		transaction: () => WithValue<TValue>,
+		params?: RunTransactionParamsBeta,
+	): TransactionValueResult<TValue, TValue>;
+
+	runTransaction(
+		transaction: () => void,
+		params?: RunTransactionParamsBeta,
+	): TransactionVoidResult;
+
+	/**
+	 * Run a synchronous transaction which groups sequential edits to the tree into a single atomic edit if possible.
+	 *
+	 * @param transaction - The function to run as the body of the transaction, which may optionally return a {@link TransactionCallbackStatusBeta | value or rollback signal}.
+	 * It may optionally return a {@link WithValue | value }, which will be returned by the `runTransaction` call.
+	 *
+	 * @param params - Optional {@link RunTransactionParamsBeta | parameters} for the transaction.
+	 *
+	 * @returns A {@link TransactionValueResult | value } indicating whether or not the transaction succeeded, and containing the value returned by `transaction`.
+	 *
+	 * @remarks
+	 * All of the changes in the transaction are applied synchronously and therefore no other changes 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.
+	 *
+	 * {@link (TreeBeta:interface).on | Change events } will be emitted for changed nodes on this client _as each edit happens_, just as they would be if the changes were made outside of a transaction.
+	 * Any other/future clients or contexts will process the transaction "squashed", i.e. they will apply its changes all at once, emitting only a single event per node (even if that node was edited multiple times in the transaction).
+	 * Edits to the tree are not permitted within these event callbacks, therefore no other local changes from this client will be interleaved with the changes in this transaction.
+	 *
+	 * Using a transaction has the following additional consequences:
+	 *
+	 * - If {@link Revertible | reverted } (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
+	 * Only the "outermost" transaction commits a change to the synchronized tree state and therefore only the outermost transaction can be reverted.
+	 * If a transaction is started and completed while another transaction is already in progress, then the inner transaction will be reverted together with the outer transaction.
+	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
+	 *
+	 * If the transaction is rolled back, a corresponding {@link TreeBranchEvents.changed | `changed`} event will also be emitted for the rollback.
+	 */
+	runTransaction<
+		TOut extends
+			| TransactionCallbackStatusBeta<unknown, unknown>
+			| VoidTransactionCallbackStatusBeta
+			| void,
+	>(
+		transaction: () => TOut,
+		params?: RunTransactionParamsBeta,
+	): TOut extends TransactionCallbackStatusBeta<infer TSuccessValue, infer TFailureValue>
+		? TransactionValueResult<TSuccessValue, TFailureValue>
+		: TransactionVoidResult;
+
+	runTransactionAsync<TValue>(
+		transaction: () => Promise<WithValue<TValue>>,
+		params?: RunTransactionParamsBeta,
+	): Promise<TransactionValueResult<TValue, TValue>>;
+
+	runTransactionAsync(
+		transaction: () => Promise<void>,
+		params?: RunTransactionParamsBeta,
+	): Promise<TransactionVoidResult>;
+
+	/**
+	 * An asynchronous version of {@link UntypedTreeView.(runTransaction:1) | runTransaction}.
+	 *
+	 * @remarks
+	 * As with synchronous transactions, all of the changes in an asynchronous transaction are treated as a unit.
+	 * Therefore, no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.
+	 *
+	 * Unlike with synchronous transactions, it is possible that other changes (e.g. from a remote client) may be applied to the branch while this transaction is in progress.
+	 * Those other changes will be not be reflected on the branch until after this transaction completes, at which point the transaction changes will be applied after those other changes.
+	 *
+	 * An asynchronous transaction may not be started while any other transaction is in progress in this view.
+	 */
+	runTransactionAsync<
+		TOut extends
+			| TransactionCallbackStatusBeta<unknown, unknown>
+			| VoidTransactionCallbackStatusBeta
+			| void,
+	>(
+		transaction: () => Promise<TOut>,
+		params?: RunTransactionParamsBeta,
+	): Promise<
+		TOut extends TransactionCallbackStatusBeta<infer TSuccessValue, infer TFailureValue>
+			? TransactionValueResult<TSuccessValue, TFailureValue>
+			: TransactionVoidResult
+	>;
+
 	/**
 	 * 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 view will not apply to this view until the new view is e.g. {@link UntypedTreeView.merge | merged} back into this view.
@@ -213,15 +298,15 @@ export interface UntypedTreeView extends IDisposable {
 export type TreeBranch = UntypedTreeView;
 
 /**
- * Provides additional APIs that may be used to interact with a tree node or a tree node's SharedTree.
- * @alpha
+ * Provides additional APIs that may be used to interact with a tree node.
+ * @sealed @beta
  */
-export interface TreeContextAlpha {
+export interface TreeContextBeta {
 	/**
 	 * Run a synchronous transaction which groups sequential edits to the tree into a single atomic edit if possible.
 	 * @param transaction - A callback run during the transaction to perform user-supplied operations.
 	 * It may optionally return a {@link WithValue | value }, which will be returned by the `runTransaction` call.
-	 * @param params - Optional {@link RunTransactionParamsAlpha | parameters} for the transaction.
+	 * @param params - Optional {@link RunTransactionParamsBeta | parameters} for the transaction.
 	 * @returns A {@link TransactionValueResult | value } indicating whether or not the transaction succeeded, and containing the value returned by `transaction`.
 	 * @remarks
 	 * All of the changes in the transaction are applied synchronously and therefore no other changes from a remote client can be interleaved with those changes.
@@ -239,15 +324,15 @@ export interface TreeContextAlpha {
 	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
 	 *
 	 * `runTransaction` may be invoked on the context of a {@link TreeStatus.InDocument | hydrated } or {@link Unhydrated | unhydrated } node.
-	 * Use {@link TreeContextAlpha.isView | isView() } to check whether this context is associated with a view and gain {@link UntypedTreeViewAlpha.(runTransaction:1) | access to more transaction capabilities} if so.
+	 * Use {@link TreeContextBeta.isView | isView()} to check whether this context is associated with a view and gain {@link UntypedTreeView.(runTransaction:1) | access to more transaction capabilities} if so.
 	 */
 	runTransaction<TValue>(
 		transaction: () => WithValue<TValue>,
-		params?: RunTransactionParamsAlpha,
+		params?: RunTransactionParamsBeta,
 	): TransactionValueResult<TValue, TValue>;
 
 	/**
-	 * An overload of {@link TreeContextAlpha.(runTransaction:1) | runTransaction } which does not return a value.
+	 * An overload of {@link TreeContextBeta.(runTransaction:1) | runTransaction } which does not return a value.
 	 *
 	 * @privateRemarks
 	 * TODO: Consider updating these methods to avoid the need for overloads.
@@ -255,11 +340,11 @@ export interface TreeContextAlpha {
 	 */
 	runTransaction(
 		transaction: () => void,
-		params?: RunTransactionParamsAlpha,
+		params?: RunTransactionParamsBeta,
 	): TransactionVoidResult;
 
 	/**
-	 * An asynchronous version of {@link TreeContextAlpha.(runTransaction:1) | runTransaction}.
+	 * An asynchronous version of {@link TreeContextBeta.(runTransaction:1) | runTransaction}.
 	 * @remarks
 	 * As with synchronous transactions, all of the changes in an asynchronous transaction are treated as a unit.
 	 * Therefore, no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.
@@ -271,16 +356,49 @@ export interface TreeContextAlpha {
 	 */
 	runTransactionAsync<TValue>(
 		transaction: () => Promise<WithValue<TValue>>,
-		params?: RunTransactionParamsAlpha,
+		params?: RunTransactionParamsBeta,
 	): Promise<TransactionValueResult<TValue, TValue>>;
 
 	/**
-	 * An overload of {@link TreeContextAlpha.(runTransactionAsync:1) | runTransactionAsync } which does not return a value.
+	 * An overload of {@link TreeContextBeta.(runTransactionAsync:1) | runTransactionAsync } which does not return a value.
 	 *
 	 * @privateRemarks
 	 * TODO: Consider updating these methods to avoid the need for overloads.
 	 * See {@link TreeViewBeta.runTransactionAsync} for an example of how to do this.
 	 */
+	runTransactionAsync(
+		transaction: () => Promise<void>,
+		params?: RunTransactionParamsBeta,
+	): Promise<TransactionVoidResult>;
+
+	/**
+	 * True if this context is associated with an {@link UntypedTreeView | untyped view} and false if it is associated with an {@link Unhydrated | unhydrated } node.
+	 * @remarks If this returns true, the context can be safely inferred or cast to {@link UntypedTreeView} to access additional view-specific APIs.
+	 * @returns Whether this context is associated with an untyped view.
+	 */
+	isView(): this is UntypedTreeView;
+}
+
+/**
+ * Provides additional APIs that may be used to interact with a tree node or a tree node's SharedTree.
+ * @sealed @alpha
+ */
+export interface TreeContextAlpha extends TreeContextBeta {
+	runTransaction<TValue>(
+		transaction: () => WithValue<TValue>,
+		params?: RunTransactionParamsAlpha,
+	): TransactionValueResult<TValue, TValue>;
+
+	runTransaction(
+		transaction: () => void,
+		params?: RunTransactionParamsAlpha,
+	): TransactionVoidResult;
+
+	runTransactionAsync<TValue>(
+		transaction: () => Promise<WithValue<TValue>>,
+		params?: RunTransactionParamsAlpha,
+	): Promise<TransactionValueResult<TValue, TValue>>;
+
 	runTransactionAsync(
 		transaction: () => Promise<void>,
 		params?: RunTransactionParamsAlpha,
@@ -385,12 +503,14 @@ export interface TreeBranchHistory {
 /**
  * An untyped view of a {@link UntypedTreeView} with alpha-level APIs.
  * @remarks
- * The untyped view for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.context` and checking {@link TreeContextAlpha.isView | isView()}.
+ * The untyped view for a specific {@link TreeNode} may be acquired by calling {@link (TreeAlpha:interface).context} and checking {@link TreeContextAlpha.isView | isView()}.
  *
  * An untyped view does not necessarily know the schema of its SharedTree. To convert it to a {@link TreeViewAlpha | view with a schema}, use {@link UntypedTreeViewAlpha.hasRootSchema | hasRootSchema()}.
  * @sealed @alpha
  */
-export interface UntypedTreeViewAlpha extends UntypedTreeView, TreeContextAlpha {
+export interface UntypedTreeViewAlpha
+	extends Omit<UntypedTreeView, "runTransaction" | "runTransactionAsync" | "isView">,
+		TreeContextAlpha {
 	/**
 	 * Events for the view's underlying branch.
 	 */
@@ -560,7 +680,7 @@ export type TreeBranchAlpha = UntypedTreeViewAlpha;
  * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.
  *
  * @see {@link TreeViewAlpha}
- * @see {@link asTreeViewAlpha}
+ * @see {@link (asAlpha:1)}
  *
  * @sealed @public
  */
@@ -848,71 +968,6 @@ export interface TreeViewBeta<in out TSchema extends ImplicitFieldSchema>
 
 	// Override the base branch method to return a typed view rather than merely a branch.
 	fork(): ReturnType<UntypedTreeView["fork"]> & TreeViewBeta<TSchema>;
-
-	/**
-	 * Run a synchronous transaction which groups sequential edits to the tree into a single atomic edit if possible.
-	 *
-	 * @param transaction - The function to run as the body of the transaction, which may optionally return a {@link TransactionCallbackStatusBeta | value or rollback signal}.
-	 * It may optionally return a {@link WithValue | value }, which will be returned by the `runTransaction` call.
-	 *
-	 * @param params - Optional {@link RunTransactionParamsBeta | parameters} for the transaction.
-	 *
-	 * @returns A {@link TransactionValueResult | value } indicating whether or not the transaction succeeded, and containing the value returned by `transaction`.
-	 *
-	 * @remarks
-	 * All of the changes in the transaction are applied synchronously and therefore no other changes 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.
-	 *
-	 * {@link (TreeBeta:interface).on | Change events } will be emitted for changed nodes on this client _as each edit happens_, just as they would be if the changes were made outside of a transaction.
-	 * Any other/future clients or contexts will process the transaction "squashed", i.e. they will apply its changes all at once, emitting only a single event per node (even if that node was edited multiple times in the transaction).
-	 * Edits to the tree are not permitted within these event callbacks, therefore no other local changes from this client will be interleaved with the changes in this transaction.
-	 *
-	 * Using a transaction has the following additional consequences:
-	 *
-	 * - If {@link Revertible | reverted } (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
-	 * Only the "outermost" transaction commits a change to the synchronized tree state and therefore only the outermost transaction can be reverted.
-	 * If a transaction is started and completed while another transaction is already in progress, then the inner transaction will be reverted together with the outer transaction.
-	 * - The internal data representation of a transaction with many changes is generally smaller and more efficient than that of the changes when separate.
-	 *
-	 * If the transaction is rolled back, a corresponding {@link TreeBranchEvents.changed | `changed`} event will also be emitted for the rollback.
-	 */
-	runTransaction<
-		TOut extends
-			| TransactionCallbackStatusBeta<unknown, unknown>
-			| VoidTransactionCallbackStatusBeta
-			| void,
-	>(
-		transaction: () => TOut,
-		params?: RunTransactionParamsBeta,
-	): TOut extends TransactionCallbackStatusBeta<infer TSuccessValue, infer TFailureValue>
-		? TransactionValueResult<TSuccessValue, TFailureValue>
-		: TransactionVoidResult;
-
-	/**
-	 * An asynchronous version of {@link TreeViewBeta.runTransaction | runTransaction}.
-	 *
-	 * @remarks
-	 * As with synchronous transactions, all of the changes in an asynchronous transaction are treated as a unit.
-	 * Therefore, no other changes (either from this client or from a remote client) can be interleaved with the transaction changes.
-	 *
-	 * Unlike with synchronous transactions, it is possible that other changes (e.g. from a remote client) may be applied to the branch while this transaction is in progress.
-	 * Those other changes will be not be reflected on the branch until after this transaction completes, at which point the transaction changes will be applied after those other changes.
-	 *
-	 * An asynchronous transaction may not be started while any other transaction is in progress in this view.
-	 */
-	runTransactionAsync<
-		TOut extends
-			| TransactionCallbackStatusBeta<unknown, unknown>
-			| VoidTransactionCallbackStatusBeta
-			| void,
-	>(
-		transaction: () => Promise<TOut>,
-		params?: RunTransactionParamsBeta,
-	): Promise<
-		TOut extends TransactionCallbackStatusBeta<infer TSuccessValue, infer TFailureValue>
-			? TransactionValueResult<TSuccessValue, TFailureValue>
-			: TransactionVoidResult
-	>;
 }
 
 /**
@@ -923,7 +978,7 @@ export interface TreeViewAlpha<
 	in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema,
 > extends Omit<
 			TreeViewBeta<ReadSchema<TSchema>>,
-			"root" | "initialize" | "fork" | "runTransaction" | "runTransactionAsync"
+			"root" | "initialize" | "fork" | "runTransaction" | "runTransactionAsync" | "isView"
 		>,
 		UntypedTreeViewAlpha {
 	get root(): ReadableField<TSchema>;
@@ -1123,9 +1178,8 @@ export interface TreeViewEvents {
 
 /**
  * Retrieve the {@link TreeViewAlpha | alpha API} for a {@link TreeView}.
- * @alpha
- * @deprecated Use {@link (asAlpha:1)} instead.
- * @privateRemarks Despite being deprecated, this function should be used within the tree package (outside of tests) rather than `asAlpha` in order to avoid circular import dependencies.
+ * @remarks
+ * This function can be used within the tree package (outside of tests) rather than {@link asAlpha} in order to avoid circular import dependencies.
  */
 export function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(
 	view: TreeView<TSchema>,

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

@@ -40,10 +40,14 @@ export interface TreeChangeEvents {
 	 *
 	 * - 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.
+	 * @param unstable - Future versions of this API (such as the one in beta on {@link TreeChangeEventsBeta.nodeChanged})
+	 * 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.
+	 *
+	 * Using an inline lambda expression as the listener callback is a good pattern to avoid cases like this where
+	 * arguments are added from breaking due to optional arguments.
 	 *
 	 * @remarks
 	 * This event is not emitted when:
@@ -91,6 +95,14 @@ export interface TreeChangeEvents {
 	 * the client that made the original edit.
 	 *
 	 * When it is emitted, the tree is guaranteed to be in-schema.
+	 *
+	 * @param unstable - Future versions of this API 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 where
+	 * arguments are added from breaking due to optional arguments.
 	 */
-	treeChanged(): void;
+	treeChanged(unstable?: unknown): void;
 }

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

@@ -0,0 +1,245 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { NodeKind, TreeNode, WithType } from "../core/index.js";
+
+import type { TreeChangeEvents } from "./treeChangeEvents.js";
+
+/**
+ * A `"retain"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements that were neither inserted into nor removed from the array.
+ * @sealed @beta
+ */
+export interface ArrayNodeRetainOp {
+	readonly type: "retain";
+	readonly count: number;
+}
+
+/**
+ * A `"retain"` op in an {@link ArrayNodeTreeChangedDeltaOp} sequence, used in
+ * {@link NodeChangedDataTreeDelta} payloads delivered to
+ * {@link TreeChangeEventsBeta.treeChanged} on array nodes.
+ *
+ * Extends {@link ArrayNodeRetainOp} with a {@link ArrayNodeTreeChangedRetainOp.subtreeChanged}
+ * flag that indicates whether any descendant of the retained element changed.
+ * @sealed @beta
+ */
+export interface ArrayNodeTreeChangedRetainOp extends ArrayNodeRetainOp {
+	/**
+	 * Whether any descendant of this retained element changed.
+	 * `true` if the element's subtree changed; `false` if nothing changed within it.
+	 * @remarks
+	 * Subscribe to `nodeChanged` or `treeChanged` on the element node itself for details.
+	 */
+	readonly subtreeChanged: boolean;
+}
+
+/**
+ * A single operation in an array-node delta delivered by {@link TreeChangeEventsBeta.treeChanged}.
+ * Extends {@link ArrayNodeDeltaOp}: retain ops carry a {@link ArrayNodeTreeChangedRetainOp.subtreeChanged}
+ * flag indicating whether any descendant of the retained element changed.
+ * @beta
+ */
+export type ArrayNodeTreeChangedDeltaOp =
+	| ArrayNodeTreeChangedRetainOp
+	| ArrayNodeInsertOp
+	| ArrayNodeRemoveOp;
+
+/**
+ * An `"insert"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements added to the array.
+ * Read the new element values from the current tree at the positions described by this op.
+ * @sealed @beta
+ */
+export interface ArrayNodeInsertOp {
+	readonly type: "insert";
+	readonly count: number;
+}
+
+/**
+ * A `"remove"` op in an {@link ArrayNodeDeltaOp} sequence.
+ * Represents elements removed from the array.
+ * @sealed @beta
+ */
+export interface ArrayNodeRemoveOp {
+	readonly type: "remove";
+	readonly count: number;
+}
+
+/**
+ * A single operation in an array node change delta. Used to efficiently sync an external
+ * representation of an array (e.g. a text editor or virtual list) with tree changes without
+ * needing to snapshot the old state or diff the entire array. Each op describes a contiguous run
+ * of positions in the array before the change. For inserts, read the new element values from the
+ * current tree at those positions.
+ *
+ * @remarks
+ * There is no dedicated `"move"` op. Moves are represented as `"remove"` + `"insert"`.
+ * When an element is moved within the same array it appears
+ * as a `"remove"` at the source position followed by an `"insert"` at the destination position.
+ * When an element is moved across two different arrays, the source array's delta contains a
+ * `"remove"` and the destination array's delta contains an `"insert"` — they cannot be
+ * correlated without additional bookkeeping on the caller's side.
+ *
+ * The operations cover the complete array: trailing elements that were not changed are included
+ * in a final `"retain"` op. Applying every operation therefore consumes the entire pre-edit array
+ * and produces the entire post-edit array.
+ *
+ * @sealed @beta
+ */
+export type ArrayNodeDeltaOp = ArrayNodeRetainOp | ArrayNodeInsertOp | ArrayNodeRemoveOp;
+
+/**
+ * Data included for {@link TreeChangeEventsBeta.nodeChanged}.
+ * @sealed @beta
+ */
+export interface NodeChangedData<TNode extends TreeNode = TreeNode> {
+	/**
+	 * When the changed node is an object, map, or record node, this lists all the properties which changed.
+	 * @remarks
+	 * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
+	 *
+	 * Not present when the {@link NodeKind} does not support this feature (currently just array nodes).
+	 *
+	 * When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.
+	 */
+	readonly changedProperties?: ReadonlySet<
+		// For Object nodes, strongly type with the property names from the schema:
+		TNode extends WithType<string, NodeKind.Object, infer TInfo>
+			? string & keyof TInfo
+			: string
+	>;
+
+	/**
+	 * When the changed node is an array node, the sequential operations describing what changed.
+	 * @remarks
+	 * Not present for non-array nodes. When present, the value may be `undefined` when the
+	 * document was updated in a way that required multiple internal change passes in a single
+	 * operation (for example, a data change combined with a schema upgrade).
+	 */
+	readonly delta?: readonly ArrayNodeDeltaOp[] | undefined;
+}
+
+/**
+ * Data included for {@link TreeChangeEventsBeta.nodeChanged} when the node is an object, map, or record node.
+ * @sealed @beta
+ */
+export interface NodeChangedDataProperties<TNode extends TreeNode = TreeNode>
+	extends NodeChangedData<TNode> {
+	/**
+	 * Lists all the properties which changed on the node.
+	 */
+	readonly changedProperties: ReadonlySet<
+		TNode extends WithType<string, NodeKind.Object, infer TInfo>
+			? string & keyof TInfo
+			: string
+	>;
+}
+
+/**
+ * Data carried by the {@link TreeChangeEventsBeta.nodeChanged} event for array nodes.
+ * @sealed @beta
+ */
+export interface NodeChangedDataDelta extends NodeChangedData {
+	/**
+	 * The sequential operations describing what changed in the array node.
+	 * @remarks
+	 * The value may be `undefined` when the document was updated in a way that required multiple
+	 * internal change passes in a single operation (for example, a data change combined with a
+	 * schema upgrade).
+	 *
+	 * See {@link ArrayNodeDeltaOp} for op semantics.
+	 */
+	readonly delta: readonly ArrayNodeDeltaOp[] | undefined;
+}
+
+/**
+ * Data carried by the {@link TreeChangeEventsBeta.treeChanged} event for array nodes.
+ * @remarks
+ * Extends {@link NodeChangedDataDelta}: the retain ops in the delta additionally carry a
+ * {@link ArrayNodeTreeChangedRetainOp.subtreeChanged} flag indicating whether any descendant
+ * of the retained element changed.
+ * @sealed @beta
+ */
+export interface NodeChangedDataTreeDelta {
+	/**
+	 * The sequential operations describing what changed in the array node,
+	 * including subtree-change information on retain ops.
+	 * @remarks
+	 * The value may be `undefined` when the document was updated in a way that required multiple
+	 * internal change passes in a single operation (for example, a data change combined with a
+	 * schema upgrade).
+	 *
+	 * See {@link ArrayNodeTreeChangedDeltaOp} for op semantics.
+	 */
+	readonly delta: readonly ArrayNodeTreeChangedDeltaOp[] | undefined;
+}
+
+/**
+ * Extensions to {@link TreeChangeEvents} which are not yet stable.
+ *
+ * @sealed @beta
+ */
+export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>
+	extends Omit<TreeChangeEvents, "nodeChanged" | "treeChanged"> {
+	/**
+	 * 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.
+	 *
+	 * @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).
+	 *
+	 * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
+	 */
+	nodeChanged: (
+		data: TNode extends WithType<string, NodeKind.Array>
+			? NodeChangedDataDelta
+			: TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record>
+				? NodeChangedDataProperties<TNode>
+				: NodeChangedData<TNode>,
+	) => void;
+
+	/**
+	 * Emitted when something in the subtree rooted at this node changes.
+	 *
+	 * @remarks
+	 * For array nodes, the event data carries a {@link NodeChangedDataTreeDelta.delta | delta}
+	 * payload describing both shallow and deep changes. Retain operations use
+	 * {@link ArrayNodeTreeChangedRetainOp.subtreeChanged} to indicate whether an element's
+	 * descendants changed.
+	 *
+	 * For non-array nodes, this has the same signature as {@link TreeChangeEvents.treeChanged}.
+	 * @privateRemarks
+	 * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
+	 */
+	treeChanged: TNode extends WithType<string, NodeKind.Array>
+		? (data: NodeChangedDataTreeDelta) => void
+		: TreeChangeEvents["treeChanged"];
+}