evnty 3.0.39 → 4.0.0-rc-1

package/LICENSE

@@ -1,13 +1,21 @@
-Copyright (c) 2023-present Ivan Zakharchanka
+The MIT License (MIT)
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+Copyright (c) 2019-2024 Ivan Zakharchanka
 
-    http://www.apache.org/licenses/LICENSE-2.0
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -14,19 +14,40 @@
 - [Features](#features)
 - [Platform Support](#platform-support)
 - [Installing](#installing)
-- [Usage](#usage)
-  - [createEvent](#createevent)
-  - [filter](#filter)
-  - [map](#map)
-  - [reduce](#reduce)
-  - [expand](#expand)
-  - [orchestrate](#orchestrate)
-  - [debounce](#debounce)
-  - [batch](#batch)
-  - [generator](#generator)
-  - [queue](#queue)
-  - [merge](#merge)
-  - [createInterval](#createinterval)
+- [API](#api)
+  - [Event](#event)
+    - [constructor(dispose?: Callback)](#constructordispose-callback)
+    - [error(): Event<unknown>](#error-eventunknown)
+    - [size(): number](#size-number)
+    - [lacks(listener: Listener<T, R>): boolean](#lackslistener-listenert-r-boolean)
+    - [has(listener: Listener<T, R>): boolean](#haslistener-listenert-r-boolean)
+    - [off(listener: Listener<T, R>): this](#offlistener-listenert-r-this)
+    - [on(listener: Listener<T, R>): Unsubscribe](#onlistener-listenert-r-unsubscribe)
+    - [once(listener: Listener<T, R>): Unsubscribe](#oncelistener-listenert-r-unsubscribe)
+    - [clear(): this](#clear-this)
+    - [then(onfulfilled, onrejected): Promise<TResult1 | TResult2>](#thenonfulfilled-onrejected-promisetresult1--tresult2)
+    - [promise(): Promise<T>](#promise-promiset)
+    - [Symbol.asyncIterator(): AsyncIterator<T>](#symbolasynciterator-asynciteratort)
+    - [pipe(generator): Event<PT, R>](#pipegenerator-eventpt-r)
+    - [generator(generator): AsyncGenerator<Awaited<PT>, void, unknown>](#generatorgenerator-asyncgeneratorawaitedpt-void-unknown)
+    - [filter(predicate: Predicate<T, P>): Event<P, R>](#filterpredicate-predicatet-p-eventp-r)
+    - [filter(filter: FilterFunction<T>): Event<P, R>](#filterfilter-filterfunctiont-eventp-r)
+    - [filter(filter: Filter<T, P>): Event<P, R>](#filterfilter-filtert-p-eventp-r)
+    - [first(predicate: Predicate<T, P>): Event<P, R>](#firstpredicate-predicatet-p-eventp-r)
+    - [first(filter: FilterFunction<T>): Event<P, R>](#firstfilter-filterfunctiont-eventp-r)
+    - [first(filter: Filter<T, P>): Event<P, R>](#firstfilter-filtert-p-eventp-r)
+    - [map(mapper: Mapper<T, M>): Event<Awaited<M>, MR>](#mapmapper-mappert-m-eventawaitedm-mr)
+    - [reduce(reducer: Reducer<T, A>, init?: A): Event<Awaited<A>, AR>](#reducereducer-reducert-a-init-a-eventawaiteda-ar)
+    - [reduce(reducer: Reducer<T, A>, ...init: unknown[]): Event<Awaited<A>, AR>](#reducereducer-reducert-a-init-unknown-eventawaiteda-ar)
+    - [expand(expander: Expander<T, ET[]>): Event<Awaited<ET>, ER>](#expandexpander-expandert-et-eventawaitedet-er)
+    - [orchestrate(conductor: Event<any, any>): Event<T, R>](#orchestrateconductor-eventany-any-eventt-r)
+    - [debounce(interval: number): Event<Awaited<T>, unknown>](#debounceinterval-number-eventawaitedt-unknown)
+    - [throttle(interval: number): Event<Awaited<T>, unknown>](#throttleinterval-number-eventawaitedt-unknown)
+    - [batch(interval: number, size?: number): Event<T[], R>](#batchinterval-number-size-number-eventt-r)
+    - [queue(): Queue<T>](#queue-queuet)
+  - [merge(...events: Events): Event<AllEventsParameters<Events>, AllEventsResults<Events>>](#mergeevents-events-eventalleventsparametersevents-alleventsresultsevents)
+  - [createInterval(interval: number): Event<number, R>](#createintervalinterval-number-eventnumber-r)
+  - [createEvent(): Event<T, R>](#createevent-eventt-r)
 - [Examples](#examples)
 - [Migration](#migration)
 - [License](#license)
@@ -79,66 +100,277 @@ Using npm:
 npm install evnty
 ```
 
-## Usage
+## API
 
-### createEvent
+### `Event`
 
-Creates a new event instance.
+A class representing an anonymous event that can be listened to or triggered.
 
-```ts
-import { createEvent, Event } from 'evnty';
+- @template T - The event type.
+- @template R - The return type of the event.
 
-type ClickEvent = { x: number; y: number; button: number };
-const clickEvent = createEvent<ClickEvent>();
+#### `constructor(dispose?: Callback)`
 
-type KeyPressEvent = { key: string };
-const keyPressEvent = createEvent<KeyPressEvent>();
+Creates a new event.
 
-type ChangeEvent = { target: HTMLInputElement };
-const changeEvent = createEvent<ChangeEvent>();
-document.querySelector('input').addEventListener('change', changeEvent);
+- @param dispose - A function to call on the event disposal.
+
+```typescript
+// Create a click event.
+const clickEvent = new Event<[x: number, y: number], void>();
+clickEvent.on(([x, y]) => console.log(`Clicked at ${x}, ${y}`));
+```
+
+#### `error(): Event<unknown>`
+
+Error event that emits errors.
+
+- @returns {Event<unknown>} The error event.
+
+#### `size(): number`
+
+The number of listeners for the event.
+
+- @readonly
+- @type {number}
+
+#### `lacks(listener: Listener<T, R>): boolean`
+
+Checks if the given listener is NOT registered for this event.
+
+- @param listener - The listener function to check against the registered listeners.
+- @returns `true` if the listener is not already registered; otherwise, `false`.
+
+```typescript
+// Check if a listener is not already added
+if (event.lacks(myListener)) {
+  event.on(myListener);
+}
+```
+
+#### `has(listener: Listener<T, R>): boolean`
+
+Checks if the given listener is registered for this event.
+
+- @param listener - The listener function to check.
+- @returns `true` if the listener is currently registered; otherwise, `false`.
+
+```typescript
+// Verify if a listener is registered
+if (event.has(myListener)) {
+  console.log('Listener is already registered');
+}
+```
+
+#### `off(listener: Listener<T, R>): this`
+
+Removes a specific listener from this event.
+
+- @param listener - The listener to remove.
+- @returns The event instance, allowing for method chaining.
+
+```typescript
+// Remove a listener
+event.off(myListener);
+```
+
+#### `on(listener: Listener<T, R>): Unsubscribe`
+
+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.
+
+```typescript
+// Add a listener to an event
+const unsubscribe = event.on((data) => {
+  console.log('Event data:', data);
+});
+```
+
+#### `once(listener: Listener<T, R>): Unsubscribe`
+
+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.
+
+```typescript
+// Register a one-time listener
+const onceUnsubscribe = event.once((data) => {
+  console.log('Received data once:', data);
+});
+```
+
+#### `clear(): this`
+
+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.
+
+```typescript
+const myEvent = new Event();
+myEvent.on((data) => console.log(data));
+myEvent.clear(); // Clears all listeners
+```
+
+#### `then(onfulfilled, onrejected): Promise<TResult1 | TResult2>`
+
+Enables the `Event` to be used in a Promise chain, resolving with the first emitted value.
+
+- @template TResult1 - The type of the fulfilled value returned by `onfulfilled` (defaults to the event's type).
+- @template TResult2 - The type of the rejected value returned by `onrejected` (defaults to `never`).
+- @param onfulfilled - A function called when the event emits its first value.
+- @param onrejected - A function called if an error occurs before the event emits.
+- @returns A Promise that resolves with the result of `onfulfilled` or `onrejected`.
+
+```typescript
+const clickEvent = new Event<[number, number]>();
+await clickEvent;
+```
+
+#### `promise(): Promise<T>`
+
+A promise that resolves with the first emitted value from this event.
+
+- @returns {Promise<T>} The promise value.
+
+#### `Symbol.asyncIterator(): AsyncIterator<T>`
+
+Makes this event iterable using `for await...of` loops.
+
+- @returns An async iterator that yields values as they are emitted by this event.
+
+```typescript
+// Assuming an event that emits numbers
+const numberEvent = new Event<number>();
+(async () => {
+  for await (const num of numberEvent) {
+    console.log('Number:', num);
+  }
+})();
+await numberEvent(1);
+await numberEvent(2);
+await numberEvent(3);
 ```
 
-### filter
+#### `pipe(generator): Event<PT, R>`
+
+Transforms the event's values using a generator function, creating a new `Event` that emits the transformed values.
+
+- @template PT - The type of values emitted by the transformed `Event`.
+- @template PR - The return type of the listeners of the transformed `Event`.
+- @param generator - A function that takes the original event's value and returns a generator (sync or async) that yields the transformed values.
+- @returns A new `Event` instance that emits the transformed values.
+
+```typescript
+const numbersEvent = new Event<number>();
+const evenNumbersEvent = numbersEvent.pipe(function* (value) {
+  if (value % 2 === 0) {
+    yield value;
+  }
+});
+evenNumbersEvent.on((evenNumber) => console.log(evenNumber));
+await numbersEvent(1);
+await numbersEvent(2);
+await numbersEvent(3);
+```
+
+#### `generator(generator): AsyncGenerator<Awaited<PT>, void, unknown>`
+
+Creates an async generator that yields values as they are emitted by this event.
+
+- @template PT - The type of values yielded by the async generator.
+- @param generator - An optional function that takes the original event's value and returns a generator (sync or async)
+  that yields values to include in the async generator.
+- @returns An async generator that yields values from this event as they occur.
+
+```typescript
+const numbersEvent = new Event<number>();
+const evenNumbersEvent = numbersEvent.pipe(function* (value) {
+  if (value % 2 === 0) {
+    yield value;
+  }
+});
+evenNumbersEvent.on((evenNumber) => console.log(evenNumber));
+await numbersEvent(1);
+await numbersEvent(2);
+await numbersEvent(3);
+```
 
-Returns a new event that will only be triggered once the provided filter function returns `true`.
-Supports predicate type guard function and filter function as a more concise variant.
+#### `filter(predicate: Predicate<T, P>): Event<P, R>`
 
-```ts
-import { Predicate } from 'evnty';
+#### `filter(filter: FilterFunction<T>): Event<P, R>`
 
-type SpacePressEvent = KeyPressEvent & { key: 'Space' };
-type LeftClickEvent = ClickEvent & { button: 1 };
+#### `filter(filter: Filter<T, P>): Event<P, R>`
 
-const spacePressPredicate: Predicate<KeyPressEvent, SpacePressEvent> = (keyPressEvent): keyPressEvent is SpacePressEvent => keyPressEvent.key === 'Space';
-// event type is inferred from the predicate function
-const spacePressPredicatedEvent = keyPressEvent.filter(spacePredicate);
-// event type is inferred from the explicitly specified type
-const spacePressFilteredEvent = keyPressEvent.filter<SpacePressEvent>(({ 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.
 
-const leftClickPredicate: Predicate<ClickEvent, LeftClickEvent> = (mouseClickEvent): mouseClickEvent is LeftClickEvent => mouseClickEvent.button === 1;
-// event type is inferred from the predicate function
-const leftClickPredicatedEvent = clickEvent.filter(leftClickPredicate);
-// event type is inferred from the explicitly specified type
-const leftClickFilteredEvent = keyPressEvent.filter<LeftClickEvent>(({ button }) => button === 1);
+- @param {Filter<T, P>} predicate The filter function or predicate to apply to each event.
+- @returns {Event<P, R>} A new event that only triggers for filtered events.
+
+```typescript
+const keyPressedEvent = new Event<string>();
+const enterPressedEvent = keyPressedEvent.filter((key) => key === 'Enter');
+enterPressedEvent.on(() => console.log('Enter key was pressed.'));
 ```
 
-### map
+#### `first(predicate: Predicate<T, P>): Event<P, R>`
+
+#### `first(filter: FilterFunction<T>): Event<P, R>`
+
+#### `first(filter: Filter<T, P>): Event<P, R>`
 
-Returns a new event that maps the values of this event using the provided mapper function.
+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.
 
-```ts
-const point = { x: 100, y: 100 };
-const distanceClickEvent = clickEvent.map((click) => (click.x - point.x) ** 2 + (click.y - point.y) ** 2);
-const lowerCaseKeyPressEvent = keyPressEvent.map(({ key }) => key.toLowerCase());
-const trimmedChangeEvent = changeEvent.map((event) => event.target.value.trim());
+- @param {Filter<T, P>} predicate - The filter function or predicate.
+- @returns {Event<P, R>} A new event that will be triggered only once when the filter condition is met.
+
+```typescript
+const sizeChangeEvent = new Event<number>();
+const sizeReachedEvent = sizeChangeEvent.first((size) => size > 1024);
+sizeReachedEvent.on(() => console.log('Size threshold exceeded.'));
+```
+
+#### `map(mapper: Mapper<T, M>): Event<Awaited<M>, MR>`
+
+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.
+
+```typescript
+// 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"
 ```
 
-### reduce
+#### `reduce(reducer: Reducer<T, A>, init?: A): Event<Awaited<A>, AR>`
+
+#### `reduce(reducer: Reducer<T, A>, ...init: unknown[]): Event<Awaited<A>, AR>`
+
+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.
 
-Returns a new event that reduces the emitted values using the provided reducer function.
+- @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.
 
-```ts
+```typescript
 const sumEvent = numberEvent.reduce((a, b) => a + b, 0);
 sumEvent.on((sum) => console.log(sum)); // 1, 3, 6
 await sumEvent(1);
@@ -146,133 +378,177 @@ await sumEvent(2);
 await sumEvent(3);
 ```
 
-### expand
+#### `expand(expander: Expander<T, ET[]>): Event<Awaited<ET>, ER>`
 
 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.
 
-```ts
+- @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.
+
+```typescript
 // 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));
+const wordEvent = sentenceEvent.expand((sentence) => sentence.split(' '));
+wordEvent.on((word) => console.log('Word:', word));
 await sentenceEvent('Hello world'); // Logs: "Word: Hello", "Word: world"
 ```
 
-### orchestrate
+#### `orchestrate(conductor: Event<any, any>): Event<T, R>`
 
 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.
 
-```ts
+- @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.
+
+```typescript
 const rightClickPositionEvent = mouseMoveEvent.orchestrate(mouseRightClickEvent);
+```
 
+```typescript
 // 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));
+synchronizedEvent.on((data) => console.log('Data on tick:', data));
 await dataEvent('Hello');
 await dataEvent('World!');
 await tickEvent(); // Logs: "Data on tick: World!"
 ```
 
-### debounce
+#### `debounce(interval: number): Event<Awaited<T>, unknown>`
 
 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.
 
-```ts
-const searchEvent = changeEvent.debounce(100);
-searchEvent.value.on(text => searchAPI(text)); // 'text'
-searchEvent.error.on(error => console.error(error));
-await searchEvent('t');
-await searchEvent('te');
-await searchEvent('tex');
-await searchEvent('text');
+- @param {number} interval - The amount of time to wait (in milliseconds) before firing the debounced event.
+- @returns {Event<T, R>} An event of debounced events.
+
+```typescript
+const debouncedEvent = textInputEvent.debounce(100);
+debouncedEvent.on((str) => console.log(str)); // only 'text' is emitted
+await event('t');
+await event('te');
+await event('tex');
+await event('text');
 ```
 
-### batch
+#### `throttle(interval: number): Event<Awaited<T>, 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.
+Creates a throttled event that emits values at most once per specified interval.
 
-```ts
-const sendData = changeEvent.batch(100, 5);
-sendData.value.on(data => console.log(data)); // ['data1', 'data2', 'data3', 'data4']
-sendData.error.on(error => console.error(error)); //
-await sendData('data1');
-await sendData('data2');
-await sendData('data3');
-await sendData('data4');
+This is useful for controlling the rate of event emissions, especially for high-frequency events.
+The throttled event will immediately emit the first value, and then only emit subsequent values
+if the specified interval has passed since the last emission.
+
+- @param interval - The time interval (in milliseconds) between allowed emissions.
+- @returns A new Event that emits throttled values.
+
+```typescript
+const scrollEvent = new Event();
+const throttledScroll = scrollEvent.throttle(100); // Emit at most every 100ms
+throttledScroll.on(() => console.log('Throttled scroll event'));
 ```
 
-### generator
-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.
+#### `batch(interval: number, size?: number): Event<T[], R>`
 
-```ts
-// Assuming an event that emits numbers
-const numberEvent = new Event<number>();
-const numberIterable = numberEvent.generator();
+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.
 
-await numberEvent(1);
-await numberEvent(2);
-await numberEvent(3);
+- @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 {Event<T[], R>} An event of the batched results.
 
-for await (const num of numberIterable) {
-  console.log('Number:', num);
-}
+```typescript
+// 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.on((messages) => console.log('Batched Messages:', messages));
 ```
 
-### queue
+#### `queue(): Queue<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.
 
-```ts
+- @returns {Queue<T>} An object representing the queue. The 'pop' method retrieves the next element from the queue, while 'stop' halts further processing.
+
+```typescript
 // Queueing tasks for sequential execution
 const taskEvent = new Event<string>();
 const taskQueue = taskEvent.queue();
+(async () => {
+  console.log('Processing:', await taskQueue.pop()); // Processing: Task 1
+  console.log('Processing:', await taskQueue.pop()); // Processing: Task 2
+})();
 await taskEvent('Task 1');
 await taskEvent('Task 2');
-console.log('Processing:', await taskQueue.pop()); // Processing: Task 1
-console.log('Processing:', await taskQueue.pop()); // Processing: Task 2
 ```
 
-### merge
+### `merge(...events: Events): Event<AllEventsParameters<Events>, AllEventsResults<Events>>`
 
 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.
 
+- @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.
 
-```ts
-import { merge } from 'evnty';
-
+```typescript
 // 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));
+inputEvent.on((event) => console.log('Input event:', event));
+```
+
+### `createInterval(interval: number): Event<number, R>`
+
+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.
+
+- @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.
+
+```typescript
+// Creating an interval event that logs a message every second
+const tickEvent = createInterval(1000);
+tickEvent.on((tickNumber) => console.log('Tick:', tickNumber));
 ```
 
-### createInterval
+### `createEvent(): Event<T, R>`
 
-Creates an event that triggers at a specified interval.
+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.
 
-```ts
-import { createInterval } from 'evnty';
+- @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.
 
-const everySecondEvent = createInterval(1000);
+```typescript
+// Create a new event that accepts a string and returns the string length
+const myEvent = createEvent<string, number>();
+myEvent.on((str: string) => str.length);
+myEvent('hello').then((results) => console.log(results)); // Logs: [5]
 ```
 
 ## Examples
@@ -338,16 +614,10 @@ const messagesBatchEvent = messageEvent.batch(100);
 
 ```
 
-## Migration
-
-### From v1 to v2
-
-A breaking change has been made: events no longer accept a list of arguments. Now, each event accepts a single argument, so simply wrap your arguments in an object. This decision was taken to leverage the benefits of predicate type guards.
-
 ## License
 
-License [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0)
-Copyright (c) 2021-present Ivan Zakharchanka
+License [MIT](./LICENSE)
+Copyright (c) 2024 Ivan Zakharchanka
 
 [npm-url]: https://www.npmjs.com/package/evnty
 [downloads-image]: https://img.shields.io/npm/dw/evnty.svg?maxAge=43200