cache-express-az v2.0.2
A simple API response caching middleware for Express/Node using durations.
Supports Redis or built-in memory engine with auto-clearing.
Hello I am Aawez Khan aawez@nodejs.community Thanks @node-community
Why?
Because route-caching of simple data/responses should ALSO be simple.
Usage
To use, simply inject the middleware (example: cache_express.middleware('5 minutes', [optionalMiddlewareToggle])
) into your routes. Everything else is automagic.
Cache a route
import express from 'express'
import cache_express from 'cache-express-az'
let app = express()
let cache = cache_express.middleware
app.get('/api/collection/:id?', cache('5 minutes'), (req, res) => {
// do some work... this will only occur once per 5 minutes
res.json({ foo: 'bar' })
})
Cache all routes
let cache = cache_express.middleware
app.use(cache('5 minutes'))
app.get('/will-be-cached', (req, res) => {
res.json({ success: true })
})
Use with Redis
import express from 'express'
import cache_express from 'cache-express-az'
import redis from 'redis'
let app = express()
// if redisClient option is defined, cache_express will use redis client
// instead of built-in memory store
let cacheWithRedis = cache_express.options({ redisClient: redis.createClient() }).middleware
app.get('/will-be-cached', cacheWithRedis('5 minutes'), (req, res) => {
res.json({ success: true })
})
Cache grouping and manual controls
import cache_express from 'cache-express-az'
let cache = cache_express.middleware
app.use(cache('5 minutes'))
// routes are automatically added to index, but may be further added
// to groups for quick deleting of collections
app.get('/api/:collection/:item?', (req, res) => {
req.cache_expressGroup = req.params.collection
res.json({ success: true })
})
// add route to display cache performance (courtesy of @killdash9)
app.get('/api/cache/performance', (req, res) => {
res.json(cache_express.getPerformance())
})
// add route to display cache index
app.get('/api/cache/index', (req, res) => {
res.json(cache_express.getIndex())
})
// add route to manually clear target/group
app.get('/api/cache/clear/:target?', (req, res) => {
res.json(cache_express.clear(req.params.target))
})
/*
GET /api/foo/bar --> caches entry at /api/foo/bar and adds a group called 'foo' to index
GET /api/cache/index --> displays index
GET /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 = (req, res) => res.statusCode === 200
const cacheSuccesses = cache('5 minutes', onlyStatus200)
app.get('/api/missing', cacheSuccesses, (req, res) => {
res.status(404).json({ results: 'will not be cached' })
})
app.get('/api/found', cacheSuccesses, (req, res) => {
res.json({ results: 'will be cached' })
})
Prevent cache-control header "max-age" from automatically being set to expiration age
let cache = cache_express.options({
headers: {
'cache-control': 'no-cache',
},
}).middleware
let cache5min = cache('5 minute') // continue to use normally
API
cache_express.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.cache_express.middleware([duration], [toggleMiddleware], [localOptions])
- the actual middleware that will be used in your routes.duration
is in the following format "length", as in"10 minutes"
or"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.cache_express.getPerformance()
- returns current cache performance (cache hit rate)cache_express.getIndex()
- returns current cache index of keyscache_express.clear([target])
- clears cache target (key or group), or entire cache if no value passed, returns new index.cache_express.newInstance([options])
- used to create a new cache_express instance (by default, simply requiring this library shares a common instance)cache_express.clone()
- used to create a new cache_express instance with the same options as the current one
Available Options (first value is default)
{
debug: false|true, // if true, enables console output
defaultDuration: '1 hour', // should be either a number (in ms) or a string, defaults to 1 hour
enabled: true|false, // if false, turns off caching globally (useful on dev)
redisClient: client, // if provided, uses the [node-redis](https://github.com/NodeRedis/node_redis) client instead of [memory-cache](https://github.com/ptarjan/node-cache)
appendKey: fn(req, res), // appendKey takes the req/res objects and returns a custom value to extend the cache key
headerBlacklist: [], // list of headers that should never be cached
statusCodes: {
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. [200] caches ONLY responses with a success/200 code)
},
trackPerformance: false, // enable/disable performance tracking... WARNING: super cool feature, but may cause memory overhead issues
headers: {
// 'cache-control': 'no-cache' // example of header overwrite
},
respectCacheControl: false|true // If true, 'Cache-Control: no-cache' in the request header will bypass the cache.
}
*Optional: Typescript Types (courtesy of @danielsogl)
$ npm install -D @types/cache_express
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.
cache_express.options({
appendKey: (req, res) => req.method + res.session.id,
})
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.cache_expressGroup = [somevalue];
to your route enables this. See example below:
var cache_express = require('cache-express-az')
var cache = cache_express.middleware
// GET collection/id
app.get('/api/:collection/:id?', cache('1 hour'), function(req, res, next) {
req.cache_expressGroup = req.params.collection
// do some work
res.send({ foo: 'bar' })
})
// POST collection/id
app.post('/api/:collection/:id?', function(req, res, next) {
// update model
cache_express.clear(req.params.collection)
res.send('added a new item, so the cache has been cleared')
})
Additionally, you could add manual cache control to the previous project with routes such as these:
// GET cache_express index (for the curious)
app.get('/api/cache/index', function(req, res, next) {
res.send(cache_express.getIndex())
})
// GET cache_express index (for the curious)
app.get('/api/cache/clear/:key?', function(req, res, next) {
res.send(200, cache_express.clear(req.params.key || req.query.key))
})
Debugging/Console Out
Using Node environment variables (plays nicely with the hugely popular debug module)
$ export DEBUG=cache_express
$ export DEBUG=cache_express,othermoduleThatDebugModuleWillPickUp,etc
By setting internal option
import cache-express-az from 'cache-express-az'
cache_express.options({ debug: true })
Client-Side Bypass
When sharing 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-cache_express-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.