Additional Details
Events Type
The Events
type defines what events can be emitted and their payload.
type Events = {
ping: 'pong',
userCreated: User,
eventWithNoPayload: void,
}
Broadcast Channel
By default Kitbag Events only emits events within the document. Alternatively, you can configure Events to use a Broadcast Channel which enables you to broadcast events across different windows, tabs, frames or iframes of the same origin.
import { createEmitter } from '@kitbag/events'
const emitter = createEmitter({
broadcastChannel: 'MyChannelName'
})
You can also set/change the broadcast channel after creating an emitter by using emitter.setOptions({ broadcastChannel: 'MyChannelName '})
Single Event Handler
Define a handler for a single event called "hello"
emitter.on('hello', value => {
console.log(value) // "world"
})
Global Event Handler
Every event emitted will trigger this callback
emitter.on(event => {
console.log(event) // { kind: 'hello', payload: 'world' }
})
Single Use Handler
Listen for a single event and then automatically remove the handler
emitter.once(...)
Waiting for an event
Wait for an event to be emitted and get the payload using the next
method.
const payload = await emitter.next() // Wait for any event
const payload = await emitter.next('hello') // Wait for the hello event
You can also pass an options object to the next
method to set a timeout.
const payload = await emitter.next({ timeout: 1000 }) // Wait for any event with a timeout of 1 second
const payload = await emitter.next('hello', { timeout: 1000 }) // Wait for the hello event with a timeout of 1 second
INFO
If the event is not emitted before the timeout, the next
method will reject with an EmitterTimeoutError
.
Removing listeners
Return Value
Emitter.on returns the off method for removing an event handler
const off = emitter.on(...)
Manually remove an event handler
const handler = (value) => console.log(value)
const globalHandler = (event) => console.log(event)
emitter.on('hello', handler)
emitter.on(globalHandler)
emitter.off('hello', handler)
emitter.off(globalHandler)
Remove all handlers for a given event
const handler1 = (value) => console.log(value)
const handler2 = (value) => console.log(value)
emitter.on('hello', handler1)
emitter.on('hello', handler2)
emitter.off('hello')
Remove all handlers for all events
emitter.clear()