@fluidframework/tree 2.3.0-288113 → 2.3.1

package/src/core/tree/anchorSet.ts

@@ -713,9 +713,17 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 			pathVisitors: new Map<PathNode, Set<PathVisitor>>(),
 			parentField: undefined as FieldKey | undefined,
 			parent: undefined as UpPath | undefined,
+
+			/**
+			 * Events collected during the visit which get sent as a batch during "free".
+			 */
 			bufferedEvents: [] as {
 				node: PathNode;
 				event: keyof AnchorEvents;
+				/**
+				 * The key for the impacted field, if the event is associated with a key.
+				 * Some events, such as afterDestroy, do not involve a key, and thus leave this undefined.
+				 */
 				changedField?: FieldKey;
 			}[],
 
@@ -760,9 +768,13 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 					}
 					emittedEvents?.push(event);
 					if (event === "childrenChangedAfterBatch") {
-						const fieldKeys = this.bufferedEvents
+						const fieldKeys: FieldKey[] = this.bufferedEvents
 							.filter((e) => e.node === node && e.event === event)
-							.map((e) => e.changedField as FieldKey);
+							.map(
+								(e) =>
+									e.changedField ??
+									fail("childrenChangedAfterBatch events should have a changedField"),
+							);
 						node.events.emit(event, { anchor: node, changedFields: new Set(fieldKeys) });
 					} else {
 						node.events.emit(event, node);
@@ -778,7 +790,10 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 			notifyChildrenChanged(): void {
 				this.maybeWithNode(
 					(p) => {
-						assert(this.parentField !== undefined, "Must be in a field");
+						assert(
+							this.parentField !== undefined,
+							0xa24 /* Must be in a field to modify its contents */,
+						);
 						p.events.emit("childrenChanged", p);
 						this.bufferedEvents.push({
 							node: p,

package/src/core/tree/detachedFieldIndex.ts

@@ -99,11 +99,11 @@ export class DetachedFieldIndex {
 		return clone;
 	}
 
-	public *entries(): Generator<
-		{ root: ForestRootId; latestRelevantRevision?: RevisionTag } & {
-			id: Delta.DetachedNodeId;
-		}
-	> {
+	public *entries(): Generator<{
+		root: ForestRootId;
+		latestRelevantRevision?: RevisionTag;
+		id: Delta.DetachedNodeId;
+	}> {
 		for (const [major, innerMap] of this.detachedNodeToField) {
 			if (major !== undefined) {
 				for (const [minor, { root, latestRelevantRevision }] of innerMap) {
@@ -331,6 +331,7 @@ export class DetachedFieldIndex {
 		this.isFullyLoaded = false;
 		const rootMap = new Map<ForestRootId, Delta.DetachedNodeId>();
 		forEachInNestedMap(detachedFieldIndex.data, ({ root }, major, minor) => {
+			setInNestedMap(this.detachedNodeToField, major, minor, { root });
 			rootMap.set(root, { major, minor });
 		});
 

package/src/core/tree/visitDelta.ts

@@ -249,8 +249,13 @@ function transferRoots(
  */
 export interface DeltaVisitor {
 	/**
-	 * Frees/releases the visitor. Must be called once the visitor is no longer needed, since trying to acquire
-	 * a new one before freeing an existing one is invalid.
+	 * Frees/releases the visitor.
+	 *
+	 * Must be called once the visitor finished traversing the delta for a couple of reasons:
+	 *
+	 * 1. Some visitors, such as those from forests, are put into a special mode while they have a visitor, forbidding some actions (like making more visitors).
+	 *
+	 * 2. Some visitors, such as those from an anchorSet, defer some events for batching purposes until the visitor is freed.
 	 */
 	free(): void;
 	/**

package/src/events/{events.ts → emitter.ts}

@@ -3,116 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import type { IEvent } from "@fluidframework/core-interfaces";
-import { getOrCreate } from "../util/index.js";
-
-/**
- * Convert a union of types to an intersection of those types. Useful for `TransformEvents`.
- * @privateRemarks
- * First an always true extends clause is used (T extends T) to distribute T into to a union of types contravariant over each member of the T union.
- * Then the constraint on the type parameter in this new context is inferred, giving the intersection.
- */
-export type UnionToIntersection<T> = (T extends T ? (k: T) => unknown : never) extends (
-	k: infer U,
-) => unknown
-	? U
-	: never;
-
-/**
- * `true` iff the given type is an acceptable shape for a {@link Listeners | event} listener
- * @public
- */
-export type IsListener<TListener> = TListener extends (...args: any[]) => void ? true : false;
-
-/**
- * Used to specify the kinds of events emitted by a {@link Listenable}.
- *
- * @remarks
- * Any object type is a valid {@link Listeners}, but only the {@link IsListener | event-like} properties of that
- * type will be included.
- *
- * @example
- * ```typescript
- * interface MyEvents {
- *   load: (user: string, data: IUserData) => void;
- *   error: (errorCode: number) => void;
- * }
- * ```
- *
- * @public
- */
-export type Listeners<T extends object> = {
-	[P in (string | symbol) & keyof T as IsListener<T[P]> extends true ? P : never]: T[P];
-};
-
-/**
- * Converts a {@link Listeners} type (i.e. the event registry for a {@link Listenable}) into a type consumable
- * by an IEventProvider from `@fluidframework/core-interfaces`.
- * @param E - the `Events` type to transform
- * @param Target - an optional `IEvent` type that will be merged into the result along with the transformed `E`
- *
- * @example
- *
- * ```typescript
- * interface MyEvents {
- *   load: (user: string, data: IUserData) => void;
- *   error: (errorCode: number) => void;
- * }
- *
- * class MySharedObject extends SharedObject<TransformEvents<MyEvents, ISharedObjectEvents>> {
- *    // ...
- * }
- * ```
- */
-export type TransformListeners<
-	TListeners extends Listeners<TListeners>,
-	TTarget extends IEvent = IEvent,
-> = {
-	[P in keyof Listeners<TListeners>]: (event: P, listener: TListeners[P]) => void;
-} extends Record<string | number | symbol, infer Z>
-	? UnionToIntersection<Z> & TTarget
-	: never;
-
-/**
- * An object which allows the registration of listeners so that subscribers can be notified when an event happens.
- * @param TListeners - All the {@link Listeners | events} that this subscribable supports
- *
- * @privateRemarks
- * `EventEmitter` can be used as a base class to implement this via extension.
- * ```ts
- * type MyEventEmitter = IEventEmitter<{
- *   load: (user: string, data: IUserData) => void;
- *   error: (errorCode: number) => void;
- * }>
- * ```
- * {@link createEmitter} can help implement this interface via delegation.
- *
- * @sealed @public
- */
-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.
-	 */
-	on<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): Off;
-}
-
-/**
- * A function that, when called, will deregister an event listener subscription that was previously registered.
- * @remarks
- * It is returned by the {@link Listenable.on | event registration function} when event registration occurs.
- * @public
- */
-export type Off = () => void;
+import { setInNestedMap } from "../util/index.js";
+import type { Listenable, Listeners, Off } from "./listeners.js";
 
 /**
  * Interface for an event emitter that can emit typed events to subscribed listeners.
- * @sealed @alpha
  */
 export interface IEmitter<TListeners extends Listeners<TListeners>> {
 	/**
@@ -141,23 +36,9 @@ export interface IEmitter<TListeners extends Listeners<TListeners>> {
 	): ReturnType<TListeners[K]>[];
 }
 
-/**
- * Create a {@link Listenable} that can be instructed to emit events via the {@link IEmitter} interface.
- *
- * A class can delegate handling {@link Listenable} to the returned value while using it to emit the events.
- * See also `EventEmitter` which be used as a base class to implement {@link Listenable} via extension.
- * @alpha
- */
-export function createEmitter<TListeners extends object>(
-	noListeners?: NoListenersCallback<TListeners>,
-): Listenable<TListeners> & IEmitter<TListeners> & HasListeners<TListeners> {
-	return new ComposableEventEmitter<TListeners>(noListeners);
-}
-
 /**
  * Called when the last listener for `eventName` is removed.
  * Useful for determining when to clean up resources related to detecting when the event might occurs.
- * @alpha
  */
 export type NoListenersCallback<TListeners extends object> = (
 	eventName: keyof Listeners<TListeners>,
@@ -165,7 +46,7 @@ export type NoListenersCallback<TListeners extends object> = (
 
 /**
  * Allows querying if an object has listeners.
- * @sealed @alpha
+ * @sealed
  */
 export interface HasListeners<TListeners extends Listeners<TListeners>> {
 	/**
@@ -188,32 +69,34 @@ export interface HasListeners<TListeners extends Listeners<TListeners>> {
  *
  * ```typescript
  * interface MyEvents {
- *   "loaded": () => void;
+ * 	loaded: () => void;
+ * 	computed: () => number;
  * }
  *
- * class MyClass extends EventEmitter<MyEvents> {
- *   private load() {
- *     this.emit("loaded");
- *   }
+ * class MyInheritanceClass extends EventEmitter<MyEvents> {
+ * 	private load() {
+ * 		this.emit("loaded");
+ * 		const results: number[] = this.emitAndCollect("computed");
+ * 	}
  * }
  * ```
  *
  * @example Composing over this class
  *
  * ```typescript
- * class MyClass implements ISubscribable<MyEvents> {
- *   private readonly events = createEmitter<MyEvents>();
+ * class MyCompositionClass implements Listenable<MyEvents> {
+ * 	private readonly events = createEmitter<MyEvents>();
  *
- *   private load() {
- *     this.events.emit("loaded");
- *   }
+ * 	private load() {
+ * 		this.events.emit("loaded");
+ * 		const results: number[] = this.events.emitAndCollect("computed");
+ * 	}
  *
- *   public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): Off {
- *     return this.events.on(eventName, listener);
- *   }
+ * 	public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): () => void {
+ * 		return this.events.on(eventName, listener);
+ * 	}
  * }
  * ```
- * @alpha
  */
 export class EventEmitter<TListeners extends Listeners<TListeners>>
 	implements Listenable<TListeners>, HasListeners<TListeners>
@@ -233,7 +116,7 @@ export class EventEmitter<TListeners extends Listeners<TListeners>>
 	): void {
 		const listeners = this.listeners.get(eventName);
 		if (listeners !== undefined) {
-			// Current TS (5.4.5) cannot spread `args` into `listener()`, but assigning to an array first makes it work.
+			// 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.
@@ -283,7 +166,7 @@ export class EventEmitter<TListeners extends Listeners<TListeners>>
 			}
 		};
 
-		getOrCreate(this.listeners, eventName, () => new Map()).set(off, listener);
+		setInNestedMap(this.listeners, eventName, off, listener);
 		return off;
 	}
 
@@ -298,7 +181,7 @@ export class EventEmitter<TListeners extends Listeners<TListeners>>
 /**
  * This class exposes the constructor and the `emit` method of `EventEmitter`, elevating them from protected to public
  */
-export class ComposableEventEmitter<TListeners extends Listeners<TListeners>>
+class ComposableEventEmitter<TListeners extends Listeners<TListeners>>
 	extends EventEmitter<TListeners>
 	implements IEmitter<TListeners>
 {
@@ -320,3 +203,33 @@ export class ComposableEventEmitter<TListeners extends Listeners<TListeners>>
 		return super.emitAndCollect(eventName, ...args);
 	}
 }
+
+/**
+ * Create a {@link Listenable} that can be instructed to emit events via the {@link IEmitter} interface.
+ *
+ * A class can delegate handling {@link Listenable} to the returned value while using it to emit the events.
+ * See also {@link EventEmitter} which be used as a base class to implement {@link Listenable} via extension.
+ * @example Forwarding events to the emitter
+ * ```typescript
+ * interface MyEvents {
+ * 	loaded(): void;
+ * }
+ *
+ * class MyClass implements Listenable<MyEvents> {
+ * 	private readonly events = createEmitterMinimal<MyEvents>();
+ *
+ * 	private load(): void {
+ * 		this.events.emit("loaded");
+ * 	}
+ *
+ * 	public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): Off {
+ * 		return this.events.on(eventName, listener);
+ * 	}
+ * }
+ * ```
+ */
+export function createEmitter<TListeners extends object>(
+	noListeners?: NoListenersCallback<TListeners>,
+): Listenable<TListeners> & IEmitter<TListeners> & HasListeners<TListeners> {
+	return new ComposableEventEmitter<TListeners>(noListeners);
+}

package/src/events/index.ts

@@ -6,14 +6,14 @@
 export {
 	createEmitter,
 	EventEmitter,
-	ComposableEventEmitter,
+	type IEmitter,
+	type NoListenersCallback,
+	type HasListeners,
+} from "./emitter.js";
+
+export {
 	type Listeners,
 	type Listenable,
 	type Off,
 	type IsListener,
-	type TransformListeners,
-	type UnionToIntersection,
-	type IEmitter,
-	type NoListenersCallback,
-	type HasListeners,
-} from "./events.js";
+} from "./listeners.js";

package/src/events/interop.ts

@@ -0,0 +1,49 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IEvent } from "@fluidframework/core-interfaces";
+import type { Listeners } from "./listeners.js";
+
+// TODO: this file is currently unused. Use it or remove it.
+
+/**
+ * Convert a union of types to an intersection of those types. Useful for `TransformEvents`.
+ * @privateRemarks
+ * First an always true extends clause is used (T extends T) to distribute T into to a union of types contravariant over each member of the T union.
+ * Then the constraint on the type parameter in this new context is inferred, giving the intersection.
+ */
+export type UnionToIntersection<T> = (T extends T ? (k: T) => unknown : never) extends (
+	k: infer U,
+) => unknown
+	? U
+	: never;
+
+/**
+ * Converts a {@link Listeners} type (i.e. the event registry for a {@link Listenable}) into a type consumable
+ * by an IEventProvider from `@fluidframework/core-interfaces`.
+ * @param E - the `Events` type to transform
+ * @param Target - an optional `IEvent` type that will be merged into the result along with the transformed `E`
+ *
+ * @example
+ *
+ * ```typescript
+ * interface MyEvents {
+ *   load: (user: string, data: IUserData) => void;
+ *   error: (errorCode: number) => void;
+ * }
+ *
+ * class MySharedObject extends SharedObject<TransformEvents<MyEvents, ISharedObjectEvents>> {
+ *    // ...
+ * }
+ * ```
+ */
+export type TransformListeners<
+	TListeners extends Listeners<TListeners>,
+	TTarget extends IEvent = IEvent,
+> = {
+	[P in keyof Listeners<TListeners>]: (event: P, listener: TListeners[P]) => void;
+} extends Record<string | number | symbol, infer Z>
+	? UnionToIntersection<Z> & TTarget
+	: never;

package/src/events/listeners.ts

@@ -0,0 +1,68 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * `true` iff the given type is an acceptable shape for a {@link Listeners | event} listener
+ * @public
+ */
+export type IsListener<TListener> = TListener extends (...args: any[]) => void ? true : false;
+
+/**
+ * Used to specify the kinds of events emitted by a {@link Listenable}.
+ *
+ * @remarks
+ * Any object type is a valid {@link Listeners}, but only the {@link IsListener | event-like} properties of that
+ * type will be included.
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   load: (user: string, data: IUserData) => void;
+ *   error: (errorCode: number) => void;
+ * }
+ * ```
+ *
+ * @public
+ */
+export type Listeners<T extends object> = {
+	[P in (string | symbol) & keyof T as IsListener<T[P]> extends true ? P : never]: T[P];
+};
+
+/**
+ * An object which allows the registration of listeners so that subscribers can be notified when an event happens.
+ * @param TListeners - All the {@link Listeners | events} that this subscribable supports
+ *
+ * @privateRemarks
+ * `EventEmitter` can be used as a base class to implement this via extension.
+ * ```ts
+ * type MyEventEmitter = IEventEmitter<{
+ *   load: (user: string, data: IUserData) => void;
+ *   error: (errorCode: number) => void;
+ * }>
+ * ```
+ * {@link createEmitter} can help implement this interface via delegation.
+ *
+ * @sealed @public
+ */
+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.
+	 */
+	on<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): Off;
+}
+
+/**
+ * A function that, when called, will deregister an event listener subscription that was previously registered.
+ * @remarks
+ * It is returned by the {@link Listenable.on | event registration function} when event registration occurs.
+ * @public
+ */
+export type Off = () => void;