etag

library1.8.1jsnpmunverified

The `etag` package is a minimalist, RFC 7232-compliant utility for generating HTTP ETags in Node.js applications. It currently maintains a stable version 1.8.1 and has a low release cadence, reflecting its maturity and focused scope. The library supports generating strong ETags for strings and `Buffer`s, and weak ETags by default for `fs.Stats` objects, with an option to override this behavior. Key differentiators include its strict adherence to the HTTP ETag specification, performance optimization for various entity sizes, and a history of robust integration within the `jshttp` ecosystem, often used by popular HTTP frameworks like Express. It prioritizes correctness and efficiency in ETag calculation, having evolved through several hashing algorithm updates to improve security and performance.

http-networking serialization web-framework

npm install etag

github ↗package ↗

INSTALL

IMPORT

SIG · ETAG

etag

http-networkingjavascriptv1.8.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.

etag

✓ import etag from 'etag';

✗ import { etag } from 'etag';

The 'etag' package exports a default function. Named imports like `import { etag } from 'etag'` will fail in ESM environments.

etag (CommonJS)

✓ const etag = require('etag');

✗ import etag from 'etag';

This is the original CommonJS import style. Modern Node.js projects configured for ESM should use `import etag from 'etag';`.

Demonstrates generating strong and weak ETags for string and Buffer entities, illustrating typical usage patterns in Node.js.

import etag from 'etag'; // Scenario 1: Generating a strong ETag for a string entity const stringBody = '<h1>Hello World!</h1>'; const strongStringEtag = etag(stringBody); console.log(`Strong ETag for string: ${strongStringEtag}`); // Scenario 2: Generating a weak ETag for a string entity const weakStringEtag = etag(stringBody, { weak: true }); console.log(`Weak ETag for string: ${weakStringEtag}`); // Scenario 3: Generating a strong ETag for a Buffer entity const bufferBody = Buffer.from('<p>This is a buffered response.</p>'); const strongBufferEtag = etag(bufferBody); console.log(`Strong ETag for buffer: ${strongBufferEtag}`); // Scenario 4: Generating a weak ETag for a Buffer entity const weakBufferEtag = etag(bufferBody, { weak: true }); console.log(`Weak ETag for buffer: ${weakBufferEtag}`); // Scenario 5: How it's typically used in an HTTP response (conceptual) // (Imagine `res` is an HTTP response object in a web framework) // const res = { // setHeader: (name, value) => console.log(`Setting Header: ${name}: ${value}`) // }; // const responseBody = 'Some dynamic content'; // res.setHeader('ETag', etag(responseBody)); // console.log("Header set for responseBody.");

Debug

Known issues

breakingIn `v1.8.0`, the underlying hashing algorithm for ETag generation was changed from MD5 to SHA1. This means ETags generated by `v1.8.0` and later will differ from those generated by prior versions for the same entity, potentially invalidating existing client caches.

fix

Be aware that existing client caches relying on pre-1.8.0 ETags will likely become stale. If strict ETag consistency across deployments or upgrades is critical, consider implementing cache-busting strategies or re-evaluating caching policies.

affects: >=1.8.0

breakingVersion `v1.7.0` introduced significant changes to ETag generation logic. This included always incorporating entity length, generating non-Stats ETags using only MD5 (CRC32 removed), and removing base64 padding. These changes result in different ETag values compared to `v1.6.0` and earlier.

fix

Similar to the `v1.8.0` change, this also impacts ETag values. Ensure client caches are appropriately handled or invalidated if upgrading from versions prior to 1.7.0. Note that the MD5 algorithm used in this range was later updated to SHA1 in `v1.8.0`.

affects: >=1.7.0 <1.8.0

gotchaBy default, `etag` generates strong ETags for strings and `Buffer`s, but a weak ETag for `fs.Stats` objects. If you require a strong ETag for `fs.Stats` or a weak ETag for strings/buffers, you must explicitly set the `options.weak` flag.

fix

Always pass `{ weak: true }` or `{ weak: false }` to the `etag()` function if you need to override the default strong/weak behavior for specific entity types or to ensure consistent behavior.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: entity must be a string, Buffer or fs.Stats

The `etag` function was called with an unsupported data type for the `entity` argument (e.g., `null`, `undefined`, a number, or a complex object that isn't `fs.Stats`).

fix

Ensure the first argument passed to `etag()` is a `string`, a `Buffer` instance, or an `fs.Stats` object (or a compatible mock object mimicking properties like `mtime`, `size`, `ino`).

ETags generated are inconsistent between different deployments or environments.

This issue typically arises when different versions of the `etag` package are used across environments. Past updates to `etag` have changed the underlying hashing algorithms (e.g., from MD5 to SHA1) or ETag generation logic, leading to different output for the same input.

fix

To guarantee consistent ETag generation, ensure that the `etag` package version is locked and identical across all deployment environments. Use package manager commands like `npm ci` or `yarn install --frozen-lockfile` to enforce exact dependency versions.

Upgrade

Version history

1.8.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jshttp/etag ↗

packagehttps://www.npmjs.com/package/etag ↗