Emitter

Description

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.

For example:

class User
  constructor: ->
    @emitter = new Emitter

  onDidChangeName: (callback) ->
    @emitter.on 'did-change-name', callback

  setName: (name) ->
    if name isnt @name
      @name = name
      @emitter.emit 'did-change-name', name
    @name

API documentation

Construction and Destruction

::constructor()

Construct an emitter.

@emitter = new Emitter()

::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 Emitter::emit.

Argument Description
eventName

String naming the event that you want to invoke the handler when emitted.
handler

Function to invoke when Emitter::emit is called with the given event name.
Return values

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

::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 Emitter::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.

Argument Description
eventName

String naming the event that you want to invoke the handler when emitted.
handler

Function to invoke when Emitter::emit is called with the given event name.
Return values

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

Event Emission

::emit(eventName, value)

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

Argument Description
eventName

The name of the event to emit. Handlers registered with Emitter::on for the same name will be invoked.
value

Callbacks will be invoked with this value as an argument.