automatically provides polling responses for long running operations

Usage no npm install needed!

<script type="module">
  import expressDelayedResponse from '';



npm version Build Status Coverage Status

Break long running processes into multiple requests with a status end point.


Use delay middleware to automatically provide polling and status functionality to following handlers.

const { delay } = require('express-delayed-response').init();

app.get('/path', delay(), potentiallySlowHandler);


By default delay will respond within 5 seconds, either with the handler response or a 202 Accepted response. This can be modified with the timeout option.

// provide the timeout in milliseconds (wait 30 seconds)
app.get('/path', delay({ timeout: 30000 }), potentiallySlowHandler);


Use status middleware to query operation status and get cached responses.

If the operation is still processing then it will return a 202 Accepted response; otherwise, it will return the cached response from the initial operation.

const { status } = require('express-delayed-response').init();

app.get('/status/:id', status());


By default, status uses the id path parameter to resolve the id of the status object to query against. To override this behavior provide a resolveID method to the options.

app.get('/status', status({
    resolveID: req => req.headers['X-STATUS-ID']

Redis Support

By default an in-memory LRU cache with 5000 entries is used to store the responses. If needed, a Redis client can be used as the cache client in place of the LRU cache.

const redis = require('redis');
const { delay, status } = require('express-delayed-response').init({ cacheClient: redis.createClient() });

The values are stored in a hash with the key express-delayed-response to customize this key supply the cacheKey option to init

const { delay, status } = require('express-delayed-response').init({ 
    cacheClient: redis.createClient(), 
    cacheKey: 'delay-key',

Set LRU options

If working in a limited memory environment, it may be necessary to control the LRU cache. Use createCacheClient to supply options to the lru-cache instance used.

const delayedResponse = require('express-delayed-response');

const { delay, status } = delayedResponse.init({ 
    cacheClient: delayedResponse.createCacheClient({ 
        max: 500,

The cache client uses lru-cache and the options are passed directly to the LRU instace created.


While the client is waiting for the server to resolve it is possible to provide status indications to the client via the status end point.

delay adds the progress method to response that accepts a string or json argument that is added to the status response progress field.

app.use(delay(), (req, res, next) => {
    const items = req.body.items;
    const state = { completed: 0, of: items.length };
    const requests = => (
        processItem(item).then((result) => {
            return result;
    Promise.all(requests).then((data) => {
        res.json({ data });

Then on a status query:

    "id": "Rasdclajs-",
    "progress": {
        "completed": 10,
        "of": 200