evnty 2.1.105 → 3.0.0

package/build/index.d.ts

@@ -5,10 +5,6 @@ export interface Callback<R = void> {
 export interface Listener<T, R = unknown> {
     (event: T): MaybePromise<R | void>;
 }
-export interface Result<T, E> {
-    ok: boolean;
-    result: T | E;
-}
 export interface FilterFunction<T> {
     (event: T): MaybePromise<boolean>;
 }
@@ -22,7 +18,27 @@ export interface Mapper<T, R> {
 export interface Reducer<T, R> {
     (result: R, event: T): MaybePromise<R>;
 }
-export type Listeners<T, R> = Listener<T, R>[];
+export interface Expander<T, R> {
+    (event: T): MaybePromise<R>;
+}
+/**
+ * Removes a listener from the provided array of listeners. It searches for the listener and removes all instances of it from the array.
+ * This method ensures that the listener is fully unregistered, preventing any residual calls to a potentially deprecated handler.
+ *
+ * @param {Listener<T, R>[]} listeners - The array of listeners from which to remove the listener.
+ * @param {Listener<T, R>} listener - The listener function to remove from the list of listeners.
+ * @returns {boolean} - Returns `true` if the listener was found and removed, `false` otherwise.
+ *
+ * @template T - The type of the event that listeners are associated with.
+ * @template R - The type of the return value that listeners are expected to return.
+ *
+ * @example
+ * // Assuming an array of listeners for click events
+ * const listeners = [onClickHandler1, onClickHandler2];
+ * const wasRemoved = removeListener(listeners, onClickHandler1);
+ * console.log(wasRemoved); // Output: true
+ */
+export declare const removeListener: <T, R>(listeners: Listener<T, R>[], listener: Listener<T, R>) => boolean;
 /**
  * An abstract class that extends the built-in Function class. It allows instances of the class
  * to be called as functions. When an instance of FunctionExt is called as a function, it will
@@ -32,30 +48,60 @@ export type Listeners<T, R> = Listener<T, R>[];
 export declare abstract class FunctionExt extends Function {
     constructor(func: Function);
 }
-export interface Dismiss {
+export interface Unsubscribe {
     (): MaybePromise<void>;
 }
 /**
  * @internal
  */
-export declare class Dismiss extends FunctionExt {
+export declare class Unsubscribe extends FunctionExt {
     constructor(callback: Callback);
-    pre(callback: Callback): Dismiss;
-    post(callback: Callback): Dismiss;
-    countdown(count: number): Dismiss;
+    pre(callback: Callback): Unsubscribe;
+    post(callback: Callback): Unsubscribe;
+    countdown(count: number): Unsubscribe;
 }
-type EventType<T> = T extends undefined ? void : T;
-export interface Event<T = unknown, R = void> {
-    (event?: EventType<T>): Promise<(R | undefined)[]>;
+export interface Event<T = any, R = any> {
+    (event: T): Promise<(void | Awaited<R>)[]>;
+}
+/**
+ * Represents a pair of events handling both successful outcomes and errors.
+ * This interface is used to manage asynchronous operations where events can either
+ * result in a successful output or an error.
+ *
+ * The `value` event is triggered when the operation succeeds and emits a result.
+ * The `error` event is triggered when the operation encounters an error, allowing
+ * error handling mechanisms to process or log the error accordingly.
+ *
+ * @template T The type of data emitted by the successful outcome of the event.
+ * @template R The type of data (if any) emitted by the error event.
+ * @template E The type of error information emitted by the error event, usually an Error object or string.
+ *
+ * @example
+ * // Assume an asynchronous function that fetches user data
+ * function fetchUserData(): ResultEvents<UserData, Error> {
+ *   const success = new Event<UserData>();
+ *   const failure = new Event<Error>();
+ *
+ *   fetch('/api/user')
+ *     .then(response => response.json())
+ *     .then(data => success(data))
+ *     .catch(error => failure(error));
+ *
+ *   return { value: success, error: failure };
+ * }
+ *
+ * const userDataEvent = fetchUserData();
+ * userDataEvent.value.on(data => console.log('User data received:', data));
+ * userDataEvent.error.on(error => console.error('An error occurred:', error));
+ */
+export interface ResultEvents<T, R, E = unknown> {
+    value: Event<T, R>;
+    error: Event<E, void>;
+}
+export interface Queue<T> {
+    pop(): MaybePromise<T | undefined>;
+    stop(): MaybePromise<void>;
 }
-export type EventParameters<T> = T extends Event<infer P, unknown> ? P : never;
-export type EventResult<T> = T extends Event<unknown, infer R> ? R : never;
-export type AllEventsParameters<T extends Event<unknown, unknown>[]> = {
-    [K in keyof T]: EventParameters<T[K]>;
-}[number];
-export type AllEventsResults<T extends Event<unknown, unknown>[]> = {
-    [K in keyof T]: EventResult<T[K]>;
-}[number];
 /**
  * A class representing an anonymous event that can be listened to or triggered.
  *
@@ -67,6 +113,11 @@ export declare class Event<T, R> extends FunctionExt {
      * The array of listeners for the event.
      */
     private listeners;
+    /**
+     * The array of listeners for the event.
+     */
+    private addSpies;
+    private removeSpies;
     /**
      * A function that disposes of the event and its listeners.
      */
@@ -76,7 +127,7 @@ export declare class Event<T, R> extends FunctionExt {
      * @example
      * // Create a click event.
      * const clickEvent = new Event<[x: number, y: number], void>();
-     * clickEvent.on((x, y) => console.log(`Clicked at ${x}, ${y}`));
+     * clickEvent.on(([x, y]) => console.log(`Clicked at ${x}, ${y}`));
      *
      * @param dispose - A function to call on the event disposal.
      */
@@ -86,145 +137,352 @@ export declare class Event<T, R> extends FunctionExt {
      */
     get size(): number;
     /**
-     * Checks if a listener is not registered for the event.
-     * @param listener - The listener to check.
-     * @returns `true` if the listener is not registered, `false` otherwise.
+     * Checks if a specific listener is not registered for the event.
+     * This method is typically used to verify whether an event listener has not been added to prevent duplicate registrations.
+     * @param listener - The listener function to check against the registered listeners.
+     * @returns `true` if the listener is not already registered; otherwise, `false`.
+     *
+     * @example
+     * // Check if a listener is not already added
+     * if (event.lacks(myListener)) {
+     *   event.on(myListener);
+     * }
+     *
      */
     lacks(listener: Listener<T, R>): boolean;
     /**
-     * Checks if a listener is registered for the event.
-     * @param listener - The listener to check.
-     * @returns `true` if the listener is registered, `false` otherwise.
+     * Checks if a specific listener is registered for the event.
+     * This method is used to confirm the presence of a listener in the event's registration list.
+     *
+     * @param listener - The listener function to verify.
+     * @returns `true` if the listener is currently registered; otherwise, `false`.
+     *
+     * @example
+     * // Verify if a listener is registered
+     * if (event.has(myListener)) {
+     *   console.log('Listener is already registered');
+     * }
      */
     has(listener: Listener<T, R>): boolean;
     /**
-     * Removes a listener from the event.
+     * Removes a listener from the event's registration list.
+     * This method is used when the listener is no longer needed, helping to prevent memory leaks and unnecessary executions.
+     *
      * @param listener - The listener to remove.
+     * @returns The event instance, allowing for method chaining.
+     *
+     * @example
+     * // Remove a listener
+     * event.off(myListener);
      */
-    off(listener: Listener<T, R>): void;
+    off(listener: Listener<T, R>): this;
     /**
-     * Adds a listener to the event.
-     * @param listener - The listener to add.
-     * @returns An object that can be used to remove the listener.
+     * Registers a listener that gets triggered whenever the event is emitted.
+     * This is the primary method for adding event handlers that will react to the event being triggered.
+     *
+     * @param listener - The function to call when the event occurs.
+     * @returns An object that can be used to unsubscribe the listener, ensuring easy cleanup.
+     *
+     * @example
+     * // Add a listener to an event
+     * const unsubscribe = event.on((data) => {
+     *   console.log('Event data:', data);
+     * });
      */
-    on(listener: Listener<T, R>): Dismiss;
+    on(listener: Listener<T, R>): Unsubscribe;
     /**
-     * Adds a listener to the event that will only be called once.
-     * @param listener - The listener to add.
-     * @returns An object that can be used to remove the listener.
+     * Adds a listener that will be called only once the next time the event is emitted.
+     * This method is useful for one-time notifications or single-trigger scenarios.
+     *
+     * @param listener - The listener to trigger once.
+     * @returns An object that can be used to remove the listener if the event has not yet occurred.
+     * @example
+     * // Register a one-time listener
+     * const onceUnsubscribe = event.once((data) => {
+     *   console.log('Received data once:', data);
+     * });
      */
-    once(listener: Listener<T, R>): Dismiss;
+    once(listener: Listener<T, R>): Unsubscribe;
     /**
-     * Returns a Promise that resolves with the first emitted by the event arguments.
-     * @returns A Promise that resolves with the first emitted by the event.
+     * Returns a Promise that resolves with the first event argument emitted.
+     * This method is useful for scenarios where you need to wait for the first occurrence
+     * of an event and then perform actions based on the event data.
+     *
+     * @returns {Promise<T>} A Promise that resolves with the first event argument emitted.
+     * @example
+     * const clickEvent = new Event<[number, number]>();
+     * clickEvent.onceAsync().then(([x, y]) => {
+     *   console.log(`First click at (${x}, ${y})`);
+     * });
      */
     onceAsync(): Promise<T>;
     /**
-     * Removes all listeners from the event.
+     * Removes all listeners from the event, effectively resetting it. This is useful when you need to
+     * cleanly dispose of all event handlers to prevent memory leaks or unwanted triggerings after certain conditions.
+     *
+     * @returns {this} The instance of the event, allowing for method chaining.
+     * @example
+     * const myEvent = new Event();
+     * myEvent.on(data => console.log(data));
+     * myEvent.clear(); // Clears all listeners
      */
-    clear(): void;
+    clear(): this;
     /**
-     * Returns a new event that only triggers when the provided filter function returns `true`.
-     * @example
-     * const spacePressEvent = keyboardEvent.filter((key) => key === 'Space');
+     * Filters events, creating a new event that only triggers when the provided filter function returns `true`.
+     * This method can be used to selectively process events that meet certain criteria.
      *
-     * @param filter The filter function to apply to the event.
-     * @returns A new event that only triggers when the provided filter function returns `true`.
+     * @param {Filter<T, P>} filter The filter function or predicate to apply to each event.
+     * @returns {Event<P, R>} A new event that only triggers for filtered events.
+     * @example
+     * const keyPressedEvent = new Event<string>();
+     * const enterPressedEvent = keyPressedEvent.filter(key => key === 'Enter');
+     * enterPressedEvent.on(() => console.log('Enter key was pressed.'));
      */
     filter<P extends T>(predicate: Predicate<T, P>): Event<P, R>;
     filter<P extends T>(filter: FilterFunction<T>): Event<P, R>;
     /**
-     * Returns a new event that will only be triggered once the provided filter function returns `true`.
-     * @example
-     * const escPressEvent = keyboardEvent.first((key) => key === 'Esc');
-     * await escPressEvent.toPromise();
+     * Creates a new event that will only be triggered once when the provided filter function returns `true`.
+     * This method is useful for handling one-time conditions in a stream of events.
      *
-     * @param filter - The filter function.
-     * @returns A new event that will only be triggered once the provided filter function returns `true`.
+     * @param {Filter<T, P>} filter - The filter function or predicate.
+     * @returns {Event<P, R>} A new event that will be triggered only once when the filter condition is met.
+     * @example
+     * const sizeChangeEvent = new Event<number>();
+     * const sizeReachedEvent = sizeChangeEvent.first(size => size > 1024);
+     * sizeReachedEvent.on(() => console.log('Size threshold exceeded.'));
      */
     first<P extends T>(predicate: Predicate<T, P>): Event<P, R>;
     first<P extends T>(filter: FilterFunction<T>): Event<P, R>;
     /**
-     * Returns a new promise that will be resolved once the provided filter function returns `true`.
-     * @example
-     * const escPressEvent = await keyboardEvent.firstAsync((key) => key === 'Esc');
+     * Returns a Promise that resolves once an event occurs that meets the filter criteria.
+     * This method is particularly useful for handling asynchronous flows where you need to wait for a specific condition.
      *
-     * @param filter - The filter function.
-     * @returns A new promise that will be resolved once the provided filter function returns `true`.
+     * @param {Filter<T, P>} filter - The filter function or predicate.
+     * @returns {Promise<P>} A Promise that resolves once the filter condition is met.
+     * @example
+     * const mouseEvent = new Event<{x: number, y: number}>();
+     * const clickAtPosition = mouseEvent.firstAsync(pos => pos.x > 200 && pos.y > 200);
+     * clickAtPosition.then(pos => console.log(`Clicked at (${pos.x}, ${pos.y})`));
      */
     firstAsync<P extends T>(predicate: Predicate<T, P>): Promise<P>;
     firstAsync<P extends T>(filter: FilterFunction<T>): Promise<P>;
     /**
-     * Returns a new event that maps the values of this event using the provided mapper function.
+     * Transforms the data emitted by this event using a mapping function. Each emitted event is processed by the `mapper`
+     * function, which returns a new value that is then emitted by the returned `Event` instance. This is useful for data transformation
+     * or adapting the event's data structure.
+     *
+     * @template M The type of data that the mapper function will produce.
+     * @template MR The type of data emitted by the mapped event, usually related to or the same as `M`.
+     * @param {Mapper<T, M>} mapper A function that takes the original event data and returns the transformed data.
+     * @returns {Event<M, MR>} A new `Event` instance that emits the mapped values.
+     *
      * @example
-     * const keyPressEvent = keyboardEvent.map((key) => key.toUpperCase()); // ['a'] -> ['A']
+     * // Assuming an event that emits numbers, create a new event that emits their squares.
+     * const numberEvent = new Event<number>();
+     * const squaredEvent = numberEvent.map(num => num * num);
+     * squaredEvent.on(squared => console.log('Squared number:', squared));
+     * await numberEvent(5); // Logs: "Squared number: 25"
      *
      * @param mapper A function that maps the values of this event to a new value.
      * @returns A new event that emits the mapped values.
      */
     map<M, MR = R>(mapper: Mapper<T, M>): Event<M, MR>;
     /**
-     * Returns a new event that reduces the emitted values using the provided reducer function.
+     * Accumulates the values emitted by this event using a reducer function, starting from an initial value. The reducer
+     * function takes the accumulated value and the latest emitted event data, then returns a new accumulated value. This
+     * new value is then emitted by the returned `Event` instance. This is particularly useful for accumulating state over time.
+     *
      * @example
      * const sumEvent = numberEvent.reduce((a, b) => a + b, 0);
      * sumEvent.on((sum) => console.log(sum)); // 1, 3, 6
-     * sumEvent(1);
-     * sumEvent(2);
-     * sumEvent(3);
-     *
-     * @typeParam A The type of the accumulated value.
-     * @typeParam AR The type of the reduced value.
-     * @param {Reducer<T, A>} reducer The reducer function that accumulates the values emitted by this `Event`.
-     * @param {A} init The initial value of the accumulated value.
-     * @returns {Event<[A], AR>} A new `Event` that emits the reduced value.
+     * await sumEvent(1);
+     * await sumEvent(2);
+     * await sumEvent(3);
+     *
+     * @template A The type of the accumulator value.
+     * @template AR The type of data emitted by the reduced event, usually the same as `A`.
+     * @param {Reducer<T, A>} reducer A function that takes the current accumulated value and the new event data, returning the new accumulated value.
+     * @param {A} init The initial value of the accumulator.
+     * @returns {Event<A, AR>} A new `Event` instance that emits the reduced value.
+     *
      */
     reduce<A, AR = R>(reducer: Reducer<T, A>, init: A): Event<A, AR>;
     /**
-     * Returns a new debounced event that will not fire until a certain amount of time has passed
-     * since the last time it was triggered.
+     * Transforms each event's data into multiple events using an expander function. The expander function takes
+     * the original event's data and returns an array of new data elements, each of which will be emitted individually
+     * by the returned `Event` instance. This method is useful for scenarios where an event's data can naturally
+     * be expanded into multiple, separate pieces of data which should each trigger further processing independently.
+     *
+     * @template ET - The type of data elements in the array returned by the expander function.
+     * @template ER - The type of responses emitted by the expanded event, usually related to or the same as `ET`.
+     * @param {Expander<T, ET[]>} expander - A function that takes the original event data and returns an array of new data elements.
+     * @returns {Event<ET, ER>} - A new `Event` instance that emits each value from the array returned by the expander function.
+     *
+     * @example
+     * // Assuming an event that emits a sentence, create a new event that emits each word from the sentence separately.
+     * const sentenceEvent = new Event<string>();
+     * const wordEvent = sentenceEvent.expand(sentence => sentence.split(' '));
+     * wordEvent.on(word => console.log('Word:', word));
+     * await sentenceEvent('Hello world'); // Logs: "Word: Hello", "Word: world"
+     */
+    expand<ET, ER>(expander: Expander<T, ET[]>): Event<ET, ER>;
+    /**
+     * Creates a new event that emits values based on a conductor event. The orchestrated event will emit the last value
+     * captured from the original event each time the conductor event is triggered. This method is useful for synchronizing
+     * events, where the emission of one event controls the timing of another.
+     *
+     * @example
+     * const rightClickPositionEvent = mouseMoveEvent.orchestrate(mouseRightClickEvent);
+     *
+     * @example
+     * // An event that emits whenever a "tick" event occurs.
+     * const tickEvent = new Event<void>();
+     * const dataEvent = new Event<string>();
+     * const synchronizedEvent = dataEvent.orchestrate(tickEvent);
+     * synchronizedEvent.on(data => console.log('Data on tick:', data));
+     * await dataEvent('Hello');
+     * await dataEvent('World!');
+     * await tickEvent(); // Logs: "Data on tick: World!"
+     *
+     * @template T The type of data emitted by the original event.
+     * @template R The type of data emitted by the orchestrated event, usually the same as `T`.
+     * @param {Event<unknown, unknown>} conductor An event that signals when the orchestrated event should emit.
+     * @returns {Event<T, R>} An orchestrated event that emits values based on the conductor's trigger.
+     *
+     */
+    orchestrate(conductor: Event<any, any>): Event<T, R>;
+    /**
+     * Creates a debounced event that delays triggering until after a specified interval has elapsed
+     * following the last time it was invoked. This method is particularly useful for limiting the rate
+     * at which a function is executed. Common use cases include handling rapid user inputs, window resizing,
+     * or scroll events.
+     *
      * @example
      * const debouncedEvent = textInputEvent.debounce(100);
-     * debouncedEvent.on((str) => console.log(str)); // 'test'
-     * event('t');
-     * event('te');
-     * event('tes');
-     * event('test');
-     *
-     * @param interval - The amount of time to wait before firing the debounced event, in milliseconds.
-     * @returns A new debounced event.
+     * debouncedEvent.on((str) => console.log(str)); // only 'text' is emitted
+     * await event('t');
+     * await event('te');
+     * await event('tex');
+     * await event('text');
+     *
+     * @param {number} interval - The amount of time to wait (in milliseconds) before firing the debounced event.
+     * @returns {ResultEvents<T, R, unknown>} An object containing two events: `value` for the debounced successful
+     * outputs and `error` for catching errors during the debounce handling.
      */
-    debounce(interval: number): Event<T, R>;
+    debounce(interval: number): ResultEvents<T, R, unknown>;
+    /**
+     * Aggregates multiple event emissions into batches and emits the batched events either at specified
+     * time intervals or when the batch reaches a predefined size. This method is useful for grouping
+     * a high volume of events into manageable chunks, such as logging or processing data in bulk.
+     *
+     * @example
+     * // Batch messages for bulk processing every 1 second or when 10 messages are collected
+     * const messageEvent = createEvent<string, void>();
+     * const batchedMessageEvent = messageEvent.batch(1000, 10);
+     * batchedMessageEvent.value.on((messages) => console.log('Batched Messages:', messages));
+     *
+     * @param {number} interval - The time in milliseconds between batch emissions.
+     * @param {number} [size] - Optional. The maximum size of each batch. If specified, triggers a batch emission
+     * once the batch reaches this size, regardless of the interval.
+     * @returns {ResultEvents<T[], R, unknown>} An object containing two events: `value` for the batched results
+     * and `error` for errors that may occur during batching.
+     */
+    batch(interval: number, size?: number): ResultEvents<T[], R, unknown>;
+    /**
+     * Transforms an event into an AsyncIterable that yields values as they are emitted by the event. This allows for the consumption
+     * of event data using async iteration mechanisms. The iterator generated will yield all emitted values until the event
+     * signals it should no longer be active.
+     *
+     * @returns {AsyncIterable<T>} An async iterable that yields values emitted by the event.
+     * @example
+     * // Assuming an event that emits numbers
+     * const numberEvent = new Event<number>();
+     * const numberIterable = numberEvent.generator();
+     * (async () => {
+     *   for await (const num of numberIterable) {
+     *     console.log('Number:', num);
+     *   }
+     * })();
+     * await numberEvent(1);
+     * await numberEvent(2);
+     * await numberEvent(3);
+     */
+    generator(): AsyncIterable<T>;
+    /**
+     * Creates a queue from the event, where each emitted value is sequentially processed. The returned object allows popping elements
+     * from the queue, ensuring that elements are handled one at a time. This method is ideal for scenarios where order and sequential processing are critical.
+     *
+     * @returns {Queue<T>} An object representing the queue. The 'pop' method retrieves the next element from the queue, while 'stop' halts further processing.
+     * @example
+     * // Queueing tasks for sequential execution
+     * const taskEvent = new Event<string>();
+     * const taskQueue = taskEvent.queue();
+     * await taskEvent('Task 1');
+     * await taskEvent('Task 2');
+     * (async () => {
+     *   console.log('Processing:', await taskQueue.pop()); // Processing: Task 1
+     *   console.log('Processing:', await taskQueue.pop()); // Processing: Task 2
+     * })();
+     */
+    queue(): Queue<T>;
 }
+export type EventParameters<T> = T extends Event<infer P, any> ? P : never;
+export type EventResult<T> = T extends Event<any, infer R> ? R : never;
+export type AllEventsParameters<T extends Event<any, any>[]> = {
+    [K in keyof T]: EventParameters<T[K]>;
+}[number];
+export type AllEventsResults<T extends Event<any, any>[]> = {
+    [K in keyof T]: EventResult<T[K]>;
+}[number];
 /**
- * Merges multiple events into a single event.
- * @example
- * const inputEvent = Event.merge(mouseEvent, keyboardEvent);
+ * Merges multiple events into a single event. This function takes any number of `Event` instances
+ * and returns a new `Event` that triggers whenever any of the input events trigger. The parameters
+ * and results of the merged event are derived from the input events, providing a flexible way to
+ * handle multiple sources of events in a unified manner.
  *
- * @param events - The events to merge.
- * @returns The merged event.
+ * @template Events - An array of `Event` instances.
+ * @param {...Events} events - A rest parameter that takes multiple events to be merged.
+ * @returns {Event<AllEventsParameters<Events>, AllEventsResults<Events>>} - Returns a new `Event` instance
+ *           that triggers with the parameters and results of any of the merged input events.
+ *
+ * @example
+ * // Merging mouse and keyboard events into a single event
+ * const mouseEvent = createEvent<MouseEvent>();
+ * const keyboardEvent = createEvent<KeyboardEvent>();
+ * const inputEvent = merge(mouseEvent, keyboardEvent);
+ * inputEvent.on(event => console.log('Input event:', event));
  */
 export declare const merge: <Events extends Event<any, any>[]>(...events: Events) => Event<AllEventsParameters<Events>, AllEventsResults<Events>>;
 /**
- * Creates an event that triggers at a specified interval.
- * @example
- * const tickEvent = Event.interval(1000);
- * tickEvent.on((tickNumber) => console.log(tickNumber));
+ * Creates a periodic event that triggers at a specified interval. The event will automatically emit
+ * an incrementing counter value each time it triggers, starting from zero. This function is useful
+ * for creating time-based triggers within an application, such as updating UI elements, polling,
+ * or any other timed operation.
  *
- * @param interval - The interval at which to trigger the event.
- * @returns The interval event.
+ * @template R - The return type of the event handler function, defaulting to `void`.
+ * @param {number} interval - The interval in milliseconds at which the event should trigger.
+ * @returns {Event<number, R>} - An `Event` instance that triggers at the specified interval,
+ *           emitting an incrementing counter value.
+ *
+ * @example
+ * // Creating an interval event that logs a message every second
+ * const tickEvent = createInterval(1000);
+ * tickEvent.on(tickNumber => console.log('Tick:', tickNumber));
  */
 export declare const createInterval: <R = void>(interval: number) => Event<number, R>;
 /**
- * Creates a new event instance.
+ * Creates a new instance of the `Event` class, which allows for the registration of event handlers that get called when the event is emitted.
+ * This factory function simplifies the creation of events by encapsulating the instantiation logic, providing a clean and simple API for event creation.
  *
- * @typeParam T - An array of argument types that the event will accept.
- * @typeParam R - The return type of the event handler function.
- * @returns A new instance of the `Event` class.
+ * @typeParam T - The tuple of argument types that the event will accept.
+ * @typeParam R - The return type of the event handler function, which is emitted after processing the event data.
+ * @returns {Event<T, R>} - A new instance of the `Event` class, ready to have listeners added to it.
  *
  * @example
- * const myEvent = createEvent<[string], number>();
+ * // Create a new event that accepts a string and returns the string length
+ * const myEvent = createEvent<string, number>();
  * myEvent.on((str: string) => str.length);
- * await myEvent('hello'); // [5]
+ * myEvent('hello').then(results => console.log(results)); // Logs: [5]
  */
 export declare const createEvent: <T, R = void>() => Event<T, R>;
 export default createEvent;