A simple API response caching middleware for Express/Node using plain-english durations.
Supports Redis or built-in memory engine with auto-clearing.
Because route-caching of simple data/responses should ALSO be simple.
$ npm install --save apicache
$ npm install -D @types/apicache
To use, simply inject the middleware (example:
apicache.middleware('5 minutes', [optionalMiddlewareToggle])) into your routes. Everything else is automagic.
Cache a route
let app =let cache = apicachemiddlewareapp
Cache all routes
let cache = apicachemiddlewareappapp
Use with Redis
let app =// if redisClient option is defined, apicache will use redis client// instead of built-in memory storelet cacheWithRedis = apicacheoptions redisClient: redismiddlewareapp
Cache grouping and manual controls
let cache = apicachemiddlewareapp// routes are automatically added to index, but may be further added// to groups for quick deleting of collectionsapp// add route to display cache indexapp// add route to manually clear target/groupapp/*GET /api/foo/bar --> caches entry at /api/foo/bar and adds a group called 'foo' to indexGET /api/cache/index --> displays indexGET /api/cache/clear/foo --> clears all cached entries for 'foo' group/collection*/
Use with middleware toggle for fine control
// higher-order function returns false for responses of other status codes (e.g. 403, 404, 500, etc)const onlyStatus200 = resstatusCode === 200const cacheSuccesses =appapp
Prevent cache-control header "max-age" from automatically being set to expiration age
let cache = apicacheoptionsheaders:'cache-control': 'no-cache'middlewarelet cache5min = // continue to use normally
apicache.options([globalOptions])- getter/setter for global options. If used as a setter, this function is chainable, allowing you to do things such as... say... return the middleware.
apicache.middleware([duration], [toggleMiddleware], [localOptions])- the actual middleware that will be used in your routes.
durationis in the following format "[length] [unit]", as in
"1 day". A second param is a middleware toggle function, accepting request and response params, and must return truthy to enable cache for the request. Third param is the options that will override global ones and affect this middleware only.
middleware.options([localOptions])- getter/setter for middleware-specific options that will override global ones.
apicache.getIndex()- returns current cache index [of keys]
apicache.clear([target])- clears cache target (key or group), or entire cache if no value passed, returns new index.
apicache.newInstance([options])- used to create a new ApiCache instance (by default, simply requiring this library shares a common instance)
apicache.clone()- used to create a new ApiCache instance with the same options as the current one
Available Options (first value is default)
debug: false|true // if true, enables console outputdefaultDuration: '1 hour' // should be either a number (in ms) or a string, defaults to 1 hourenabled: true|false // if false, turns off caching globally (useful on dev)redisClient: client // if provided, uses the [node-redis]() client instead of [memory-cache]()appendKey: // appendKey takes the req/res objects and returns a custom value to extend the cache keyheaderBlacklist: // list of headers that should never be cachedstatusCodes:exclude: // list status codes to specifically exclude (e.g. [404, 403] cache all responses unless they had a 404 or 403 status)include: // list status codes to require (e.g.  caches ONLY responses with a success/200 code)headers:// 'cache-control': 'no-cache' // example of header overwrite
Custom Cache Keys
Sometimes you need custom keys (e.g. save routes per-session, or per method). We've made it easy!
Note: All req/res attributes used in the generation of the key must have been set previously (upstream). The entire route logic block is skipped on future cache hits so it can't rely on those params.
apicacheoptionsreqmethod + ressessionid
Cache Key Groups
Oftentimes it benefits us to group cache entries, for example, by collection (in an API). This
would enable us to clear all cached "post" requests if we updated something in the "post" collection
for instance. Adding a simple
req.apicacheGroup = [somevalue]; to your route enables this. See example below:
var apicache =var cache = apicachemiddleware// GET collection/idapp;// POST collection/idapp;
Additionally, you could add manual cache control to the previous project with routes such as these:
// GET apicache index (for the curious)app;// GET apicache index (for the curious)app;
debug module)Using Node environment variables (plays nicely with the hugely popular
$ export DEBUG=apicache $ export DEBUG=apicache,othermoduleThatDebugModuleWillPickUp,etc
By setting internal option
apicacheoptions debug: true
GET routes between admin and public sites, you'll likely want the
routes to be cached from your public client, but NOT cached when from the admin client. This
is achieved by sending a
"x-apicache-bypass": true header along with the requst from the admin.
The presence of this header flag will bypass the cache, ensuring you aren't looking at stale data.
Special thanks to all those that use this library and report issues, but especially to the following active users that have helped add to the core functionality!
- @svozza - added restify tests, test suite refactor, and fixed header issue with restify. Node v7 + Restify v5 conflict resolution, etag/if-none-match support, etcetc, etc. Triple thanks!!!
- @andredigenova - Added header blacklist as options, correction to caching checks
- @peteboere - Node v7 headers update
- @rutgernation - JSONP support
- @enricsangra - added x-apicache-force-fetch header
- @tskillian - custom appendKey path support
- @agolden - Content-Encoding preservation (for gzip, etc)
- @davidyang - express 4+ compatibility
- @nmors - redis support
- @maytis, @ashwinnaidu - redis expiration
- @killdash9 - restify support and response accumulator method
- @ubergesundheit - Corrected buffer accumulation using res.write with Buffers
- @danielsogl - Keeping dev deps up to date, Typescript Types
- @vectart - Added middleware local options support
- @davebaol - Added string support to defaultDuration option (previously just numeric ms)
- @Rauttis - Added ioredis support
Bugfixes, Documentation, etc.
- @Amhri, @Webcascade, @conmarap, @cjfurelid, @scambier, @lukechilds, @Red-Lv, @gesposito, @viebel, @RowanMeara, @GoingFast, @luin
- v0.4.0 - dropped lodash and memory-cache external dependencies, and bumped node version requirements to 4.0.0+ to allow Object.assign native support
- v0.5.0 - updated internals to use res.end instead of res.send/res.json/res.jsonp, allowing for any response type, adds redis tests
- v0.6.0 - removed final dependency (debug) and updated README
- v0.7.0 - internally sets cache-control/max-age headers of response object
- v0.8.0 - modifies response accumulation (thanks @killdash9) to support res.write + res.end accumulation, allowing integration with restify. Adds gzip support (Node v4.3.2+ now required) and tests.
- v0.8.1 - fixed restify support and added appropriate tests (thanks @svozza)
- v0.8.2 - test suite and mock API refactor (thanks @svozza)
- v0.8.3 - added tests for x-apicache-bypass and x-apicache-force-fetch (legacy) and fixed a bug in the latter (thanks @Red-Lv)
- v0.8.4 - corrected buffer accumulation, with test support (thanks @ubergesundheit)
- v0.8.5 - dev dependencies update (thanks @danielsogl)
- v0.8.6, v0.8.7 - README update
- v0.8.8 - corrected to use node v7+ headers (thanks @peteboere)
- v0.9.0 - corrected Node v7.7 & v8 conflicts with restify (huge thanks to @svozza for chasing this down and fixing upstream in restify itself). Added coveralls. Added middleware.localOptions support (thanks @vectart). Added ability to overwrite/embed headers (e.g. "cache-control": "no-cache") through options.
- v0.9.1 - added eslint in prep for v1.x branch, minor ES6 to ES5 in master branch tests
- v0.10.0 - added ability to blacklist headers (prevents caching) via options.headersBlacklist (thanks @andredigenova)
- v0.11.0 - Added string support to defaultDuration option, previously just numeric ms - thanks @davebaol
- v0.11.1 - correction to status code caching, and max-age headers are no longer sent when not cached. middlewareToggle now works as intended with example of statusCode checking (checks during shouldCacheResponse cycle)
- v0.11.2 - dev-deps update, courtesy of @danielsogl
- v1.0.0 - stamping v0.11.2 into official production version, will now begin developing on branch v2.x (redesign)
- v1.1.0 - added the much-requested feature of a custom appendKey function (previously only took a path to a single request attribute). Now takes (request, response) objects and returns some value to be appended to the cache key.
- v1.1.1 - bugfixes in expiration timeout clearing and content header preservation under compression (thanks @RowanMeara and @samimakicc).
- v1.2.0 - Supports ioredis (thanks @Rauttis)
- v1.2.1 - Updated deps
- v1.2.2 - bugfix: ioredis.expire params (thanks @GoingFast and @luin)
- v1.2.3 - add etag to if-none-match 304 support (thanks for the test/issue @svozza)