@fluidframework/tree 2.10.0 → 2.11.0

package/src/events/emitter.ts

@@ -1,256 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { getOrCreate } 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.
- */
-export interface IEmitter<TListeners extends Listeners<TListeners>> {
-	/**
-	 * Emits an event with the specified name and arguments, notifying all subscribers by calling their registered listener functions.
-	 * @param eventName - the name of the event to fire
-	 * @param args - the arguments passed to the event listener functions
-	 */
-	emit<K extends keyof Listeners<TListeners>>(
-		eventName: K,
-		...args: Parameters<TListeners[K]>
-	): void;
-
-	/**
-	 * Emits an event with the specified name and arguments, notifying all subscribers by calling their registered listener functions.
-	 * It also collects the return values of all listeners into an array.
-	 *
-	 * Warning: This method should be used with caution. It deviates from the standard event-based integration pattern as creates substantial coupling between the emitter and its listeners.
-	 * For the majority of use-cases it is recommended to use the standard {@link IEmitter.emit} functionality.
-	 * @param eventName - the name of the event to fire
-	 * @param args - the arguments passed to the event listener functions
-	 * @returns An array of the return values of each listener, preserving the order listeners were called.
-	 */
-	emitAndCollect<K extends keyof Listeners<TListeners>>(
-		eventName: K,
-		...args: Parameters<TListeners[K]>
-	): ReturnType<TListeners[K]>[];
-}
-
-/**
- * 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.
- */
-export type NoListenersCallback<TListeners extends object> = (
-	eventName: keyof Listeners<TListeners>,
-) => void;
-
-/**
- * Allows querying if an object has listeners.
- * @sealed
- */
-export interface HasListeners<TListeners extends Listeners<TListeners>> {
-	/**
-	 * When no `eventName` is provided, returns true iff there are any listeners.
-	 *
-	 * When `eventName` is provided, returns true iff there are listeners for that event.
-	 *
-	 * @remarks
-	 * This can be used to know when its safe to cleanup data-structures which only exist to fire events for their listeners.
-	 */
-	hasListeners(eventName?: keyof Listeners<TListeners>): boolean;
-}
-
-/**
- * Provides an API for subscribing to and listening to events.
- *
- * @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
- *
- * ```typescript
- * interface MyEvents {
- * 	loaded: () => void;
- * 	computed: () => number;
- * }
- *
- * class MyInheritanceClass extends EventEmitter<MyEvents> {
- * 	private load() {
- * 		this.emit("loaded");
- * 		const results: number[] = this.emitAndCollect("computed");
- * 	}
- * }
- * ```
- *
- * @example Composing over this class
- *
- * ```typescript
- * class MyCompositionClass implements Listenable<MyEvents> {
- * 	private readonly events = createEmitter<MyEvents>();
- *
- * 	private load() {
- * 		this.events.emit("loaded");
- * 		const results: number[] = this.events.emitAndCollect("computed");
- * 	}
- *
- * 	public on<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): () => void {
- * 		return this.events.on(eventName, listener);
- * 	}
- * }
- * ```
- *
- * @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,
-		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.
-	// Instead, use the static `create` function to get an instance which allows emitting events.
-	protected constructor(private readonly noListeners?: NoListenersCallback<TListeners>) {}
-
-	protected emit<K extends keyof TListeners>(
-		eventName: K,
-		...args: Parameters<TListeners[K]>
-	): void {
-		const listeners = this.listeners.get(eventName);
-		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 listener of [...listeners]) {
-				// If listener has been unsubscribed while invoking other listeners, skip it.
-				if (listeners.has(listener)) {
-					listener(...argArray);
-				}
-			}
-		}
-	}
-
-	protected emitAndCollect<K extends keyof TListeners>(
-		eventName: K,
-		...args: Parameters<TListeners[K]>
-	): ReturnType<TListeners[K]>[] {
-		const listeners = this.listeners.get(eventName);
-		if (listeners !== undefined) {
-			const argArray: unknown[] = args;
-			const resultArray: ReturnType<TListeners[K]>[] = [];
-			for (const listener of [...listeners.values()]) {
-				resultArray.push(listener(...argArray));
-			}
-			return resultArray;
-		}
-		return [];
-	}
-
-	public on<K extends keyof Listeners<TListeners>>(
-		eventName: K,
-		listener: TListeners[K],
-	): Off {
-		const listeners = getOrCreate(this.listeners, eventName, () => new Set());
-		if (listeners.has(listener)) {
-			const eventDescription =
-				typeof eventName === "symbol" ? eventName.description : String(eventName.toString());
-
-			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 {
-		if (eventName === undefined) {
-			return this.listeners.size !== 0;
-		}
-		return this.listeners.has(eventName);
-	}
-}
-
-/**
- * This class exposes the constructor and the `emit` method of `EventEmitter`, elevating them from protected to public
- */
-class ComposableEventEmitter<TListeners extends Listeners<TListeners>>
-	extends EventEmitter<TListeners>
-	implements IEmitter<TListeners>
-{
-	public constructor(noListeners?: NoListenersCallback<TListeners>) {
-		super(noListeners);
-	}
-
-	public override emit<K extends keyof TListeners>(
-		eventName: K,
-		...args: Parameters<TListeners[K]>
-	): void {
-		return super.emit(eventName, ...args);
-	}
-
-	public override emitAndCollect<K extends keyof TListeners>(
-		eventName: K,
-		...args: Parameters<TListeners[K]>
-	): ReturnType<TListeners[K]>[] {
-		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);
- * 	}
- *
- * 	public off<K extends keyof MyEvents>(eventName: K, listener: MyEvents[K]): void {
- * 		return this.events.off(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

@@ -1,19 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-export {
-	createEmitter,
-	EventEmitter,
-	type IEmitter,
-	type NoListenersCallback,
-	type HasListeners,
-} from "./emitter.js";
-
-export {
-	type Listeners,
-	type Listenable,
-	type Off,
-	type IsListener,
-} from "./listeners.js";

package/src/events/interop.ts

@@ -1,38 +0,0 @@
-/*!
- * 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";
-import type { UnionToIntersection } from "../util/index.js";
-
-// TODO: this file is currently unused. Use it or remove it.
-
-/**
- * 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

@@ -1,80 +0,0 @@
-/*!
- * 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 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;
-}
-
-/**
- * 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;

package/src/shared-tree-core/transactionStack.ts

@@ -1,45 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import type { RevisionTag } from "../core/index.js";
-import { fail } from "../util/index.js";
-
-/**
- * A helper class that organizes the state needed for managing nesting transactions.
- */
-export class TransactionStack {
-	private readonly stack: {
-		startRevision: RevisionTag;
-		dispose: () => void;
-	}[] = [];
-
-	/**
-	 * The number of transactions currently ongoing.
-	 */
-	public get size(): number {
-		return this.stack.length;
-	}
-
-	/**
-	 * Pushes a new transaction onto the stack. That transaction becomes the current transaction.
-	 * @param startRevision - the revision of the latest commit when this transaction begins
-	 * @param disposables - an optional collection of disposable data to release after finishing a transaction
-	 */
-	public push(startRevision: RevisionTag, dispose: () => void): void {
-		this.stack.push({ startRevision, dispose });
-	}
-
-	/**
-	 * Ends the current transaction. Fails if there is currently no ongoing transaction.
-	 * @returns The revision that the closed transaction began on.
-	 */
-	public pop(): {
-		startRevision: RevisionTag;
-	} {
-		const transaction = this.stack.pop() ?? fail("No transaction is currently in progress");
-		transaction.dispose();
-		return transaction;
-	}
-}

package/src/util/transactionResult.ts

@@ -1,19 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/**
- * Describes the result of a transaction.
- * Transactions may either succeed and commit, or fail and abort.
- */
-export enum TransactionResult {
-	/**
-	 * Indicates the transaction failed.
-	 */
-	Abort,
-	/**
-	 * Indicates the transaction succeeded.
-	 */
-	Commit,
-}