HTTP ETag Generator

Common errors

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

  cause 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.

  cause 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.

Warnings

• breaking In `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.
• breaking Version `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`.
• gotcha By 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.

Install

• npm install etag npm
• yarn add etag yarn
• pnpm add etag pnpm

Imports

• etag
  wrong:

  import { etag } from 'etag';

  correct:

  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)
  wrong:

  import etag from 'etag';

  correct:

  const etag = require('etag');

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

Quickstart

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.");