Install

npm install emits

yarn add emits

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.