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, R>(name: E, fn: EventHandler<M[E], R>): 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], R>`	—	The listener function, called with the event's arguments on each emit.

`addOnceListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): 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], R>`	—	The listener function, called once with the event's arguments then removed.

`prependListener<E extends keyof M, R>(name: E, fn: EventHandler<M[E], R>): 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], R>`	—	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, R>(name: E, fn: EventHandler<M[E], R>): 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], R>`	—	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, R>(name: E, fn: EventHandler<M[E], R>): 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], R>`	—	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, R>(name: E, fn: EventHandler<M[E], R>): this`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name.
`fn`	`EventHandler<M[E], R>`	—	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, R>(name: E, fn: EventHandler<M[E], R>): this`

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name.
`fn`	`EventHandler<M[E], R>`	—	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, R>(name: E, fn: EventHandler<M[E], R>): this`

Alias for removeListener.

Parameters

Parameter	Type	Default	Description
`name`	`E`	—	The event name to remove the listener from.
`fn`	`EventHandler<M[E], R>`	—	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, R>(name: E): EventHandler<M[E], R>`

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, R>(name: E): EventHandler<M[E], R>[]`

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.

Parameters

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

`getMaxListeners(): number`

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

`setMaxListeners(n: number): void`

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 EventMap, E extends keyof F, T extends 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): number`

Parameters

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

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

`EventEmitter.listenerCount`

EventEmitter.listenerCount<M extends EventMap, E extends keyof M>(emitter: EventEmitter<M>, name: E): number

Return the number of listeners registered for name.

Parameters

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

`EventEmitter.on`

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

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`.

`EventEmitter.once`

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

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`.

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

Parameters

Parameter	Type	Default	Description
`n`	`number`	—	The maximum number of listeners to allow.
`emitters`	`EventEmitter[]`	—	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 {
  [event: string | symbol]: unknown[]
}

`EventHandler`

interface EventHandler<in A extends unknown[] = unknown[], out R = unknown> {
  (...args: A): R
}

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 extends EventTarget {}

`EventOptions`

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

`CustomEventOptions`

interface CustomEventOptions<T = any> extends EventOptions {
  detail?: T
}

`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 {
  (event: Event): void
}

`web.EventHandler`

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

bare-events

On this page