Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/guidesmiths/stashback
A library for stashing and retrieving callbacks
https://github.com/guidesmiths/stashback
hacktoberfest
Last synced: 2 months ago
JSON representation
A library for stashing and retrieving callbacks
- Host: GitHub
- URL: https://github.com/guidesmiths/stashback
- Owner: guidesmiths
- Created: 2015-03-22T22:37:40.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2023-01-08T19:18:06.000Z (about 2 years ago)
- Last Synced: 2024-10-14T11:14:39.788Z (3 months ago)
- Topics: hacktoberfest
- Language: JavaScript
- Size: 684 KB
- Stars: 8
- Watchers: 13
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
## Stashback
[](https://github.com/guidesmiths/stashback/actions/workflows/node-js-ci.yml)
[](https://www.npmjs.com/package/stashback)
[](https://www.npmjs.com/package/stashback)
[](https://codeclimate.com/github/guidesmiths/stashback)
[](https://codeclimate.com/github/guidesmiths/stashback/coverage)
[](https://github.com/prettier/prettier)
[](https://snyk.io/advisor/npm-package/stashback)
[](https://www.npmjs.com/package/zunit)
Stashback is a library for stashing and retrieving callbacks in a decoupled request/response workflow. Its primary use case is to enable code within an http request/response sequence to publish a message to an ESB, e.g. [RabbitMQ](http://www.rabbitmq.com/) and wait for a reply.
### Installation
```bash
npm install stashback
```
### Example Usage (Express)
```js
const rabbitmq = require('./my-rabbitmq-client');
const express = require('express');
const { v4: uuid } = require('uuid');
const stashback = require('stashback')({ timeout: 5000 });
var app = express();
app.get('/greet/:id', function (req, res, next) {
// Generate a unique id for the callback
var callbackId = uuid();
// Define the callback
var callback = (err, user) => {
if (err) return next(err);
res.send(`Hello ${user.name}`);
};
// Stash the callback for later execution
stashback.stash(callbackId, callback, (err) => {
// An error will occur if you've used a duplicate callbackId.
if (err) return next(err);
// Publish the message to the ESB, requesting user for the specified id. Using rabbitmq as an example.
rabbitmq.publish({ callbackId, userId: req.params.id });
});
});
app.listen(3000);
function onMessage(message) {
// When we receive the user response unstash the callback using the callbackId specified in the message
stashback.unstash(message.callbackId, (err, cb) => {
// Execute the callback passing it the user object (the callback will be a no-op if something went wrong)
cb(err, message.user);
});
}
```
### Callback Expiry
In order to prevent a slow memory leak and to abort slow running requests it's a good idea to configure stashback with a timeout. This can be done globally and for each 'stash' operation. See the [api](api.md) for more details.
### Duplicates
Attempting to 'stash' multiple callbacks with the same id results in an error. Attempting to 'unstash' a callback twice (or after it has expired) results in both an error and a no-op callback being returned. i.e.
```js
stashback.unstash('never-stashed-or-expired', function (err, callback) {
assert.equal(err.message, 'Unknown key: never-stashed-or-expired');
assert.equal(typeof callback, 'function');
});
```
### API
#### options
Returns a configured stashback object
| Param | Type | Description |
| ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| options | Object | |
| options.timeout | milliseconds | This timeout is applied to the callback being stashed. If the timeout is exceeded the callback is executed with an error object. |
| options.onUnknownKey | function | Function to be executed when instructed to unstash an unknown (or expired) key. It will be invoked with the key and next parameters. |
| options.onDuplicateKey | function | Function to be executed when instructed to stash a duplicate key. It will be invoked with the key and next parameters. |
| options.onExpiry | function | Function to be executed after expiring a key. It will be invoked with the key and callback to be expired. |
#### stash
Stashes a callback for subsequent retrieval
| Param | Type | Description |
| ---------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| key | String | The callback id |
| callback | function | The callback to be stashed |
| options | Object | |
| options.timeout | milliseconds | This timeout is applied to the callback being stashed. If the timeout is exceeded the callback is executed with an error object. |
| options.onDuplicateKey | function | Function to be executed when instructed to stash a duplicate key. It will be invoked with the key and next parameters. |
| options.onExpiry | function | Function to be executed after expiring a key. It will be invoked with the key and next parameters. |
| next | callback | Callback which will be invoked an the error object |
#### unstash
Unstashes a callback for execution
| Param | Type | Description |
| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | String | The callback id |
| options | Object | |
| options.onUnknownKey | function | Function to be executed when instructed to unstash an unknown (or expired) key. Will be invoked with the key and next parameters. |
| next | callback | Callback which will be invoked with the error object and the unstashed callback (or no-op function if the callback was not found or has expired). |
#### unstashAll
Unstashes all callbacks for execution
| Param | Type | Description |
| ------- | --------------------- | ----------------------------------------------------------------------------------------- |
| options | Object | |
| next | callback | Callback which will be invoked with the error object and an array of unstashed callbacks. |
#### stats
Provides statistics
**Returns**: Object - stats An object containing the number of 'stashed' and 'expired' callbacks