@xylabs/events 5.0.83 → 5.0.84

package/README.md

@@ -54,6 +54,9 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ***
 
+Base class that combines the Base utility class with typed event emission capabilities.
+Delegates all event operations to an internal Events instance.
+
 ## Extends
 
 - `Base`\<`TParams`\>
@@ -146,6 +149,8 @@ Base.globalInstancesCountHistory
 eventData: TEventData;
 ```
 
+Type-level reference to the event data shape for external type queries.
+
 ### Implementation of
 
 [`EventEmitter`](#../interfaces/EventEmitter).[`eventData`](../interfaces/EventEmitter.md#eventdata)
@@ -492,16 +497,22 @@ Base.stopHistory
 clearListeners(eventNames): BaseEmitter<TParams, TEventData>;
 ```
 
+Removes all listeners for the specified event name(s).
+
 ### Parameters
 
 #### eventNames
 
+One or more event names to clear listeners for.
+
 keyof `TEventData` | keyof `TEventData`[]
 
 ### Returns
 
 `BaseEmitter`\<`TParams`, `TEventData`\>
 
+This instance for chaining.
+
 ### Implementation of
 
 [`EventEmitter`](#../interfaces/EventEmitter).[`clearListeners`](../interfaces/EventEmitter.md#clearlisteners)
@@ -514,6 +525,8 @@ keyof `TEventData` | keyof `TEventData`[]
 emit<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
 ```
 
+Emits an event, invoking all registered listeners concurrently.
+
 ### Type Parameters
 
 #### TEventName
@@ -530,10 +543,14 @@ emit<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
 
 `TEventName`
 
+The event to emit.
+
 #### eventArgs
 
 `TEventArgs`
 
+The data to pass to listeners.
+
 ### Returns
 
 `Promise`\<`void`\>
@@ -550,6 +567,8 @@ emit<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
 emitSerial<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
 ```
 
+Emits an event, invoking all registered listeners sequentially in order.
+
 ### Type Parameters
 
 #### TEventName
@@ -566,10 +585,14 @@ emitSerial<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
 
 `TEventName`
 
+The event to emit.
+
 #### eventArgs
 
 `TEventArgs`
 
+The data to pass to listeners.
+
 ### Returns
 
 `Promise`\<`void`\>
@@ -586,16 +609,22 @@ emitSerial<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
 listenerCount(eventNames): number;
 ```
 
+Returns the total number of listeners registered for the specified event name(s).
+
 ### Parameters
 
 #### eventNames
 
+One or more event names to count listeners for.
+
 keyof `TEventData` | keyof `TEventData`[]
 
 ### Returns
 
 `number`
 
+The total listener count.
+
 ### Implementation of
 
 [`EventEmitter`](#../interfaces/EventEmitter).[`listenerCount`](../interfaces/EventEmitter.md#listenercount)
@@ -608,6 +637,8 @@ keyof `TEventData` | keyof `TEventData`[]
 off<TEventName>(eventNames, listener): void;
 ```
 
+Removes a specific listener from the specified event name(s).
+
 ### Type Parameters
 
 #### TEventName
@@ -618,12 +649,16 @@ off<TEventName>(eventNames, listener): void;
 
 #### eventNames
 
+One or more event names to unsubscribe from.
+
 `TEventName` | `TEventName`[]
 
 #### listener
 
 [`EventListener`](#../type-aliases/EventListener)\<`TEventData`\[`TEventName`\]\>
 
+The listener to remove.
+
 ### Returns
 
 `void`
@@ -640,12 +675,16 @@ off<TEventName>(eventNames, listener): void;
 offAny(listener): void;
 ```
 
+Removes a wildcard listener that was receiving all events.
+
 ### Parameters
 
 #### listener
 
 [`EventAnyListener`](#../type-aliases/EventAnyListener)
 
+The wildcard listener to remove.
+
 ### Returns
 
 `void`
@@ -662,6 +701,8 @@ offAny(listener): void;
 on<TEventName>(eventNames, listener): (...args) => void;
 ```
 
+Subscribes a listener to the specified event name(s).
+
 ### Type Parameters
 
 #### TEventName
@@ -672,14 +713,20 @@ on<TEventName>(eventNames, listener): (...args) => void;
 
 #### eventNames
 
+One or more event names to listen for.
+
 `TEventName` | `TEventName`[]
 
 #### listener
 
 [`EventListener`](#../type-aliases/EventListener)\<`TEventData`\[`TEventName`\]\>
 
+The callback to invoke when the event fires.
+
 ### Returns
 
+An unsubscribe function.
+
 ```ts
 (...args): void;
 ```
@@ -706,14 +753,20 @@ on<TEventName>(eventNames, listener): (...args) => void;
 onAny(listener): (...args) => void;
 ```
 
+Subscribes a wildcard listener that receives all events.
+
 ### Parameters
 
 #### listener
 
 [`EventAnyListener`](#../type-aliases/EventAnyListener)
 
+The callback to invoke for any event.
+
 ### Returns
 
+An unsubscribe function.
+
 ```ts
 (...args): void;
 ```
@@ -740,6 +793,8 @@ onAny(listener): (...args) => void;
 once<TEventName>(eventName, listener): (...args) => void;
 ```
 
+Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
+
 ### Type Parameters
 
 #### TEventName
@@ -752,12 +807,18 @@ once<TEventName>(eventName, listener): (...args) => void;
 
 `TEventName`
 
+The event to listen for.
+
 #### listener
 
 [`EventListener`](#../type-aliases/EventListener)\<`TEventData`\[`TEventName`\]\>
 
+The callback to invoke once.
+
 ### Returns
 
+An unsubscribe function.
+
 ```ts
 (...args): void;
 ```
@@ -782,6 +843,9 @@ once<TEventName>(eventName, listener): (...args) => void;
 
 ***
 
+Core typed event emitter implementation supporting named events, wildcard listeners,
+serial and concurrent emission, listener filtering, and debug logging.
+
 ## Extends
 
 - `Base`\<[`EventsParams`](#../type-aliases/EventsParams)\>
@@ -886,6 +950,8 @@ protected static eventsMap: WeakMap<object, Map<PropertyKey, Set<EventListenerIn
 eventData: TEventData;
 ```
 
+Type-level reference to the event data shape for external type queries.
+
 ### Implementation of
 
 [`EventEmitter`](#../interfaces/EventEmitter).[`eventData`](../interfaces/EventEmitter.md#eventdata)
@@ -1108,6 +1174,8 @@ Base.tracer
 get static isDebugEnabled(): boolean;
 ```
 
+Whether debug mode is enabled globally or via the DEBUG environment variable.
+
 #### Returns
 
 `boolean`
@@ -1138,6 +1206,8 @@ set static isDebugEnabled(newValue): void;
 get debug(): DebugOptions | undefined;
 ```
 
+The debug configuration for this instance, if provided.
+
 #### Returns
 
 [`DebugOptions`](#../type-aliases/DebugOptions) \| `undefined`
@@ -1276,10 +1346,14 @@ Base.stopHistory
 clearListeners(eventNames): void;
 ```
 
+Removes all listeners for the specified event name(s).
+
 ### Parameters
 
 #### eventNames
 
+One or more event names to clear listeners for.
+
 keyof `TEventData` | keyof `TEventData`[]
 
 ### Returns
@@ -1298,6 +1372,8 @@ keyof `TEventData` | keyof `TEventData`[]
 emit<TEventName>(eventName, eventArgs): Promise<void>;
 ```
 
+Emits an event, invoking all registered listeners concurrently.
+
 ### Type Parameters
 
 #### TEventName
@@ -1310,10 +1386,14 @@ emit<TEventName>(eventName, eventArgs): Promise<void>;
 
 `TEventName`
 
+The event to emit.
+
 #### eventArgs
 
 `TEventData`\[`TEventName`\]
 
+The data to pass to listeners.
+
 ### Returns
 
 `Promise`\<`void`\>
@@ -1330,6 +1410,8 @@ emit<TEventName>(eventName, eventArgs): Promise<void>;
 emitMetaEvent<TEventName>(eventName, eventArgs): Promise<boolean | undefined>;
 ```
 
+Emits an internal meta event (listenerAdded or listenerRemoved).
+
 ### Type Parameters
 
 #### TEventName
@@ -1342,14 +1424,20 @@ emitMetaEvent<TEventName>(eventName, eventArgs): Promise<boolean | undefined>;
 
 `TEventName`
 
+The meta event name.
+
 #### eventArgs
 
 [`MetaEventData`](#../type-aliases/MetaEventData)\<`TEventData`\>\[`TEventName`\]
 
+The meta event data containing listener and event information.
+
 ### Returns
 
 `Promise`\<`boolean` \| `undefined`\>
 
+True if the meta event was emitted successfully.
+
 ***
 
 ### emitSerial()
@@ -1358,6 +1446,8 @@ emitMetaEvent<TEventName>(eventName, eventArgs): Promise<boolean | undefined>;
 emitSerial<TEventName>(eventName, eventArgs): Promise<void>;
 ```
 
+Emits an event, invoking all registered listeners sequentially in order.
+
 ### Type Parameters
 
 #### TEventName
@@ -1370,10 +1460,14 @@ emitSerial<TEventName>(eventName, eventArgs): Promise<void>;
 
 `TEventName`
 
+The event to emit.
+
 #### eventArgs
 
 `TEventData`\[`TEventName`\]
 
+The data to pass to listeners.
+
 ### Returns
 
 `Promise`\<`void`\>
@@ -1390,16 +1484,22 @@ emitSerial<TEventName>(eventName, eventArgs): Promise<void>;
 listenerCount(eventNames?): number;
 ```
 
+Returns the total number of listeners registered for the specified event name(s).
+
 ### Parameters
 
 #### eventNames?
 
+One or more event names to count listeners for.
+
 keyof `TEventData` | keyof `TEventData`[]
 
 ### Returns
 
 `number`
 
+The total listener count.
+
 ### Implementation of
 
 [`EventEmitter`](#../interfaces/EventEmitter).[`listenerCount`](../interfaces/EventEmitter.md#listenercount)
@@ -1415,6 +1515,8 @@ logIfDebugEnabled<TEventName>(
    eventArgs?): void;
 ```
 
+Logs debug information if debug mode is enabled.
+
 ### Type Parameters
 
 #### TEventName
@@ -1427,14 +1529,20 @@ logIfDebugEnabled<TEventName>(
 
 `string`
 
+The type of operation being logged.
+
 #### eventName?
 
 `TEventName`
 
+The event name, if applicable.
+
 #### eventArgs?
 
 [`EventArgs`](#../type-aliases/EventArgs)
 
+The event data, if applicable.
+
 ### Returns
 
 `void`
@@ -1447,6 +1555,8 @@ logIfDebugEnabled<TEventName>(
 off<TEventName, TEventListener>(eventNames, listener): void;
 ```
 
+Removes a specific listener from the specified event name(s).
+
 ### Type Parameters
 
 #### TEventName
@@ -1461,12 +1571,16 @@ off<TEventName, TEventListener>(eventNames, listener): void;
 
 #### eventNames
 
+One or more event names to unsubscribe from.
+
 `TEventName` | `TEventName`[]
 
 #### listener
 
 `TEventListener`
 
+The listener to remove.
+
 ### Returns
 
 `void`
@@ -1483,12 +1597,16 @@ off<TEventName, TEventListener>(eventNames, listener): void;
 offAny(listener): void;
 ```
 
+Removes a wildcard listener that was receiving all events.
+
 ### Parameters
 
 #### listener
 
 [`EventAnyListener`](#../type-aliases/EventAnyListener)
 
+The wildcard listener to remove.
+
 ### Returns
 
 `void`
@@ -1508,6 +1626,8 @@ on<TEventName>(
    filter?): (...args) => void;
 ```
 
+Subscribes a listener to the specified event name(s).
+
 ### Type Parameters
 
 #### TEventName
@@ -1518,18 +1638,26 @@ on<TEventName>(
 
 #### eventNames
 
+One or more event names to listen for.
+
 `TEventName` | `TEventName`[]
 
 #### listener
 
 [`EventListener`](#../type-aliases/EventListener)\<`TEventData`\[`TEventName`\]\>
 
+The callback to invoke when the event fires.
+
 #### filter?
 
 `TEventData`\[`TEventName`\]
 
+Optional filter to selectively invoke the listener based on event data.
+
 ### Returns
 
+An unsubscribe function.
+
 ```ts
 (...args): void;
 ```
@@ -1556,14 +1684,20 @@ on<TEventName>(
 onAny(listener): (...args) => void;
 ```
 
+Subscribes a wildcard listener that receives all events.
+
 ### Parameters
 
 #### listener
 
 [`EventAnyListener`](#../type-aliases/EventAnyListener)
 
+The callback to invoke for any event.
+
 ### Returns
 
+An unsubscribe function.
+
 ```ts
 (...args): void;
 ```
@@ -1590,6 +1724,8 @@ onAny(listener): (...args) => void;
 once<TEventName>(eventName, listener): (...args) => void;
 ```
 
+Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
+
 ### Type Parameters
 
 #### TEventName
@@ -1602,12 +1738,18 @@ once<TEventName>(eventName, listener): (...args) => void;
 
 `TEventName`
 
+The event to listen for.
+
 #### listener
 
 [`EventListener`](#../type-aliases/EventListener)\<`TEventData`\[`TEventName`\]\>
 
+The callback to invoke once.
+
 ### Returns
 
+An unsubscribe function.
+
 ```ts
 (...args): void;
 ```
@@ -1634,12 +1776,16 @@ once<TEventName>(eventName, listener): (...args) => void;
 
 ***
 
+Fields specific to BaseEmitter configuration parameters.
+
   ### <a id="EventEmitter"></a>EventEmitter
 
 [**@xylabs/events**](#../README)
 
 ***
 
+Interface for a typed event emitter that supports subscribing, unsubscribing, and emitting events.
+
 ## Type Parameters
 
 ### T
@@ -1654,6 +1800,8 @@ once<TEventName>(eventName, listener): (...args) => void;
 eventData: T;
 ```
 
+Type-level reference to the event data shape for external type queries.
+
 ## Methods
 
 ### clearListeners()
@@ -1662,6 +1810,8 @@ eventData: T;
 clearListeners(eventNames): void;
 ```
 
+Removes all listeners for the specified event name(s).
+
 ### Parameters
 
 #### eventNames
@@ -1680,6 +1830,8 @@ keyof `T` | keyof `T`[]
 emit<TEventName>(eventName, eventArgs): Promise<void>;
 ```
 
+Emits an event, invoking all registered listeners concurrently.
+
 ### Type Parameters
 
 #### TEventName
@@ -1708,6 +1860,8 @@ emit<TEventName>(eventName, eventArgs): Promise<void>;
 emitSerial<TEventName>(eventName, eventArgs): Promise<void>;
 ```
 
+Emits an event, invoking all registered listeners sequentially in order.
+
 ### Type Parameters
 
 #### TEventName
@@ -1736,6 +1890,8 @@ emitSerial<TEventName>(eventName, eventArgs): Promise<void>;
 listenerCount(eventNames): number;
 ```
 
+Returns the total number of listeners registered for the specified event name(s).
+
 ### Parameters
 
 #### eventNames
@@ -1754,6 +1910,8 @@ keyof `T` | keyof `T`[]
 off<TEventName>(eventNames, listener): void;
 ```
 
+Removes a specific listener from the specified event name(s).
+
 ### Type Parameters
 
 #### TEventName
@@ -1782,6 +1940,8 @@ off<TEventName>(eventNames, listener): void;
 offAny(listener): void;
 ```
 
+Removes a wildcard listener that was receiving all events.
+
 ### Parameters
 
 #### listener
@@ -1800,6 +1960,8 @@ offAny(listener): void;
 on<TEventName>(eventNames, listener): EventUnsubscribeFunction;
 ```
 
+Subscribes a listener to the specified event name(s) and returns an unsubscribe function.
+
 ### Type Parameters
 
 #### TEventName
@@ -1828,6 +1990,8 @@ on<TEventName>(eventNames, listener): EventUnsubscribeFunction;
 onAny(listener): EventUnsubscribeFunction;
 ```
 
+Subscribes a wildcard listener that receives all events and returns an unsubscribe function.
+
 ### Parameters
 
 #### listener
@@ -1846,6 +2010,8 @@ onAny(listener): EventUnsubscribeFunction;
 once<TEventName>(eventName, listener): EventUnsubscribeFunction;
 ```
 
+Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
+
 ### Type Parameters
 
 #### TEventName
@@ -1878,6 +2044,8 @@ once<TEventName>(eventName, listener): EventUnsubscribeFunction;
 type BaseEmitterParams<T> = BaseParams<T & BaseEmitterParamsFields & T>;
 ```
 
+Parameters type for configuring a BaseEmitter instance.
+
 ## Type Parameters
 
 ### T
@@ -1969,6 +2137,8 @@ readonly name: string;
 type EventAnyListener<TEventArgs> = (eventName, eventData) => Promisable<void>;
 ```
 
+A listener that receives all events regardless of name.
+
 ## Type Parameters
 
 ### TEventArgs
@@ -1981,10 +2151,14 @@ type EventAnyListener<TEventArgs> = (eventName, eventData) => Promisable<void>;
 
 [`EventName`](#EventName)
 
+The name of the emitted event.
+
 ### eventData
 
 `TEventArgs`
 
+The data associated with the event.
+
 ## Returns
 
 `Promisable`\<`void`\>
@@ -1999,6 +2173,8 @@ type EventAnyListener<TEventArgs> = (eventName, eventData) => Promisable<void>;
 type EventArgs = string | number | object;
 ```
 
+The allowed types for event argument payloads.
+
   ### <a id="EventData"></a>EventData
 
 [**@xylabs/events**](#../README)
@@ -2009,6 +2185,8 @@ type EventArgs = string | number | object;
 type EventData = object;
 ```
 
+A mapping of event names to their corresponding event argument types.
+
 ## Index Signature
 
 ```ts
@@ -2025,6 +2203,8 @@ type EventData = object;
 type EventListener<TEventArgs> = (eventData) => Promisable<void>;
 ```
 
+A listener for a specific event type.
+
 ## Type Parameters
 
 ### TEventArgs
@@ -2037,6 +2217,8 @@ type EventListener<TEventArgs> = (eventData) => Promisable<void>;
 
 `TEventArgs`
 
+The data associated with the event.
+
 ## Returns
 
 `Promisable`\<`void`\>
@@ -2051,6 +2233,8 @@ type EventListener<TEventArgs> = (eventData) => Promisable<void>;
 type EventListenerInfo<TEventArgs> = object;
 ```
 
+Information about a registered event listener, including an optional filter for selective invocation.
+
 ## Type Parameters
 
 ### TEventArgs
@@ -2083,6 +2267,8 @@ listener: EventListener<TEventArgs>;
 type EventName = PropertyKey;
 ```
 
+A valid event name, which can be any property key (string, number, or symbol).
+
   ### <a id="EventUnsubscribeFunction"></a>EventUnsubscribeFunction
 
 [**@xylabs/events**](#../README)
@@ -2093,6 +2279,8 @@ type EventName = PropertyKey;
 type EventUnsubscribeFunction = () => void;
 ```
 
+A function returned by event subscription methods that unsubscribes the listener when called.
+
 ## Returns
 
 `void`
@@ -2109,6 +2297,8 @@ type EventsParams = BaseParams<{
 }>;
 ```
 
+Parameters for constructing an Events instance, with optional debug configuration.
+
   ### <a id="MetaEventData"></a>MetaEventData
 
 [**@xylabs/events**](#../README)
@@ -2119,6 +2309,8 @@ type EventsParams = BaseParams<{
 type MetaEventData<TEventData> = object;
 ```
 
+Data shape for internal meta events that fire when listeners are added or removed.
+
 ## Type Parameters
 
 ### TEventData