fluid-framework 2.0.0-dev-rc.3.0.0.250606 → 2.0.0-dev-rc.3.0.0.253463

package/api-report/fluid-framework.api.md

@@ -22,9 +22,6 @@ export type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
 // @public
 export type ApplyKind<T, Kind extends FieldKind> = Kind extends FieldKind.Required ? T : undefined | T;
 
-// @public
-export type ArrayToUnion<T extends readonly unknown[]> = T[number];
-
 // @public
 export enum AttachState {
     Attached = "Attached",
@@ -41,8 +38,8 @@ export enum CommitKind {
 
 // @public
 export interface CommitMetadata {
-    isLocal: boolean;
-    kind: CommitKind;
+    readonly isLocal: boolean;
+    readonly kind: CommitKind;
 }
 
 // @public
@@ -89,7 +86,7 @@ export interface ContainerSchema {
 // @public
 export type DataObjectClass<T extends IFluidLoadable = IFluidLoadable> = {
     readonly factory: {
-        IFluidDataStoreFactory: DataObjectClass<T>["factory"];
+        readonly IFluidDataStoreFactory: DataObjectClass<T>["factory"];
     };
 } & (new (...args: any[]) => T);
 
@@ -135,13 +132,21 @@ export enum FieldKind {
     Required = 1
 }
 
+// @public
+export interface FieldProps {
+    readonly key?: string;
+}
+
 // @public @sealed
 export class FieldSchema<out Kind extends FieldKind = FieldKind, out Types extends ImplicitAllowedTypes = ImplicitAllowedTypes> {
-    constructor(kind: Kind, allowedTypes: Types);
-    // (undocumented)
+    constructor(
+    kind: Kind,
+    allowedTypes: Types,
+    props?: FieldProps | undefined);
     readonly allowedTypes: Types;
-    // (undocumented)
+    get allowedTypeSet(): ReadonlySet<TreeNodeSchema>;
     readonly kind: Kind;
+    readonly props?: FieldProps | undefined;
     protected _typeCheck?: MakeNominal;
 }
 
@@ -149,12 +154,12 @@ export class FieldSchema<out Kind extends FieldKind = FieldKind, out Types exten
 export type FlexList<Item = unknown> = readonly LazyItem<Item>[];
 
 // @public
-export type FlexListToUnion<TList extends FlexList> = ExtractItemType<ArrayToUnion<TList>>;
+export type FlexListToUnion<TList extends FlexList> = ExtractItemType<TList[number]>;
 
 // @public
 export interface IConnection {
-    id: string;
-    mode: "write" | "read";
+    readonly id: string;
+    readonly mode: "write" | "read";
 }
 
 // @public
@@ -190,8 +195,8 @@ export interface IFluidContainerEvents extends IEvent {
 
 // @public
 export interface IMember {
-    connections: IConnection[];
-    userId: string;
+    readonly connections: IConnection[];
+    readonly userId: string;
 }
 
 // @public
@@ -223,7 +228,7 @@ export type InsertableTypedNode<T extends TreeNodeSchema> = (T extends {
 
 // @public
 export interface IServiceAudience<M extends IMember> extends IEventProvider<IServiceAudienceEvents<M>> {
-    getMembers(): Map<string, M>;
+    getMembers(): ReadonlyMap<string, M>;
     getMyself(): Myself<M> | undefined;
 }
 
@@ -269,8 +274,8 @@ export interface ITree extends IChannel {
 
 // @public @sealed
 export interface IValueChanged {
-    key: string;
-    previousValue: any;
+    readonly key: string;
+    readonly previousValue: any;
 }
 
 // @public
@@ -291,7 +296,7 @@ export type MemberChangedListener<M extends IMember> = (clientId: string, member
 
 // @public
 export type Myself<M extends IMember = IMember> = M & {
-    currentConnection: string;
+    readonly currentConnection: string;
 };
 
 // @public
@@ -339,15 +344,16 @@ export class SchemaFactory<out TScope extends string | undefined = string | unde
     readonly boolean: TreeNodeSchema<"com.fluidframework.leaf.boolean", NodeKind.Leaf, boolean, boolean>;
     // @deprecated
     fixRecursiveReference<T extends AllowedTypes>(...types: T): void;
-    readonly handle: TreeNodeSchema<"com.fluidframework.leaf.handle", NodeKind.Leaf, IFluidHandle<FluidObject & IFluidLoadable>, IFluidHandle<FluidObject & IFluidLoadable>>;
+    readonly handle: TreeNodeSchema<"com.fluidframework.leaf.handle", NodeKind.Leaf, IFluidHandle<FluidObject<unknown> & IFluidLoadable>, IFluidHandle<FluidObject<unknown> & IFluidLoadable>>;
     map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>, Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, true, T>;
     map<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>, Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, true, T>;
     namedArray_internal<Name extends TName | string, const T extends ImplicitAllowedTypes, const ImplicitlyConstructable extends boolean>(name: Name, allowedTypes: T, customizable: boolean, implicitlyConstructable: ImplicitlyConstructable): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Array, TreeArrayNode<T> & WithType<ScopedSchemaName<TScope, string>>, Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>, ImplicitlyConstructable, T>;
     namedMap_internal<Name extends TName | string, const T extends ImplicitAllowedTypes, const ImplicitlyConstructable extends boolean>(name: Name, allowedTypes: T, customizable: boolean, implicitlyConstructable: ImplicitlyConstructable): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Map, TreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>, Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>, ImplicitlyConstructable, T>;
     readonly null: TreeNodeSchema<"com.fluidframework.leaf.null", NodeKind.Leaf, null, null>;
     readonly number: TreeNodeSchema<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number>;
-    object<const Name extends TName, const T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>(name: Name, t: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, TreeNode & ObjectFromSchemaRecord<T> & WithType<ScopedSchemaName<TScope, Name>>, object & InsertableObjectFromSchemaRecord<T>, true, T>;
-    optional<const T extends ImplicitAllowedTypes>(t: T): FieldSchema<FieldKind.Optional, T>;
+    object<const Name extends TName, const T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>(name: Name, fields: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, TreeObjectNode<T, ScopedSchemaName<TScope, Name>>, object & InsertableObjectFromSchemaRecord<T>, true, T>;
+    optional<const T extends ImplicitAllowedTypes>(t: T, props?: FieldProps): FieldSchema<FieldKind.Optional, T>;
+    required<const T extends ImplicitAllowedTypes>(t: T, props?: FieldProps): FieldSchema<FieldKind.Required, T>;
     // (undocumented)
     readonly scope: TScope;
     readonly string: TreeNodeSchema<"com.fluidframework.leaf.string", NodeKind.Leaf, string, string>;
@@ -409,6 +415,12 @@ export interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom> extends Readonl
     removeRange(start?: number, end?: number): void;
 }
 
+// @public
+export interface TreeChangeEvents {
+    nodeChanged(): void;
+    treeChanged(): void;
+}
+
 // @public
 export class TreeConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> {
     constructor(schema: TSchema, initialTree: () => InsertableTreeFieldFromImplicitField<TSchema>);
@@ -439,17 +451,12 @@ export abstract class TreeNode implements WithType {
 export interface TreeNodeApi {
     is<TSchema extends TreeNodeSchema>(value: unknown, schema: TSchema): value is NodeFromSchema<TSchema>;
     key(node: TreeNode): string | number;
-    on<K extends keyof TreeNodeEvents>(node: TreeNode, eventName: K, listener: TreeNodeEvents[K]): () => void;
+    on<K extends keyof TreeChangeEvents>(node: TreeNode, eventName: K, listener: TreeChangeEvents[K]): () => void;
     parent(node: TreeNode): TreeNode | undefined;
     schema<T extends TreeNode | TreeLeafValue>(node: T): TreeNodeSchema<string, NodeKind, unknown, T>;
     readonly status: (node: TreeNode) => TreeStatus;
 }
 
-// @public
-export interface TreeNodeEvents {
-    afterChange(): void;
-}
-
 // @public
 export type TreeNodeFromImplicitAllowedTypes<TSchema extends ImplicitAllowedTypes = TreeNodeSchema> = TSchema extends TreeNodeSchema ? NodeFromSchema<TSchema> : TSchema extends AllowedTypes ? NodeFromSchema<FlexListToUnion<TSchema>> : unknown;
 
@@ -478,6 +485,9 @@ export interface TreeNodeSchemaNonClass<out Name extends string = string, out Ki
     create(data: TInsertable): TNode;
 }
 
+// @public
+export type TreeObjectNode<T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecord<T> & WithType<TypeName>;
+
 // @public
 export enum TreeStatus {
     Deleted = 2,

package/dist/fluid-framework-alpha.d.ts

@@ -30,12 +30,6 @@ export declare type AllowedTypes = readonly LazyItem<TreeNodeSchema>[];
  */
 export declare type ApplyKind<T, Kind extends FieldKind> = Kind extends FieldKind.Required ? T : undefined | T;
 
-/**
- * Convert a Array type into a union of its value types.
- * @public
- */
-export declare type ArrayToUnion<T extends readonly unknown[]> = T[number];
-
 /**
  * The attachment state of some Fluid data (e.g. a container or data store), denoting whether it is uploaded to the
  * service.  The transition from detached to attached state is a one-way transition.
@@ -81,11 +75,11 @@ export declare interface CommitMetadata {
     /**
      * A {@link CommitKind} enum value describing whether the commit represents an Edit, an Undo, or a Redo.
      */
-    kind: CommitKind;
+    readonly kind: CommitKind;
     /**
      * Indicates whether the commit is a local edit
      */
-    isLocal: boolean;
+    readonly isLocal: boolean;
 }
 
 /**
@@ -231,7 +225,7 @@ export declare interface ContainerSchema {
  */
 export declare type DataObjectClass<T extends IFluidLoadable = IFluidLoadable> = {
     readonly factory: {
-        IFluidDataStoreFactory: DataObjectClass<T>["factory"];
+        readonly IFluidDataStoreFactory: DataObjectClass<T>["factory"];
     };
 } & (new (...args: any[]) => T);
 
@@ -375,6 +369,65 @@ export declare enum FieldKind {
     Required = 1
 }
 
+/**
+ * Additional information to provide to a {@link FieldSchema}.
+ *
+ * @public
+ */
+export declare interface FieldProps {
+    /**
+     * The unique identifier of a field, used in the persisted form of the tree.
+     *
+     * @remarks
+     * If not explicitly set via the schema, this is the same as the schema's property key.
+     *
+     * Specifying a stored key that differs from the property key is particularly useful in refactoring scenarios.
+     * To update the developer-facing API, while maintaining backwards compatibility with existing SharedTree data,
+     * you can change the property key and specify the previous property key as the stored key.
+     *
+     * Notes:
+     *
+     * - Stored keys have no impact on standard JavaScript behavior, on tree nodes. For example, `Object.keys`
+     * will always return the property keys specified in the schema, ignoring any stored keys that differ from
+     * the property keys.
+     *
+     * - When specifying stored keys in an object schema, you must ensure that the final set of stored keys
+     * (accounting for those implicitly derived from property keys) contains no duplicates.
+     * This is validated at runtime.
+     *
+     * @example Refactoring code without breaking compatibility with existing data
+     *
+     * Consider some existing object schema:
+     *
+     * ```TypeScript
+     * class Point extends schemaFactory.object("Point", {
+     * 	xPosition: schemaFactory.number,
+     * 	yPosition: schemaFactory.number,
+     * 	zPosition: schemaFactory.optional(schemaFactory.number),
+     * });
+     * ```
+     *
+     * Developers using nodes of this type would access the the `xPosition` property as `point.xPosition`.
+     *
+     * We would like to refactor the schema to omit "Position" from the property keys, but application data has
+     * already been persisted using the original property keys. To maintain compatibility with existing data,
+     * we can refactor the schema as follows:
+     *
+     * ```TypeScript
+     * class Point extends schemaFactory.object("Point", {
+     * 	x: schemaFactory.required(schemaFactory.number, { key: "xPosition" }),
+     * 	y: schemaFactory.required(schemaFactory.number, { key: "yPosition" }),
+     * 	z: schemaFactory.optional(schemaFactory.number, { key: "zPosition" }),
+     * });
+     * ```
+     *
+     * Now, developers can access the `x` property as `point.x`, while existing data can still be collaborated on.
+     *
+     * @defaultValue If not specified, the key that is persisted is the property key that was specified in the schema.
+     */
+    readonly key?: string;
+}
+
 /**
  * All policy for a specific field,
  * including functionality that does not have to be kept consistent across versions or deterministic.
@@ -383,19 +436,44 @@ export declare enum FieldKind {
  * @sealed @public
  */
 export declare class FieldSchema<out Kind extends FieldKind = FieldKind, out Types extends ImplicitAllowedTypes = ImplicitAllowedTypes> {
+    /**
+     * The {@link https://en.wikipedia.org/wiki/Kind_(type_theory) | kind } of this field.
+     * Determines the multiplicity, viewing and editing APIs as well as the merge resolution policy.
+     */
     readonly kind: Kind;
+    /**
+     * What types of tree nodes are allowed in this field.
+     */
     readonly allowedTypes: Types;
+    /**
+     * Optional properties associated with the field.
+     */
+    readonly props?: FieldProps | undefined;
     /**
      * This class is used with instanceof, and therefore should have nominal typing.
      * This field enforces that.
      */
     protected _typeCheck?: MakeNominal;
+    private readonly lazyTypes;
     /**
-     * @param kind - The [kind](https://en.wikipedia.org/wiki/Kind_(type_theory)) of this field.
-     * Determine the multiplicity, viewing and editing APIs as well as the merge resolution policy.
-     * @param allowedTypes - What types of tree nodes are allowed in this field.
+     * What types of tree nodes are allowed in this field.
+     * @remarks Counterpart to {@link FieldSchema.allowedTypes}, with any lazy definitions evaluated.
      */
-    constructor(kind: Kind, allowedTypes: Types);
+    get allowedTypeSet(): ReadonlySet<TreeNodeSchema>;
+    constructor(
+    /**
+     * The {@link https://en.wikipedia.org/wiki/Kind_(type_theory) | kind } of this field.
+     * Determines the multiplicity, viewing and editing APIs as well as the merge resolution policy.
+     */
+    kind: Kind, 
+    /**
+     * What types of tree nodes are allowed in this field.
+     */
+    allowedTypes: Types, 
+    /**
+     * Optional properties associated with the field.
+     */
+    props?: FieldProps | undefined);
 }
 
 /**
@@ -414,7 +492,7 @@ export declare type FlexList<Item = unknown> = readonly LazyItem<Item>[];
  * Normalize FlexList type to a union.
  * @public
  */
-export declare type FlexListToUnion<TList extends FlexList> = ExtractItemType<ArrayToUnion<TList>>;
+export declare type FlexListToUnion<TList extends FlexList> = ExtractItemType<TList[number]>;
 
 /**
  * Base interface for information for each connection made to the Fluid session.
@@ -426,11 +504,11 @@ export declare interface IConnection {
     /**
      * A unique ID for the connection.  A single user may have multiple connections, each with a different ID.
      */
-    id: string;
+    readonly id: string;
     /**
      * Whether the connection is in read or read/write mode.
      */
-    mode: "write" | "read";
+    readonly mode: "write" | "read";
 }
 
 /**
@@ -657,11 +735,11 @@ export declare interface IMember {
     /**
      * An ID for the user, unique among each individual user connecting to the session.
      */
-    userId: string;
+    readonly userId: string;
     /**
      * The set of connections the user has made, e.g. from multiple tabs or devices.
      */
-    connections: IConnection[];
+    readonly connections: IConnection[];
 }
 
 /**
@@ -743,7 +821,7 @@ export declare interface IServiceAudience<M extends IMember> extends IEventProvi
      * member object.  The implementation may choose to exclude certain connections from the returned map.
      * E.g. ServiceAudience excludes non-interactive connections to represent only the roster of live users.
      */
-    getMembers(): Map<string, M>;
+    getMembers(): ReadonlyMap<string, M>;
     /**
      * Returns the current active user on this client once they are connected. Otherwise, returns undefined.
      */
@@ -942,11 +1020,11 @@ export declare interface IValueChanged {
     /**
      * The key storing the value that changed.
      */
-    key: string;
+    readonly key: string;
     /**
      * The value that was stored at the key prior to the change.
      */
-    previousValue: any;
+    readonly previousValue: any;
 }
 
 /**
@@ -1070,7 +1148,7 @@ export declare type MemberChangedListener<M extends IMember> = (clientId: string
  * @public
  */
 export declare type Myself<M extends IMember = IMember> = M & {
-    currentConnection: string;
+    readonly currentConnection: string;
 };
 
 /**
@@ -1281,18 +1359,19 @@ export declare class SchemaFactory<out TScope extends string | undefined = strin
     /**
      * {@link TreeNodeSchema} for holding an {@link @fluidframework/core-interfaces#(IFluidHandle:interface)}.
      */
-    readonly handle: TreeNodeSchema<"com.fluidframework.leaf.handle", NodeKind.Leaf, IFluidHandle<FluidObject & IFluidLoadable>, IFluidHandle<FluidObject & IFluidLoadable>>;
+    readonly handle: TreeNodeSchema<"com.fluidframework.leaf.handle", NodeKind.Leaf, IFluidHandle<FluidObject<unknown> & IFluidLoadable>, IFluidHandle<FluidObject<unknown> & IFluidLoadable>>;
     /**
      * Construct a class that provides the common parts all TreeNodeSchemaClass share.
      * More specific schema extend this class.
      */
     private nodeSchema;
     /**
-     * Define a {@link TreeNodeSchema} for an object node.
+     * Define a {@link TreeNodeSchema} for a {@link TreeObjectNode}.
      *
      * @param name - Unique identifier for this schema within this factory's scope.
+     * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.
      */
-    object<const Name extends TName, const T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>(name: Name, t: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, TreeNode & ObjectFromSchemaRecord<T> & WithType<ScopedSchemaName<TScope, Name>>, object & InsertableObjectFromSchemaRecord<T>, true, T>;
+    object<const Name extends TName, const T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>(name: Name, fields: T): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, TreeObjectNode<T, ScopedSchemaName<TScope, Name>>, object & InsertableObjectFromSchemaRecord<T>, true, T>;
     /**
      * Define a structurally typed {@link TreeNodeSchema} for a {@link TreeMapNode}.
      *
@@ -1400,9 +1479,23 @@ export declare class SchemaFactory<out TScope extends string | undefined = strin
      */
     namedArray_internal<Name extends TName | string, const T extends ImplicitAllowedTypes, const ImplicitlyConstructable extends boolean>(name: Name, allowedTypes: T, customizable: boolean, implicitlyConstructable: ImplicitlyConstructable): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Array, TreeArrayNode<T> & WithType<ScopedSchemaName<TScope, string>>, Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>, ImplicitlyConstructable, T>;
     /**
-     * Make a field optional instead of the default which is required.
+     * Make a field optional instead of the default, which is required.
+     *
+     * @param t - The types allowed under the field.
+     * @param props - Optional properties to associate with the field.
+     */
+    optional<const T extends ImplicitAllowedTypes>(t: T, props?: FieldProps): FieldSchema<FieldKind.Optional, T>;
+    /**
+     * Make a field explicitly required.
+     *
+     * @param t - The types allowed under the field.
+     * @param props - Optional properties to associate with the field.
+     *
+     * @remarks
+     * Fields are required by default, but this API can be used to make the required nature explicit in the schema,
+     * and allows associating custom {@link FieldProps | properties} with the field.
      */
-    optional<const T extends ImplicitAllowedTypes>(t: T): FieldSchema<FieldKind.Optional, T>;
+    required<const T extends ImplicitAllowedTypes>(t: T, props?: FieldProps): FieldSchema<FieldKind.Required, T>;
     /**
      * Function which can be used for its compile time side-effects to tweak the evaluation order of recursive types to make them compile.
      * @remarks
@@ -1460,14 +1553,14 @@ export declare interface SchemaIncompatible {
 export declare type ScopedSchemaName<TScope extends string | undefined, TName extends number | string> = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`;
 
 /**
- * {@inheritDoc ISharedMap}
+ * Entrypoint for {@link ISharedMap} creation.
  * @public
  * @deprecated Please use SharedTree for new containers. SharedMap is supported for loading preexisting Fluid Framework 1.0 containers only.
  */
 export declare const SharedMap: ISharedObjectKind<ISharedMap>;
 
 /**
- * {@inheritDoc ISharedMap}
+ * Entrypoint for {@link ISharedMap} creation.
  * @public
  * @deprecated Use ISharedMap instead.
  * @privateRemarks
@@ -1694,6 +1787,86 @@ export declare interface TreeArrayNodeBase<out T, in TNew, in TMoveFrom> extends
     moveRangeToIndex(index: number, sourceStart: number, sourceEnd: number, source: TMoveFrom): void;
 }
 
+/**
+ * A collection of events that can be raised 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.
+ *
+ * @public
+ */
+export declare interface TreeChangeEvents {
+    /**
+     * Emitted by a node when a batch of changes is applied to it, where a change is:
+     *
+     * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
+     * to something else, including `undefined`).
+     *
+     * - For an array node, when an element is added, removed, or moved.
+     *
+     * - For a map node, when an entry is added, updated, or removed.
+     *
+     * @remarks
+     * This event is not raised when:
+     *
+     * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing
+     * elements/entries) will raise 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 raised 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.
+     * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about
+     * how many times this event will be raised during any intermediate states.
+     * When it is raised, 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).
+     */
+    nodeChanged(): void;
+    /**
+     * Emitted by a node when something _may_ have changed anywhere in the subtree rooted at it.
+     *
+     * @remarks
+     * This event is guaranteed to be emitted whenever the subtree _has_ changed.
+     * However, it might also be emitted when the subtree has no visible changes compared to before the event firing.
+     *
+     * Consumers of this event have the guarantee that they won't miss any changes, but should also handle the scenario
+     * where the event fires with no visible changes as well.
+     *
+     * This event is not raised when the node itself is moved to a different location in the tree or removed from the tree.
+     * In that case it is raised 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.
+     * While a batch of edits will as a whole update the tree to the appropriate end state, no guarantees are made about
+     * how many times this event will be raised during any intermediate states.
+     * When it is raised, the tree is guaranteed to be in-schema.
+     */
+    treeChanged(): void;
+}
+
 /**
  * Configuration for how to {@link ITree.schematize|schematize} a tree.
  * @public
@@ -1847,27 +2020,19 @@ export declare interface TreeNodeApi {
     key(node: TreeNode): string | number;
     /**
      * 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 TreeNodeEvents>(node: TreeNode, eventName: K, listener: TreeNodeEvents[K]): () => void;
+    on<K extends keyof TreeChangeEvents>(node: TreeNode, eventName: K, listener: TreeChangeEvents[K]): () => void;
     /**
      * Returns the {@link TreeStatus} of the given node.
      */
     readonly status: (node: TreeNode) => TreeStatus;
 }
 
-/**
- * A collection of events that can be raised by a {@link TreeNode}.
- * @public
- */
-export declare interface TreeNodeEvents {
-    /**
-     * Raised on a node right after a change is applied to one of its fields or the fields of a descendant node.
-     */
-    afterChange(): void;
-}
-
 /**
  * Type of of tree node for a field of the given schema.
  * @public
@@ -1948,6 +2113,18 @@ export declare interface TreeNodeSchemaNonClass<out Name extends string = string
     create(data: TInsertable): TNode;
 }
 
+/**
+ * A {@link TreeNode} which modules a JavaScript object.
+ * @remarks
+ * Object nodes consist of a type which specifies which {@link TreeNodeSchema} they use (see {@link TreeNodeApi.schema}), and a collections of fields, each with a distinct `key` and its own {@link FieldSchema} defining what can be placed under that key.
+ *
+ * All non-empty fields on an object node are exposed as enumerable own properties with string keys.
+ * No other own `own` or `enumerable` properties are included on object nodes unless the user of the node manually adds custom session only state.
+ * This allows a majority of general purpose JavaScript object processing operations (like `for...in`, `Reflect.ownKeys()` and `Object.entries()`) to enumerate all the children.
+ * @public
+ */
+export declare type TreeObjectNode<T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecord<T> & WithType<TypeName>;
+
 /**
  * Status of the tree that a particular node belongs to.
  * @public