@fluidframework/tree 2.2.0 → 2.3.0

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

@@ -32,11 +32,6 @@ export enum ValueSchema {
  * Set of allowed tree types.
  * Providing multiple values here allows polymorphism, tagged union style.
  *
- * If not specified, types are unconstrained
- * (equivalent to the set containing every TreeNodeSchemaIdentifier defined in the document).
- *
- * Note that even when unconstrained, children must still be in-schema for their own type.
- *
  * In the future, this could be extended to allow inlining a TreeNodeStoredSchema here
  * (or some similar structural schema system).
  * For structural types which could go here, there are a few interesting options:
@@ -58,7 +53,7 @@ export enum ValueSchema {
  * Care would need to be taken to make sure this is sound for the schema updating mechanisms.
  * @internal
  */
-export type TreeTypeSet = ReadonlySet<TreeNodeSchemaIdentifier> | undefined;
+export type TreeTypeSet = ReadonlySet<TreeNodeSchemaIdentifier>;
 
 /**
  * Declarative portion of a Field Kind.
@@ -109,7 +104,7 @@ export interface TreeFieldStoredSchema {
 	 * The set of allowed child types.
 	 * If not specified, types are unconstrained.
 	 */
-	readonly types?: TreeTypeSet;
+	readonly types: TreeTypeSet;
 }
 
 /**
@@ -295,20 +290,18 @@ function decodeValueSchema(inMemory: PersistedValueSchema): ValueSchema {
 }
 
 export function encodeFieldSchema(schema: TreeFieldStoredSchema): FieldSchemaFormat {
-	const out: FieldSchemaFormat = {
+	return {
 		kind: schema.kind,
+		// Types are sorted by identifier to improve stability of persisted data to increase chance of schema blob reuse.
+		types: [...schema.types].sort(),
 	};
-	if (schema.types !== undefined) {
-		out.types = [...schema.types];
-	}
-	return out;
 }
 
 export function decodeFieldSchema(schema: FieldSchemaFormat): TreeFieldStoredSchema {
 	const out: TreeFieldStoredSchema = {
 		// TODO: maybe provide actual FieldKind objects here, error on unrecognized kinds.
 		kind: schema.kind,
-		types: schema.types === undefined ? undefined : new Set(schema.types),
+		types: new Set(schema.types),
 	};
 	return out;
 }

package/src/core/tree/anchorSet.ts

@@ -30,7 +30,7 @@ import type {
 	RangeUpPath,
 	UpPath,
 } from "./pathTree.js";
-import { EmptyKey, type Value } from "./types.js";
+import { EmptyKey } from "./types.js";
 import type { DeltaVisitor } from "./visitDelta.js";
 import type { PathVisitor } from "./visitPath.js";
 import type { AnnouncedVisitor } from "./visitorUtils.js";
@@ -127,7 +127,10 @@ export interface AnchorEvents {
 	 *
 	 * Compare to {@link AnchorEvents.childrenChanged} which is emitted in the middle of the batch/delta-visit.
 	 */
-	childrenChangedAfterBatch(anchor: AnchorNode): void;
+	childrenChangedAfterBatch(arg: {
+		anchor: AnchorNode;
+		changedFields: ReadonlySet<FieldKey>;
+	}): void;
 
 	/**
 	 * Emitted in the middle of applying a batch of changes (i.e. during a delta a visit), if something in the subtree
@@ -177,11 +180,6 @@ export interface AnchorEvents {
 	 * fire when something _may_ have changed or _may_ be about to change.
 	 */
 	subtreeChangedAfterBatch(anchor: AnchorNode): void;
-
-	/**
-	 * Value on this node is changing.
-	 */
-	valueChanging(anchor: AnchorNode, value: Value): void;
 }
 
 /**
@@ -715,7 +713,19 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 			pathVisitors: new Map<PathNode, Set<PathVisitor>>(),
 			parentField: undefined as FieldKey | undefined,
 			parent: undefined as UpPath | undefined,
-			bufferedEvents: [] as { node: PathNode; event: keyof AnchorEvents }[],
+
+			/**
+			 * 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;
+			}[],
 
 			// 'currentDepth' and 'depthThresholdForSubtreeChanged' serve to keep track of when do we need to emit
 			// subtreeChangedAfterBatch events.
@@ -757,7 +767,18 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 						continue;
 					}
 					emittedEvents?.push(event);
-					node.events.emit(event, node);
+					if (event === "childrenChangedAfterBatch") {
+						const fieldKeys: FieldKey[] = this.bufferedEvents
+							.filter((e) => e.node === node && e.event === event)
+							.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);
+					}
 				}
 			},
 			notifyChildrenChanging(): void {
@@ -769,10 +790,15 @@ export class AnchorSet implements Listenable<AnchorSetRootEvents>, AnchorLocator
 			notifyChildrenChanged(): void {
 				this.maybeWithNode(
 					(p) => {
+						assert(
+							this.parentField !== undefined,
+							0xa24 /* Must be in a field to modify its contents */,
+						);
 						p.events.emit("childrenChanged", p);
 						this.bufferedEvents.push({
 							node: p,
 							event: "childrenChangedAfterBatch",
+							changedField: this.parentField,
 						});
 					},
 					() => {},

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,112 +3,8 @@
  * 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.
@@ -140,18 +36,6 @@ 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.
- */
-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.
@@ -161,6 +45,8 @@ export type NoListenersCallback<TListeners extends object> = (
 ) => void;
 
 /**
+ * Allows querying if an object has listeners.
+ * @sealed
  */
 export interface HasListeners<TListeners extends Listeners<TListeners>> {
 	/**
@@ -183,29 +69,32 @@ 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 = EventEmitter.create<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);
+ * 	}
  * }
  * ```
  */
@@ -227,7 +116,9 @@ export class EventEmitter<TListeners extends Listeners<TListeners>>
 	): void {
 		const listeners = this.listeners.get(eventName);
 		if (listeners !== undefined) {
-			const argArray: unknown[] = args; // TODO: Current TS (4.5.5) cannot spread `args` into `listener()`, but future versions (e.g. 4.8.4) can.
+			// 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]) {
 				// If listener has been unsubscribed while invoking other listeners, skip it.
@@ -275,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;
 	}
 
@@ -290,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>
 {
@@ -312,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;