EventEmitter

Source: EventEmitter.ts:132

Type-safe event emitter class

Remarks

Provides a robust event system with support for:

• Typed events with type inference
• One-time listeners
• Priority-based execution
• Async event handlers
• Wildcard event listening

A local image referenced from a TypeScript doc comment is copied into the built site and its path rewritten, just like in docs pages and the README. The diagram below lives in img/event-flow.svg, referenced from this source file (src/services/) with a ../../img/ relative path:

Type Parameters

• TEvents extends Record<string, unknown> = Record<string, unknown> — Event map type defining event names and data types

Example

Define typed events:
```typescript
interface MyEvents \{
  'user:login': \{ userId: string; timestamp: Date \}
  'user:logout': \{ userId: string \}
  'error': Error
  'ready': void
\}

const emitter = new EventEmitter<MyEvents>()
```

Subscribe to events:
```typescript
// Type-safe event subscription
emitter.on('user:login', (data) => \{
  console.log(`User ${data.userId} logged in at ${data.timestamp}`)
\})

// One-time listener
emitter.once('ready', () => \{
  console.log('Application is ready!')
\})

// Priority listener (executes first)
emitter.on('error', (error) => \{
  console.error('Critical error:', error)
\}, \{ priority: 100 \})
```

Emit events:
```typescript
emitter.emit('user:login', \{
  userId: 'user-123',
  timestamp: new Date()
\})

emitter.emit('ready')
```

Constructors

new EventEmitter< TEvents extends Record<string, unknown> = Record<string, unknown>, >( ): EventEmitter<TEvents>

Returns

EventEmitter<TEvents>

Methods

emit< K extends string | number | symbol, >( event: K, ...args: TEvents[K] extends void ? [] : [data: TEvents[K]], ): boolean

Emits an event to all listeners

Type Parameters

• K extends string | number | symbol — Event name type

Parameters

• event (K) — Event name to emit
• args (TEvents[K] extends void ? [] : [data: TEvents[K]])

Returns

• boolean — True if event had listeners

Example

emitter.emit('user:login', {
  userId: 'user-123',
  timestamp: new Date()
})

emitAsync< K extends string | number | symbol, >( event: K, ...args: TEvents[K] extends void ? [] : [data: TEvents[K]], ): Promise<boolean>

Emits an event and waits for all async handlers

Type Parameters

• K extends string | number | symbol — Event name type

Parameters

• event (K) — Event name to emit
• args (TEvents[K] extends void ? [] : [data: TEvents[K]])

Returns

• Promise<boolean> — Promise that resolves when all handlers complete

Example

await emitter.emitAsync('data:save', { records: [...] })
console.log('All save handlers completed!')

eventNames(): (keyof TEvents)[]

Gets all event names with listeners

Returns

• (keyof TEvents)[] — Array of event names

getMaxListeners(): number

Gets the maximum number of listeners per event

Returns

• number — Maximum listeners count

listenerCount< K extends string | number | symbol, >( event: K, ): number

Gets the number of listeners for an event

Type Parameters

• K extends string | number | symbol

Parameters

• event (K) — Event name

Returns

• number — Number of listeners

off< K extends string | number | symbol, >( event: K, handler: EventHandler<TEvents[K]>, ): boolean

Removes an event listener

Type Parameters

• K extends string | number | symbol — Event name type

Parameters

• event (K) — Event name
• handler (EventHandler<TEvents[K]>) — Handler function to remove

Returns

• boolean — True if a listener was removed

on< K extends string | number | symbol, >( event: K, handler: EventHandler<TEvents[K]>, options: ListenerOptions, ): EventSubscription

Adds an event listener

Type Parameters

• K extends string | number | symbol — Event name type

Parameters

• event (K) — Event name to listen for
• handler (EventHandler<TEvents[K]>) — Handler function
• options (ListenerOptions, default: "{}") — Listener options

Returns

• EventSubscription — Subscription object for unsubscribing

Example

const subscription = emitter.on('user:login', (data) => {
  console.log(data.userId)
})

// Later: remove the listener
subscription.unsubscribe()

onAny( handler: EventHandler<unknown>, options: ListenerOptions, ): EventSubscription

Adds a wildcard listener that receives all events

Parameters

• handler (EventHandler<unknown>) — Handler function
• options (ListenerOptions, default: "{}") — Listener options

Returns

• EventSubscription — Subscription object

Example

emitter.onAny((data) => {
  console.log('Event emitted:', data)
})

once< K extends string | number | symbol, >( event: K, handler: EventHandler<TEvents[K]>, options: ListenerOptions, ): EventSubscription

Adds a one-time event listener

Type Parameters

• K extends string | number | symbol — Event name type

Parameters

• event (K) — Event name to listen for
• handler (EventHandler<TEvents[K]>) — Handler function
• options (ListenerOptions, default: "{}") — Listener options (once is automatically set to true)

Returns

• EventSubscription — Subscription object

Example

emitter.once('ready', () => {
  console.log('This runs only once!')
})

removeAllListeners< K extends string | number | symbol, >( event?: K, ): this

Removes all listeners for an event or all events

Type Parameters

• K extends string | number | symbol

Parameters

• event (K, optional) — Optional event name (if omitted, removes all)

Returns

• this — This emitter for chaining

setMaxListeners(max: number): this

Sets the maximum number of listeners per event

Parameters

• max (number) — Maximum listeners (0 for unlimited)

Returns

• this — This emitter for chaining

Example

emitter.setMaxListeners(10)

waitFor< K extends string | number | symbol, >( event: K, timeout?: number, ): Promise<TEvents[K]>

Waits for an event to be emitted

Type Parameters

• K extends string | number | symbol — Event name type

Parameters

• event (K) — Event to wait for
• timeout (number, optional) — Optional timeout in milliseconds

Returns

• Promise<TEvents[K]> — Promise resolving to the event data

Throws

• Error If timeout is reached

Example

const loginData = await emitter.waitFor('user:login', 5000)
console.log('User logged in:', loginData.userId)