Route-Cache

Common errors

• TypeError: Cannot read properties of null (reading 'json')

  cause An issue where JSON parsing failed if the response body was null, fixed in v0.4.7.
  fix Upgrade `route-cache` to version 0.4.7 or higher to resolve the underlying JSON null error.

• Old content is being served even after data has changed.

  cause The route is being cached, and the cache has not expired or been explicitly cleared.
  fix Either decrease the `ttl` (Time-To-Live) for `cacheSeconds`, or explicitly call `routeCache.removeCache('/your-route')` after data updates to invalidate the specific cached entry. For production, consider using distributed caching with invalidation hooks.

• Responses for different users are getting mixed up in the cache.

  cause The default cache key (`req.originalUrl`) does not differentiate between personalized content for different users.
  fix Implement a custom cache key function for the affected route. The key should incorporate identifying information like `req.session.userId` or a unique user identifier, e.g., `routeCache.cacheSeconds(ttl, (req, res) => req.originalUrl + '|' + res.locals.userId);`.

Warnings

• breaking Prior to v0.1.2, `route-cache` might cache HTTP responses with status codes >= 400 (e.g., error pages). From v0.1.2 onwards, it explicitly avoids caching these invalid responses, which changes caching behavior for applications relying on the previous, less desirable default.
  Fix: Upgrade to v0.1.2 or newer. If you need to cache specific error responses, implement custom caching logic that explicitly overrides this behavior via a dynamic key function.
• breaking Version v0.6.1 introduced status code caching. This means the HTTP status code itself will be part of the cached response. While this is generally an improvement, it could subtly alter behavior if previous versions were used where the status code was re-evaluated on subsequent requests to a cached body.
  Fix: Review routes where status code caching might introduce unexpected behavior. If dynamic status codes are critical, consider conditional caching or dynamic keys that factor in status logic.
• gotcha By default, `route-cache` uses `req.originalUrl` as the cache key. For applications with dynamic content based on user sessions, query parameters (that are not part of `originalUrl` if not configured), or other request-specific data, this default key might lead to incorrect or shared cached responses.
  Fix: Always define a custom cache key function (`routeCache.cacheSeconds(ttl, function(req, res){ ... })`) for routes serving personalized or highly dynamic content to ensure proper cache isolation. Return `false` from the function to prevent caching for specific requests.
• gotcha The package documentation primarily uses CommonJS `require` syntax. Directly using ES module `import` syntax might not work out-of-the-box in pure ESM environments without proper configuration (e.g., transpilation or specific Node.js loader setup) or if the package does not explicitly provide ESM exports.
  Fix: Stick to CommonJS `require()` for importing `route-cache` and its sub-modules to ensure compatibility, or verify ESM support in your specific Node.js version and project configuration.

Install

• npm install route-cache npm
• yarn add route-cache yarn
• pnpm add route-cache pnpm

Imports

• routeCache
  wrong:

  import routeCache from 'route-cache';

  correct:

  const routeCache = require('route-cache');

  This package is primarily CommonJS. While Node.js's CJS-ESM interop might allow the ESM import in some contexts, the documented and guaranteed-to-work method is CommonJS `require`.
• cacheSeconds
  wrong:

  import { cacheSeconds } from 'route-cache';

  correct:

  app.get('/path', routeCache.cacheSeconds(ttl), ...);

  This is a method on the `routeCache` object, not a direct named export.
• IoRedisStore
  wrong:

  import IoRedisStore from 'route-cache/ioRedisStore';

  correct:

  const IoRedisStore = require('route-cache/ioRedisStore');

  This distributed cache store is a separate CommonJS module within the package.

Quickstart

This quickstart demonstrates how to use `route-cache` with an Express application, showing basic route caching with a TTL, dynamic cache key generation based on request/response properties (including conditional caching), and manual cache invalidation.

const express = require('express');
const routeCache = require('route-cache');
const app = express();

// Cache a route for 20 seconds using the default cache key (req.originalUrl)
app.get('/cached-index', routeCache.cacheSeconds(20), (req, res) => {
  console.log('This message will only appear once every 20 seconds for /cached-index');
  res.send('This response is cached!');
});

// Cache a route with a custom, dynamic key based on user authentication status
app.get('/user-data/:id', routeCache.cacheSeconds(60, (req, res) => {
  // Assuming res.locals.isAuthenticated indicates user login status
  if (!res.locals.isAuthenticated) return false; // Do not cache for unauthenticated requests
  return req.originalUrl + '|' + req.params.id + '|' + res.locals.userId;
}), (req, res) => {
  res.locals.isAuthenticated = Math.random() > 0.5; // Simulate auth status
  res.locals.userId = res.locals.isAuthenticated ? 'user123' : 'guest';
  console.log(`Serving user data for ${req.params.id}. Authenticated: ${res.locals.isAuthenticated}`);
  res.send(`Data for user ${req.params.id}. (Auth: ${res.locals.isAuthenticated})`);
});

// Example of how to explicitly remove a cached route
app.post('/clear-cache', (req, res) => {
  const routeToClear = req.body.route || '/cached-index';
  routeCache.removeCache(routeToClear);
  res.send(`Cache for ${routeToClear} cleared.`);
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
  console.log('Try visiting /cached-index multiple times, and /user-data/1 and /user-data/2');
});