stashback

Stashback


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 and wait for a reply.

$3

``bash
npm install stashback
`

$3

`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);
});
}
`

$3

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 for more details.

$3

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');
});
``

$3

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