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`

_Source

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`

_Source

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`

_Source

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`

_Source

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`

_Source

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`

_Source

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`

_Source

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`

_Source

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`

_Source

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

_Source

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>[]`

_Source

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)[]`

_Source

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

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

_Source

Return the number of listeners registered for name.

Parameters

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

`getMaxListeners(): number`

_Source

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

`setMaxListeners(n: number): void`

_Source

Parameters

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

Static utilities

`EventEmitter.defaultMaxListeners: number`

_Source

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

_Source

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`

_Source

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

_Source

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]>

_Source

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]>

_Source

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`

_Source

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`

_Source

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`

_Source

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[]
}

_Source

`EventHandler`

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

_Source

type EventConstructor = typeof events.Event

_Source

`CustomEventConstructor`

type CustomEventConstructor = typeof events.CustomEvent

_Source

`EventTargetConstructor`

type EventTargetConstructor = typeof events.EventTarget

_Source

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

_Source

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`

_Source

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

_Source

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

_Source

`EventOptions`

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

_Source

`CustomEventOptions`

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

_Source

`AddEventListenerOptions`

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

_Source

`RemoveEventListenerOptions`

interface RemoveEventListenerOptions {
  capture?: boolean
}

_Source

`EventListener`

type EventListener = EventCallback | EventHandler

_Source

`EventCallback`

interface EventCallback {
  (event: Event): void
}

_Source

`web.EventHandler`

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

_Source

bare-events

On this page