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.

For example:

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

Construction and Destruction

::constructor()

Construct an emitter.

this.emitter = new Emitter()

::clear()

Clear out any existing subscribers.

::dispose()

Unsubscribe all handlers.

Event Subscription

::on(eventName, handler)

Register the given handler function to be invoked whenever events by the given name are emitted via ::emit.

Return values

Returns a Boolean indicating whether object is a valid Disposable.

::once(eventName, handler)

Register the given handler function to be invoked the next time an events with the given name is emitted via ::emit.

Return values

Returns a Boolean indicating whether object is a valid Disposable.

::preempt(eventName, handler)

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.

Return values

Returns a Boolean indicating whether object is a valid Disposable.

Event Emission

::emit(eventName, value)

Invoke handlers registered via ::on for the given event name.

Can you help us improve these docs?

The source of these docs is here on GitHub. If you see a way these docs can be improved, please fork us!