@xylabs/events
Advanced tools
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
Using npm:
npm install {{name}}
Using yarn:
yarn add {{name}}
Using pnpm:
pnpm add {{name}}
Using bun:
bun add {{name}}
See the LICENSE file for license rights and limitations (LGPL-3.0-only).
### .temp-typedoc
### classes
### <a id="BaseEmitter"></a>BaseEmitter
Base class that combines the Base utility class with typed event emission capabilities. Delegates all event operations to an internal Events instance.
Base<TParams>TParams extends BaseParams = BaseParams
TEventData extends EventData = EventData
EventEmitter<TEventData>new BaseEmitter<TParams, TEventData>(params): BaseEmitter<TParams, TEventData>;
BaseParams<TParams>
BaseEmitter<TParams, TEventData>
Base<TParams>.constructor
static optional defaultLogger?: Logger;
Base.defaultLogger
readonly static globalInstances: Record<BaseClassName, WeakRef<Base>[]>;
Base.globalInstances
readonly static globalInstancesCountHistory: Record<BaseClassName, number[]>;
Base.globalInstancesCountHistory
eventData: TEventData;
Type-level reference to the event data shape for external type queries.
get static historyInterval(): number;
number
set static historyInterval(value): void;
number
void
Base.historyInterval
get static historyTime(): number;
number
set static historyTime(value): void;
number
void
Base.historyTime
get static maxGcFrequency(): number;
number
set static maxGcFrequency(value): void;
number
void
Base.maxGcFrequency
get static maxHistoryDepth(): number;
number
Base.maxHistoryDepth
get logger(): Logger | undefined;
Logger | undefined
Base.logger
get meter(): Meter | undefined;
Meter | undefined
Base.meter
get params(): BaseParams<TParams>;
BaseParams<TParams>
Base.params
get tracer(): Tracer | undefined;
Tracer | undefined
Base.tracer
static gc(force?): void;
boolean
void
Base.gc
static gc(className): void;
BaseClassName
void
Base.gc
static instanceCount(className): number;
BaseClassName
number
Base.instanceCount
static instanceCounts(): Record<BaseClassName, number>;
Record<BaseClassName, number>
Base.instanceCounts
static startHistory(): void;
void
Base.startHistory
static stopHistory(): void;
void
Base.stopHistory
clearListeners(eventNames): BaseEmitter<TParams, TEventData>;
Removes all listeners for the specified event name(s).
keyof TEventData | keyof TEventData[]
One or more event names to clear listeners for.
BaseEmitter<TParams, TEventData>
This instance for chaining.
emit<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners concurrently.
TEventName extends string | number | symbol = keyof TEventData
TEventArgs extends EventArgs = TEventData[TEventName]
TEventName
The event to emit.
TEventArgs
The data to pass to listeners.
Promise<void>
emitSerial<TEventName, TEventArgs>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners sequentially in order.
TEventName extends string | number | symbol = keyof TEventData
TEventArgs extends EventArgs = TEventData[TEventName]
TEventName
The event to emit.
TEventArgs
The data to pass to listeners.
Promise<void>
listenerCount(eventNames): number;
Returns the total number of listeners registered for the specified event name(s).
keyof TEventData | keyof TEventData[]
One or more event names to count listeners for.
number
The total listener count.
off<TEventName>(eventNames, listener): void;
Removes a specific listener from the specified event name(s).
TEventName extends string | number | symbol
TEventName | TEventName[]
One or more event names to unsubscribe from.
EventListener<TEventData[TEventName]>
The listener to remove.
void
offAny(listener): void;
Removes a wildcard listener that was receiving all events.
The wildcard listener to remove.
void
on<TEventName>(eventNames, listener): (...args) => void;
Subscribes a listener to the specified event name(s).
TEventName extends string | number | symbol
TEventName | TEventName[]
One or more event names to listen for.
EventListener<TEventData[TEventName]>
The callback to invoke when the event fires.
An unsubscribe function.
(...args) => void
onAny(listener): (...args) => void;
Subscribes a wildcard listener that receives all events.
The callback to invoke for any event.
An unsubscribe function.
(...args) => void
once<TEventName>(eventName, listener): (...args) => void;
Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
TEventName extends string | number | symbol
TEventName
The event to listen for.
EventListener<TEventData[TEventName]>
The callback to invoke once.
An unsubscribe function.
(...args) => void
### <a id="Events"></a>Events
Core typed event emitter implementation supporting named events, wildcard listeners, serial and concurrent emission, listener filtering, and debug logging.
Base<EventsParams>TEventData extends EventData = EventData
EventEmitter<TEventData>new Events<TEventData>(params?): Events<TEventData>;
EventsParams = {}
Events<TEventData>
Base<EventsParams>.constructor
static optional defaultLogger?: Logger;
Base.defaultLogger
readonly static globalInstances: Record<BaseClassName, WeakRef<Base>[]>;
Base.globalInstances
readonly static globalInstancesCountHistory: Record<BaseClassName, number[]>;
Base.globalInstancesCountHistory
protected static anyMap: WeakMap<object, Set<EventAnyListener>>;
protected static eventsMap: WeakMap<object, Map<PropertyKey, Set<EventListenerInfo<EventArgs>>>>;
eventData: TEventData;
Type-level reference to the event data shape for external type queries.
get static historyInterval(): number;
number
set static historyInterval(value): void;
number
void
Base.historyInterval
get static historyTime(): number;
number
set static historyTime(value): void;
number
void
Base.historyTime
get static maxGcFrequency(): number;
number
set static maxGcFrequency(value): void;
number
void
Base.maxGcFrequency
get static maxHistoryDepth(): number;
number
Base.maxHistoryDepth
get logger(): Logger | undefined;
Logger | undefined
Base.logger
get meter(): Meter | undefined;
Meter | undefined
Base.meter
get params(): BaseParams<TParams>;
BaseParams<TParams>
Base.params
get tracer(): Tracer | undefined;
Tracer | undefined
Base.tracer
get static isDebugEnabled(): boolean;
Whether debug mode is enabled globally or via the DEBUG environment variable.
boolean
set static isDebugEnabled(newValue): void;
boolean
void
get debug(): DebugOptions | undefined;
The debug configuration for this instance, if provided.
DebugOptions | undefined
static gc(force?): void;
boolean
void
Base.gc
static gc(className): void;
BaseClassName
void
Base.gc
static instanceCount(className): number;
BaseClassName
number
Base.instanceCount
static instanceCounts(): Record<BaseClassName, number>;
Record<BaseClassName, number>
Base.instanceCounts
static startHistory(): void;
void
Base.startHistory
static stopHistory(): void;
void
Base.stopHistory
clearListeners(eventNames): void;
Removes all listeners for the specified event name(s).
keyof TEventData | keyof TEventData[]
One or more event names to clear listeners for.
void
emit<TEventName>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners concurrently.
TEventName extends string | number | symbol
TEventName
The event to emit.
TEventData[TEventName]
The data to pass to listeners.
Promise<void>
emitMetaEvent<TEventName>(eventName, eventArgs): Promise<boolean | undefined>;
Emits an internal meta event (listenerAdded or listenerRemoved).
TEventName extends keyof MetaEventData<TEventData>
TEventName
The meta event name.
MetaEventData<TEventData>[TEventName]
The meta event data containing listener and event information.
Promise<boolean | undefined>
True if the meta event was emitted successfully.
emitSerial<TEventName>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners sequentially in order.
TEventName extends string | number | symbol
TEventName
The event to emit.
TEventData[TEventName]
The data to pass to listeners.
Promise<void>
listenerCount(eventNames?): number;
Returns the total number of listeners registered for the specified event name(s).
keyof TEventData | keyof TEventData[]
One or more event names to count listeners for.
number
The total listener count.
logIfDebugEnabled<TEventName>(
type,
eventName?,
eventArgs?): void;
Logs debug information if debug mode is enabled.
TEventName extends PropertyKey
string
The type of operation being logged.
TEventName
The event name, if applicable.
The event data, if applicable.
void
off<TEventName, TEventListener>(eventNames, listener): void;
Removes a specific listener from the specified event name(s).
TEventName extends string | number | symbol
TEventListener = EventListener<TEventData[TEventName]>
TEventName | TEventName[]
One or more event names to unsubscribe from.
TEventListener
The listener to remove.
void
offAny(listener): void;
Removes a wildcard listener that was receiving all events.
The wildcard listener to remove.
void
on<TEventName>(
eventNames,
listener,
filter?): (...args) => void;
Subscribes a listener to the specified event name(s).
TEventName extends string | number | symbol = keyof TEventData
TEventName | TEventName[]
One or more event names to listen for.
EventListener<TEventData[TEventName]>
The callback to invoke when the event fires.
TEventData[TEventName]
Optional filter to selectively invoke the listener based on event data.
An unsubscribe function.
(...args) => void
onAny(listener): (...args) => void;
Subscribes a wildcard listener that receives all events.
The callback to invoke for any event.
An unsubscribe function.
(...args) => void
once<TEventName>(eventName, listener): (...args) => void;
Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
TEventName extends string | number | symbol
TEventName
The event to listen for.
EventListener<TEventData[TEventName]>
The callback to invoke once.
An unsubscribe function.
(...args) => void
### interfaces
### <a id="BaseEmitterParamsFields"></a>BaseEmitterParamsFields
Fields specific to BaseEmitter configuration parameters.
### <a id="DebugOptions"></a>DebugOptions
Configure debug options of an instance.
optional enabled?: boolean;
optional logger?: DebugLogger;
readonly name: string;
### <a id="EventEmitter"></a>EventEmitter
Interface for a typed event emitter that supports subscribing, unsubscribing, and emitting events.
T extends EventData
eventData: T;
Type-level reference to the event data shape for external type queries.
clearListeners(eventNames): void;
Removes all listeners for the specified event name(s).
keyof T | keyof T[]
void
emit<TEventName>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners concurrently.
TEventName extends string | number | symbol
TEventName
T[TEventName]
Promise<void>
emitSerial<TEventName>(eventName, eventArgs): Promise<void>;
Emits an event, invoking all registered listeners sequentially in order.
TEventName extends string | number | symbol
TEventName
T[TEventName]
Promise<void>
listenerCount(eventNames): number;
Returns the total number of listeners registered for the specified event name(s).
keyof T | keyof T[]
number
off<TEventName>(eventNames, listener): void;
Removes a specific listener from the specified event name(s).
TEventName extends string | number | symbol
TEventName | TEventName[]
EventListener<T[TEventName]>
void
offAny(listener): void;
Removes a wildcard listener that was receiving all events.
| Promise<void>
| EventAnyListener
void
on<TEventName>(eventNames, listener): EventUnsubscribeFunction;
Subscribes a listener to the specified event name(s) and returns an unsubscribe function.
TEventName extends string | number | symbol
TEventName | TEventName[]
EventListener<T[TEventName]>
onAny(listener): EventUnsubscribeFunction;
Subscribes a wildcard listener that receives all events and returns an unsubscribe function.
once<TEventName>(eventName, listener): EventUnsubscribeFunction;
Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
TEventName extends string | number | symbol
TEventName
EventListener<T[TEventName]>
### <a id="EventListenerInfo"></a>EventListenerInfo
Information about a registered event listener, including an optional filter for selective invocation.
TEventArgs extends EventArgs = EventArgs
optional filter?: TEventArgs;
listener: EventListener<TEventArgs>;
### <a id="MetaEventData"></a>MetaEventData
Data shape for internal meta events that fire when listeners are added or removed.
TEventData extends EventData
listenerAdded: object;
optional eventName?: keyof TEventData;
listener:
| EventListener<TEventData[keyof TEventData]>
| EventAnyListener<TEventData[keyof TEventData]>;
listenerRemoved: object;
optional eventName?: keyof TEventData;
listener:
| EventListener<TEventData[keyof TEventData]>
| EventAnyListener<TEventData[keyof TEventData]>;
### type-aliases
### <a id="BaseEmitterParams"></a>BaseEmitterParams
type BaseEmitterParams<T> = BaseParams<T & BaseEmitterParamsFields & T>;
Parameters type for configuring a BaseEmitter instance.
T extends EmptyObject = EmptyObject
### <a id="DebugLogger"></a>DebugLogger
type DebugLogger = (type, debugName, eventName?, eventData?) => void;
Emittery can collect and log debug information.
To enable this feature set the DEBUG environment variable to emittery or *. Additionally, you can set the static isDebugEnabled variable to true
on the Emittery class, or myEmitter.debug.enabled on an instance of it for debugging a single instance.
See API for more information on how debugging works.
string
string
void
### <a id="EventAnyListener"></a>EventAnyListener
type EventAnyListener<TEventArgs> = (eventName, eventData) => Promisable<void>;
A listener that receives all events regardless of name.
TEventArgs extends EventArgs = EventArgs
The name of the emitted event.
TEventArgs
The data associated with the event.
Promisable<void>
### <a id="EventArgs"></a>EventArgs
type EventArgs = string | number | object;
The allowed types for event argument payloads.
### <a id="EventData"></a>EventData
type EventData = Record<EventName, EventArgs>;
A mapping of event names to their corresponding event argument types.
### <a id="EventListener"></a>EventListener
type EventListener<TEventArgs> = (eventData) => Promisable<void>;
A listener for a specific event type.
TEventArgs extends EventArgs = EventArgs
TEventArgs
The data associated with the event.
Promisable<void>
### <a id="EventName"></a>EventName
type EventName = PropertyKey;
A valid event name, which can be any property key (string, number, or symbol).
### <a id="EventUnsubscribeFunction"></a>EventUnsubscribeFunction
type EventUnsubscribeFunction = () => void;
A function returned by event subscription methods that unsubscribes the listener when called.
void
### <a id="EventsParams"></a>EventsParams
type EventsParams = BaseParams<{
debug?: DebugOptions;
}>;
Parameters for constructing an Events instance, with optional debug configuration.
FAQs
Base functionality used throughout XY Labs TypeScript/JavaScript libraries
The npm package @xylabs/events receives a total of 3,460 weekly downloads. As such, @xylabs/events popularity was classified as popular.
We found that @xylabs/events demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Docker and Socket have uncovered malicious Checkmarx KICS images and suspicious code extension releases in a broader supply chain compromise.
Research
Malicious Namastex.ai npm packages appear to replicate TeamPCP-style Canister Worm tradecraft, including exfiltration and self-propagation.
Product
Explore exportable charts for vulnerabilities, dependencies, and usage with Reports, Socket’s new extensible reporting framework.