@fluidframework/tree 2.2.0 → 2.3.0

package/src/simple-tree/ProxyBinding.md

@@ -1,6 +1,6 @@
-# simple-tree Proxy Binding
+# simple-tree node Binding
 
-Proxy binding is a technique used in the simple-tree API implementation which enables a useful API feature, namely the ability to use a node proxy after it is inserted into the tree.
+Hydration is a three step process which provides the ability to use a simple-tree node both before and after it is inserted into the tree.
 This allows developers to "read back" values that they insert into the tree much more succinctly.
 Here is an example:
 
@@ -10,7 +10,7 @@ function addPoint(curve: Curve, x: number, y: number): Point {
 	curve.points.insertAtEnd(point);
 	// After insertion, `point` can be queried:
 	assert(point.x === 3);
-	// In fact, `point` is the same proxy object that you would get from reading it off of its new parent in the tree:
+	// In fact, `point` is the same simple-tree node object that you would get from reading it off of its new parent in the tree:
 	assert(point === curve.points[curve.points.length - 1]);
 	// So, to read the content that was just inserted, the original object can be used and there is no need to read via the parent:
 	return point;
@@ -20,22 +20,22 @@ function addPoint(curve: Curve, x: number, y: number): Point {
 
 ## Implementation
 
-This feature is supported by doing some bookkeeping to ensure that the proxy objects,
+This feature is supported by doing some bookkeeping to ensure that the simple-tree objects,
 flex tree nodes and anchor nodes in the tree get associated and disassociated at the right times.
-There are three states that a node proxy can be in: "raw", "marinated" and "cooked".
+There are three states that a node simple-tree node can be in: "raw", "marinated" and "cooked".
 
 Note from the public API perspective, `Unhydrated` nodes are "raw", and hydrated nodes are either "marinated" or "cooked".
 
 ### Raw Proxies
 
-A newly created proxy, a.k.a. a **raw** proxy. A raw proxy is produced by invoking the schema-provided constructor for a node:
+A newly created simple-tree node, a.k.a. a **raw** simple-tree node. A raw simple-tree node is produced by invoking the schema-provided constructor for a node:
 
 ```ts
 const rawPoint = new Point({ x: 3, y: 3 });
 ```
 
-Such a proxy will be raw until it is inserted into the tree and becomes "marinated" (see below).
-As of 2024-03-21 raw proxies cannot be read or mutated, but in the future they will be capable of both.
+Such a simple-tree node will be raw until it is inserted into the tree and becomes "marinated" (see below).
+As raw nodes can be read or mutated.
 
 ### Marinated Proxies
 
@@ -60,15 +60,15 @@ app.graph = {
 };
 ```
 
-A marinated proxy, by definition, is bound bi-directionally to an `AnchorNode`.
-When insertion occurs, an `AnchorNode` will be created for the location of the new content.
-The proxy for that content will then be mapped to the `AnchorNode` and the `AnchorNode` will be mapped to the proxy.
-Note that the `AnchorNode` does not yet have a `FlexTreeNode` associated with it - that happens when the node becomes "cooked" (see below).
+A marinated simple-tree node, by definition, is bound bi-directionally to an `AnchorNode`.
+When insertion occurs, an `AnchorNode` will be created (if not already present) for the location of the new content.
+The simple-tree node for that content will then be mapped to the `AnchorNode` (via its kernel) and the `AnchorNode` will be mapped to the simple-tree node.
+Note that the `AnchorNode` may not yet have a `FlexTreeNode` associated with it - that happens when the node becomes "cooked" (see below).
 
 ### Cooked Proxies
 
-A proxy is fully cooked when it finally associates itself with a `FlexTreeNode`.
-This happens lazily on demand, if/when a marinated proxy is read or mutated.
+A simple-tree node is fully cooked when it finally associates itself with a `FlexTreeNode`.
+This happens lazily on demand, if/when a marinated simple-tree node is read or mutated (by the local client).
 
 ```ts
 const point = new Point({ x: 3, y: 3 }); // `point` is raw
@@ -76,29 +76,29 @@ curves.points.insertAtEnd(point); // `point` becomes marinated
 const x = point.x; // `point` becomes cooked in order to support the read of `x`
 ```
 
-This laziness prevents the proxy tree from generating unnecessary `FlexTreeNodes`.
+This laziness prevents the simple-tree node tree from generating unnecessary `FlexTreeNodes`.
 
-Cooking a marinated proxy works as follows:
+Cooking a marinated simple-tree node works as follows:
 
-1. Get the `AnchorNode` associated with the marinated proxy.
+1. Get the `AnchorNode` associated with the marinated simple-tree node.
 2. Get or create a `FlexTreeNode` for the anchor.
-3. This will cause the `FlexTreeNode` to be generated which corresponds to the proxy.
+3. This will cause the `FlexTreeNode` to be generated which corresponds to the simple-tree node.
 
 ### Mappings
 
 ```mermaid
 graph LR;
-    AnchorNode(AnchorNode)<-->|Cooked|FlexTreeNode(FlexTreeNode)
-    AnchorNode<--->|Marinated|Proxy(Proxy)-.->|Raw|RawTreeNode(RawTreeNode)
+    AnchorNode(AnchorNode)<-->|Cooked and sometimes when Marinated|FlexTreeNode(FlexTreeNode)
+    AnchorNode<--->|Marinated or Cooked|TreeNode(TreeNode)-.->|Raw|RawTreeNode(RawTreeNode)
     linkStyle 0 stroke:#0f0
     linkStyle 1 stroke:#00f
     linkStyle 2 stroke:#f00
 ```
 
-Note that it is possible for the `Cooked` mappings between an `AnchorNode` and a `FlexTreeNode` to exist regardless of whether there is also a proxy yet created for that node.
-In that case, when that proxy is created it will immediately be given its `Marinated` mappings and therefore already be cooked.
+Note that it is possible for the `Cooked` mappings between an `AnchorNode` and a `FlexTreeNode` to exist regardless of whether there is also a simple-tree node yet created for that node.
+In that case, when that simple-tree node is created it will immediately be given its `Marinated` mappings and therefore already be cooked.
 
 `RawTreeNode`s, which implement the `FlexTreeNode` interface (or at least, as of 2024-03-21, pretend to), are substitutes for the true `FlexTreeNode`s that don't yet exist for a raw node.
-The `Raw` mapping is removed when a proxy is marinated, and the `RawTreeNode` is forgotten.
+The `Raw` mapping is removed when a simple-tree node is marinated, and the `RawTreeNode` is forgotten.
 
 See [proxyBinding.ts](./proxyBinding.ts) for more details.

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

@@ -23,12 +23,13 @@ import {
 	FieldKinds,
 	intoStoredSchema,
 	mapTreeFromCursor,
+	UnhydratedContext,
 	type NodeKeyManager,
 } from "../../feature-libraries/index.js";
-import { getOrCreateNodeFromFlexTreeNode, type InsertableContent } from "../proxies.js";
+import { getOrCreateNodeFromFlexTreeNode } from "../proxies.js";
 import { getOrCreateMapTreeNode, isFieldInSchema } from "../../feature-libraries/index.js";
 import { toFlexSchema } from "../toFlexSchema.js";
-import { inSchemaOrThrow, mapTreeFromNodeData } from "../toMapTree.js";
+import { inSchemaOrThrow, mapTreeFromNodeData, type InsertableContent } from "../toMapTree.js";
 import {
 	applySchemaToParserOptions,
 	cursorFromVerbose,
@@ -171,7 +172,11 @@ export function createFromCursor<TSchema extends ImplicitFieldSchema>(
 	// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 	const mapTree = mapTrees[0]!;
 	const rootSchema = flexSchema.nodeSchema.get(mapTree.type) ?? fail("missing schema");
-	const mapTreeNode = getOrCreateMapTreeNode(rootSchema, mapTree);
+	const mapTreeNode = getOrCreateMapTreeNode(
+		new UnhydratedContext(flexSchema),
+		rootSchema,
+		mapTree,
+	);
 
 	// TODO: ensure this works for InnerNodes to create unhydrated nodes
 	const result = getOrCreateNodeFromFlexTreeNode(mapTreeNode);

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

@@ -4,11 +4,11 @@
  */
 
 import type { JsonTreeSchema } from "./jsonSchema.js";
-import type { ImplicitAllowedTypes } from "./schemaTypes.js";
+import type { ImplicitAllowedTypes } from "../schemaTypes.js";
 import { toJsonSchema } from "./simpleSchemaToJsonSchema.js";
 import { getSimpleSchema } from "./getSimpleSchema.js";
-import { getOrCreate } from "../util/index.js";
-import type { TreeNodeSchema } from "./core/index.js";
+import { getOrCreate } from "../../util/index.js";
+import type { TreeNodeSchema } from "../core/index.js";
 
 /**
  * Cache in which the results of {@link getJsonSchema} are saved.

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

@@ -3,9 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import { getOrCreate } from "../util/index.js";
-import type { TreeNodeSchema } from "./core/index.js";
-import type { ImplicitAllowedTypes } from "./schemaTypes.js";
+import { getOrCreate } from "../../util/index.js";
+import type { TreeNodeSchema } from "../core/index.js";
+import type { ImplicitAllowedTypes } from "../schemaTypes.js";
 import type { SimpleTreeSchema } from "./simpleSchema.js";
 import { toSimpleTreeSchema } from "./viewSchemaToSimpleSchema.js";
 

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

@@ -26,6 +26,26 @@ export {
 } from "./schemaCreationUtilities.js";
 export { treeNodeApi, type TreeNodeApi } from "./treeNodeApi.js";
 export { createFromInsertable, cursorFromInsertable } from "./create.js";
+export type { SimpleTreeSchema } from "./simpleSchema.js";
+export {
+	type JsonSchemaId,
+	type JsonSchemaType,
+	type JsonObjectNodeSchema,
+	type JsonArrayNodeSchema,
+	type JsonMapNodeSchema,
+	type JsonLeafNodeSchema,
+	type JsonSchemaRef,
+	type JsonRefPath,
+	type JsonNodeSchema,
+	type JsonNodeSchemaBase,
+	type JsonTreeSchema,
+	type JsonFieldSchema,
+	type JsonLeafSchemaType,
+} from "./jsonSchema.js";
+export { getJsonSchema } from "./getJsonSchema.js";
+export { getSimpleSchema } from "./getSimpleSchema.js";
+
+export { TreeBeta, type NodeChangedData, type TreeChangeEventsBeta } from "./treeApiBeta.js";
 
 // Exporting the schema (RecursiveObject) to test that recursive types are working correctly.
 // These are `@internal` so they can't be included in the `InternalClassTreeTypes` due to https://github.com/microsoft/rushstack/issues/3639

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { NodeKind } from "./core/index.js";
+import type { NodeKind } from "../core/index.js";
 
 /**
  * The fully-qualified {@link TreeNodeSchemaCore.identifier}.

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

@@ -100,7 +100,7 @@ export function schemaFromValue(value: TreeValue): TreeNodeSchema {
 /**
  * The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.
  *
- * @public
+ * @system @public
  */
 export type ScopedSchemaName<
 	TScope extends string | undefined,
@@ -134,17 +134,46 @@ export type ScopedSchemaName<
  * The usage below generalizes this to include array and map like objects as well.
  *
  * There are two ways to use these APIs:
- * |                     | Customizable | POJO Emulation |
- * | ------------------- | ------------ |--------------- |
- * | Declaration         | `class X extends schemaFactory.object("x", {}) {}` | `const X = schemaFactory.object("x", {}); type X = NodeFromSchema<typeof X>; `
- * | Allows adding "local" (non-persisted) members | Yes. Members (including methods) can be added to class.        | No. Attempting to set non-field members will error. |
- * | Prototype | The user defined class | `Object.prototype`, `Map.prototype` or `Array.prototype` depending on node kind |
- * | Structurally named Schema | Not Supported | Supported |
- * | Explicitly named Objects | Supported | Supported |
- * | Explicitly named Maps and Arrays | Supported: Both declaration approaches can be used | Not Supported |
- * | node.js assert.deepEqual | Compares like class instances: equal to other nodes of the same type with the same content, including custom local fields. | Compares like plain objects: equal to plain JavaScript objects with the same fields, and other nodes with the same fields, even if the types are different. |
- * | IntelliSense | Shows and links to user defined class by name: `X` | Shows internal type generation logic: `object & TreeNode & ObjectFromSchemaRecord<{}> & WithType<"test.x">` |
- * | Recursion | Supported with special declaration patterns. | Unsupported: Generated d.ts files replace recursive references with `any`, breaking use of recursive schema across compilation boundaries |
+ *
+ * Customizable Approach:
+ *
+ * 1. Declaration: `class X extends schemaFactory.object("x", {}) {}`
+ *
+ * 2. Allows adding "local" (non-persisted) members: Yes. Members (including methods) can be added to the class.
+ *
+ * 3. Prototype: The user-defined class.
+ *
+ * 4. Structurally named Schema: Not Supported.
+ *
+ * 5. Explicitly named Objects: Supported.
+ *
+ * 6. Explicitly named Maps and Arrays: Supported: Both declaration approaches can be used.
+ *
+ * 7. Node.js `assert.deepEqual`: Compares like class instances: equal to other nodes of the same type with the same content, including custom local fields.
+ *
+ * 8. IntelliSense: Shows and links to user-defined class by name: `X`.
+ *
+ * 9. Recursion: Supported with special declaration patterns.
+ *
+ * POJO Emulation Approach:
+ *
+ * 1. Declaration: `const X = schemaFactory.object("x", {}); type X = NodeFromSchema<typeof X>;`
+ *
+ * 2. Allows adding "local" (non-persisted) members: No. Attempting to set non-field members will result in an error.
+ *
+ * 3. Prototype: `Object.prototype`, `Map.prototype`, or `Array.prototype` depending on node kind.
+ *
+ * 4. Structurally named Schema: Supported.
+ *
+ * 5. Explicitly named Objects: Supported.
+ *
+ * 6. Explicitly named Maps and Arrays: Not Supported.
+ *
+ * 7. Node.js `assert.deepEqual`: Compares like plain objects: equal to plain JavaScript objects with the same fields, and other nodes with the same fields, even if the types are different.
+ *
+ * 8. IntelliSense: Shows internal type generation logic: `object & TreeNode & ObjectFromSchemaRecord<{}> & WithType<"test.x">`.
+ *
+ * 9. Recursion: Unsupported: Generated `.d.ts` files replace recursive references with `any`, breaking the use of recursive schema across compilation boundaries.
  *
  * Note that while "POJO Emulation" nodes act a lot like POJO objects, they are not true POJO objects:
  *
@@ -165,6 +194,8 @@ export type ScopedSchemaName<
  * Allowing (or banning) custom/out-of-schema properties on the class is also possible in both modes: it could be orthogonal.
  * Also for consistency, if keeping the current approach to detecting `POJO Emulation` mode it might make sense to make explicitly named Maps and Arrays do the detection the same as how object does it.
  *
+ * Note: the comparison between the customizable and POJO modes is not done in a table because TSDoc does not currently have support for embedded markdown.
+ *
  * @sealed @public
  */
 export class SchemaFactory<
@@ -748,7 +779,7 @@ export function structuralName<const T extends string>(
 		names.sort();
 		// Ensure name can't have collisions by quoting and escaping any quotes in the names of types.
 		// Using JSON is a simple way to accomplish this.
-		// The outer `[]` around the result are also needed so that a single type name "Any" would not collide with the "any" case above.
+		// The outer `[]` around the result were needed so that a single type name "Any" would not collide with the "any" case which used to exist.
 		inner = JSON.stringify(names);
 	}
 	return `${collectionName}<${inner}>`;

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

@@ -3,9 +3,9 @@
  * Licensed under the MIT License.
  */
 
-import type { ValueSchema } from "../core/index.js";
-import type { NodeKind } from "./core/index.js";
-import type { FieldKind } from "./schemaTypes.js";
+import type { ValueSchema } from "../../core/index.js";
+import type { NodeKind } from "../core/index.js";
+import type { FieldKind } from "../schemaTypes.js";
 
 /**
  * Base interface for all {@link SimpleNodeSchema} implementations.
@@ -28,7 +28,7 @@ export interface SimpleNodeSchemaBase<TNodeKind extends NodeKind> {
  */
 export interface SimpleObjectNodeSchema extends SimpleNodeSchemaBase<NodeKind.Object> {
 	/**
-	 * Schemas for each of the object's fields, keyed off of schema's view keys.
+	 * Schemas for each of the object's fields, keyed off of schema's property keys.
 	 */
 	readonly fields: Record<string, SimpleFieldSchema>;
 }

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

@@ -5,8 +5,8 @@
 
 import { unreachableCase } from "@fluidframework/core-utils/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { ValueSchema } from "../core/index.js";
-import { getOrCreate } from "../util/index.js";
+import { ValueSchema } from "../../core/index.js";
+import { getOrCreate } from "../../util/index.js";
 import type {
 	JsonArrayNodeSchema,
 	JsonFieldSchema,
@@ -19,7 +19,7 @@ import type {
 	JsonTreeSchema,
 	JsonLeafSchemaType,
 } from "./jsonSchema.js";
-import { FieldKind } from "./schemaTypes.js";
+import { FieldKind } from "../schemaTypes.js";
 import type {
 	SimpleArrayNodeSchema,
 	SimpleLeafNodeSchema,
@@ -28,7 +28,7 @@ import type {
 	SimpleObjectNodeSchema,
 	SimpleTreeSchema,
 } from "./simpleSchema.js";
-import { NodeKind } from "./core/index.js";
+import { NodeKind } from "../core/index.js";
 
 /**
  * Generates a JSON Schema representation from a simple tree schema.

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

@@ -6,18 +6,14 @@
 import type { IFluidLoadable, IDisposable } from "@fluidframework/core-interfaces";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
-import type { CommitMetadata } from "../../core/index.js";
+import type { CommitMetadata, RevertibleFactory } from "../../core/index.js";
 import type { Listenable } from "../../events/index.js";
-import type { RevertibleFactory } from "../../shared-tree/index.js";
 
 import {
-	type ImplicitAllowedTypes,
-	normalizeFieldSchema,
 	type ImplicitFieldSchema,
 	type InsertableTreeFieldFromImplicitField,
 	type TreeFieldFromImplicitField,
 	FieldKind,
-	normalizeAllowedTypes,
 } from "../schemaTypes.js";
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import { toFlexSchema } from "../toFlexSchema.js";
@@ -27,6 +23,7 @@ import { isObjectNodeSchema, type ObjectNodeSchema } from "../objectNodeTypes.js
 import { markSchemaMostDerived } from "./schemaFactory.js";
 import { fail, getOrCreate } from "../../util/index.js";
 import type { MakeNominal } from "../../util/index.js";
+import { walkFieldSchema } from "../walkSchema.js";
 /**
  * Channel for a Fluid Tree DDS.
  * @remarks
@@ -343,72 +340,6 @@ export function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): v
 	}
 }
 
-export function walkNodeSchema(
-	schema: TreeNodeSchema,
-	visitor: SchemaVisitor,
-	visitedSet: Set<TreeNodeSchema>,
-): void {
-	if (visitedSet.has(schema)) {
-		return;
-	}
-	visitedSet.add(schema);
-	if (schema instanceof LeafNodeSchema) {
-		// nothing to do
-	} else if (isObjectNodeSchema(schema)) {
-		for (const field of schema.fields.values()) {
-			walkFieldSchema(field, visitor, visitedSet);
-		}
-	} else {
-		assert(
-			schema.kind === NodeKind.Array || schema.kind === NodeKind.Map,
-			0x9b3 /* invalid schema */,
-		);
-		const childTypes = schema.info as ImplicitAllowedTypes;
-		walkAllowedTypes(normalizeAllowedTypes(childTypes), visitor, visitedSet);
-	}
-	// This visit is done at the end so the traversal order is most inner types first.
-	// This was picked since when fixing errors,
-	// working from the inner types out to the types that use them will probably go better than the reverse.
-	// This does not however ensure all types referenced by a type are visited before it, since in recursive cases thats impossible.
-	visitor.node?.(schema);
-}
-
-export function walkFieldSchema(
-	schema: ImplicitFieldSchema,
-	visitor: SchemaVisitor,
-	visitedSet: Set<TreeNodeSchema> = new Set(),
-): void {
-	walkAllowedTypes(normalizeFieldSchema(schema).allowedTypeSet, visitor, visitedSet);
-}
-
-export function walkAllowedTypes(
-	allowedTypes: Iterable<TreeNodeSchema>,
-	visitor: SchemaVisitor,
-	visitedSet: Set<TreeNodeSchema>,
-): void {
-	for (const childType of allowedTypes) {
-		walkNodeSchema(childType, visitor, visitedSet);
-	}
-	visitor.allowedTypes?.(allowedTypes);
-}
-
-/**
- * Callbacks for use in {@link walkFieldSchema} / {@link walkAllowedTypes} / {@link walkNodeSchema}.
- */
-export interface SchemaVisitor {
-	/**
-	 * Called once for each node schema.
-	 */
-	node?: (schema: TreeNodeSchema) => void;
-	/**
-	 * Called once for each set of allowed types.
-	 * Includes implicit allowed types (when a single type was used instead of an array).
-	 *
-	 * This includes every field, but also the allowed types array for maps and arrays and the root if starting at {@link walkAllowedTypes}.
-	 */
-	allowedTypes?: (allowedTypes: Iterable<TreeNodeSchema>) => void;
-}
-
 /**
  * An editable view of a (version control style) branch of a shared tree based on some schema.
  *

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

@@ -0,0 +1,101 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { NodeKind, TreeChangeEvents, TreeNode, WithType } from "../core/index.js";
+import { treeNodeApi } from "./treeNodeApi.js";
+
+/**
+ * Data included for {@link TreeChangeEventsBeta.nodeChanged}.
+ * @sealed @beta
+ */
+export interface NodeChangedData<TNode extends TreeNode = TreeNode> {
+	/**
+	 * When the node changed is an object or Map node, this lists all the properties which changed.
+	 * @remarks
+	 * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
+	 *
+	 * Set to `undefined` when the {@link NodeKind} does not support this feature (currently just ArrayNodes).
+	 *
+	 * 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, make changedProperties required and strongly typed with the property names from the schema:
+		TNode extends WithType<string, NodeKind.Object, infer TInfo>
+			? string & keyof TInfo
+			: string
+	>;
+}
+
+/**
+ * Extensions to {@link TreeChangeEvents} which are not yet stable.
+ *
+ * @sealed @beta
+ */
+export interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>
+	extends 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.
+	 *
+	 * @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: NodeChangedData<TNode> &
+			// For object and Map nodes, make properties specific to them required instead of optional:
+			(TNode extends WithType<string, NodeKind.Map | NodeKind.Object>
+				? Required<Pick<NodeChangedData<TNode>, "changedProperties">>
+				: unknown),
+	) => void;
+}
+
+/**
+ * Extensions to {@link Tree} which are not yet stable.
+ * @sealed @beta
+ */
+export const TreeBeta = {
+	/**
+	 * Register an event listener on the given node.
+	 * @param node - The node whose events should be subscribed to.
+	 * @param eventName - Which event to subscribe to.
+	 * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.
+	 * @returns A callback function which will deregister the event.
+	 * This callback should be called only once.
+	 */
+	on<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(
+		node: TNode,
+		eventName: K,
+		listener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,
+	): () => void {
+		return treeNodeApi.on(node, eventName, listener);
+	},
+} as const;