{"id":16037,"library":"fresh","title":"HTTP Response Freshness Testing","description":"The `fresh` package (version 0.5.2, last published in September 2017) is a minimalist Node.js utility designed to determine if an HTTP response is \"fresh\" according to client-provided caching headers. Part of the `jshttp` organization, which maintains foundational HTTP middleware and utilities leveraged by frameworks such as Express.js, this library compares a client's `If-None-Match` and `If-Modified-Since` request headers against a server's `ETag` and `Last-Modified` response headers. It returns `true` if the cached response is still valid, indicating a conditional GET request can result in a 304 Not Modified status, or `false` if the cache is stale and a full response is required. Its primary differentiators are strict adherence to HTTP specifications and a focused scope, prioritizing reliability for efficient conditional GET implementations. Given its mature and foundational nature, the package maintains a stable, maintenance-level release cadence with infrequent updates.","status":"maintenance","version":"0.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/jshttp/fresh","tags":["javascript","fresh","http","conditional","cache"],"install":[{"cmd":"npm install fresh","lang":"bash","label":"npm"},{"cmd":"yarn add fresh","lang":"bash","label":"yarn"},{"cmd":"pnpm add fresh","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While natively a CommonJS module, modern bundlers typically allow this default import syntax in ESM contexts. The package exports a single function as its default.","wrong":"import { fresh } from 'fresh'","symbol":"fresh","correct":"import fresh from 'fresh'"},{"note":"This package is primarily a CommonJS module, exporting the freshness checking function directly. Attempting to access a named export like `.fresh` will result in undefined.","wrong":"const fresh = require('fresh').fresh","symbol":"fresh","correct":"const fresh = require('fresh')"}],"quickstart":{"code":"import fresh from 'fresh';\n\n// Simulate a client request with caching headers\nconst requestHeaders = {\n  'if-none-match': '\"my-etag-v1\"',\n  'if-modified-since': new Date(Date.now() - 3600000).toUTCString() // 1 hour ago\n};\n\n// Simulate server response headers for a resource\nconst responseHeadersFresh = {\n  'etag': '\"my-etag-v1\"',\n  'last-modified': new Date().toUTCString()\n};\n\nconst responseHeadersStale = {\n  'etag': '\"my-etag-v2\"',\n  'last-modified': new Date(Date.now() - 7200000).toUTCString() // 2 hours ago\n};\n\n// Check freshness against a fresh resource\nconst isFresh1 = fresh(requestHeaders, responseHeadersFresh);\nconsole.log(`Is resource 1 fresh? ${isFresh1}`); // Expected: true\n\n// Check freshness against a stale resource (different ETag)\nconst isFresh2 = fresh(requestHeaders, responseHeadersStale);\nconsole.log(`Is resource 2 fresh? ${isFresh2}`); // Expected: false\n\n// Simulate Cache-Control: no-cache from client\nconst requestHeadersNoCache = { ...requestHeaders, 'cache-control': 'no-cache' };\nconst isFreshNoCache = fresh(requestHeadersNoCache, responseHeadersFresh);\nconsole.log(`Is resource fresh with no-cache? ${isFreshNoCache}`); // Expected: false (client forces revalidation)\n","lang":"javascript","description":"Demonstrates how to use the `fresh` function with example request and response headers to check HTTP cache freshness."},"warnings":[{"fix":"For applications requiring workarounds for specific client caching behaviors, consider augmenting `fresh` with additional logic or middleware like `jumanji` (for Express) to handle known browser inconsistencies.","message":"The `fresh` module is designed to strictly follow HTTP specifications and does not implement workarounds for client-side browser bugs. Notably, certain versions of Safari have a known issue where they might incorrectly make a request that allows `fresh` to validate resource freshness even when Safari does not possess a representation of the resource in its cache. For Express applications, the `jumanji` module is suggested as a workaround for this specific Safari bug.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use `const fresh = require('fresh');` for strict CommonJS environments. For native ESM environments, rely on bundler transpilation, or use dynamic `import('fresh').then(m => m.default)` if direct ESM loading is required and the package's `package.json` does not include `exports`.","message":"The `fresh` package, being published in 2017, is fundamentally a CommonJS module. While modern build tools and Node.js environments often provide interoperability for `import fresh from 'fresh'`, direct usage in native ESM environments requiring strict ESM imports might necessitate `createRequire` or other compatibility layers for older CJS-only packages.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use a default import for ESM (`import fresh from 'fresh'`) or directly assign the result of `require()` for CommonJS (`const fresh = require('fresh')`).","cause":"Attempting to import the `fresh` function as a named import (e.g., `import { fresh } from 'fresh'`) or trying to access it as a property on the `require`d object (e.g., `require('fresh').fresh`) when it is exported as a default/module.exports.","error":"TypeError: fresh is not a function"},{"fix":"Ensure request and response header keys are consistently lowercase or normalized before passing them to `fresh`, or rely on the module's internal parsing to handle standard HTTP header casing. Always provide full HTTP-standard header strings (e.g., `Last-Modified` in RFC1123 format).","cause":"Although HTTP headers are case-insensitive, JavaScript object keys are case-sensitive. If the header keys provided to `fresh` (e.g., `If-None-Match`) do not match the expected internal parsing or are in an unexpected format, the freshness check may yield incorrect results.","error":"Resource incorrectly reported as fresh/stale due to header casing or format."}],"ecosystem":"npm"}