@fluidframework/core-interfaces 2.10.0 → 2.12.0

package/src/events/emitter.ts

@@ -0,0 +1,73 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { Listeners } from "./listeners.js";
+
+/**
+ * Interface for an event emitter that can emit typed events to subscribed listeners.
+ * @internal
+ */
+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.
+	 *
+	 * @remarks
+	 * 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 a given `eventName` is removed.
+ * @remarks
+ * Useful for determining when to clean up resources related to detecting when the event might occurs.
+ * @internal
+ */
+export type NoListenersCallback<TListeners extends object> = (
+	eventName: keyof Listeners<TListeners>,
+) => void;
+
+/**
+ * Allows querying if an object has listeners.
+ * @sealed
+ * @internal
+ */
+export interface HasListeners<TListeners extends Listeners<TListeners>> {
+	/**
+	 * Determines whether or not any listeners are registered for the specified event name.
+	 *
+	 * @remarks
+	 * If no event name is given, checks if *any* listeners are registered.
+	 * 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;
+}
+
+/**
+ * Subset of Map interface including only the `get` and `set` methods.
+ * @internal
+ */
+export interface MapGetSet<K, V> {
+	get(key: K): V | undefined;
+	set(key: K, value: V): void;
+}

package/src/events/index.ts

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

package/src/events/listeners.ts

@@ -0,0 +1,80 @@
+/*!
+ * 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
+ * {@link @fluid-internal/client-utils#CustomEventEmitter} can be used as a base class to implement this via extension.
+ * ```ts
+ * type MyEventEmitter = IEmitter<{
+ *   load: (user: string, data: IUserData) => void;
+ *   error: (errorCode: number) => void;
+ * }>
+ * ```
+ * {@link @fluid-internal/client-utils#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/events.ts

@@ -18,7 +18,6 @@ export interface IEvent {
 	 *
 	 * @eventProperty
 	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	(event: string, listener: (...args: any[]) => void);
 }
 

package/src/index.ts

@@ -48,3 +48,14 @@ export type { FluidObjectProviderKeys, FluidObject, FluidObjectKeys } from "./pr
 export type { ConfigTypes, IConfigProviderBase } from "./config.js";
 export type { ISignalEnvelope } from "./messages.js";
 export type { ErasedType } from "./erasedType.js";
+
+export type {
+	HasListeners,
+	IEmitter,
+	IsListener,
+	Listeners,
+	Listenable,
+	MapGetSet,
+	NoListenersCallback,
+	Off,
+} from "./events/index.js";