obsidian-dev-utils 67.0.0 → 69.0.0

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

@@ -1,17 +1,20 @@
+/// <reference path="./library.d.mts" />
 /**
  * @file
  *
  * Async event emitter.
  */
+import type { AbstractConstructor, Promisable } from 'type-fest';
 import type { GenericPromisableVoidFunction } from './function.mjs';
+import type { StringKeys } from './type.mjs';
 /**
  * Async event reference.
  */
 export interface AsyncEventRef {
     /**
-     * An event emitter.
+     * An event source.
      */
-    asyncEvents: AsyncEvents;
+    asyncEventSource: GenericAsyncEventSource;
     /**
      * A callback to call when the event is triggered.
      */
@@ -25,15 +28,188 @@ export interface AsyncEventRef {
      */
     thisArg: 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 {
+    /**
+     * Remove an event listener.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Args - 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>, Args extends CallbackArgs<EventMap, EventName>>(name: EventName, callback: (...args: Args) => Promisable<void>): void;
+    /**
+     * Add an event listener.
+     *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Args - The arguments of the event.
+     * @param name - The name of the event.
+     * @param callback - The callback to call when the event is triggered.
+     * @param thisArg - The context passed as `this` to the `callback`.
+     * @returns A reference to the event listener.
+     *
+     * @example
+     * ```ts
+     * events.on('my-event', async (arg1, arg2) => {
+     *     await sleep(100);
+     *     console.log(arg1, arg2);
+     * });
+     * ```
+     */
+    on<EventName extends StringKeys<EventMap>, Args extends CallbackArgs<EventMap, EventName>>(name: EventName, callback: (...args: Args) => Promisable<void>, thisArg?: 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 thisArg - The context passed as `this` to the `callback`.
+     * @returns A reference to the event listener.
+     *
+     * @example
+     * ```ts
+     * events.once('my-event', async (arg1, arg2) => {
+     *     await sleep(100);
+     *     console.log(arg1, arg2);
+     * });
+     * ```
+     */
+    once<EventName extends StringKeys<EventMap>, Args extends CallbackArgs<EventMap, EventName>>(name: EventName, callback: (...args: Args) => Promisable<void>, thisArg?: 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 args - The data to pass to the event listeners.
+     */
+    trigger<EventName extends StringKeys<EventMap>>(name: EventName, ...args: CallbackArgs<EventMap, EventName>): void;
+    /**
+     * Trigger an event asynchronously.
+     *
+     * @typeParam EventName - The name of the event.
+     * @param name - The name of the event.
+     * @param args - 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, ...args: CallbackArgs<EventMap, EventName>): Promise<void>;
+    /**
+     * Try to trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Args - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param args - The data to pass to the event listeners.
+     */
+    tryTrigger<Args extends unknown[]>(eventRef: AsyncEventRef, args: Args): void;
+    /**
+     * Try to trigger an event asynchronously.
+     *
+     * @typeParam Args - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param args - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    tryTriggerAsync<Args extends unknown[]>(eventRef: AsyncEventRef, args: Args): 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 CallbackArgs<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;
+}
+type EventMapConstraint<T> = Record<keyof T, unknown[]>;
 type GenericCallback = GenericPromisableVoidFunction<unknown[]>;
 /**
- * Async event emitter implementation
+ * 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 class AsyncEvents {
+export declare abstract class AsyncEventsBase<EventMap extends EventMapConstraint<EventMap> = EventMapBase> implements AsyncEventSource<EventMap> {
     private readonly eventRefsMap;
     /**
      * Remove an event listener.
      *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Args - The types of the arguments the event callback accepts.
      * @param name - The name of the event.
      * @param callback - The callback to remove.
      *
@@ -42,7 +218,7 @@ export declare class AsyncEvents {
      * events.off('my-event', myListener);
      * ```
      */
-    off<Args extends unknown[]>(name: string, callback: GenericPromisableVoidFunction<Args>): void;
+    off<EventName extends StringKeys<EventMap>, Args extends CallbackArgs<EventMap, EventName>>(name: EventName, callback: (...args: Args) => Promisable<void>): void;
     /**
      * Remove an event listener by reference.
      *
@@ -57,6 +233,8 @@ export declare class AsyncEvents {
     /**
      * Add an event listener.
      *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Args - 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 thisArg - The context passed as `this` to the `callback`.
@@ -70,10 +248,12 @@ export declare class AsyncEvents {
      * });
      * ```
      */
-    on<Args extends unknown[]>(name: string, callback: GenericPromisableVoidFunction<Args>, thisArg?: unknown): AsyncEventRef;
+    on<EventName extends StringKeys<EventMap>, Args extends CallbackArgs<EventMap, EventName>>(name: EventName, callback: (...args: Args) => Promisable<void>, thisArg?: unknown): AsyncEventRef;
     /**
      * Add an event listener that will be triggered only once.
      *
+     * @typeParam EventName - The name of the event.
+     * @typeParam Args - 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 thisArg - The context passed as `this` to the `callback`.
@@ -87,10 +267,11 @@ export declare class AsyncEvents {
      * });
      * ```
      */
-    once<Args extends unknown[]>(name: string, callback: GenericPromisableVoidFunction<Args>, thisArg?: unknown): AsyncEventRef;
+    once<EventName extends StringKeys<EventMap>, Args extends CallbackArgs<EventMap, EventName>>(name: EventName, callback: (...args: Args) => Promisable<void>, thisArg?: 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 args - The data to pass to the event listeners.
      *
@@ -99,17 +280,20 @@ export declare class AsyncEvents {
      * events.trigger('my-event', 'arg1', 'arg2');
      * ```
      */
-    trigger<Args extends unknown[]>(name: string, ...args: Args): void;
+    protected trigger<EventName extends StringKeys<EventMap>>(name: EventName, ...args: CallbackArgs<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 args - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
      */
-    triggerAsync<Args extends unknown[]>(name: string, ...args: Args): Promise<void>;
+    protected triggerAsync<EventName extends StringKeys<EventMap>>(name: EventName, ...args: CallbackArgs<EventMap, EventName>): Promise<void>;
     /**
      * Try to trigger an event, executing all the listeners in order even if some of them throw an error.
      *
+     * @typeParam Args - The types of the arguments the function accepts.
      * @param eventRef - The event reference.
      * @param args - The data to pass to the event listeners.
      *
@@ -118,13 +302,81 @@ export declare class AsyncEvents {
      * events.tryTrigger(myRef, ['arg1', 'arg2']);
      * ```
      */
+    protected tryTrigger<Args extends unknown[]>(eventRef: AsyncEventRef, args: Args): void;
+    /**
+     * Try to trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Args - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param args - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
+     */
+    protected tryTriggerAsync<Args extends unknown[]>(eventRef: AsyncEventRef, args: Args): Promise<void>;
+}
+/**
+ * A class that extends {@link AsyncEventsBase} and provides public methods for triggering events.
+ *
+ * This class exists as parity with {@link obsidian#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 args - The data to pass to the event listeners.
+     */
+    trigger<EventName extends StringKeys<EventMap>>(name: EventName, ...args: CallbackArgs<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 args - 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, ...args: CallbackArgs<EventMap, EventName>): Promise<void>;
+    /**
+     * Try to trigger an event, executing all the listeners in order even if some of them throw an error.
+     *
+     * @typeParam Args - The types of the arguments the function accepts.
+     * @param eventRef - The event reference.
+     * @param args - The data to pass to the event listeners.
+     */
     tryTrigger<Args extends unknown[]>(eventRef: AsyncEventRef, args: Args): void;
     /**
      * Try to trigger an event asynchronously, executing all the listeners in order even if some of them throw an error.
      *
+     * @typeParam Args - The types of the arguments the function accepts.
      * @param eventRef - The event reference.
      * @param args - The data to pass to the event listeners.
+     * @returns A {@link Promise} that resolves when all listeners have completed.
      */
     tryTriggerAsync<Args extends unknown[]>(eventRef: AsyncEventRef, args: Args): 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;
 export {};