@fluidframework/tree 2.10.0-305357 → 2.10.0-307060

package/src/core/forest/forest.ts

@@ -58,7 +58,12 @@ export interface ForestEvents {
  *
  * When invalidating, all outstanding cursors must be freed or cleared.
  */
-export interface IForestSubscription extends Listenable<ForestEvents> {
+export interface IForestSubscription {
+	/**
+	 * Events for this forest.
+	 */
+	readonly events: Listenable<ForestEvents>;
+
 	/**
 	 * Set of anchors this forest is tracking.
 	 *

package/src/core/index.ts

@@ -121,7 +121,7 @@ export {
 	type TreeFieldStoredSchema,
 	ValueSchema,
 	TreeNodeStoredSchema,
-	type TreeStoredSchemaSubscription as TreeStoredSchemaSubscription,
+	type TreeStoredSchemaSubscription,
 	type MutableTreeStoredSchema,
 	type FieldKindIdentifier,
 	type FieldKindData,

package/src/core/schema-stored/storedSchemaRepository.ts

@@ -37,9 +37,12 @@ export interface SchemaEvents {
 /**
  * A collection of stored schema that fires events in response to changes.
  */
-export interface TreeStoredSchemaSubscription
-	extends Listenable<SchemaEvents>,
-		TreeStoredSchema {}
+export interface TreeStoredSchemaSubscription extends TreeStoredSchema {
+	/**
+	 * Events for this schema subscription.
+	 */
+	readonly events: Listenable<SchemaEvents>;
+}
 
 /**
  * Mutable collection of stored schema.
@@ -59,7 +62,8 @@ export interface MutableTreeStoredSchema extends TreeStoredSchemaSubscription {
 export class TreeStoredSchemaRepository implements MutableTreeStoredSchema {
 	protected nodeSchemaData: BTree<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>;
 	protected rootFieldSchemaData: TreeFieldStoredSchema;
-	protected readonly events = createEmitter<SchemaEvents>();
+	protected readonly _events = createEmitter<SchemaEvents>();
+	public readonly events: Listenable<SchemaEvents> = this._events;
 
 	/**
 	 * Copies in the provided schema. If `data` is an TreeStoredSchemaRepository, it will be cheap-cloned.
@@ -92,13 +96,6 @@ export class TreeStoredSchemaRepository implements MutableTreeStoredSchema {
 		}
 	}
 
-	public on<K extends keyof SchemaEvents>(
-		eventName: K,
-		listener: SchemaEvents[K],
-	): () => void {
-		return this.events.on(eventName, listener);
-	}
-
 	public get nodeSchema(): ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema> {
 		// Btree implements iterator, but not in a type-safe way
 		return this.nodeSchemaData as unknown as ReadonlyMap<
@@ -112,12 +109,12 @@ export class TreeStoredSchemaRepository implements MutableTreeStoredSchema {
 	}
 
 	public apply(newSchema: TreeStoredSchema): void {
-		this.events.emit("beforeSchemaChange", newSchema);
+		this._events.emit("beforeSchemaChange", newSchema);
 		const clone = new TreeStoredSchemaRepository(newSchema);
 		// In the future, we could use btree's delta functionality to do a more efficient update
 		this.rootFieldSchemaData = clone.rootFieldSchemaData;
 		this.nodeSchemaData = clone.nodeSchemaData;
-		this.events.emit("afterSchemaChange", newSchema);
+		this._events.emit("afterSchemaChange", newSchema);
 	}
 
 	public clone(): TreeStoredSchemaRepository {

package/src/core/tree/anchorSet.ts

@@ -206,7 +206,12 @@ export interface AnchorSetRootEvents {
 /**
  * Node in a tree of anchors.
  */
-export interface AnchorNode extends UpPath<AnchorNode>, Listenable<AnchorEvents> {
+export interface AnchorNode extends UpPath<AnchorNode> {
+	/**
+	 * Events for this anchor node.
+	 */
+	readonly events: Listenable<AnchorEvents>;
+
 	/**
 	 * Allows access to data stored on the Anchor in "slots".
 	 * Use {@link anchorSlot} to create slots.
@@ -277,8 +282,10 @@ export function anchorSlot<TContent>(): AnchorSlot<TContent> {
  *
  * @sealed
  */
-export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator {
-	private readonly events = createEmitter<AnchorSetRootEvents>();
+export class AnchorSet implements AnchorLocator {
+	readonly #events = createEmitter<AnchorSetRootEvents>();
+	public readonly events: Listenable<AnchorSetRootEvents> = this.#events;
+
 	/**
 	 * Incrementing counter to give each anchor in this set a unique index for its identifier.
 	 * "0" is reserved for the `NeverAnchor`.
@@ -312,7 +319,7 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 	private activeVisitor?: DeltaVisitor;
 
 	public constructor() {
-		this.on("treeChanging", () => {
+		this.events.on("treeChanging", () => {
 			this.generationNumber += 1;
 		});
 	}
@@ -344,13 +351,6 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 		}
 	}
 
-	public on<K extends keyof AnchorSetRootEvents>(
-		eventName: K,
-		listener: AnchorSetRootEvents[K],
-	): () => void {
-		return this.events.on(eventName, listener);
-	}
-
 	/**
 	 * Check if there are currently no anchors tracked.
 	 * Mainly for testing anchor cleanup.
@@ -792,7 +792,7 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 			notifyChildrenChanging(): void {
 				this.maybeWithNode(
 					(p) => p.events.emit("childrenChanging", p),
-					() => this.anchorSet.events.emit("childrenChanging", this.anchorSet),
+					() => this.anchorSet.#events.emit("childrenChanging", this.anchorSet),
 				);
 			},
 			notifyChildrenChanged(): void {
@@ -1098,7 +1098,7 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 				this.parentField = undefined;
 			},
 		};
-		this.events.emit("treeChanging", this);
+		this.#events.emit("treeChanging", this);
 		this.activeVisitor = visitor;
 		return visitor;
 	}
@@ -1209,13 +1209,6 @@ class PathNode extends ReferenceCountedBase implements UpPath<PathNode>, AnchorN
 		super(1);
 	}
 
-	public on<K extends keyof AnchorEvents>(
-		eventName: K,
-		listener: AnchorEvents[K],
-	): () => void {
-		return this.events.on(eventName, listener);
-	}
-
 	public child(key: FieldKey, index: number): UpPath<AnchorNode> {
 		// Fast path: if child exists, return it.
 		return (

package/src/events/emitter.ts

@@ -3,7 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { setInNestedMap } from "../util/index.js";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { getOrCreate } from "../util/index.js";
 import type { Listenable, Listeners, Off } from "./listeners.js";
 
 /**
@@ -63,7 +64,7 @@ export interface HasListeners<TListeners extends Listeners<TListeners>> {
 /**
  * Provides an API for subscribing to and listening to events.
  *
- * @remarks Classes wishing to emit events may either extend this class or compose over it.
+ * @remarks Classes wishing to emit events may either extend this class, compose over it, or expose it as a property of type {@link Listenable}.
  *
  * @example Extending this class
  *
@@ -97,13 +98,27 @@ export interface HasListeners<TListeners extends Listeners<TListeners>> {
  * 	}
  * }
  * ```
+ *
+ * @example Exposing this class as a property
+ *
+ * ```typescript
+ * class MyExposingClass {
+ * 	private readonly _events = createEmitter<MyEvents>();
+ * 	public readonly events: Listenable<MyEvents> = this._events;
+ *
+ * 	private load() {
+ * 		this._events.emit("loaded");
+ * 		const results: number[] = this._events.emitAndCollect("computed");
+ * 	}
+ * }
+ * ```
  */
 export class EventEmitter<TListeners extends Listeners<TListeners>>
 	implements Listenable<TListeners>, HasListeners<TListeners>
 {
 	protected readonly listeners = new Map<
 		keyof TListeners,
-		Map<Off, (...args: any[]) => TListeners[keyof TListeners]>
+		Set<(...args: any[]) => TListeners[keyof TListeners]>
 	>();
 
 	// Because this is protected and not public, calling this externally (not from a subclass) makes sending events to the constructed instance impossible.
@@ -118,11 +133,10 @@ export class EventEmitter<TListeners extends Listeners<TListeners>>
 		if (listeners !== undefined) {
 			// Current tsc (5.4.5) cannot spread `args` into `listener()`.
 			const argArray: unknown[] = args;
-
 			// This explicitly copies listeners so that new listeners added during this call to emit will not receive this event.
-			for (const [off, listener] of [...listeners]) {
+			for (const listener of [...listeners]) {
 				// If listener has been unsubscribed while invoking other listeners, skip it.
-				if (listeners.has(off)) {
+				if (listeners.has(listener)) {
 					listener(...argArray);
 				}
 			}
@@ -145,29 +159,32 @@ export class EventEmitter<TListeners extends Listeners<TListeners>>
 		return [];
 	}
 
-	/**
-	 * Register an event listener.
-	 * @param eventName - the name of the event
-	 * @param listener - the handler to run when the event is fired by the emitter
-	 * @returns a function which will deregister the listener when run.
-	 * This function will error if called more than once.
-	 */
 	public on<K extends keyof Listeners<TListeners>>(
 		eventName: K,
 		listener: TListeners[K],
 	): Off {
-		const off: Off = () => {
-			const currentListeners = this.listeners.get(eventName);
-			if (currentListeners?.delete(off) === true) {
-				if (currentListeners.size === 0) {
-					this.listeners.delete(eventName);
-					this.noListeners?.(eventName);
-				}
-			}
-		};
+		const listeners = getOrCreate(this.listeners, eventName, () => new Set());
+		if (listeners.has(listener)) {
+			const eventDescription =
+				typeof eventName === "symbol" ? eventName.description : String(eventName.toString());
 
-		setInNestedMap(this.listeners, eventName, off, listener);
-		return off;
+			throw new UsageError(
+				`Attempted to register the same listener object twice for event ${eventDescription}`,
+			);
+		}
+		listeners.add(listener);
+		return () => this.off(eventName, listener);
+	}
+
+	public off<K extends keyof Listeners<TListeners>>(
+		eventName: K,
+		listener: TListeners[K],
+	): void {
+		const listeners = this.listeners.get(eventName);
+		if (listeners?.delete(listener) === true && listeners.size === 0) {
+			this.listeners.delete(eventName);
+			this.noListeners?.(eventName);
+		}
 	}
 
 	public hasListeners(eventName?: keyof TListeners): boolean {
@@ -225,6 +242,10 @@ class ComposableEventEmitter<TListeners extends Listeners<TListeners>>
  * 	public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): Off {
  * 		return this.events.on(eventName, listener);
  * 	}
+ *
+ * 	public off<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): void {
+ * 		return this.events.off(eventName, listener);
+ * 	}
  * }
  * ```
  */

package/src/events/listeners.ts

@@ -50,13 +50,25 @@ export interface Listenable<TListeners extends object> {
 	/**
 	 * Register an event listener.
 	 * @param eventName - The name of the event.
-	 * @param listener - the handler to run when the event is fired by the emitter
-	 * @returns a {@link Off | function} which will deregister the listener when called.
-	 * This deregistration function is idempotent and therefore may be safely called more than once with no effect.
-	 * @remarks Do not register the exact same `listener` object for the same event more than once.
-	 * Doing so will result in undefined behavior, and is not guaranteed to behave the same in future versions of this library.
+	 * @param listener - The listener function to run when the event is fired.
+	 * @returns A {@link Off | function} which will deregister the listener when called.
+	 * Calling the deregistration function more than once will have no effect.
+	 *
+	 * Listeners may also be deregistered by passing the listener to {@link Listenable.off | off()}.
+	 * @remarks Registering the exact same `listener` object for the same event more than once will throw an error.
+	 * If registering the same listener for the same event multiple times is desired, consider using a wrapper function for the second subscription.
 	 */
 	on<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): Off;
+
+	/**
+	 * Deregister an event listener.
+	 * @param eventName - The name of the event.
+	 * @param listener - The listener function to remove from the current set of event listeners.
+	 * @remarks If `listener` is not currently registered, this method will have no effect.
+	 *
+	 * Listeners may also be deregistered by calling the {@link Off | deregistration function} returned when they are {@link Listenable.on | registered}.
+	 */
+	off<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): void;
 }
 
 /**

package/src/feature-libraries/chunked-forest/basicChunk.ts

@@ -30,14 +30,22 @@ export class BasicChunk extends ReferenceCountedBase implements TreeChunk {
 	/**
 	 * Create a tree chunk with ref count 1.
 	 *
-	 * @param fields - provides exclusive deep ownership of this map to this object (which might mutate it in the future).
-	 * The caller must have already accounted for this reference to the children in this map (via `referenceAdded`),
-	 * and any edits to this must update child reference counts.
-	 * @param value - the value on this node, if any.
+	 * Caller must have already accounted for references via `fields` to the children in the fields map (via `referenceAdded`).
 	 */
 	public constructor(
 		public type: TreeNodeSchemaIdentifier,
+		/**
+		 * Fields of this node.
+		 * @remarks
+		 * This object has exclusive deep ownership of this map (which might mutate it in the future).
+		 * Any code editing this map must update child reference counts.
+		 *
+		 * Like with {@link MapTree}, fields with no nodes must be removed from the map.
+		 */
 		public fields: Map<FieldKey, TreeChunk[]>,
+		/**
+		 * The value on this node, if any.
+		 */
 		public value?: TreeValue,
 	) {
 		super();

package/src/feature-libraries/chunked-forest/chunkTree.ts

@@ -134,7 +134,7 @@ export class Chunker implements IChunker {
 		if (cached !== undefined) {
 			return cached;
 		}
-		this.unregisterSchemaCallback = this.schema.on("afterSchemaChange", () =>
+		this.unregisterSchemaCallback = this.schema.events.on("afterSchemaChange", () =>
 			this.schemaChanged(),
 		);
 		return this.tryShapeFromSchema(this.schema, this.policy, schema, this.typeShapes);

package/src/feature-libraries/chunked-forest/chunkedForest.ts

@@ -28,7 +28,7 @@ import {
 	mapCursorField,
 	rootFieldKey,
 } from "../../core/index.js";
-import { createEmitter } from "../../events/index.js";
+import { createEmitter, type Listenable } from "../../events/index.js";
 import { assertValidRange, brand, fail, getOrAddEmptyToMap } from "../../util/index.js";
 
 import { BasicChunk, BasicChunkCursor, type SiblingsOrKey } from "./basicChunk.js";
@@ -53,7 +53,8 @@ interface StackNode {
 export class ChunkedForest implements IEditableForest {
 	private activeVisitor?: DeltaVisitor;
 
-	private readonly events = createEmitter<ForestEvents>();
+	readonly #events = createEmitter<ForestEvents>();
+	public readonly events: Listenable<ForestEvents> = this.#events;
 
 	/**
 	 * @param roots - dummy node above the root under which detached fields are stored. All content of the forest is reachable from this.
@@ -73,13 +74,6 @@ export class ChunkedForest implements IEditableForest {
 		return this.roots.fields.size === 0;
 	}
 
-	public on<K extends keyof ForestEvents>(
-		eventName: K,
-		listener: ForestEvents[K],
-	): () => void {
-		return this.events.on(eventName, listener);
-	}
-
 	public clone(schema: TreeStoredSchemaSubscription, anchors: AnchorSet): ChunkedForest {
 		this.roots.referenceAdded();
 		return new ChunkedForest(this.roots, schema, this.chunker.clone(schema), anchors);
@@ -119,11 +113,11 @@ export class ChunkedForest implements IEditableForest {
 				this.forest.activeVisitor = undefined;
 			},
 			destroy(detachedField: FieldKey, count: number): void {
-				this.forest.events.emit("beforeChange");
+				this.forest.#events.emit("beforeChange");
 				this.forest.roots.fields.delete(detachedField);
 			},
 			create(content: ProtoNodes, destination: FieldKey): void {
-				this.forest.events.emit("beforeChange");
+				this.forest.#events.emit("beforeChange");
 				const chunks: TreeChunk[] = content.map((c) =>
 					chunkTree(c, {
 						policy: this.forest.chunker,
@@ -131,7 +125,7 @@ export class ChunkedForest implements IEditableForest {
 					}),
 				);
 				this.forest.roots.fields.set(destination, chunks);
-				this.forest.events.emit("afterRootFieldCreated", destination);
+				this.forest.#events.emit("afterRootFieldCreated", destination);
 			},
 			attach(source: FieldKey, count: number, destination: PlaceIndex): void {
 				this.attachEdit(source, count, destination);
@@ -146,7 +140,7 @@ export class ChunkedForest implements IEditableForest {
 			 * @param destination - The index in the current field at which to attach the content.
 			 */
 			attachEdit(source: FieldKey, count: number, destination: PlaceIndex): void {
-				this.forest.events.emit("beforeChange");
+				this.forest.#events.emit("beforeChange");
 				const sourceField = this.forest.roots.fields.get(source) ?? [];
 				this.forest.roots.fields.delete(source);
 				if (sourceField.length === 0) {
@@ -166,7 +160,7 @@ export class ChunkedForest implements IEditableForest {
 			 * If not specified, the detached range is destroyed.
 			 */
 			detachEdit(source: Range, destination: FieldKey | undefined): void {
-				this.forest.events.emit("beforeChange");
+				this.forest.#events.emit("beforeChange");
 				const parent = this.getParent();
 				const sourceField = parent.mutableChunk.fields.get(parent.key) ?? [];
 
@@ -201,6 +195,11 @@ export class ChunkedForest implements IEditableForest {
 					newContentSource !== oldContentDestination,
 					0x7b0 /* Replace detached source field and detached destination field must be different */,
 				);
+				// TODO: optimize this to: perform in-place replace in uniform chunks when possible.
+				// This should result in 3 cases:
+				// 1. In-place update of uniform chunk. No allocations, no ref count changes, no new TreeChunks.
+				// 2. Uniform chunk is shared: copy it (and parent path as needed), and update the copy.
+				// 3. Fallback to detach then attach (Which will copy parents and convert to basic chunks as needed).
 				this.detachEdit(range, oldContentDestination);
 				this.attachEdit(newContentSource, range.end - range.start, range.start);
 			},

package/src/feature-libraries/flex-tree/context.ts

@@ -49,7 +49,8 @@ export interface FlexTreeContext {
  * A common context of a "forest" of FlexTrees.
  * It handles group operations like transforming cursors into anchors for edits.
  */
-export interface FlexTreeHydratedContext extends FlexTreeContext, Listenable<ForestEvents> {
+export interface FlexTreeHydratedContext extends FlexTreeContext {
+	readonly events: Listenable<ForestEvents>;
 	/**
 	 * Gets the root field of the tree.
 	 */
@@ -92,7 +93,7 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 		public readonly nodeKeyManager: NodeKeyManager,
 	) {
 		this.eventUnregister = [
-			this.checkout.forest.on("beforeChange", () => {
+			this.checkout.forest.events.on("beforeChange", () => {
 				this.prepareForEdit();
 			}),
 		];
@@ -160,11 +161,8 @@ export class Context implements FlexTreeHydratedContext, IDisposable {
 		return field;
 	}
 
-	public on<K extends keyof ForestEvents>(
-		eventName: K,
-		listener: ForestEvents[K],
-	): () => void {
-		return this.checkout.forest.on(eventName, listener);
+	public get events(): Listenable<ForestEvents> {
+		return this.checkout.forest.events;
 	}
 }
 

package/src/feature-libraries/flex-tree/lazyField.ts

@@ -151,7 +151,7 @@ export abstract class LazyField extends LazyEntity<FieldAnchor> implements FlexT
 			const anchorNode =
 				context.checkout.forest.anchors.locate(fieldAnchor.parent) ??
 				fail("parent anchor node should always exist since field is under a node");
-			this.offAfterDestroy = anchorNode.on("afterDestroy", () => {
+			this.offAfterDestroy = anchorNode.events.on("afterDestroy", () => {
 				this[disposeSymbol]();
 			});
 		}

package/src/feature-libraries/flex-tree/lazyNode.ts

@@ -89,7 +89,7 @@ export class LazyTreeNode extends LazyEntity<Anchor> implements FlexTreeNode {
 		this.storedSchema = context.schema.nodeSchema.get(this.schema) ?? fail("missing schema");
 		assert(cursor.mode === CursorLocationType.Nodes, 0x783 /* must be in nodes mode */);
 		anchorNode.slots.set(flexTreeSlot, this);
-		this.#removeDeleteCallback = anchorNode.on("afterDestroy", cleanupTree);
+		this.#removeDeleteCallback = anchorNode.events.on("afterDestroy", cleanupTree);
 	}
 
 	public borrowCursor(): ITreeCursorSynchronous {

package/src/feature-libraries/flex-tree/utilities.ts

@@ -99,7 +99,7 @@ export function getSchemaAndPolicy(nodeOrField: FlexTreeEntity): SchemaAndPolicy
  */
 export function indexForAt(index: number, length: number): number | undefined {
 	let finalIndex = Math.trunc(+index);
-	if (isNaN(finalIndex)) {
+	if (Number.isNaN(finalIndex)) {
 		finalIndex = 0;
 	}
 	if (finalIndex < -length || finalIndex >= length) {

package/src/feature-libraries/index.ts

@@ -74,7 +74,7 @@ export {
 	type FieldChangeEncodingContext,
 	type FieldKindConfiguration,
 	type FieldKindConfigurationEntry,
-	getAllowedContentIncompatibilities,
+	getAllowedContentDiscrepancies,
 	isRepoSuperset,
 	isNeverTree,
 } from "./modular-schema/index.js";

package/src/feature-libraries/modular-schema/comparison.ts

@@ -54,6 +54,10 @@ export function allowsTreeSuperset(
 		return false;
 	}
 
+	if (superset instanceof LeafNodeStoredSchema) {
+		return false;
+	}
+
 	assert(
 		original instanceof MapNodeStoredSchema || original instanceof ObjectNodeStoredSchema,
 		0x893 /* unsupported node kind */,