Registry / http-networking / http-cache-middleware

http-cache-middleware

library1.4.1jsnpmunverified

http-cache-middleware is a high-performance connect-like HTTP cache middleware designed for Node.js applications. It leverages the popular `cache-manager` package, providing flexibility to integrate various storage engines like in-memory, Redis, and more. The library significantly reduces latency by enabling robust caching strategies, capable of improving response times from tens of milliseconds down to single digits. It supports custom `x-cache-timeout` and `x-cache-expire` headers for fine-grained control over cache entry and invalidation using glob patterns. Additionally, it transparently handles standard HTTP `Cache-Control` and `ETag` headers to facilitate browser-side caching and validation. The current stable version is 1.4.1, with recent updates indicating an active maintenance and development cadence focused on fixes and dependency updates, with minor cumulative releases.

http-networking database

npm install http-cache-middleware

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-CACHE-MIDDLEW

http-cache-middleware

http-networkingjavascriptv1.4.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

middleware

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

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

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

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

✗ import CacheManager from 'cache-manager'

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

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

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

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

Debug

Known issues

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

affects: >=1.0.0

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

affects: >=1.2.0

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

affects: >=1.3.8

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

affects: >=1.3.5

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

affects: >=1.3.10

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

affects: >=1.4.1

Errors

Common errors & fixes

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

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

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

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

Upgrade

Version history

1.4.1latest on npm

Audit

Dependencies

cache-managerrequiredCore caching layer, providing extensibility for various storage engines (e.g., Memory, Redis).

msrequiredUsed for parsing human-readable time strings (e.g., '1 minute', '1 hour') for cache timeouts.

matcherrequiredPowers the pattern matching for cache invalidation using the `x-cache-expire` header.

middleware-if-unlessrequiredProvides conditional execution logic for the middleware, fixed in v1.4.1 for proper integration.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/jkyberneees/http-cache-middleware ↗

packagehttps://www.npmjs.com/package/http-cache-middleware ↗