bare-events

stable

bare-events — Event emitters for JavaScript.

Mirrors the Node.js events module.

npm i bare-events

Usage

const EventEmitter = require('bare-events')

const e = new EventEmitter()

e.on('hello', function (data) {
  console.log(data)
})

e.emit('hello', 'world')

API

Adding and removing listeners

`addListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Add fn as a listener for name, called on every subsequent emit. Returns this for chaining.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name to listen for.
`fn`	`EventHandler<M[E]>`	—	The listener function, called with the event's arguments on each emit.

`addOnceListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Add fn as a listener for name that is removed after it fires once. Returns this for chaining.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name to listen for.
`fn`	`EventHandler<M[E]>`	—	The listener function, called once with the event's arguments then removed.

`prependListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Like addListener, but adds fn to the beginning of the listener list instead of the end.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name to listen for.
`fn`	`EventHandler<M[E]>`	—	The listener function to add to the front of the listener list instead of the end.

Returns this — The emitter itself, for chaining, like addListener.

`prependOnceListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Like addOnceListener, but adds fn to the beginning of the listener list instead of the end.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name to listen for.
`fn`	`EventHandler<M[E]>`	—	The listener function to add to the front of the listener list, removed after it fires once.

Returns this — The emitter itself, for chaining, like addOnceListener.

`removeListener<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Remove one instance of fn from the listeners for name. Returns this for chaining.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name to remove the listener from.
`fn`	`EventHandler<M[E]>`	—	The listener function to remove.

`removeAllListeners<E extends keyof M>(name?: E): this`

Remove all listeners, or only those for name if given. Returns this for chaining.

Parameters

Parameter	Type	Default	Description
`name?`	`E`	—	If given, remove listeners only for this event name; otherwise remove all listeners for every event.

`on<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Alias for addListener.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name.
`fn`	`EventHandler<M[E]>`	—	The listener function, called with the event's arguments on each emit.

Returns this — The emitter itself, for chaining — implemented identically to addListener.

