HTTP Cache Middleware

Common errors

• Redis store error when passing empty keys array to cache.del

  cause Older versions of the middleware (prior to v1.3.10) would throw an error if an `x-cache-expire` pattern resulted in an empty array of keys to be deleted from the Redis cache.
  fix Upgrade `http-cache-middleware` to version 1.3.10 or newer. This version includes a fix that gracefully handles empty key arrays.

• Wildcard patterns in x-cache-expire are not invalidating expected entries

  cause Versions prior to 1.3.8 had a bug where wildcard pattern support for cache invalidation was not working correctly.
  fix Update `http-cache-middleware` to version 1.3.8 or newer. Ensure your patterns are valid according to the `matcher` package syntax (e.g., `*/users` to match all paths ending with `/users`).

• TypeError: middleware is not a function

  cause In CommonJS environments, the `require('http-cache-middleware')` call returns a factory function, which must then be invoked to get the actual middleware instance. Developers often forget to call this function.
  fix Ensure you invoke the factory function: `const middleware = require('http-cache-middleware')();`

Warnings

• gotcha The `ms` package, used for parsing `x-cache-timeout` header values, does not support the 'millisecond' unit. Ensure you use supported units like 'second', 'minute', 'hour', etc.
  Fix: Use supported units for `x-cache-timeout` (e.g., '1s', '1m', '1h') or provide a numerical value in seconds directly if using an alternative method for timeout.
• gotcha When using `x-cache-timeout` to automatically generate `Cache-Control` and `ETag` headers for browser caching, these generated headers will only be observable on subsequent requests *after* the initial response has been cached (i.e., on a cache hit).
  Fix: Be aware that the first request to a resource will not contain the generated browser cache headers. These headers appear only once the response is stored in the internal `http-cache-middleware` cache and subsequently served from it.
• breaking Fixes were introduced in v1.3.8 for wildcard pattern support in `x-cache-expire` that were previously not working as described. If you relied on broken behavior or custom workarounds, this fix might change behavior.
  Fix: Ensure your `x-cache-expire` patterns are correctly defined according to `matcher` package specifications. Review any existing invalidation logic that might have worked around the previous bug.
• breaking Version 1.3.5 introduced ordered, two-step async cache writing to prevent timing issues under high concurrency. While a fix, systems relying on specific concurrent cache writing behaviors might observe changes.
  Fix: No direct fix needed, but be aware of this change if you have observed or relied on specific timing in cache write operations under heavy load. This is generally a stability improvement.
• breaking A critical bug in v1.3.10 fixed `redis store error when passing empty keys array` to `cache.del`. Older versions would throw an error if an empty array was passed for cache invalidation.
  Fix: Update to `v1.3.10` or newer to prevent errors when calling `cache.del` (implicitly via `x-cache-expire`) with patterns that resolve to an empty set of keys.
• breaking The integration of `iff` and `unless` utility functions was fixed in v1.4.1. Previous versions might have had inconsistent or incorrect conditional middleware execution.
  Fix: Ensure you are on v1.4.1 or newer for reliable conditional middleware behavior using `iff` or `unless`.

Install

• npm install http-cache-middleware npm
• yarn add http-cache-middleware yarn
• pnpm add http-cache-middleware pnpm

Imports

• middleware
  wrong:

  import { middleware } from 'http-cache-middleware'

  correct:

  import createCacheMiddleware from 'http-cache-middleware'; const middleware = createCacheMiddleware();

  The package exports a default function that, when called, returns the middleware instance. It's typically used as a default import in ESM or a direct require call in CJS.
• CacheManager
  wrong:

  import CacheManager from 'cache-manager'

  correct:

  import { caching } from 'cache-manager'; const redisCache = caching({ store: redisStore, ... });

  When integrating with specific `cache-manager` stores, you'll import `caching` and `redisStore` (or other store implementations) directly from `cache-manager` and its respective store packages.
• httpCacheMiddleware
  wrong:

  const httpCacheMiddleware = require('http-cache-middleware')

  correct:

  const httpCacheMiddleware = require('http-cache-middleware')();

  In CommonJS, the `require` call directly returns the factory function, which must then be invoked to get the middleware instance. Omitting the `()` will result in a function, not the middleware itself.

Quickstart

This quickstart demonstrates how to initialize the HTTP cache middleware with `restana`, set a cache timeout for a GET endpoint, and invalidate it using a DELETE request with `x-cache-expire`.

import createCacheMiddleware from 'http-cache-middleware';
import restana from 'restana';

const middleware = createCacheMiddleware();
const service = restana();

service.use(middleware);

service.get('/cache-on-get', (req, res) => {
  setTimeout(() => {
    res.setHeader('x-cache-timeout', '1 minute');
    res.send('this supposed to be a cacheable response, fetched at ' + new Date().toISOString());
  }, 50);
});

service.delete('/invalidate-cache', (req, res) => {
  // Simulate a data change that requires cache invalidation
  console.log('Invalidating cache for /cache-on-get');
  res.setHeader('x-cache-expire', '*/cache-on-get');
  res.send('Cache invalidated');
});

const port = process.env.PORT || 3000;
service.start(port).then(() => {
  console.log(`Server started on port ${port}`);
  console.log(`Try: curl http://localhost:${port}/cache-on-get`);
  console.log(`Then: curl http://localhost:${port}/invalidate-cache`);
  console.log(`Then: curl http://localhost:${port}/cache-on-get again`);
});