Emitter

Utility class to be used when implementing event-based APIs that allows for handlers registered via ::on to be invoked with calls to ::emit. Instances of this class are intended to be used internally by classes that expose an event-based API. You can use it by requiring event-kit module.

import { Emitter } from 'event-kit'

class User {
  constructor() {
    this.emitter = new Emitter()
  }

  onDidChangeName(callback) {
    this.emitter.on('did-change-name', callback)
  }

  setName(name) {
    if (name !== this.name) {
      this.name = name
      this.emitter.emit('did-change-name', name)
    }

    return this.name
  }
}

constructor()

Construction

Construct an emitter.

Example

const emitter = new Emitter();

dispose()

Destruction

Unsubscribe all handlers.

Example

emitter.dispose();

clear()

Clear subscribers

Clear out any existing subscribers.

Example

emitter.clear();

on<T>(eventName, handler)

Event Subscription: Repeated execution

Parameters

Name
eventName
Type
string
Required
Description
String naming the event that you want to invoke the handler when emitted.
Name
handler
Type
(value?: T) => void
Required
Description
Function to invoke when ::emit is called with the given event name. T is the type of the value passed when calling ::emit.

Return value

Returns a Disposable.

Example

emitter.on(
    'did-change-name', 
    (value) => console.log(value)
);

once<T>(eventName, handler)

Event Subscription: One-time execution

Parameters

Name
eventName
Type
string
Required
Description
String naming the event that you want to invoke the handler when emitted.
Name
handler
Type
(value?: T) => void
Required
Description
Function to invoke when ::emit is called with the given event name. T is the type of the value passed when calling ::emit.

Return value

Returns a Disposable.

Example

emitter.once(
    'did-change-name',
    (value) => console.log("Once", value)
);

preempt<T>(eventName, handler)

Event Subscription: Prioritized execution

Register the given handler function to be invoked before all other handlers existing at the time of subscription whenever events by the given name are emitted via ::emit.

Use this method when you need to be the first to handle a given event. This could be required when a data structure in a parent object needs to be updated before third-party event handlers registered on a child object via a public API are invoked. Your handler could itself be preempted via subsequent calls to this method, but this can be controlled by keeping methods based on ::preempt private.

Parameters

Name
eventName
Type
string
Required
Description
String naming the event that you want to invoke the handler when emitted.
Name
handler
Type
(value?: T) => void
Required
Description
Function to invoke when ::emit is called with the given event name. T is the type of the value passed when calling ::emit.

Return value

Returns a Disposable.

Example

emitter.preempt(
    'did-change-name',
    (value) => console.log("First", value)
);

emit<T>(eventName, value)

Event Emission

Invoke all handlers registered for the given event name.

Parameters

Name
eventName
Type
string
Required
Description
The name of the event to emit. Handlers registered for the same name will be invoked.
Name
value
Type
T
Required
Description
Callbacks will be invoked with this value as an argument.

Example

emitter.emit('did-change-name', "string value");