lighter-emitter

Emitter creates event emitters with additional methods and slightly better performance than Node's builtin EventEmitter.

Installation

From your project directory, install and save as a dependency:

npm install --save lighter-emitter

API

The lighter-emitter package exports a constructor that extends the Type constructor from lighter-type.

• Emitter
  • .init(object, [overwrite], [args])
  • .extend([constructor], [prototypeProperties], [constructorProperties])
  • .decorate(object, [map], [overwrite])
  • .include(type, [overwrite])
  • .is(type)
  • .has(type)
  • .hide(object, key, value)
  • .defaultMaxListeners
  • .prototype
    • .on(event, listener) or .addListener(event, listener)
    • .once(event, listener)
    • .off(event, listener) or .removeListener(event, listener)
    • .clear([event]) or .removeAllListeners([event])
    • .setMaxListeners(n)
    • .getMaxListeners()
    • .all(event) or .listeners(event)
    • .emit(event, [arg1], [arg2], [...])
    • .count(event) or .listenerCount(event)

Emitter

A new emitter object can be constructed simply with the new keyword.

var Emitter = require('lighter-emitter')

// Create a brand new Emitter object.
var emitter = new Emitter()

Emitter.init(object, [overwrite], [args])

See Type.init.

A plain JavaScript object can be made into an emitter by running the init method on it, thereby decorating it with Emitter.prototype methods, and executing the Emitter constructor on it. However, it does not become an instance of Emitter.

var Emitter = require('lighter-emitter')

var emitter = new Emitter()
var object = {}
Emitter.init(object)

function hi (me) {
  me.on('hi', function (message) {
    console.log('Hi! ' + message + '.')
  })
  if (me instanceof Emitter) {
    me.emit('hi', 'I\'m an emitter')
  } else {
    me.emit('hi', 'I behave like an emitter')
  }
}

hi(emitter)
//> Hi! I'm an emitter.

hi(object)
//> Hi! I behave like an emitter.

Emitter.extend([constructor], [prototypeProperties], [constructorProperties])

See Type.extend.

Define and return a sub type of the Emitter object, with its prototype and constructor optionally decorated with properties (beyond what the sub type inherits from its super type).

var Emitter = require('lighter-emitter')

var BoomEmitter = Emitter.extend({

  emit: function (type) {
    this._super.emit.apply(this, arguments)
    console.log('Boom!')
  }

})

var boomer = new BoomEmitter()
boomer.on('hi', function () {
  console.log('Hi!')
})
boomer.emit('hi')

//> Hi!
//> Boom!

Emitter.decorate(object, [map], [overwrite])

Decorate an object with a map of additional properties. See (Type.decorate)[https://github.com/lighterio/lighter-type#Type.decorate].

Emitter.include(type, [overwrite])

Implement multiple inheritance by decorating a Emitter's prototype. See (Type.include)[https://github.com/lighterio/lighter-type#Type.include].

Emitter.is(type)

Check whether this Emitter is descended from another type. See (Type.is)[https://github.com/lighterio/lighter-type#Type.is].

Emitter.has(type)

Check whether this Emitter has acquired the functionality of another type. See (Type.has)[https://github.com/lighterio/lighter-type#Type.has].

Emitter.hide(object, key, value)

Create a non-enumerable object property. See (Type.hide)[https://github.com/lighterio/lighter-type#Type.hide].

Emitter.prototype.on(event, listener) or Emitter.prototype.addListener(event, listener)

Adds a listener to the end of the listeners array for the specified event. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of event and listener will result in the listener being added multiple times.

server.on('connection', function (stream) {
  console.log('someone connected!')
})

Returns emitter, so calls can be chained.

Emitter.prototype.once(event, listener)

Adds a one time listener for the event. This listener is invoked only the next time the event is fired, after which it is removed.

server.once('connection', function (stream) {
  console.log('Ah, we have our first user!')
})

Returns emitter, so calls can be chained.

Emitter.prototype.off(event, listener) or Emitter.prototype.removeListener(event, listener)

Removes a listener from the listener array for the specified event. Caution: changes array indices in the listener array behind the listener.

var callback = function(stream) {
  console.log('someone connected!')
}
server.on('connection', callback)
// ...
server.off('connection', callback)

off will remove, at most, one instance of a listener from the listener array. If any single listener has been added multiple times to the listener array for the specified event, then removeListener must be called multiple times to remove each instance.

Returns emitter, so calls can be chained.

Emitter.prototype.clear([event]) or Emitter.prototype.removeAllListeners([event])

Removes all listeners, or those of the specified event. It's not a good idea to remove listeners that were added elsewhere in the code, especially when it's on an emitter that you didnt create (e.g. sockets or file streams).

Returns emitter, so calls can be chained.

Emitter.prototype.setMaxListeners(n)

By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default which helps finding memory leaks. Not all Emitters should be limited to 10, so this function allows that to be increased. Set to zero for unlimited.

Returns emitter, so calls can be chained.

Emitter.prototype.getMaxListeners()

Returns the current max listener value for the emitter which is either set by Emitter.prototype.setMaxListeners(n) or defaults to 10.

This can be useful to increment/decrement max listeners to avoid the warning while not being irresponsible and setting a too big number.

Emitter.prototype.setMaxListeners(Emitter.prototype.getMaxListeners() + 1)
Emitter.prototype.once('event', function () {
  // do stuff
  Emitter.prototype.setMaxListeners(Math.max(Emitter.prototype.getMaxListeners() - 1, 0))
})

Emitter.defaultMaxListeners

Emitter.prototype.setMaxListeners(n) sets the maximum on a per-instance basis. This class property lets you set it for all Emitter instances, current and future, effective immediately. Use with care.

Note that Emitter.prototype.setMaxListeners(n) still has precedence over Emitter.defaultMaxListeners.

Emitter.prototype.all(event) or Emitter.prototype.listeners(event)

Returns a copy of the array of listeners for the specified event.

server.on('connection', function (stream) {
  console.log('someone connected!')
})
console.log(util.inspect(server.listeners(connection)))
//> [ [Function] ]

Emitter.prototype.emit(event, [arg1], [arg2], [...])

Calls each of the listeners in order with the supplied arguments.

Returns true if event had listeners, false otherwise.

Emitter.prototype.count(event) or Emitter.prototype.listenerCount(event)

Returns the number of listeners listening to the event of event.

Omissions

Node's builtin EventEmitter is already highly optimized, so in order to build a faster Emitter, some features were omitted.

Emitter does not:

• Emit "newListener" and "removeListener" events.
• Support domains.
• Have a magic "error" listener.

More on lighter-emitter...

• Contributing
• License (ISC)
• Change Log
• Benchmarks
• Roadmap