Registry / http-networking / request-etag

request-etag

JSON →
library2.0.3jsnpmunverified

request-etag is a small, in-memory module designed for ETag-based HTTP response caching. It manages the `If-None-Match` header automatically for subsequent GET requests to the same URL, retrieving cached bodies for 304 Not Modified responses. The package currently leverages `lru-cache` for its underlying caching mechanism, which can be configured with options like `max` size. Crucially, `request-etag` defaults to using the `request` library as its HTTP client, which has been officially deprecated and is no longer maintained since February 11th, 2020. While an alternative HTTP client can be injected, it *must* adhere to the `request` library's API signature. The package's current stable version is 2.0.3, but its reliance on a deprecated core dependency suggests a slow or inactive release cadence, limiting its suitability for new projects. Its primary differentiator is its focused, lightweight approach to abstracting ETag caching logic.

http-networkingserialization
npm install request-etag
github ↗package ↗
INSTALL
IMPORT
SIG · REQUEST-ETAG
R
request-etag
http-networkingjavascriptv2.0.3
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.

ETagRequest
✓ const ETagRequest = require('request-etag');
✗ import ETagRequest from 'request-etag';
The package uses CommonJS `require` syntax for its default export. Direct ESM `import` is not supported without a CommonJS wrapper or bundler configuration due to its age.
ETagRequest constructor
✓ const eTagRequest = new ETagRequest(cacheConfig, modernHttpClient);
✗ const eTagRequest = new ETagRequest(cacheConfig);
The default HTTP client is the deprecated `request` library. It is strongly recommended to provide an alternative, modern, and maintained HTTP client (wrapped to match `request`'s API signature) as the second argument to the constructor.
Callback signature
✓ eTagRequest(url, function (error, response, body) { /* ... */ });
The callback function adheres to the `(error, response, body)` signature, mimicking the `request` library's callback pattern for consistent handling of HTTP responses.

This quickstart demonstrates how to initialize `request-etag` with a cache configuration and perform ETag-aware GET requests, showing the behavior of both initial 200 OK and subsequent 304 Not Modified responses with cached bodies.

const ETagRequest = require('request-etag'); const request = require('request'); // In a real application, use a modern HTTP client compatible with 'request' API // Configure the cache, e.g., max 10MB to store response bodies const cacheConfig = { max: 10 * 1024 * 1024 // 10MB limit for the cache }; // Initialize ETagRequest. In a production environment, 'request' should be replaced // with a modern, maintained HTTP client that provides the same API signature. const eTagRequest = new ETagRequest(cacheConfig, request); // Define a target URL for caching const urlToCache = 'https://www.google.com/'; console.log('--- First request (expecting 200 OK) ---'); eTagRequest(urlToCache, function (error, response, body) { if (error) { console.error('Initial request failed:', error); return; } if (response.statusCode === 200) { console.log(`Status: ${response.statusCode} - Body retrieved from actual HTTP response.`); // console.log(body.substring(0, 100) + '...'); // Log a snippet of the body } else { console.log(`Initial request unexpected status: ${response.statusCode}`); } console.log('\n--- Second request (expecting 304 Not Modified from cache) ---'); eTagRequest(urlToCache, function (error2, response2, body2) { if (error2) { console.error('Second request failed:', error2); return; } if (response2.statusCode === 304) { console.log(`Status: ${response2.statusCode} - Body retrieved from internal cache.`); // console.log(body2.substring(0, 100) + '...'); // Log a snippet of the cached body } else if (response2.statusCode === 200) { console.log(`Status: ${response2.statusCode} - Unexpected 200 on second request, cache might be bypassed.`); } else { console.log(`Second request unexpected status: ${response2.statusCode}`); } }); });
Debug
Known issues
breakingCritical security vulnerability and maintenance risk due to reliance on the deprecated 'request' library. The 'request' package is no longer maintained, meaning it won't receive security updates or bug fixes.
fix
Do not use `request-etag` in new projects. For existing projects, it is imperative to provide an alternative, maintained HTTP client (e.g., `axios`, `node-fetch`, or `undici` wrapped to match `request`'s API) to the `ETagRequest` constructor. Consider migrating to a more modern and actively maintained caching solution.
affects: >=0.0.1
gotchaThe module is explicitly designed for GET requests only; other HTTP methods (POST, PUT, DELETE, etc.) will not be cached.
fix
Ensure all requests intended for caching are GET requests. For other methods, `request-etag` will not provide caching benefits.
affects: >=0.0.1
gotchaCaching will not occur if the HTTP response lacks an ETag header, or if the request includes a non-empty `Cookie` header.
fix
Verify that your server is configured to send `ETag` headers for cacheable resources. Avoid sending `Cookie` headers with requests if you intend `request-etag` to cache their responses.
affects: >=0.0.1
gotchaThe underlying HTTP client provided to `ETagRequest` must strictly adhere to the API signature of the deprecated `request` library.
fix
When overriding the default client, ensure your custom client function accepts `(url, callback)` or `(options, callback)` and specifically uses the `(error, response, body)` callback signature, as expected by `request-etag`.
affects: >=0.0.1
gotchaResponses with bodies larger than the configured `max` cache size (set in `cacheConfig`) will not be stored in the cache.
fix
Adjust the `max` configuration option in `cacheConfig` to accommodate the maximum expected size of the response bodies you wish to cache. If bodies exceed this, they will be fetched every time.
affects: >=0.0.1
Errors
Common errors & fixes
My request is not being cached, even though I expect it to be.
The HTTP method used for the request was not GET. `request-etag` only caches GET requests.
fix
Ensure that the HTTP request you are attempting to cache is a GET request.
My request is not being cached, even though I expect it to be.
The server response did not include an ETag header, which is essential for `request-etag` to identify and manage cached resources.
fix
Check the server's configuration to confirm that `ETag` headers are being sent for the resources you wish to cache.
My request is not being cached, even though I expect it to be.
The outbound request included a non-empty `Cookie` header, which `request-etag` interprets as a reason not to cache the response.
fix
Remove any `Cookie` headers from requests that you intend for `request-etag` to cache. If cookies are necessary, `request-etag` cannot cache that specific response.
TypeError: Cannot read properties of undefined (reading 'call') or similar when using a custom HTTP client.
The custom HTTP client provided to the `ETagRequest` constructor does not precisely match the expected API signature of the deprecated `request` library.
fix
Verify that your custom HTTP client's function signature and callback arguments (specifically `(error, response, body)`) perfectly mimic those of the `request` library, as `request-etag` relies on this specific interface.
Upgrade
Version history
2.0.3latest on npm
Audit
Dependencies
lru-cacherequiredProvides the underlying in-memory caching mechanism for storing HTTP responses.
requestoptionalServes as the default HTTP client for making requests. This library is officially deprecated and unmaintained, posing security and stability risks.
Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/Belema/request-etag ↗
packagehttps://www.npmjs.com/package/request-etag ↗
request-etag — npm install request-etag · libregistry