@xylabs/events

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

Reference

@xylabs/events

Classes

| Class | Description | | ------ | ------ | | BaseEmitter | Base class that combines the Base utility class with typed event emission capabilities. Delegates all event operations to an internal Events instance. | | Events | Core typed event emitter implementation supporting named events, wildcard listeners, serial and concurrent emission, listener filtering, and debug logging. |

Interfaces

| Interface | Description | | ------ | ------ | | BaseEmitterParamsFields | Fields specific to BaseEmitter configuration parameters. | | EventEmitter | Interface for a typed event emitter that supports subscribing, unsubscribing, and emitting events. |

Type Aliases

| Type Alias | Description | | ------ | ------ | | BaseEmitterParams | Parameters type for configuring a BaseEmitter instance. | | DebugLogger | Emittery can collect and log debug information. | | EventListenerInfo | Information about a registered event listener, including an optional filter for selective invocation. | | DebugOptions | Configure debug options of an instance. | | MetaEventData | Data shape for internal meta events that fire when listeners are added or removed. | | EventsParams | Parameters for constructing an Events instance, with optional debug configuration. | | EventName | A valid event name, which can be any property key (string, number, or symbol). | | EventArgs | The allowed types for event argument payloads. | | EventData | A mapping of event names to their corresponding event argument types. | | EventUnsubscribeFunction | A function returned by event subscription methods that unsubscribes the listener when called. | | EventAnyListener | A listener that receives all events regardless of name. | | EventListener | A listener for a specific event type. |

classes

BaseEmitter

@xylabs/events

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>

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TParams extends BaseParams | BaseParams | | TEventData extends EventData | EventData |

Implements

• EventEmitter<TEventData>

Constructors

Constructor

new BaseEmitter<TParams, TEventData>(params: BaseParams<TParams>): BaseEmitter<TParams, TEventData>;

Parameters

| Parameter | Type | | ------ | ------ | | params | BaseParams<TParams> |

Returns

BaseEmitter<TParams, TEventData>

Overrides

Base<TParams>.constructor

Properties

| Property | Modifier | Type | Description | Inherited from | | ------ | ------ | ------ | ------ | ------ | | defaultLogger? | static | Logger | - | Base.defaultLogger | | globalInstances | readonly | Record<BaseClassName, WeakRef<Base>[]> | - | Base.globalInstances | | globalInstancesCountHistory | readonly | Record<BaseClassName, number[]> | - | Base.globalInstancesCountHistory | | eventData | public | TEventData | Type-level reference to the event data shape for external type queries. | - |

Accessors

historyInterval

Get Signature

get static historyInterval(): number;

Returns

number

Set Signature

