Why?
The library solve the need of a multi process and multi server oriented messaging API in Node.js.
Using the known EventEmitter API, listeners registration and events emitting is super simple.
A new 'emitToOne' method allows one-to-one events notification, intended for request/response flows on clustered services.
The classic 'emit' method broadcast custom events to local and distributed listeners.
For non-distributed usage of this API (browser, single node process or development) developers can use: process-eventemitter
Quick Start
- Mailer server (A.js):
var EventEmitter = ;var events = ; // host: localhost, port: 61613events;
- Run mailer server as a cluster with PM2:
pm2 start A.js -i 4 --node-args="--harmony"
- Mailer client (B.js):
var EventEmitter = ;var events = ; // host: localhost, port: 61613events;
- Run mailer client:
node --harmony B.js
Example using ES6 generators
"use strict"; const EventEmitter = ;const co = ;const events = ; // host: localhost, port: 61613 ;
Requirements
-
Running STOMP compliant server instance. Default client destinations are:
- /topic/distributed-eventemitter: Used for events broadcast (emit)
-
/queue/distributed-eventemitter: Used for one-to-one events (emitToOne)
If the server require clients to be authenticated, you can use:
'host': 'localhost''connectHeaders':'heart-beat': '5000,5000''host': '''login': 'username''passcode': 'password'
Installation
$ npm install distributed-eventemitter
Features
- Extends eventemitter2. (wildcards are enabled).
- ECMA6 Promise based API.
- Request/Response communication intended for service clusters (emitToOne). Uncaught exceptions automatically invoke 'reject(error.message)'
- Events broadcast to local and distributed listeners (emit)
- Works with any STOMP compliant server (ie. ActiveMQ, RabbitMQ, ...).
- Uses stompit as STOMP client. (automated server reconnection is supported)
Config params
var config = {};configdestination = 'distributed-eventemitter'; // server topic and queue destinationsconfigexcludedEvents = ; // events that are not distributedconfigservers = 'host': 'localhost' 'port': 61613 'connectHeaders': 'heart-beat': '5000,5000' 'host': '' 'login': '' 'passcode': '' ;configreconnectOpts = maxReconnects: 10; var events = config;
For more details about 'servers' and 'reconnectOpts' params please check: http://gdaws.github.io/node-stomp/api/connect-failover/
Internal events
events; events; events: events: events: events:
API
getId: Get the emitter instance unique id.
events; // UUID v4 value
connect: Connect the emitter to the server. Emit the 'connected' event.
events;
disconnect: Disconnect the emitter from the server. Emit the 'disconnected' event.
events;
emitToOne: Notify a custom event to only one target listener (locally or in the network). The method accept only one argument as event data.
events; // calling without timeoutevents; // calling with timeout (ms)events;
Roadmap
- Express integration.
Known limitations
- The feature 'emitAsync' from the EventEmitter2, only work locally(not distributed).
Tests
$ npm install$ npm test
History changes
1.1.x
- From version 1.1.0+ we use Stompit as STOMP client because Stompjs does not support server reconnections and is also unmaintained.
- No API changes from 1.0 version except the configuration params, since now we consider a list of STOMP servers to connect/reconnect.
1.1.1
- Supporting request/request events intended for pre invocation content filtering and modification.
1.1.2
- Fixing dependencies declaration (due to automatic modification from 'npm update --save').
1.1.3
- Fixing issue on distributed events broadcast(emit) that caused repeated broadcasts.
1.1.4
- Updating dependencies and adding generators example to docs.
1.1.5
- Updating dependencies and docs.
1.1.6
- Improving unexpected error handling when data can't be transmited because the STOMP connection is closed. Produced exceptions are notified as an 'error' event on the emitter.
1.2.0
- Supporting jWebSocket EventBus. JVM based applications using the jWebSocket EventBus component, can communicate with nodejs services through this module.
1.2.1
- Minor source code refactorization.
- Package updates.