RqrsEmitter - event emitter with request-response capability for JavaScript (NodeJS, ReactNative, browser).
This component extends standard event emitter with another feature layer that allows developers to use request-response semantics. It's useful for integration between software components when just emitting events is not enough because you expect to receive some result back from the event handler.
EventEmitter3 is used as a foundation layer, please check their documentation in order to use RqrsEmitter as a basic event emitter (all base layer functionality is available).
Jump to sections below:
Using Yarn:
yarn add rqrs-emitter
Using NPM:
npm install --save rqrs-emitter
Load the module and create RqrsEmitter instance:
const RqrsEmitter = require('rqrs-emitter');
const rre = new RqrsEmitter();
Create request handler for request named test
:
rre.handler('test', async req => {
// some work here, using "req"
// send response back
return { ok: true };
});
Send test
request with additional details:
const res = await rre.request('test', { data: 1 });
// "res" contains result returned by handler
Additional details are optional in case handler do not require them:
const res = await rre.request('test');
// "res" contains result returned by handler
To remove handler for test
request:
rre.removeHandler('test');
Any exceptions thrown by the handler function are re-thrown inside request sender execution context. So normal exception handling can be used to catch and process all errors.
RqrsEmitter provides method aliases for adding and removing request handlers:
handler
method can be called asaddRequestHandler
removeHandler
method can be called asremoveRequestHandler
Define event types that will be processed by event emitter. Each event must incorporate following parts:
type: string
- defines event name as a simple stringrequest
- defines request typesresponse
- defines response type
Example:
type AppleEvent = {
type: 'apple',
request: number,
response: string
};
In case you need event only to be used with emit
method, which means no
response is expected, define response type as never
.
Example:
type OrangeEvent = {
type: 'orange',
request: string,
response: never
};
Import RqrsEmitter:
import RqrsEmitter from 'rqrs-emitter';
Use one or more event types to instantiate new RqrsEmitter object. Examples:
const rre = new RqrsEmitter<AppleEvent>();
// OR
const rre = new RqrsEmitter<AppleEvent|OrangeEvent>();
// OR
type MyEvents = AppleEvent | OrangeEvent;
const rre = new RqrsEmitter<MyEvents>();
Specify event type for each request/response method or standard event emitter method.
Example:
rre.handler<AppleEvent>('apple', (req: number) => 'ok');
const resp = await rre.request<AppleEvent>('apple', 1);
// resp equals 'ok'
Example without response:
rre.on<OrangeEvent>('orange', (req: string) => { /* do something */ });
rre.emit<OrangeEvent>('orange', 'hello');
- Add ability to create multiple response handlers. Currently it allows only 1 response handler. In case of multiple handlers they all should be called and result returned to caller should contain all responses (as array, or maybe hash map if we can identify responses somehow).