Conditional cache responses
Return a not-modified response when the client already has a valid cached representation.
Express.js · Pipe
req.fresh
req.fresh reports whether the client's cached response is still fresh. It is false for stale caches and for requests carrying Cache-Control: no-cache.
How it works
req.fresh is a Boolean request property that reflects whether the client's cached representation still matches the response validators. Use it to avoid sending the full representation; a request carrying Cache-Control: no-cache forces the property to be false.
Syntax
req.freshReturns
Boolean
Key points
- A true value means the client cache is considered fresh for the response.
- A false value indicates that the cached response is stale and the complete response should be sent.
- When freshness fails, send the representation instead of relying on the client's cached copy.
Common mistakes
- A client reload request with
Cache-Control: no-cachemakesreq.freshfalse, even if validators would otherwise match.
Example: Use request freshness
const express = require('express');
const app = express();
app.get('/resource', (req, res) => {
if (req.fresh) return res.status(304).end();
res.set('Cache-Control', 'public, max-age=60');
res.send({ updatedAt: new Date().toISOString() });
});
app.listen(3000);Run the server, then request /resource with conditional headers such as If-None-Match or If-Modified-Since.
When to use it
Avoid unnecessary work
Skip expensive response generation when cache validators show the client copy is current.
Forced reload handling
Honor explicit end-to-end reload requests rather than serving from cache.
Interview questions
QWhat does req.fresh represent?
req.fresh is a Boolean. It is true when the response remains fresh in the client's cache and false when the cache is stale, allowing the application to avoid sending the complete response.
Follow-up: What request header overrides a normally fresh result? Cache-Control: no-cache causes the property to return false.
QHow can an Express route use req.fresh?
Use it as a conditional branch before generating or sending the full response. A fresh result can be answered with a suitable not-modified response, while a stale result should receive the representation.
Follow-up: What must support freshness checks in practice? The response needs cache validators such as an ETag or Last-Modified value, plus appropriate cache behavior.
QWhen does req.fresh return false?
The property is false when the client cache is stale, so the full response should be sent. It is also deliberately false for an end-to-end reload signaled by Cache-Control: no-cache.
Follow-up: Why is that override useful? It lets reload handling remain transparent instead of treating a forced reload as a cache hit.
Related
req.headersreq.get()req.staleres.status()res.send()