stashback

    2.0.1 • Public • Published

    Stashback

    CI NPM version NPM downloads Code Climate Test Coverage Code Style stashback Discover 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 and wait for a reply.

    Installation

    npm install stashback

    Example Usage (Express)

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

    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

    Install

    npm i stashback

    DownloadsWeekly Downloads

    14,461

    Version

    2.0.1

    License

    ISC

    Unpacked Size

    19.6 kB

    Total Files

    16

    Last publish

    Collaborators

    • cressie176
    • ulisesgascon
    • feliun
    • guidesmiths_bot