0.3.0 • Published 4 years ago

aframework.events v0.3.0

Weekly downloads
3
License
MIT
Repository
github
Last release
4 years ago

aFramework.Events

This library provides two EventEmitters: RedisQueue and RedisEvents, providing easy Queues and Pub/Sub functionality for use in a multi-instance or a sever farm environment.

RedisQueue provides Queuing functionality. Exactly one subscribed process will recieve the event, if any listener on that process fails to completely process the event (throws an error) the event will be requeued and handled by another subscribed process.

RedisEvents provides Pub/Sub functionality. Every subscriber will recieve every event which occurs while they are listening.

Important Methods

async Events.on(eventName, listener)

When an event matching the eventName is emitted, the listener will be called and supplied the argument object. To begin listening to redis a network/io call needs to be made. If this method is not awaited, any events emitted on this client before that resolves will be lost. This is only a concern if you hope to immediately emit an event that the current client cares about.

Queue.on(eventName, listener)

When an event matching the eventName is emitted, the listener will be called and supplied the argument object. This method will generate a new redis client (by using the blockingQueueClientFunction) and wait on an entry to appear in redis, looping only when an event has been successfully processed. If an error is thrown in a listener, the event will not be removed, instead being requeued once the delay ends. This will also cause the process to stop listening to prevent the client from endlessly churning a single event.

async emit(eventName, args)

Emits the event and optional arguments object. Awaiting is optional unless you require a gaurntee that the event has been stored in redis before continuing.

async removeListener(eventName, listener)

Unsubscribes or ends the redis connection for the specific listener+function.

async off(eventName, listener)

Alias for removeListener

async close()

Cleans up active redis connections and listeners.

Basic Usage

let aEvents = require('aframework.events');

let rQueue = new aEvents.RedisQueue({redis:{host:'127.0.0.1', port:'6379'}});

await rQueue.on('queue', (args) => {
    console.log(`#1 recieved queue job: ${JSON.stringify(args)}`);
});
await rQueue.on('queue', (args) =>{
    console.log(`#2 recieved queue job: ${JSON.stringify(args)}`);
});

rQueue.emit('queue', {arg1:'test'});
// #1 recieved queue job: {"arg1":"test","eventId":"4fb88d9b-8786-4654-9e3b-28a7f79fc266","emittedAt":1572026515983}
// #2 recieved queue job: {"arg1":"test","eventId":"4fb88d9b-8786-4654-9e3b-28a7f79fc266","emittedAt":1572026515983}
let aEvents = require('aframework.events');
let rEvents = new aEvents.RedisEvents({redis:{host:'127.0.0.1', port:'6379'}});
await rEvents.on('broadcast', (args) =>{
    console.log(`#1 recieved broadcast: ${JSON.stringify(args)}`);
});
await rEvents.on('broadcast', (args) =>{
    console.log(`#2 recieved broadcast: ${JSON.stringify(args)}`);
});

rEvents.emit('broadcast', {arg2:'test'});
// #1 recieved broadcast: {"arg2":"test","eventId":"f0ef26d6-aef6-4ee3-ab91-0445a0e75c36","emittedAt":1572026762102}
//#2 recieved broadcast: {"arg2":"test","eventId":"f0ef26d6-aef6-4ee3-ab91-0445a0e75c36","emittedAt":1572026762102}

Options

Queue

OptionDescription
redisobject detailing redis configuration
redis.queueKeyPredicatea string which will be prepended to all queue keys in redis.
redis.requeueDelaythe delay in miliseconds before an event will be re-queued. Defaults to 60 seconds.
redis.hostthe host of the redis instance (required if queueClient is not supplied)
redis.portthe port of the redis instance (required if queueClient is not supplied)
redis.queueClienta writable redis client instance. ioRedis is used internally, but can be most clients.
redis.blockingQueueClientFunctiona function which returns a redis client instance when called. Each instance will be blocked while waiting for an event, so it's best for this function to return a newly created client which will be disposed of on close
loga function which will be called with a string parameter containing Error info.

Events

OptionDescription
redisobject detailing redis configuration
redis.hostthe host of the redis instance (required if subHost or sub/pubClients are not supplied)
redis.portthe port of the redis instance (required if pubHost or sub/pubClients are not supplied)
redis.subClienta readable redis client instance. ioRedis is used internally, but can be most clients.
redis.pubClienta writable redis client instance. ioRedis is used internally, but can be most clients.
redis.subHostthe host of a readable redis instance (used to specify different hosts/ports between sub/pub clients)
redis.subPortthe port of a readable redis instance (used to specify different hosts/ports between sub/pub clients)
redis.pubHostthe host of a readable redis instance (used to specify different hosts/ports between sub/pub clients)
redis.pubPortthe port of a readable redis instance (used to specify different hosts/ports between sub/pub clients)
loga function which will be called with a string parameter containing Error info.

TODO:

  • Allow Queue listeners to provide failure status beyond throwing
  • Publish on NPM