BetterEvents

An improved version of the Node.js EventEmitter.

Installation

npm i better-events --save

Changes

• v3.0.0
  • The promises returned by the BetterEvents.once and emitter.once methods now get cached. The same promise gets returned until the event gets emitted.
  • Add static shareEvent method.
• v2.0.0
  • Promises for the "error" event will now be rejected when an error is emitted.

Class: BetterEvents

The BetterEvents constructor extends the default Node.js EventEmitter.

For more information on the EventEmitter see the Node.js docs: https://nodejs.org/api/events.html

Here are the specs for the new methods of BetterEvents.

BetterEvents.once(source, eventName[, arrayMode])

• source <EventEmitter> The source for the Event.
• eventName <String> | <Symbol> The name of the event.
• arrayMode <Boolean> resolve the promise with an array containing all arguments of the event

Returns a <Promise> that gets resolved with the first argument of the event. It gets resolved when the source emits the event. If the eventName is "error" then the promise gets rejected as soon as an error is emitted.

const { once } = require('better-events')

async function read() {
  const readstream = fs.createReadStream('example.txt')

  let text = ''
  readstream.on('data', chunk => {
    text += chunk
  })

  // Await the "close" event.
  await once(readstream, 'close')

  // Log the contents of the file.
  console.log('text:', text)
}

read()

BetterEvents.shareEvent(eventName, source, target, once)

• eventName <String> | <Symbol> The name of the event.
• source <EventEmitter> the EventEmitter that emits the event.
• target <EventEmitter> The EventEmitter to share the event with.
• once <Boolean> Share the event only once.

Returns the listener that has been applied to the source so one can use .removeListener().

This method allows you to share events. If the event gets emitted on the source, it also gets emitted on the target. This works only one way. If the shared event gets emitted on the target, it is not emitted on the source.

const {
  BetterEvents,
  shareEvent
} = require('better-events')

const emitter1 = new BetterEvents()
const emitter2 = new BetterEvents()

shareEvent('hello', emitter1, emitter2)

emitter2.on('hello', () => console.log('received event'))

emitter1.emit('hello')
// "received event" will be logged.

emitter.once(eventName[, listener])

• eventName <String> | <Symbol> The name of the event.
• listener <Function> | <Boolean> callback function

Like the original method (see: https://nodejs.org/api/events.html#events_emitter_once_eventname_listener) with exceptions.

If no callback is provided the method returns a <Promise> that resolves with the first argument of the event when the event is fired. If the eventName is "error" then the promise gets rejected as soon as an error is emitted.

If one provides true instead of the callback the array mode gets activated. The method returns a <Promise> which resolves with an array containing all the arguments of the event. It gets resolved when the event is fired.

const BetterEvents = require('better-events')

// Create your own class that extends BetterEvents.
class Seconds extends BetterEvents {
  constructor() {
    setInterval(() => {
      this.emit('second')
    }, 1000)
  }
}

// Create an instance of your class.
const example = new Seconds()

// Get a promise for the 'second' event.
example.once('second').then(() => {
  console.log('one second has passed')
})

emitter.collect(eventName, source)

• eventName <String> | <Symbol> The name of the event.
• source <EventEmitter> The source for the Event.

Returns the listener that has been applied to the source so one can use .removeListener().

When the event specified by the eventName gets fired at the source it will also be emitted on this instance.

emitter.collectOnce(eventName, source)

• eventName <String> | <Symbol> The name of the event.
• source <EventEmitter> The target for the Event.

Returns the listener that has been applied to the source so one can use .removeListener().

Similar to emitter.collect() but works only once.

emitter.share(eventName, target)

• eventName <String> | <Symbol> The name of the event.
• target <EventEmitter> The target for the Event.

Returns the listener that has been applied to the source so one can use .removeListener().

When the event specified by the eventName gets fired at this instance it will also be emitted on the target.

emitter.shareOnce(eventName, target)

• eventName <String> | <Symbol> The name of the event.
• target <EventEmitter> The target for the Event.

Returns the listener that has been applied to the source so one can use .removeListener().

Similar to emitter.share() but works only once.