emits v3.0.0

emits

Installation

This module is compatible with browserify and node.js and is therefore released through npm:

npm install --save emits

Usage

In all examples we assume that you've assigned the emits function to the prototype of your class. This class should inherit from an EventEmitter class which uses the emit function to emit events. For example:

'use strict';

var EventEmitter = require('events').EventEmitter
  , emits = require('emits');

function Example() {
  EventEmitter.call(this);
}

require('util').inherits(Example, EventEmitter);

//
// You can directly assign the function to the prototype if you wish or store it
// in a variable and then assign it to the prototype. What pleases you more.
//
Example.prototype.emits = emits; // require('emits');

//
// Also initialize the example so we can use the assigned method.
//
var example = new Example();

Now that we've set up our example code we can finally demonstrate the beauty of this functionality. To create a function that emits data we can simply do:

var data = example.emits('data');

Every time you invoke the data() function it will emit the data event with all the arguments you supplied. If you want to "curry" some extra arguments you can add those after the event name:

var data = example.emits('data', 'foo');

Now when you call data() the data event will receive foo as first argument and the rest of the arguments would be the ones that you've supplied to the data() function.

If you supply a function as the last argument we assume that this is an async argument parser. This allows you to modify the arguments, prevent the event from being fired or just clear all supplied arguments (except for the ones that are curried in). The first argument of the function is always the callback function, all other arguments after that are the ones emitted with the event. The callback function follows the usual error first pattern. When the callback is invoked with an error it will emit an error event on the EventEmitter instance. In our case the example instance:

var data = example.emits('data', function parser(next, arg) {
  try { arg = JSON.parse(arg); }
  catch (e) { return next(e); }

  next(undefined, arg);
});

To modify the data you need to supply the change as second argument:

var data = example.emits('data', function parser(next, arg) {
  next(undefined, 'bar');
});

In the example above we've transformed the incoming argument to bar. So when you call data() it will emit a data event with bar as the second argument. If you call the callback with undefined as second argument we assume that no modifications have been made and we emit all received arguments. If you want to clear all received arguments, call the callback with null:

var data = example.emits('data', function parser(next, arg) {
  next(undefined, null);
});

Patterns

In Primus the most common pattern for this module is to proxy events from one instance to another:

eventemitter.on('data', example.emits('data'));

It is also very useful to re-format data. For example, in the case of WebSockets, if we don't want to reference evt.data every time we need to access the data, we can parse the argument as following:

var ws = new WebSocket('wss://example.org/path');
ws.onmessage = example.emits('data', function parser(next, evt) {
  next(undefined, evt.data);
});

In the example above we will now emit the data event with a direct reference to evt.data. The following final example shows how you can prevent events from being emitted.

var ws = new WebSocket('wss://example.org/path');
ws.onmessage = example.emits('data', function parser(next, evt) {
  var data;

  try { data = JSON.parse(evt.data); }
  catch (e) { return next(e); }

  if ('object' !== typeof data || Array.isArray(data)) return;

  next(undefined, data);
});

By not calling the callback we make sure that the event is not emitted. So the data event will only be fired if we've received a valid JSON document from the server and it's an object.

License

MIT