@mnaoumov/typescript-lib 0.0.0 → 1.0.0

package/dist/lib/esm/async-events.d.mts

@@ -0,0 +1,456 @@
+/// <reference path="./library.d.mts" />
+/**
+ * @file
+ *
+ * Async event emitter.
+ */
+import type { AbstractConstructor, Promisable } from 'type-fest';
+import type { AsyncDisposableEx } from './disposable.mjs';
+import type { GenericPromisableVoidFunction } from './function.mjs';
+import type { StringKeys } from './type.mjs';
+import { AsyncDisposableBase } from './disposable.mjs';
+declare const ASYNC_EVENT_MAP: unique symbol;
+/**
+ * Async event reference.
+ */
+export interface AsyncEventRef {
+    /**
+     * An event source.
+     */
+    asyncEventSource: GenericAsyncEventSource;
+    /**
+     * A callback to call when the event is triggered.
+     */
+    callback: GenericCallback;
+    /**
+     * A name of the event.
+     */
+    name: string;
+    /**
+     * A context passed as `this` to the `callback`.
+     */
+    thisArgument: unknown;
+}
+/**
+ * Async event emitter implementation.
+ *
+ * @typeParam EventMap - Maps event names to their argument tuples.
+ * When omitted, the emitter accepts any string event name with any arguments.
+ * When provided, methods enforce correct event names and argument types
+ * with full autocomplete. Works with both `type` aliases and `interface` declarations.
+ *
+ * @example
+ * ```ts
+ * // Untyped (default) — any event name, any args:
+ * const events = new AsyncEvents();
+ * events.on('my-event', (arg1: string) => { ... });
+ *
+ * // Typed — only declared events with correct args:
+ * interface MyEventMap {
+ *   save: [data: string];
+ *   load: [id: number, force: boolean];
+ * }
+ * const events = new AsyncEvents<MyEventMap>();
+ * events.on('save', (data) => { ... });   // data: string — autocomplete on event name
+ * events.on('load', (id, force) => { ... }); // id: number, force: boolean
+ * ```
+ */
+export interface AsyncEventSource<EventMap extends EventMapConstraint<EventMap> = EventMapBase> extends GenericAsyncEventSource {
+    /**
+     * Phantom marker that makes {@link EventMap} inferable from an {@link AsyncEventSource} (e.g. via
+     * `Source extends AsyncEventSource<infer EventMap>`). Never present at runtime.
+     */
+    readonly [ASYNC_EVENT_MAP]?: EventMap;
+    /**
+     * Remove an event listener.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Arguments - The arguments of the event.
+     * @param name - The name of the event.
+     * @param callback - The callback to remove.
+     *
+     * @example
+     * ```ts
+     * events.off('my-event', myListener);
+     * ```
+     */
+    off: <EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>) => void;
+    /**
+     * Add an event listener.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Arguments - The arguments of the event.
+     * @param name - The name of the event.
+     * @param callback - The callback to call when the event is triggered.
+     * @param thisArgument - The context passed as `this` to the `callback`.
+     * @returns A reference to the event listener.
+     *
+     * @remarks Not refactored to parameter-object pattern, to keep the parity with Obsidian's `Events.on` (or once, correspondingly).
+     *
+     * @example
+     * ```ts
+     * events.on('my-event', async (arg1, arg2) => {
+     *     await sleep(100);
+     *     console.log(arg1, arg2);
+     * });
+     * ```
+     */
+    on: <EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>, thisArgument?: unknown) => AsyncEventRef;
+    /**
+     * Add an event listener that will be triggered only once.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param callback - The callback to call when the event is triggered.
+     * @param thisArgument - The context passed as `this` to the `callback`.
+     * @returns A reference to the event listener.
+     *
+     * @remarks Not refactored to parameter-object pattern, to keep the parity with Obsidian's `Events.on` (or once, correspondingly).
+     *
+     * @example
+     * ```ts
+     * events.once('my-event', async (arg1, arg2) => {
+     *     await sleep(100);
+     *     console.log(arg1, arg2);
+     * });
+     * ```
+     */
+    once: <EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>, thisArgument?: unknown) => AsyncEventRef;
+}
+/**
+ * Interface exposing event-triggering methods for subclasses of mixin-created classes.
+ *
+ * These methods are `protected` at runtime but surfaced in the declaration type
+ * because TypeScript cannot represent `protected` in anonymous-class return types.
+ *
+ * @typeParam EventMap - Maps event names to their argument tuples.
+ */
+export interface AsyncEventTrigger<EventMap extends EventMapConstraint<EventMap> = EventMapBase> {
+    /**
+     * Trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     */
+    trigger: <EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>) => void;
+    /**
+     * Trigger an event asynchronously.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    triggerAsync: <EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>) => Promise<void>;
+    /**
+     * Try to trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     */
+    tryTrigger: <Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments) => void;
+    /**
+     * Try to trigger an event asynchronously.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    tryTriggerAsync: <Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments) => Promise<void>;
+}
+/**
+ * Resolves callback argument types for an event.
+ *
+ * - When `EventMap` has an index signature (untyped default): returns `unknown[]`,
+ *   allowing `Args` to be inferred freely from the callback.
+ * - When `EventMap` has explicit keys only (typed map): returns `EventMap[EventName]`,
+ *   enforcing the declared argument types and enabling autocomplete.
+ *
+ * @typeParam EventMap - Maps event names to their argument tuples.
+ * @typeParam EventName - The name of the event.
+ */
+export type CallbackArguments<EventMap, EventName extends string> = string extends keyof EventMap ? unknown[] : (EventName extends keyof EventMap ? EventMap[EventName] : unknown[]);
+/**
+ * Base event map type for untyped emitters.
+ */
+export type EventMapBase = Record<string, unknown[]>;
+/**
+ * Interface for event source, used by {@link AsyncEventRef}
+ * so that refs can be stored regardless of the emitter's `EventMap`.
+ */
+export interface GenericAsyncEventSource {
+    /**
+     * Remove an event listener by reference.
+     *
+     * @param eventRef - The reference to remove.
+     */
+    offref: (eventRef: AsyncEventRef) => void;
+}
+/**
+ * Parameters for {@link subscribeAsyncDisposableEvent}.
+ *
+ * @typeParam Source - The {@link AsyncEventSource} type.
+ * @typeParam EventName - The event name, constrained to the source's known events.
+ */
+export interface SubscribeAsyncDisposableEventParams<Source extends GenericAsyncEventSource, EventName extends AsyncEventNameOf<Source>> {
+    /**
+     * The async event source to subscribe on.
+     */
+    readonly asyncEventSource: Source;
+    /**
+     * The event callback. Its argument types are inferred from {@link SubscribeAsyncDisposableEventParams.name}.
+     */
+    readonly callback: AsyncEventCallbackOf<Source, EventName>;
+    /**
+     * The event name to subscribe to.
+     */
+    readonly name: EventName;
+    /**
+     * The context passed as `this` to the callback.
+     */
+    readonly thisArgument?: unknown;
+}
+type AsyncEventCallbackOf<Source extends GenericAsyncEventSource, EventName extends AsyncEventNameOf<Source>> = EventMapOf<Source>[EventName] extends infer Arguments extends unknown[] ? (...$arguments: Arguments) => Promisable<void> : never;
+type AsyncEventNameOf<Source extends GenericAsyncEventSource> = keyof EventMapOf<Source> & string;
+type EventMapConstraint<T> = Record<keyof T, unknown[]>;
+type EventMapOf<Source> = Source extends AsyncEventSource<infer EventMap> ? EventMap : never;
+type GenericCallback = GenericPromisableVoidFunction<unknown[]>;
+/**
+ * An {@link AsyncDisposableEx} that unregisters an {@link AsyncEventRef} on dispose, via the event source stored
+ * on the ref itself. Async counterpart of the native `EventRefDisposable`.
+ */
+export declare class AsyncEventRefDisposable extends AsyncDisposableBase {
+    private readonly asyncEventRef;
+    /**
+     * Creates a disposable wrapping an existing {@link AsyncEventRef}.
+     *
+     * @param asyncEventRef - The async event reference to unregister on dispose.
+     */
+    constructor(asyncEventRef: AsyncEventRef);
+    /**
+     * Unregisters the event via the source stored on the ref (`asyncEventSource.offref`).
+     */
+    protected performDisposeAsync(): void;
+}
+/**
+ * Async event source implementation.
+ *
+ * @typeParam EventMap - Maps event names to their argument tuples.
+ * When omitted, the emitter accepts any string event name with any arguments.
+ * When provided, methods enforce correct event names and argument types
+ * with full autocomplete. Works with both `type` aliases and `interface` declarations.
+ *
+ * @example
+ * ```ts
+ * // Untyped (default) — any event name, any args:
+ * const events = new AsyncEvents();
+ * events.on('my-event', (arg1: string) => { ... });
+ *
+ * // Typed — only declared events with correct args:
+ * interface MyEventMap {
+ *   save: [data: string];
+ *   load: [id: number, force: boolean];
+ * }
+ * const events = new AsyncEvents<MyEventMap>();
+ * events.on('save', (data) => { ... });   // data: string — autocomplete on event name
+ * events.on('load', (id, force) => { ... }); // id: number, force: boolean
+ * ```
+ */
+export declare abstract class AsyncEventsBase<EventMap extends EventMapConstraint<EventMap> = EventMapBase> implements AsyncEventSource<EventMap> {
+    /**
+     * The registry mapping each event name to its list of registered listener references.
+     */
+    protected readonly eventReferencesMap: Map<string, AsyncEventRef[]>;
+    /**
+     * Remove an event listener.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Arguments - The types of the arguments the event callback accepts.
+     * @param name - The name of the event.
+     * @param callback - The callback to remove.
+     *
+     * @example
+     * ```ts
+     * events.off('my-event', myListener);
+     * ```
+     */
+    off<EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>): void;
+    /**
+     * Remove an event listener by reference.
+     *
+     * @param eventRef - The reference to the event listener.
+     *
+     * @example
+     * ```ts
+     * events.offref(myRef);
+     * ```
+     */
+    offref(eventRef: AsyncEventRef): void;
+    /**
+     * Add an event listener.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Arguments - The types of the arguments the event callback accepts.
+     * @param name - The name of the event.
+     * @param callback - The callback to call when the event is triggered.
+     * @param thisArgument - The context passed as `this` to the `callback`.
+     * @returns A reference to the event listener.
+     *
+     * @remarks Not refactored to parameter-object pattern, to keep the parity with Obsidian's `Events.on` (or once, correspondingly).
+     *
+     * @example
+     * ```ts
+     * events.on('my-event', async (arg1, arg2) => {
+     *     await sleep(100);
+     *     console.log(arg1, arg2);
+     * });
+     * ```
+     */
+    on<EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>, thisArgument?: unknown): AsyncEventRef;
+    /**
+     * Add an event listener that will be triggered only once.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Arguments - The types of the arguments the event callback accepts.
+     * @param name - The name of the event.
+     * @param callback - The callback to call when the event is triggered.
+     * @param thisArgument - The context passed as `this` to the `callback`.
+     * @returns A reference to the event listener.
+     *
+     * @remarks Not refactored to parameter-object pattern, to keep the parity with Obsidian's `Events.on` (or once, correspondingly).
+     *
+     * @example
+     * ```ts
+     * events.once('my-event', async (arg1, arg2) => {
+     *     await sleep(100);
+     *     console.log(arg1, arg2);
+     * });
+     * ```
+     */
+    once<EventName extends StringKeys<EventMap>, Arguments extends CallbackArguments<EventMap, EventName>>(name: EventName, callback: (...$arguments: Arguments) => Promisable<void>, thisArgument?: unknown): AsyncEventRef;
+    /**
+     * Trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     *
+     * @example
+     * ```ts
+     * events.trigger('my-event', 'arg1', 'arg2');
+     * ```
+     */
+    protected trigger<EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>): void;
+    /**
+     * Trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    protected triggerAsync<EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>): Promise<void>;
+    /**
+     * Try to trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     *
+     * @example
+     * ```ts
+     * events.tryTrigger(myRef, ['arg1', 'arg2']);
+     * ```
+     */
+    protected tryTrigger<Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments): void;
+    /**
+     * Try to trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    protected tryTriggerAsync<Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments): Promise<void>;
+}
+/**
+ * A class that extends {@link AsyncEventsBase} and provides public methods for triggering events.
+ *
+ * This class exists as parity with Obsidian's `Events`. But exposing publicly `trigger()` methods violates encapsulation.
+ *
+ * Avoid using it in favor of {@link AsyncEventsBase}.
+ *
+ * @typeParam EventMap - The type of the event map.
+ */
+export declare class AsyncEvents<EventMap extends EventMapConstraint<EventMap> = EventMapBase> extends AsyncEventsBase<EventMap> {
+    /**
+     * Trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     */
+    trigger<EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>): void;
+    /**
+     * Trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    triggerAsync<EventName extends StringKeys<EventMap>>(name: EventName, ...$arguments: CallbackArguments<EventMap, EventName>): Promise<void>;
+    /**
+     * Try to trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     */
+    tryTrigger<Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments): void;
+    /**
+     * Try to trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Arguments - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param $arguments - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    tryTriggerAsync<Arguments extends unknown[]>(eventRef: AsyncEventRef, $arguments: Arguments): Promise<void>;
+}
+/**
+ * Mixin that adds {@link AsyncEventSource} delegation to a base class.
+ *
+ * All event methods delegate to a private {@link AsyncEventsBase} instance.
+ * The `EventMap` generic is fixed at mixin-application time — if you need a class
+ * that is itself generic over its event map, use composition instead.
+ *
+ * @typeParam EventMap - Maps event names to their argument tuples.
+ * @returns A function that takes a base class and returns a new class extending it with {@link AsyncEventSource}.
+ *
+ * @example
+ * ```ts
+ * interface MyEvents {
+ *   save: [data: string];
+ * }
+ * class MyComponent extends mixinAsyncEvents<MyEvents>()(Component) {
+ *   // on(), off(), once(), offref() are available
+ * }
+ * ```
+ */
+export declare function mixinAsyncEvents<EventMap extends EventMapConstraint<EventMap> = EventMapBase>(): <TBase extends AbstractConstructor<object>>(baseClass: TBase) => AbstractConstructor<AsyncEventSource<EventMap> & AsyncEventTrigger<EventMap>> & TBase;
+/**
+ * Subscribes to an event on an {@link AsyncEventSource} and returns an {@link AsyncDisposableEx} that unregisters
+ * it on dispose. Async counterpart of the native `subscribeDisposableEvent`; the event name and callback argument
+ * types are inferred from the source's event map.
+ *
+ * @typeParam Source - The {@link AsyncEventSource} type.
+ * @typeParam EventName - The event name.
+ * @param params - The subscription parameters.
+ * @returns An {@link AsyncDisposableEx} that unregisters the handler when disposed.
+ */
+export declare function subscribeAsyncDisposableEvent<Source extends GenericAsyncEventSource, EventName extends AsyncEventNameOf<Source>>(params: SubscribeAsyncDisposableEventParams<Source, EventName>): AsyncDisposableEx;
+export {};