# 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.

Latest version **0.3.0** (published 2019-10-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install aframework.events
pnpm add aframework.events
yarn add aframework.events
bun add aframework.events
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2019-10-25 |
| First published | 2019-10-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=7.6 |
| Dependencies | 3 |
| Unpacked size | 61.3 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Alex Dobeck |
| Maintainers | alexdobeck |
| Keywords | events, redis, distributed, queue, pub/sub |

## Links

- npm: https://www.npmjs.com/package/aframework.events
- Repository: https://github.com/AlexDobeck/aFramework.Events
- Homepage: https://github.com/AlexDobeck/aFramework.Events#readme
- Issues: https://github.com/AlexDobeck/aFramework.Events/issues
- npm.io page: https://npm.io/package/aframework.events

## Dependencies (3)

- [uuid](https://npm.io/package/uuid.md) ^3.3.3
- [ioredis](https://npm.io/package/ioredis.md) ^4.14.1
- [assert-plus](https://npm.io/package/assert-plus.md) ^1.0.0

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 0.3.0 (latest) — 2019-10-25
- 0.2.0 — 2019-10-25

## README

# 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
```javascript
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}
```
```javascript
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
Option | Description
------------ | -------------
redis | object detailing redis configuration
redis.queueKeyPredicate | a string which will be prepended to all queue keys in redis.
redis.requeueDelay | the delay in miliseconds before an event will be re-queued. Defaults to 60 seconds.
redis.host | the host of the redis instance (required if queueClient is not supplied)
redis.port | the port of the redis instance (required if queueClient is not supplied)
redis.queueClient | a writable redis client instance. ioRedis is used internally, but can be most clients.
redis.blockingQueueClientFunction | a 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
log | a function which will be called with a string parameter containing Error info.

### Events
Option | Description
------------ | -------------
redis | object detailing redis configuration
redis.host | the host of the redis instance (required if subHost or sub/pubClients are not supplied)
redis.port | the port of the redis instance (required if pubHost or sub/pubClients are not supplied)
redis.subClient | a readable redis client instance. ioRedis is used internally, but can be most clients.
redis.pubClient | a writable redis client instance. ioRedis is used internally, but can be most clients.
redis.subHost  | the host of a readable redis instance (used to specify different hosts/ports between sub/pub clients)
redis.subPort | the port of a readable redis instance (used to specify different hosts/ports between sub/pub clients)
redis.pubHost  | the host of a readable redis instance (used to specify different hosts/ports between sub/pub clients)
redis.pubPort | the port of a readable redis instance (used to specify different hosts/ports between sub/pub clients)
log | a 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

---
_Source: https://npm.io/package/aframework.events · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._