https://github.com/aaronjan/stanchionjs
A simple & fast queue done right. backed by Redis, supports auto-reconnect, TypeScript, Promise and Rxjs.
https://github.com/aaronjan/stanchionjs
nodejs queue redis rxjs rxjs5 simple typescript
Last synced: about 1 year ago
JSON representation
A simple & fast queue done right. backed by Redis, supports auto-reconnect, TypeScript, Promise and Rxjs.
- Host: GitHub
- URL: https://github.com/aaronjan/stanchionjs
- Owner: AaronJan
- License: apache-2.0
- Created: 2017-08-16T11:46:25.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2018-02-05T08:22:19.000Z (over 8 years ago)
- Last Synced: 2025-04-09T09:04:03.532Z (about 1 year ago)
- Topics: nodejs, queue, redis, rxjs, rxjs5, simple, typescript
- Language: TypeScript
- Homepage: https://github.com/AaronJan/StanchionJS
- Size: 25.4 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
StanchionJS
A simple & fast queue done right. backed by Redis, supports auto-reconnect, TypeScript, Promise and Rxjs.
## Features
- **Fast.** Just `BLPOP` and `RPUSH`, no other fancy stuff, simple and fast.
- **Auto-Reconnect.**
- **Works with Promise.** Unleash the power of `async / await`, say bye-bye to callback.
- **Better error handling.**
- **Written in TypeScript.** No hacky code and provides better experience if you are using `TypeScript`.
- **Reactive.** If you don't like making promises, there're reactive APIs too, all APIs have two versions.
## Installation
```
$ npm i stanchionjs
```
## Examples
### Initialize
```javascript
const { Stanchion } = require('stanchionjs');
const stanchion = new Stanchion({
redis: {
host: '127.0.0.1',
port: 6379,
db: '1',
},
concurrency: 20,
});
```
### How To Create a Job
```javascript
const { Stanchion } = require('stanchionjs');
const stanchion = new Stanchion();
// Payload will be serialized using `JSON.stringify`
const job_1 = {
thing: 'apple',
};
const job_2 = {
thing: 'banana',
};
//
// Promise way:
//
stanchion.push(job_1, job_2).then(() => {
console.log('jobs created.');
});
//
// Rxjs way:
//
stanchion.push$(job_1, job_2).subscribe(() => {
console.log('jobs created.');
});
```
### How To Process a Job
When a Job processing is done, you must tell `StanchionJS` so it can go fetching next Job for you. `StanchionJS` provides several ways to do that:
```javascript
const { Stanchion } = require('stanchionjs');
const { Observable } = require('rxjs'); // Not required.
const stanchion = new Stanchion();
//
// Promise way:
//
stanchion.process(job => new Promise((resolve, reject) => {
console.log('Got a job:', job);
resolve();
}));
//
// Async / Await way:
//
stanchion.process(async job => {
console.log('Got a job:', job);
});
//
// Rxjs way:
//
stanchion.process$(
job => Observable.of(job)
.map(job => {
console.log('Got a job:', job);
})
).subscribe(); // Don't forget to subscribe!
```
### Error Handling
Every exception (including those from `redis`) can be obtained by attach handler to `Stanchion` instance:
```javascript
const { Stanchion } = require('stanchionjs');
const stanchion = new Stanchion();
//
// Callback handler:
//
stanchion.onError(err => {
console.log('error occurred', err);
});
//
// Rxjs stream:
//
stanchion.onError$().subscribe(err => {
console.log('error occurred', err);
});
```
### How To Exit
```javascript
const { Stanchion } = require('stanchionjs');
const stanchion = new Stanchion();
//
// Promise way:
//
stanchion.shutdown().then(() => {
console.log('Stanchion exited.');
});
//
// Rxjs way:
//
stanchion.shutdown$().subscribe(() => {
console.log('Stanchion exited.');
});
```
### When Exited
```javascript
const { Stanchion } = require('stanchionjs');
const stanchion = new Stanchion();
//
// Promise way:
//
stanchion.onShutdowned(() => {
console.log('Stanchion exited.');
});
//
// Rxjs way:
//
stanchion.onShutdowned$().subscribe(() => {
console.log('Stanchion exited.');
});
```
## Reference
### Interfaces
#### ConstructOptions
Default value:
```javascript
{
// Redis configuration.
redis: {
host: '127.0.0.1',
port: 6739,
},
// If you have lots of I/O intensive jobs, increase this may help.
concurrency: 10,
// Redis key for this queue.
// Stanchion also support multiple keys, just use:
// rediskey: ['stanchion_queue1', 'stanchion_queue2']
redisKey: 'stanchion_queue',
// How many times you want Stanchion to try reconnecting when connection is lost.
retryAttempts: 6,
}
```
### Stanchion
#### Stanchion#constructor
```typescript
constructor(options: ConstructOptions)
```
#### Stanchion#push
```typescript
push(...jobs: any[]): Promise
```
#### Stanchion#push$
```typescript
push$(...jobs: any[]): Observable
```
#### Stanchion#getSize
```typescript
getSize(): Promise
```
#### Stanchion#getSize$
```typescript
getSize$(): Observable
```
#### Stanchion#onError
```typescript
onError(handler: ErrorHandler): Subscription
```
#### Stanchion#onError$
```typescript
onError$(): Subject
```
#### Stanchion#process
```typescript
process(processor: PromiseProcessor): Promise
```
#### Stanchion#process$
```typescript
process$(processor: ObservableProcessor): Observable
```
#### Stanchion#shutdown
```typescript
shutdown(): Promise
```
#### Stanchion#shutdown$
```typescript
shutdown$(): Observable
```
#### Stanchion#isShutdowned
```typescript
isShutdowned(): boolean
```
#### Stanchion#onShutdowned
```typescript
onShutdowned(cb: VoidFunction): Subscription
```
#### Stanchion#onShutdowned$
```typescript
onShutdowned$(): Observable
```
## TODOs
- Tests. Although Stanchion is bettle-tested, handling about 26K jobs per second.
- Multiple queue (Redis key) support.
- "unprocess" method.
- Key-sharding support for cluster usage.
## Credits
Awesome icon by [Freepik](http://www.freepik.com), licensed under the [Creative Commons BY 3.0](http://creativecommons.org/licenses/by/3.0/).
Inspired by [Neamar/featureless-job-queue](https://github.com/Neamar/featureless-job-queue).