`once<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Alias for addOnceListener.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name.
`fn`	`EventHandler<M[E]>`	—	The listener function, called once with the event's arguments then removed.

Returns this — The emitter itself, for chaining — implemented identically to addOnceListener.

`off<E extends keyof M>(name: E, fn: EventHandler<M[E]>): this`

Alias for removeListener.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name to remove the listener from.
`fn`	`EventHandler<M[E]>`	—	The listener function to remove.

Returns this — The emitter itself, for chaining — implemented identically to removeListener.

Synchronously call each listener registered for name, in registration order, with args. Returns true if there were listeners, false otherwise. Emitting 'error' with no 'error' listeners throws the error asynchronously instead of calling any listener.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name to emit.
`args`	`M[E]`	—	Arguments passed to each listener registered for `name`.

Inspecting listeners

`listeners<E extends keyof M>(name: E): EventHandler<M[E]>[]`

Return a copy of the listener array for name.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name to return the listener array for.

`rawListeners<E extends keyof M>(name: E): EventHandler<M[E]>[]`

Return a copy of the listener array for name, including one-time wrapper listeners as registered.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name to return the raw listener array for.

`eventNames(): (keyof M)[]`

Return an array of the event names that currently have listeners.

`listenerCount<E extends keyof M>(name: E): number`

Return the number of listeners registered for name, or 0 if there are none.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name.

`getMaxListeners(): number`

Return the maximum number of listeners allowed for this emitter.

Returns number — EventEmitter.defaultMaxListeners; bare-events does not track a per-instance limit separately.

`setMaxListeners(n: number): this`

Set the maximum number of listeners for this emitter. Accepted for compatibility, but the limit is not recorded and the call has no effect.

Parameters

Parameter	Type	Default	Description
`n`	`number`	—	The maximum number of listeners to allow.

Static utilities

`EventEmitter.defaultMaxListeners: number`

The default max-listeners value used by getMaxListeners().

`EventEmitter.forward`

EventEmitter.forward<F extends Record<keyof F, unknown[]>, E extends keyof F, T extends Record<keyof T, unknown[]> & Pick<F, E>>(from: EventEmitter<F>, to: EventEmitter<T>, names: E | E[], opts?: { emit?: (name: E, ...args: T[E]) => void }): void

Forward events named in names from from to to, re-emitting them on to only while to has at least one listener for that event.

Parameters

Parameter	Type	Default	Description
`from`	`EventEmitter<F>`	—	The emitter to forward events from.
`to`	`EventEmitter<T>`	—	The emitter to forward events to.
`names`	`E` \| `E[]`	—	The event name, or array of event names, to forward.
`opts?`	`{ emit?: (name: E, ...args: T[E]) => void }`	—	Options; `emit` overrides how forwarded events are re-emitted on `to` (defaults to `to.emit`).

`EventEmitter.getMaxListeners(emitter: EventEmitter<any>): number`

Return the maximum number of listeners for emitter.

Parameters

Parameter	Type	Default	Description
`emitter`	`EventEmitter<any>`	—	The emitter to query.

Returns number — emitter.getMaxListeners() if the emitter has that method, otherwise EventEmitter.defaultMaxListeners.

`EventEmitter.listenerCount`

EventEmitter.listenerCount<M extends Record<keyof M, unknown[]>, E extends keyof M>(emitter: EventEmitter<M>, name: E): number

Return the number of listeners registered on emitter for name, by calling the emitter's own listenerCount method.

Parameters

Parameter	Type	Default	Description
`emitter`	`EventEmitter<M>`	—	The emitter to query.
`name`	`E`	—	The event name.

`EventEmitter.on`

EventEmitter.on<M extends Record<keyof M, unknown[]>, E extends keyof M>(emitter: EventEmitter<M>, name: E, opts?: { signal?: AbortSignal }): AsyncIterableIterator<M[E]>

Iterate the name events emitted by emitter, yielding the arguments of each emit as an array. Unless name is 'error', an 'error' event on emitter ends the iteration by rejecting with the emitted error.

Parameters

Parameter	Type	Default	Description
`emitter`	`EventEmitter<M>`	—	The emitter to iterate events from.
`name`	`E`	—	The event name.
`opts?`	`{ signal?: AbortSignal }`	—	Options; `signal` aborts the iteration, rejecting it with an `EventEmitterError`.

Returns AsyncIterableIterator<M[E]> — An async iterator of the emitted arguments, which stops listening once it is returned from or throws.

Throws

If opts.signal has already been aborted.

`EventEmitter.once`

EventEmitter.once<M extends Record<keyof M, unknown[]>, E extends keyof M>(emitter: EventEmitter<M>, name: E, opts?: { signal?: AbortSignal }): Promise<M[E]>

Wait for the next name event emitted by emitter. Unless name is 'error', an 'error' event on emitter rejects the wait with the emitted error instead.

Parameters

Parameter	Type	Default	Description
`emitter`	`EventEmitter<M>`	—	The emitter to wait on.
`name`	`E`	—	The event name.
`opts?`	`{ signal?: AbortSignal }`	—	Options; `signal` aborts the wait, rejecting the promise with an `EventEmitterError`.

Returns Promise<M[E]> — A promise resolving with the arguments of the next emit, as an array.

`EventEmitter.setMaxListeners(n: number, ...emitters: EventEmitter<any>[]): void`

Set the maximum number of listeners on each of emitters that has a setMaxListeners method.

Parameters

Parameter	Type	Default	Description
`n`	`number`	—	The maximum number of listeners to allow.
`emitters`	`EventEmitter<any>[]`	—	The emitters to apply the new limit to; if omitted, sets the global default instead.

Errors

`EventEmitterError.OPERATION_ABORTED(cause: Error, msg?: string): EventEmitterError`

Create an EventEmitterError wrapping cause, used when an AbortSignal aborts a pending events.on or events.once wait.

Parameters

Parameter	Type	Default	Description
`cause`	`Error`	—	The abort reason wrapped by the error.
`msg?`	`string`	—	An optional custom message for the wrapping error.

`EventEmitterError.UNHANDLED_ERROR(cause: Error, msg?: string): EventEmitterError`

Create an EventEmitterError wrapping cause, used when an 'error' event is emitted with no listeners attached.

Parameters

Parameter	Type	Default	Description
`cause`	`Error`	—	The underlying error wrapped by the error.
`msg?`	`string`	—	An optional custom message for the wrapping error.

Types

`EventMap`

interface EventMap {
}

`EventHandler`

interface EventHandler<in A extends unknown[] = unknown[], out R = unknown> {
}

type EventConstructor = typeof events.Event

`CustomEventConstructor`

type CustomEventConstructor = typeof events.CustomEvent

`EventTargetConstructor`

type EventTargetConstructor = typeof events.EventTarget

Parameter	Type	Default	Description
`type`	`string`	—	The event's type, exposed as `event.type`.
`options?`	`EventOptions`	—	Options controlling `bubbles`, `cancelable`, and `composed`.

Parameter	Type	Default	Description
`type`	`string`	—	The event's type, exposed as `event.type`.
`options?`	`CustomEventOptions<T>`	—	Options controlling `bubbles`/`cancelable`/`composed` plus the `detail` value.

addEventListener(type: string, callback: EventListener, options?: AddEventListenerOptions | boolean): void

Parameters

Parameter	Type	Default	Description
`type`	`string`	—	The event type to listen for.
`callback`	`EventListener`	—	The listener function, or an object with a `handleEvent` method.
`options?`	`AddEventListenerOptions` \| `boolean`	—	Options, or a boolean shorthand for `capture`; `once` removes the listener after it fires, `signal` removes it when the given `AbortSignal` aborts.

`dispatchEvent(event: Event): boolean`

Parameters

Parameter	Type	Default	Description
`event`	`Event`	—	The event to dispatch to this target's listeners.

Returns boolean — false if the event is cancelable and preventDefault() was called on it during dispatch, true otherwise.

`removeEventListener`

removeEventListener(type: string, callback: EventListener, options?: RemoveEventListenerOptions | boolean): void

Parameters

Parameter	Type	Default	Description
`type`	`string`	—	The event type to stop listening for.
`callback`	`EventListener`	—	The listener to remove.
`options?`	`RemoveEventListenerOptions` \| `boolean`	—	Options, or a boolean shorthand for `capture`; must match the `capture` value passed to `addEventListener`.

Types

`AbortSignal`

interface AbortSignal {
  addEventListener(
    type: string,
    callback: EventListener,
    options?: AddEventListenerOptions | boolean
  ): void
  removeEventListener(
    type: string,
    callback: EventListener,
    options?: RemoveEventListenerOptions | boolean
  ): void
  dispatchEvent(event: Event): boolean
}

`EventOptions`

interface EventOptions {
  bubbles?: boolean
  cancelable?: boolean
  composed?: boolean
}

`CustomEventOptions`

interface CustomEventOptions<T = any> {
  detail?: T
  bubbles?: boolean
  cancelable?: boolean
  composed?: boolean
}

`AddEventListenerOptions`

interface AddEventListenerOptions {
  capture?: boolean
  passive?: boolean
  once?: boolean
  signal?: AbortSignal | null
}

`RemoveEventListenerOptions`

interface RemoveEventListenerOptions {
  capture?: boolean
}

`EventListener`

type EventListener = EventCallback | EventHandler

`EventCallback`

interface EventCallback {
}

`web.EventHandler`

interface EventHandler {
  handleEvent(event: Event): void
}

bare-events

On this page