set static historyInterval(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

Base.historyInterval

historyTime

Get Signature

get static historyTime(): number;

Returns

number

Set Signature

set static historyTime(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

Base.historyTime

maxGcFrequency

Get Signature

get static maxGcFrequency(): number;

Returns

number

Set Signature

set static maxGcFrequency(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

Base.maxGcFrequency

maxHistoryDepth

Get Signature

get static maxHistoryDepth(): number;

Returns

number

Inherited from

Base.maxHistoryDepth

logger

Get Signature

get logger(): Logger | undefined;

Returns

Logger | undefined

Inherited from

Base.logger

meter

Get Signature

get meter(): Meter | undefined;

Returns

Meter | undefined

Inherited from

Base.meter

params

Get Signature

get params(): BaseParams<TParams>;

Returns

BaseParams<TParams>

Inherited from

Base.params

tracer

Get Signature

get tracer(): Tracer | undefined;

Returns

Tracer | undefined

Inherited from

Base.tracer

Methods

gc()

Call Signature

static gc(force?: boolean): void;

Parameters

| Parameter | Type | | ------ | ------ | | force? | boolean |

Returns

void

Inherited from

Base.gc

Call Signature

static gc(className: BaseClassName): void;

Parameters

| Parameter | Type | | ------ | ------ | | className | BaseClassName |

Returns

void

Inherited from

Base.gc

instanceCount()

static instanceCount(className: BaseClassName): number;

Parameters

| Parameter | Type | | ------ | ------ | | className | BaseClassName |

Returns

number

Inherited from

Base.instanceCount

instanceCounts()

static instanceCounts(): Record<BaseClassName, number>;

Returns

Record<BaseClassName, number>

Inherited from

Base.instanceCounts

startHistory()

static startHistory(): void;

Returns

void

Inherited from

Base.startHistory

stopHistory()

static stopHistory(): void;

Returns

void

Inherited from

Base.stopHistory

clearListeners()

clearListeners(eventNames: keyof TEventData | keyof TEventData[]): BaseEmitter<TParams, TEventData>;

Removes all listeners for the specified event name(s).

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | keyof TEventData | keyof TEventData[] | One or more event names to clear listeners for. |

Returns

BaseEmitter<TParams, TEventData>

This instance for chaining.

Implementation of

EventEmitter.clearListeners

emit()

emit<TEventName, TEventArgs>(eventName: TEventName, eventArgs: TEventArgs): Promise<void>;

Emits an event, invoking all registered listeners concurrently.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TEventName extends string | number | symbol | keyof TEventData | | TEventArgs extends EventArgs | TEventData[TEventName] |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to emit. | | eventArgs | TEventArgs | The data to pass to listeners. |

Returns

Promise<void>

Implementation of

EventEmitter.emit

emitSerial()

emitSerial<TEventName, TEventArgs>(eventName: TEventName, eventArgs: TEventArgs): Promise<void>;

Emits an event, invoking all registered listeners sequentially in order.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TEventName extends string | number | symbol | keyof TEventData | | TEventArgs extends EventArgs | TEventData[TEventName] |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to emit. | | eventArgs | TEventArgs | The data to pass to listeners. |

Returns

Promise<void>

Implementation of

EventEmitter.emitSerial

listenerCount()

listenerCount(eventNames: keyof TEventData | keyof TEventData[]): number;

Returns the total number of listeners registered for the specified event name(s).

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | keyof TEventData | keyof TEventData[] | One or more event names to count listeners for. |

Returns

number

The total listener count.

Implementation of

EventEmitter.listenerCount

off()

off<TEventName>(eventNames: TEventName | TEventName[], listener: EventListener<TEventData[TEventName]>): void;

Removes a specific listener from the specified event name(s).

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | TEventName | TEventName[] | One or more event names to unsubscribe from. | | listener | EventListener<TEventData[TEventName]> | The listener to remove. |

Returns

void

Implementation of

EventEmitter.off

offAny()

offAny(listener: EventAnyListener): void;

Removes a wildcard listener that was receiving all events.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | listener | EventAnyListener | The wildcard listener to remove. |

Returns

void

Implementation of

EventEmitter.offAny

on()

on<TEventName>(eventNames: TEventName | TEventName[], listener: EventListener<TEventData[TEventName]>): (...args: []) => void;

Subscribes a listener to the specified event name(s).

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | TEventName | TEventName[] | One or more event names to listen for. | | listener | EventListener<TEventData[TEventName]> | The callback to invoke when the event fires. |

Returns

An unsubscribe function.

(...args: []): void;

Parameters

| Parameter | Type | | ------ | ------ | | ...args | [] |

Returns

void

Implementation of

EventEmitter.on

onAny()

onAny(listener: EventAnyListener): (...args: []) => void;

Subscribes a wildcard listener that receives all events.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | listener | EventAnyListener | The callback to invoke for any event. |

Returns

An unsubscribe function.

(...args: []): void;

Parameters

| Parameter | Type | | ------ | ------ | | ...args | [] |

Returns

void

Implementation of

EventEmitter.onAny

once()

once<TEventName>(eventName: TEventName, listener: EventListener<TEventData[TEventName]>): (...args: []) => void;

Subscribes a listener that will be invoked only once for the specified event, then automatically removed.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to listen for. | | listener | EventListener<TEventData[TEventName]> | The callback to invoke once. |

Returns

An unsubscribe function.

(...args: []): void;

Parameters

| Parameter | Type | | ------ | ------ | | ...args | [] |

Returns

void

Implementation of

EventEmitter.once

Events

@xylabs/events

Core typed event emitter implementation supporting named events, wildcard listeners, serial and concurrent emission, listener filtering, and debug logging.

Extends

• Base<EventsParams>

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TEventData extends EventData | EventData |

Implements

• EventEmitter<TEventData>

Constructors

Constructor

new Events<TEventData>(params?: EventsParams): Events<TEventData>;

Parameters

| Parameter | Type | | ------ | ------ | | params | EventsParams |

Returns

Events<TEventData>

Overrides

Base<EventsParams>.constructor

Properties

| Property | Modifier | Type | Description | Inherited from | | ------ | ------ | ------ | ------ | ------ | | defaultLogger? | static | Logger | - | Base.defaultLogger | | globalInstances | readonly | Record<BaseClassName, WeakRef<Base>[]> | - | Base.globalInstances | | globalInstancesCountHistory | readonly | Record<BaseClassName, number[]> | - | Base.globalInstancesCountHistory | | anyMap | static | WeakMap<object, Set<EventAnyListener>> | - | - | | eventsMap | static | WeakMap<object, Map<PropertyKey, Set<EventListenerInfo<EventArgs>>>> | - | - | | eventData | public | TEventData | Type-level reference to the event data shape for external type queries. | - |

Accessors

historyInterval

Get Signature

get static historyInterval(): number;

Returns

number

Set Signature

set static historyInterval(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

Base.historyInterval

historyTime

Get Signature

get static historyTime(): number;

Returns

number

Set Signature

set static historyTime(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

Base.historyTime

maxGcFrequency

Get Signature

get static maxGcFrequency(): number;

Returns

number

Set Signature

set static maxGcFrequency(value: number): void;

Parameters

| Parameter | Type | | ------ | ------ | | value | number |

Returns

void

Inherited from

Base.maxGcFrequency

maxHistoryDepth

Get Signature

get static maxHistoryDepth(): number;

Returns

number

Inherited from

Base.maxHistoryDepth

logger

Get Signature

get logger(): Logger | undefined;

Returns

Logger | undefined

Inherited from

Base.logger

meter

Get Signature

get meter(): Meter | undefined;

Returns

Meter | undefined

Inherited from

Base.meter

params

Get Signature

get params(): BaseParams<TParams>;

Returns

BaseParams<TParams>

Inherited from

Base.params

tracer

Get Signature

get tracer(): Tracer | undefined;

Returns

Tracer | undefined

Inherited from

Base.tracer

isDebugEnabled

Get Signature

get static isDebugEnabled(): boolean;

Whether debug mode is enabled globally or via the DEBUG environment variable.

Returns

boolean

Set Signature

set static isDebugEnabled(newValue: boolean): void;

Parameters

| Parameter | Type | | ------ | ------ | | newValue | boolean |

Returns

void

debug

Get Signature

get debug(): DebugOptions | undefined;

The debug configuration for this instance, if provided.

Returns

DebugOptions | undefined

Methods

gc()

Call Signature

static gc(force?: boolean): void;

Parameters

| Parameter | Type | | ------ | ------ | | force? | boolean |

Returns

void

Inherited from

Base.gc

Call Signature

static gc(className: BaseClassName): void;

Parameters

| Parameter | Type | | ------ | ------ | | className | BaseClassName |

Returns

void

Inherited from

Base.gc

instanceCount()

static instanceCount(className: BaseClassName): number;

Parameters

| Parameter | Type | | ------ | ------ | | className | BaseClassName |

Returns

number

Inherited from

Base.instanceCount

instanceCounts()

static instanceCounts(): Record<BaseClassName, number>;

Returns

Record<BaseClassName, number>

Inherited from

Base.instanceCounts

startHistory()

static startHistory(): void;

Returns

void

Inherited from

Base.startHistory

stopHistory()

static stopHistory(): void;

Returns

void

Inherited from

Base.stopHistory

clearListeners()

clearListeners(eventNames: keyof TEventData | keyof TEventData[]): void;

Removes all listeners for the specified event name(s).

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | keyof TEventData | keyof TEventData[] | One or more event names to clear listeners for. |

Returns

void

Implementation of

EventEmitter.clearListeners

emit()

emit<TEventName>(eventName: TEventName, eventArgs: TEventData[TEventName]): Promise<void>;

Emits an event, invoking all registered listeners concurrently.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to emit. | | eventArgs | TEventData[TEventName] | The data to pass to listeners. |

Returns

Promise<void>

Implementation of

EventEmitter.emit

emitMetaEvent()

emitMetaEvent<TEventName>(eventName: TEventName, eventArgs: MetaEventData<TEventData>[TEventName]): Promise<boolean | undefined>;

Emits an internal meta event (listenerAdded or listenerRemoved).

Type Parameters

| Type Parameter | | ------ | | TEventName extends keyof MetaEventData<TEventData> |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The meta event name. | | eventArgs | 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()

emitSerial<TEventName>(eventName: TEventName, eventArgs: TEventData[TEventName]): Promise<void>;

Emits an event, invoking all registered listeners sequentially in order.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to emit. | | eventArgs | TEventData[TEventName] | The data to pass to listeners. |

Returns

Promise<void>

Implementation of

EventEmitter.emitSerial

listenerCount()

listenerCount(eventNames?: keyof TEventData | keyof TEventData[]): number;

Returns the total number of listeners registered for the specified event name(s).

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames? | keyof TEventData | keyof TEventData[] | One or more event names to count listeners for. |

Returns

number

The total listener count.

Implementation of

EventEmitter.listenerCount

logIfDebugEnabled()

logIfDebugEnabled<TEventName>(
   type: string, 
   eventName?: TEventName, 
   eventArgs?: EventArgs): void;

Logs debug information if debug mode is enabled.

Type Parameters

| Type Parameter | | ------ | | TEventName extends PropertyKey |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | type | string | The type of operation being logged. | | eventName? | TEventName | The event name, if applicable. | | eventArgs? | EventArgs | The event data, if applicable. |

Returns

void

off()

off<TEventName, TEventListener>(eventNames: TEventName | TEventName[], listener: TEventListener): void;

Removes a specific listener from the specified event name(s).

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TEventName extends string | number | symbol | - | | TEventListener | EventListener<TEventData[TEventName]> |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | TEventName | TEventName[] | One or more event names to unsubscribe from. | | listener | TEventListener | The listener to remove. |

Returns

void

Implementation of

EventEmitter.off

offAny()

offAny(listener: EventAnyListener): void;

Removes a wildcard listener that was receiving all events.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | listener | EventAnyListener | The wildcard listener to remove. |

Returns

void

Implementation of

EventEmitter.offAny

on()

on<TEventName>(
   eventNames: TEventName | TEventName[], 
   listener: EventListener<TEventData[TEventName]>, 
   filter?: TEventData[TEventName]): (...args: []) => void;

Subscribes a listener to the specified event name(s).

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TEventName extends string | number | symbol | keyof TEventData |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventNames | TEventName | TEventName[] | One or more event names to listen for. | | listener | 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.

(...args: []): void;

Parameters

| Parameter | Type | | ------ | ------ | | ...args | [] |

Returns

void

Implementation of

EventEmitter.on

onAny()

onAny(listener: EventAnyListener): (...args: []) => void;

Subscribes a wildcard listener that receives all events.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | listener | EventAnyListener | The callback to invoke for any event. |

Returns

An unsubscribe function.

(...args: []): void;

Parameters

| Parameter | Type | | ------ | ------ | | ...args | [] |

Returns

void

Implementation of

EventEmitter.onAny

once()

once<TEventName>(eventName: TEventName, listener: EventListener<TEventData[TEventName]>): (...args: []) => void;

Subscribes a listener that will be invoked only once for the specified event, then automatically removed.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | TEventName | The event to listen for. | | listener | EventListener<TEventData[TEventName]> | The callback to invoke once. |

Returns

An unsubscribe function.

(...args: []): void;

Parameters

| Parameter | Type | | ------ | ------ | | ...args | [] |

Returns

void

Implementation of

EventEmitter.once

interfaces

BaseEmitterParamsFields

@xylabs/events

Fields specific to BaseEmitter configuration parameters.

EventEmitter

@xylabs/events

Interface for a typed event emitter that supports subscribing, unsubscribing, and emitting events.

Type Parameters

| Type Parameter | | ------ | | T extends EventData |

Properties

| Property | Type | Description | | ------ | ------ | ------ | | eventData | T | Type-level reference to the event data shape for external type queries. |

Methods

clearListeners()

clearListeners(eventNames: keyof T | keyof T[]): void;

Removes all listeners for the specified event name(s).

Parameters

| Parameter | Type | | ------ | ------ | | eventNames | keyof T | keyof T[] |

Returns

void

emit()

emit<TEventName>(eventName: TEventName, eventArgs: T[TEventName]): Promise<void>;

Emits an event, invoking all registered listeners concurrently.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | | ------ | ------ | | eventName | TEventName | | eventArgs | T[TEventName] |

Returns

Promise<void>

emitSerial()

emitSerial<TEventName>(eventName: TEventName, eventArgs: T[TEventName]): Promise<void>;

Emits an event, invoking all registered listeners sequentially in order.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | | ------ | ------ | | eventName | TEventName | | eventArgs | T[TEventName] |

Returns

Promise<void>

listenerCount()

listenerCount(eventNames: keyof T | keyof T[]): number;

Returns the total number of listeners registered for the specified event name(s).

Parameters

| Parameter | Type | | ------ | ------ | | eventNames | keyof T | keyof T[] |

Returns

number

off()

off<TEventName>(eventNames: TEventName | TEventName[], listener: EventListener<T[TEventName]>): void;

Removes a specific listener from the specified event name(s).

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | | ------ | ------ | | eventNames | TEventName | TEventName[] | | listener | EventListener<T[TEventName]> |

Returns

void

offAny()

offAny(listener: 
  | Promise<void>
  | EventAnyListener): void;

Removes a wildcard listener that was receiving all events.

Parameters

| Parameter | Type | | ------ | ------ | | listener | | Promise<void> | EventAnyListener |

Returns

void

on()

on<TEventName>(eventNames: TEventName | TEventName[], listener: EventListener<T[TEventName]>): EventUnsubscribeFunction;

Subscribes a listener to the specified event name(s) and returns an unsubscribe function.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | | ------ | ------ | | eventNames | TEventName | TEventName[] | | listener | EventListener<T[TEventName]> |

Returns

EventUnsubscribeFunction

onAny()

onAny(listener: EventAnyListener): EventUnsubscribeFunction;

Subscribes a wildcard listener that receives all events and returns an unsubscribe function.

Parameters

| Parameter | Type | | ------ | ------ | | listener | EventAnyListener |

Returns

EventUnsubscribeFunction

once()

once<TEventName>(eventName: TEventName, listener: EventListener<T[TEventName]>): EventUnsubscribeFunction;

Subscribes a listener that will be invoked only once for the specified event, then automatically removed.

Type Parameters

| Type Parameter | | ------ | | TEventName extends string | number | symbol |

Parameters

| Parameter | Type | | ------ | ------ | | eventName | TEventName | | listener | EventListener<T[TEventName]> |

Returns

EventUnsubscribeFunction

type-aliases

BaseEmitterParams

@xylabs/events

type BaseEmitterParams<T> = BaseParams<T & BaseEmitterParamsFields & T>;

Parameters type for configuring a BaseEmitter instance.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | T extends EmptyObject | EmptyObject |

DebugLogger

@xylabs/events

type DebugLogger = (type: string, debugName: string, eventName?: EventName, eventData?: EventArgs) => 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.

Parameters

| Parameter | Type | | ------ | ------ | | type | string | | debugName | string | | eventName? | EventName | | eventData? | EventArgs |

Returns

void

DebugOptions

@xylabs/events

type DebugOptions = {
  enabled?: boolean;
  logger?: DebugLogger;
  name: string;
};

Configure debug options of an instance.

Properties

| Property | Modifier | Type | | ------ | ------ | ------ | | enabled? | public | boolean | | logger? | public | DebugLogger | | name | readonly | string |

EventAnyListener

@xylabs/events

type EventAnyListener<TEventArgs> = (eventName: EventName, eventData: TEventArgs) => Promisable<void>;

A listener that receives all events regardless of name.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TEventArgs extends EventArgs | EventArgs |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventName | EventName | The name of the emitted event. | | eventData | TEventArgs | The data associated with the event. |

Returns

Promisable<void>

EventArgs

@xylabs/events

type EventArgs = string | number | object;

The allowed types for event argument payloads.

EventData

@xylabs/events

type EventData = {
[key: string | number | symbol]: EventArgs;
};

A mapping of event names to their corresponding event argument types.

Index Signature

[key: string | number | symbol]: EventArgs

EventListener

@xylabs/events

type EventListener<TEventArgs> = (eventData: TEventArgs) => Promisable<void>;

A listener for a specific event type.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TEventArgs extends EventArgs | EventArgs |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | eventData | TEventArgs | The data associated with the event. |

Returns

Promisable<void>

EventListenerInfo

@xylabs/events

type EventListenerInfo<TEventArgs> = {
  filter?: TEventArgs;
  listener: EventListener<TEventArgs>;
};

Information about a registered event listener, including an optional filter for selective invocation.

Type Parameters

| Type Parameter | Default type | | ------ | ------ | | TEventArgs extends EventArgs | EventArgs |

Properties

| Property | Type | | ------ | ------ | | filter? | TEventArgs | | listener | EventListener<TEventArgs> |

EventName

@xylabs/events

type EventName = PropertyKey;

A valid event name, which can be any property key (string, number, or symbol).

EventUnsubscribeFunction

@xylabs/events

type EventUnsubscribeFunction = () => void;

A function returned by event subscription methods that unsubscribes the listener when called.

Returns

void

EventsParams

@xylabs/events

type EventsParams = BaseParams<{
  debug?: DebugOptions;
}>;

Parameters for constructing an Events instance, with optional debug configuration.

MetaEventData

@xylabs/events

type MetaEventData<TEventData> = {
  listenerAdded: {
     eventName?: keyof TEventData;
     listener:   | EventListener<TEventData[keyof TEventData]>
        | EventAnyListener<TEventData[keyof TEventData]>;
  };
  listenerRemoved: {
     eventName?: keyof TEventData;
     listener:   | EventListener<TEventData[keyof TEventData]>
        | EventAnyListener<TEventData[keyof TEventData]>;
  };
};

Data shape for internal meta events that fire when listeners are added or removed.

Type Parameters

| Type Parameter | | ------ | | TEventData extends EventData |

Properties

| Property | Type | | ------ | ------ | | listenerAdded | { eventName?: keyof TEventData; listener: | EventListener<TEventData[keyof TEventData]> | EventAnyListener<TEventData[keyof TEventData]>; } | | listenerAdded.eventName? | keyof TEventData | | listenerAdded.listener | | EventListener<TEventData[keyof TEventData]> | EventAnyListener<TEventData[keyof TEventData]> | | listenerRemoved | { eventName?: keyof TEventData; listener: | EventListener<TEventData[keyof TEventData]> | EventAnyListener<TEventData[keyof TEventData]>; } | | listenerRemoved.eventName? | keyof TEventData | | listenerRemoved.listener | | EventListener<TEventData[keyof TEventData]> | EventAnyListener<TEventData[keyof TEventData]> |

Part of sdk-js

Maintainers

• Arie Trouw (arietrouw.com)
• Matt Jones
• Joel Carter
• Jordan Trouw

License

See the LICENSE file for license details

Credits

Made with 🔥 and ❄️ by XYLabs