evnty 5.0.0 → 5.1.0

package/build/event.d.ts

@@ -1,131 +1,89 @@
-import { MaybePromise, Callback, Listener, FilterFunction, Predicate, Mapper, Reducer } from './types.js';
-import { Callable, CallableAsyncIterator } from './callable.js';
+import { Callback, Listener, FilterFunction, Predicate, Mapper, Reducer, Action, Fn, Emitter, MaybePromise, Promiseable } from './types.js';
+import { Signal } from './signal.js';
+import { DispatchResult } from './dispatch-result.js';
+export type Unsubscribe = Action;
 /**
- * Represents an unsubscribe function that can be called to remove a listener.
- * Provides additional utilities for chaining and conditional unsubscription.
- *
  * @internal
  */
-export declare class Unsubscribe extends Callable<[], MaybePromise<void>> {
-    private _done;
-    constructor(callback: Callback);
-    get done(): boolean;
-    /**
-     * Creates a new unsubscribe function that executes the given callback before this unsubscribe.
-     *
-     * @param callback - The callback to execute before unsubscribing.
-     * @returns {Unsubscribe} A new Unsubscribe instance.
-     */
-    pre(callback: Callback): Unsubscribe;
-    /**
-     * Creates a new unsubscribe function that executes the given callback after this unsubscribe.
-     *
-     * @param callback - The callback to execute after unsubscribing.
-     * @returns {Unsubscribe} A new Unsubscribe instance.
-     */
-    post(callback: Callback): Unsubscribe;
-    /**
-     * Creates a new unsubscribe function that only executes after being called a specified number of times.
-     *
-     * @param count - The number of times this must be called before actually unsubscribing.
-     * @returns {Unsubscribe} A new Unsubscribe instance.
-     */
-    countdown(count: number): Unsubscribe;
-}
-/**
- * Wraps an array of values or promises (typically listener results) and provides batch resolution.
- *
- * @template T
- */
-export declare class EventResult<T> implements PromiseLike<T[]> {
+export declare class EventIterator<T> implements AsyncIterator<T, void, void> {
     #private;
-    readonly [Symbol.toStringTag] = "EventResult";
-    /**
-     * @param results - An array of values or Promise-returning listener calls.
-     */
-    constructor(results: MaybePromise<T>[]);
-    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
-    /**
-     * Resolves all listener results, rejecting if any promise rejects.
-     *
-     * @returns {Promise<T[]>} A promise that fulfills with an array of all resolved values.
-     */
-    all(): Promise<T[]>;
-    /**
-     * Waits for all listener results to settle, regardless of fulfillment or rejection.
-     *
-     * @returns {Promise<PromiseSettledResult<T>[]>} A promise that fulfills with an array of each result's settled status and value/reason.
-     */
-    settled(): Promise<PromiseSettledResult<T>[]>;
+    constructor(signal: Signal<T>);
+    next(): Promise<IteratorResult<T, void>>;
+    return(): Promise<IteratorResult<T, void>>;
 }
 /**
- * A class representing a multi-listener event emitter with async support.
- * Events allow multiple listeners to react to emitted values, with each listener
- * potentially returning a result. All listeners are called for each emission.
- *
- * Key characteristics:
- * - Multiple listeners - all are called for each emission
- * - Listeners can return values collected in EventResult
- * - Supports async listeners and async iteration
- * - Provides lifecycle hooks for listener management
- * - Memory efficient using RingBuffer for storage
+ * Multi-listener event emitter with async support.
+ * All registered listeners are called for each emission, and their return
+ * values are collected in a DispatchResult. Supports async iteration and
+ * an `onDispose` callback for cleanup.
  *
  * Differs from:
- * - Signal: Events have multiple persistent listeners vs Signal's one-time resolution per consumer
- * - Sequence: Events broadcast to all listeners vs Sequence's single consumer queue
+ * - Signal: Event has persistent listeners; Signal is promise-based (receive per round)
+ * - Sequence: Event broadcasts to all listeners; Sequence is a single-consumer queue
  *
  * @template T - The type of value emitted to listeners (event payload)
  * @template R - The return type of listener functions
  */
-export declare class Event<T = unknown, R = unknown> extends CallableAsyncIterator<T, EventResult<void | R>> {
-    /**
-     * The ring buffer containing all registered listeners for the event.
-     */
-    private listeners;
-    /**
-     * The ring buffer containing hook listeners that respond to listener lifecycle events.
-     */
-    private hooks;
-    /**
-     * Flag indicating whether this event has been disposed.
-     */
-    private _disposed;
-    /**
-     * A function that disposes of the event and its listeners.
-     */
-    readonly dispose: Callback;
+export declare class Event<T = unknown, R = unknown> implements Emitter<T, DispatchResult<void | R>>, Promiseable<T>, Promise<T>, Disposable, AsyncIterable<T> {
+    #private;
     readonly [Symbol.toStringTag] = "Event";
     /**
      * Creates a new event.
      *
-     * @param dispose - A function to call on the event disposal.
+     * @param onDispose - A function to call on the event disposal.
      *
+     * @example
      * ```typescript
      * // Create a click event.
      * const clickEvent = new Event<[x: number, y: number], void>();
      * clickEvent.on(([x, y]) => console.log(`Clicked at ${x}, ${y}`));
+     * clickEvent.emit([10, 20]);
      * ```
      */
-    constructor(dispose?: Callback);
+    constructor(onDispose?: Callback);
     /**
-     * The number of listeners for the event.
+     * Returns a bound emit function for use as a callback.
+     * Useful for passing to other APIs that expect a function.
      *
-     * @readonly
-     * @type {number}
+     * @example
+     * ```typescript
+     * const event = new Event<string>();
+     * someApi.onMessage(event.sink);
+     * ```
+     */
+    get sink(): Fn<[T], DispatchResult<void | R>>;
+    /**
+     * DOM EventListener interface compatibility.
+     * Allows the event to be used directly with addEventListener.
+     */
+    handleEvent(event: T): void;
+    /**
+     * The number of listeners for the event.
      */
     get size(): number;
     /**
-     * Checks if the event has been disposed.
+     * Emits a value to all registered listeners.
+     * Each listener is called with the value and their return values are collected.
+     *
+     * @param value - The value to emit to all listeners.
+     * @returns A DispatchResult containing all listener return values.
      *
-     * @returns {boolean} `true` if the event has been disposed; otherwise, `false`.
+     * @example
+     * ```typescript
+     * const event = new Event<string, number>();
+     * event.on(str => str.length);
+     * const result = event.emit('hello');
+     * await result.all(); // [5]
+     * ```
      */
-    get disposed(): boolean;
+    emit(value: T): DispatchResult<void | R>;
     /**
      * Checks if the given listener is NOT registered for this event.
      *
      * @param listener - The listener function to check against the registered listeners.
-     * @returns {boolean} `true` if the listener is not already registered; otherwise, `false`.
+     * @returns `true` if the listener is not already registered; otherwise, `false`.
      *
+     * @example
      * ```typescript
      * // Check if a listener is not already added
      * if (event.lacks(myListener)) {
@@ -138,8 +96,9 @@ export declare class Event<T = unknown, R = unknown> extends CallableAsyncIterat
      * Checks if the given listener is registered for this event.
      *
      * @param listener - The listener function to check.
-     * @returns {boolean} `true` if the listener is currently registered; otherwise, `false`.
+     * @returns `true` if the listener is currently registered; otherwise, `false`.
      *
+     * @example
      * ```typescript
      * // Verify if a listener is registered
      * if (event.has(myListener)) {
@@ -152,8 +111,9 @@ export declare class Event<T = unknown, R = unknown> extends CallableAsyncIterat
      * Removes a specific listener from this event.
      *
      * @param listener - The listener to remove.
-     * @returns {this} The event instance, allowing for method chaining.
+     * @returns The event instance for chaining.
      *
+     * @example
      * ```typescript
      * // Remove a listener
      * event.off(myListener);
@@ -161,14 +121,13 @@ export declare class Event<T = unknown, R = unknown> extends CallableAsyncIterat
      */
     off(listener: Listener<T, R>): this;
     /**
-     * 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.
+     * Registers a listener that is called on every emission.
      *
      * @param listener - The function to call when the event occurs.
-     * @returns {Unsubscribe} An object that can be used to unsubscribe the listener, ensuring easy cleanup.
+     * @returns A function that removes this listener when called.
      *
+     * @example
      * ```typescript
-     * // Add a listener to an event
      * const unsubscribe = event.on((data) => {
      *   console.log('Event data:', data);
      * });
@@ -176,75 +135,54 @@ export declare class Event<T = unknown, R = unknown> extends CallableAsyncIterat
      */
     on(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.
+     * Registers a listener that is called only once on the next emission, then auto-removed.
      *
      * @param listener - The listener to trigger once.
-     * @returns {Unsubscribe} An object that can be used to remove the listener if the event has not yet occurred.
+     * @returns A function that removes this listener when called (if it hasn't fired yet).
      *
+     * @example
      * ```typescript
-     * // Register a one-time listener
-     * const onceUnsubscribe = event.once((data) => {
+     * const cancel = event.once((data) => {
      *   console.log('Received data once:', data);
      * });
      * ```
      */
     once(listener: Listener<T, R>): Unsubscribe;
     /**
-     * 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 triggers after certain conditions.
+     * Removes all listeners from the event.
+     * Does not dispose the event - new listeners can still be added after clearing.
      *
-     * @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
-     * ```
+     * @returns The event instance for chaining.
      */
     clear(): this;
     /**
-     * Waits for the next event emission and returns the emitted value.
-     * This method allows the event to be used as a promise that resolves with the next emitted value.
+     * Waits for the next emission and returns the emitted value.
      *
-     * @returns {Promise<T>} A promise that resolves with the next emitted event value.
+     * @returns A promise that resolves with the next emitted value.
      */
-    next(): Promise<T>;
+    receive(): Promise<T>;
+    then<OK = T, ERR = never>(onfulfilled?: Fn<[T], MaybePromise<OK>> | null, onrejected?: Fn<[unknown], MaybePromise<ERR>> | null): Promise<OK | ERR>;
+    catch<ERR = never>(onrejected?: Fn<[unknown], MaybePromise<ERR>> | null): Promise<T | ERR>;
+    finally(onfinally?: Action | null): Promise<T>;
     /**
-     * Waits for the event to settle, returning a `PromiseSettledResult`.
+     * Waits for the next emission via `receive()` and wraps the outcome in a
+     * `PromiseSettledResult` - always resolves, never rejects.
      *
-     * @returns {Promise<PromiseSettledResult<T>>} A promise that resolves with the settled result.
+     * @returns A promise that resolves with the settled result.
      *
      * @example
      * ```typescript
      * const result = await event.settle();
      * if (result.status === 'fulfilled') {
-     *   console.log('Event fulfilled with value:', result.value);
+     *   console.log('Value:', result.value);
      * } else {
-     *   console.error('Event rejected with reason:', result.reason);
+     *   console.error('Reason:', result.reason);
      * }
      * ```
      */
     settle(): Promise<PromiseSettledResult<T>>;
-    /**
-     * Makes this event iterable using `for await...of` loops.
-     *
-     * @returns {AsyncIterator<T>} 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);
-     * ```
-     */
-    [Symbol.asyncIterator](): AsyncIterator<T>;
+    [Symbol.asyncIterator](): AsyncIterator<T, void, void>;
+    dispose(): void;
     [Symbol.dispose](): void;
 }
 export type EventParameters<T> = T extends Event<infer P, any> ? P : never;
@@ -256,18 +194,14 @@ export type AllEventsResults<T extends Event<any, any>[]> = {
     [K in keyof T]: EventReturn<T[K]>;
 }[number];
 /**
- * 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.
+ * Merges multiple events into a single event that triggers whenever any source triggers.
+ * Disposing the merged event unsubscribes from all sources.
  *
- * @template Events - An array of `Event` instances.
- * @param 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.
+ * @param events - The events to merge.
+ * @returns A new Event that forwards emissions from all sources.
  *
+ * @example
  * ```typescript
- * // Merging mouse and keyboard events into a single event
  * const mouseEvent = createEvent<MouseEvent>();
  * const keyboardEvent = createEvent<KeyboardEvent>();
  * const inputEvent = merge(mouseEvent, keyboardEvent);
@@ -276,18 +210,14 @@ export type AllEventsResults<T extends Event<any, any>[]> = {
  */
 export declare const merge: <Events extends Event<any, any>[]>(...events: Events) => Event<AllEventsParameters<Events>, AllEventsResults<Events>>;
 /**
- * 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.
+ * Creates a periodic event that emits an incrementing counter (starting from 0) at a fixed interval.
+ * Disposing the event clears the interval.
  *
- * @template R - The return type of the event handler function, defaulting to `void`.
- * @param 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.
+ * @param interval - The interval in milliseconds.
+ * @returns An Event that triggers at the specified interval.
  *
+ * @example
  * ```typescript
- * // Creating an interval event that logs a message every second
  * const tickEvent = createInterval(1000);
  * tickEvent.on(tickNumber => console.log('Tick:', tickNumber));
  * ```
@@ -295,23 +225,18 @@ export declare const merge: <Events extends Event<any, any>[]>(...events: Events
 export declare const createInterval: <R = unknown>(interval: number) => Event<number, R>;
 /**
  * Creates a new Event instance for multi-listener event handling.
- * This is the primary way to create events in the library.
- *
- * @template T - The type of value emitted to listeners (event payload)
- * @template R - The return type of listener functions (collected in EventResult)
- * @returns {Event<T, R>} A new Event instance ready for listener registration
  *
+ * @example
  * ```typescript
- * // Create an event that accepts a string payload
  * const messageEvent = createEvent<string>();
  * messageEvent.on(msg => console.log('Received:', msg));
- * messageEvent('Hello'); // All listeners receive 'Hello'
+ * messageEvent.emit('Hello'); // All listeners receive 'Hello'
  *
- * // Create an event where listeners return values
+ * // Listeners can return values, collected via DispatchResult
  * const validateEvent = createEvent<string, boolean>();
  * validateEvent.on(str => str.length > 0);
  * validateEvent.on(str => str.length < 100);
- * const results = await validateEvent('test'); // EventResult with [true, true]
+ * const results = await validateEvent.emit('test').all(); // [true, true]
  * ```
  */
 export declare const createEvent: <T = unknown, R = unknown>() => Event<T, R>;

package/build/event.js

@@ -1,162 +1,130 @@
-import { RingBuffer } from 'fastds';
-import { HookType } from "./types.js";
-import { Callable, CallableAsyncIterator } from "./callable.js";
-import { Sequence } from "./sequence.js";
-export class Unsubscribe extends Callable {
-    _done = false;
-    constructor(callback){
-        super(async ()=>{
-            this._done = true;
-            await callback();
-        });
-    }
-    get done() {
-        return this._done;
-    }
-    pre(callback) {
-        return new Unsubscribe(async ()=>{
-            await callback();
-            await this();
-        });
-    }
-    post(callback) {
-        return new Unsubscribe(async ()=>{
-            await this();
-            await callback();
-        });
-    }
-    countdown(count) {
-        return new Unsubscribe(async ()=>{
-            if (!--count) {
-                await this();
-            }
-        });
+import { Disposer } from "./async.js";
+import { Signal } from "./signal.js";
+import { ListenerRegistry } from "./listener-registry.js";
+import { DispatchResult } from "./dispatch-result.js";
+export class EventIterator {
+    #signal;
+    constructor(signal){
+        this.#signal = signal;
     }
-}
-export class EventResult {
-    #results;
-    [Symbol.toStringTag] = 'EventResult';
-    constructor(results){
-        this.#results = results;
-    }
-    then(onfulfilled, onrejected) {
-        return this.all().then(onfulfilled, onrejected);
-    }
-    all() {
-        return Promise.all(this.#results);
+    async next() {
+        try {
+            const value = await this.#signal.receive();
+            return {
+                value,
+                done: false
+            };
+        } catch  {
+            return {
+                value: undefined,
+                done: true
+            };
+        }
     }
-    settled() {
-        return Promise.allSettled(this.#results);
+    async return() {
+        return {
+            value: undefined,
+            done: true
+        };
     }
 }
-export class Event extends CallableAsyncIterator {
-    listeners;
-    hooks = new RingBuffer();
-    _disposed = false;
-    dispose;
+export class Event {
+    #listeners = new ListenerRegistry();
+    #signal = new Signal();
+    #disposer;
+    #onDispose;
+    #sink;
     [Symbol.toStringTag] = 'Event';
-    constructor(dispose){
-        const listeners = new RingBuffer();
-        super((value)=>{
-            const results = listeners.toArray().map(async (listener)=>listener(await value));
-            return new EventResult(results);
-        });
-        this.listeners = listeners;
-        this.dispose = ()=>{
-            this._disposed = true;
-            void this.clear();
-            void dispose?.();
-        };
+    constructor(onDispose){
+        this.#onDispose = onDispose;
+        this.#disposer = new Disposer(this);
+    }
+    get sink() {
+        return this.#sink ??= this.emit.bind(this);
+    }
+    handleEvent(event) {
+        this.emit(event);
     }
     get size() {
-        return this.listeners.length;
+        return this.#listeners.size;
     }
-    get disposed() {
-        return this._disposed;
+    emit(value) {
+        this.#signal.emit(value);
+        return new DispatchResult(this.#listeners.dispatch(value));
     }
     lacks(listener) {
-        return !this.listeners.has(listener);
+        return !this.#listeners.has(listener);
     }
     has(listener) {
-        return this.listeners.has(listener);
+        return this.#listeners.has(listener);
     }
     off(listener) {
-        if (this.listeners.compact((l)=>l !== listener) && this.hooks.length) {
-            [
-                ...this.hooks
-            ].forEach((hook)=>hook(listener, HookType.Remove));
-        }
+        this.#listeners.off(listener);
         return this;
     }
     on(listener) {
-        this.listeners.push(listener);
-        if (this.hooks.length) {
-            [
-                ...this.hooks
-            ].forEach((hook)=>hook(listener, HookType.Add));
-        }
-        return new Unsubscribe(()=>{
-            void this.off(listener);
-        });
+        this.#listeners.on(listener);
+        return ()=>void this.off(listener);
     }
     once(listener) {
-        const oneTimeListener = (event)=>{
-            void this.off(oneTimeListener);
-            return listener(event);
-        };
-        return this.on(oneTimeListener);
+        this.#listeners.once(listener);
+        return ()=>void this.off(listener);
     }
     clear() {
-        this.listeners.clear();
-        if (this.hooks.length) {
-            [
-                ...this.hooks
-            ].forEach((hook)=>hook(undefined, HookType.Remove));
-        }
+        this.#listeners.clear();
         return this;
     }
-    async next() {
-        const { promise, resolve } = Promise.withResolvers();
-        this.listeners.push(resolve);
-        return promise.finally(()=>{
-            this.listeners.removeFirst(resolve);
-        });
+    receive() {
+        return this.#signal.receive();
+    }
+    then(onfulfilled, onrejected) {
+        return this.receive().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.receive().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.receive().finally(onfinally);
     }
-    async settle() {
-        return await Promise.allSettled([
-            this.next()
-        ]).then(([settled])=>settled);
+    settle() {
+        return this.receive().then((value)=>({
+                status: 'fulfilled',
+                value
+            }), (reason)=>({
+                status: 'rejected',
+                reason
+            }));
     }
     [Symbol.asyncIterator]() {
-        const ctrl = new AbortController();
-        const sequence = new Sequence(ctrl.signal);
-        const emitEvent = (value)=>{
-            sequence(value);
-        };
-        this.listeners.push(emitEvent);
-        const hook = (target = emitEvent, action)=>{
-            if (target === emitEvent && action === HookType.Remove) {
-                ctrl.abort('done');
-                this.listeners.removeFirst(emitEvent);
-            }
-        };
-        this.hooks.push(hook);
-        return sequence[Symbol.asyncIterator]();
+        return new EventIterator(this.#signal);
+    }
+    dispose() {
+        this[Symbol.dispose]();
     }
     [Symbol.dispose]() {
-        void this.dispose();
+        if (this.#disposer[Symbol.dispose]()) {
+            this.#signal[Symbol.dispose]();
+            this.#listeners.clear();
+            void this.#onDispose?.();
+        }
     }
 }
 export const merge = (...events)=>{
-    const mergedEvent = new Event();
-    events.forEach((event)=>event.on(mergedEvent));
+    const mergedEvent = new Event(()=>{
+        for (const event of events){
+            event.off(mergedEvent.sink);
+        }
+    });
+    for (const event of events){
+        event.on(mergedEvent.sink);
+    }
     return mergedEvent;
 };
 export const createInterval = (interval)=>{
     let counter = 0;
     const intervalEvent = new Event(()=>clearInterval(timerId));
     const timerId = setInterval(()=>{
-        void intervalEvent(counter++);
+        intervalEvent.emit(counter++);
     }, interval);
     return intervalEvent;
 };