Wrap native HTTP requests with RFC compliant cache support
RFC 7234 compliant HTTP caching for native Node.js HTTP/HTTPS requests. Caching works out of the box in memory or is easily pluggable with a wide range of storage adapters.
Note: This is a low level wrapper around the core HTTP modules, it's not a high level request library.
Keyv has been updated to version 5. With this update, you can no longer pass in a connection string directly to the CacheableRequest constructor. Instead, you should pass in a Keyv or Keyv storage adapter instance.
Breaking Changes with v10.0.0
This release contains breaking changes. This is the new way to use this package.
Usage Before v10
import http from 'http';import CacheableRequest from 'cacheable-request';// Then instead ofconst req = http.request('http://example.com', cb);req.end();// You can doconst cacheableRequest = new CacheableRequest(http.request);const cacheReq = cacheableRequest('http://example.com', cb);cacheReq.on('request', req => req.end());// Future requests to 'example.com' will be returned from cache if still valid// You pass in any other http.request API compatible method to be wrapped with cache support:const cacheableRequest = new CacheableRequest(https.request);const cacheableRequest = new CacheableRequest(electron.net);
Usage After v10.1.0
import CacheableRequest from 'cacheable-request';// Now You can doconst cacheableRequest = new CacheableRequest(http.request).request();const cacheReq = cacheableRequest('http://example.com', cb);cacheReq.on('request', req => req.end());// Future requests to 'example.com' will be returned from cache if still valid// You pass in any other http.request API compatible method to be wrapped with cache support:const cacheableRequest = new CacheableRequest(https.request).request();const cacheableRequest = new CacheableRequest(electron.net).request();
The biggest change is that when you do a new CacheableRequest you now want to call request method will give you the instance to use.
- const cacheableRequest = new CacheableRequest(http.request);+ const cacheableRequest = new CacheableRequest(http.request).request();
import http from 'http';import CacheableRequest from 'cacheable-request';// Then instead ofconst req = http.request('http://example.com', cb);req.end();// You can doconst cacheableRequest = new CacheableRequest(http.request).createCacheableRequest();const cacheReq = cacheableRequest('http://example.com', cb);cacheReq.on('request', req => req.end());// Future requests to 'example.com' will be returned from cache if still valid// You pass in any other http.request API compatible method to be wrapped with cache support:const cacheableRequest = new CacheableRequest(https.request).createCacheableRequest();const cacheableRequest = new CacheableRequest(electron.net).createCacheableRequest();
Storage Adapters
cacheable-request uses Keyv to support a wide range of storage adapters.
For example, to use Redis as a cache backend, you just need to install the official Redis Keyv storage adapter:
npm install @keyv/redis
And then you can pass CacheableRequest your connection string:
import KeyvRedis from '@keyv/redis';import CacheableRequest from 'cacheable-request';const keyvRedis = new KeyvRedis('redis://localhost:6379');const cacheableRequest = new CacheableRequest(http.request, KeyvRedis).createCacheableRequest();
If the cache should be used. Setting this to false will completely bypass the cache for the current request.
opts.strictTtl
Type: boolean
Default: false
If set to true once a cached resource has expired it is deleted and will have to be re-requested.
If set to false (default), after a cached resource's TTL expires it is kept in the cache and will be revalidated on the next request with If-None-Match/If-Modified-Since headers.
opts.maxTtl
Type: number
Default: undefined
Limits TTL. The number represents milliseconds.
opts.automaticFailover
Type: boolean
Default: false
When set to true, if the DB connection fails we will automatically fallback to a network request. DB errors will still be emitted to notify you of the problem even though the request callback may succeed.
opts.forceRefresh
Type: boolean
Default: false
Forces refreshing the cache. If the response could be retrieved from the cache, it will perform a new request and override the cache instead.
cb
Type: function
The callback function which will receive the response as an argument.
request event to get the request object of the request.
Note: This event will only fire if an HTTP request is actually made, not when a response is retrieved from cache. However, you should always handle the request event to end the request and handle any potential request errors.
.on('response', response)
response event to get the response object from the HTTP request or cache.
.on('error', error)
error event emitted in case of an error with the cache.
Errors emitted here will be an instance of CacheableRequest.RequestError or CacheableRequest.CacheError. You will only ever receive a RequestError if the request function throws (normally caused by invalid user input). Normal request errors should be handled inside the request event.
To properly handle all error scenarios you should use the following pattern:
Note: Database connection errors are emitted here, however cacheable-request will attempt to re-request the resource and bypass the cache on a connection error. Therefore a database connection error doesn't necessarily mean the request won't be fulfilled.
Using Hooks
Hooks have been implemented since version v9 and are very useful to modify response before saving it in cache. You can use hooks to modify response before saving it in cache.
Add Hooks
The hook will pre compute response right before saving it in cache. You can include many hooks and it will run in order you add hook on response object.
import http from 'http';import CacheableRequest from 'cacheable-request';const cacheableRequest = new CacheableRequest(request, cache).request();// adding a hook to decompress responsecacheableRequest.addHook('onResponse', async (value: CacheValue, response: any) => { const buffer = await pm(gunzip)(value.body); value.body = buffer.toString(); return value;});
here is also an example of how to add in the remote address
import CacheableRequest, {CacheValue} from 'cacheable-request';const cacheableRequest = new CacheableRequest(request, cache).request();cacheableRequest.addHook('onResponse', (value: CacheValue, response: any) => { if (response.connection) { value.remoteAddress = response.connection.remoteAddress; } return value;});
Remove Hooks
You can also remove hook by using below
CacheableRequest.removeHook('onResponse');
How to Contribute
Cacheable-Request is an open source package and community driven that is maintained regularly. In addition we have a couple of other guidelines for review:
SECURITY.md - Security guidelines and supported versions
Post an Issue
To post an issue, navigate to the "Issues" tab in the main repository, and then select "New Issue." Enter a clear title describing the issue, as well as a description containing additional relevant information. Also select the label that best describes your issue type. For a bug report, for example, create an issue with the label "bug." In the description field, Be sure to include replication steps, as well as any relevant error messages.
If you're reporting a security violation, be sure to check out the project's security policy.
Please also refer to our Code of Conduct for more information on how to report issues.
Ask a Question
To ask a question, create an issue with the label "question." In the issue description, include the related code and any context that can help us answer your question.