In-memory Cache for Node.js

Common errors

• TypeError: myCache.get is not a function (when using callbacks after v5)

  cause Attempting to use callback-based API (`myCache.get(key, callback)`) after upgrading to v5.x, where callbacks were removed by default.
  fix Remove the callback argument and use the synchronous return value: `const value = myCache.get(key);`

• Error: Key type 'object' is not supported. Use 'string' or 'number'.

  cause Trying to use an object (or other non-string/non-number type) as a cache key.
  fix Convert your key to a string (e.g., `JSON.stringify(myObjectKey)` or `myObjectKey.id.toString()`) or ensure it's a number before passing it to cache methods.

• Cache is full, cannot add new key (when maxKeys is set)

  cause Attempting to add a new item to the cache when the `maxKeys` limit has been reached.
  fix Increase the `maxKeys` option during initialization (`new NodeCache({ maxKeys: desiredLimit })`), implement a custom eviction strategy by manually deleting less important keys, or handle the error gracefully.

• Values were still being deleted after expiration even with 'deleteOnExpire: false' (pre-v5.0.2)

  cause A bug in versions prior to 5.0.2 caused expired values to be deleted regardless of the `deleteOnExpire` setting.
  fix Upgrade to `node-cache` version 5.0.2 or newer to ensure `deleteOnExpire: false` functions as intended, allowing you to handle expired items manually via the 'expired' event.

Warnings

• breaking Version 5.0.0 completely removed support for callback-based API methods. All operations are now synchronous. If you rely on callbacks, you must migrate to synchronous calls or temporarily enable legacy callbacks.
  Fix: Rewrite code to use synchronous methods (e.g., `cache.get(key)` instead of `cache.get(key, callback)`). For a temporary migration path, initialize with `new NodeCache({ enableLegacyCallbacks: true })` but note this will be removed in v6.x.
• breaking Node.js versions prior to 8.x are no longer supported since v5.x. Running on older Node.js environments will lead to compatibility issues or errors.
  Fix: Upgrade your Node.js runtime to version 8.0.0 or higher. The recommended version is the latest LTS.
• breaking In version 4.0.0, the behavior of `.ttl(key, 0)` and `stdTTL=0` was fixed. Previously, setting TTL to 0 would immediately delete the key. It now correctly sets an unlimited TTL.
  Fix: Review code that explicitly sets TTL to 0 or relies on `stdTTL=0` to ensure it's intended for unlimited expiration, not immediate deletion. For immediate deletion, use `.del(key)`.
• gotcha The `useClones` option (default: `true`) determines if stored values are deep-cloned. If `true`, you get a copy, preventing external mutations from affecting cached data. If `false`, you get a reference, which is faster but means cached objects can be mutated externally, potentially leading to unexpected behavior.
  Fix: Carefully consider the implications of `useClones`. For immutable data or read-only access, `true` (default) is safer. For performance-critical scenarios with mutable objects where you understand the risks, `false` can be used. Be aware that changing the default to `false` might introduce subtle bugs if not handled carefully.
• gotcha Keys must be `string` or `number` types since v4.1.0. Other types will throw an error during `set` operations.
  Fix: Ensure all keys passed to `set`, `get`, `del`, etc., are either strings or numbers. Convert other types to strings if necessary before caching.
• deprecated The `enableLegacyCallbacks` option, which re-enables callback support for compatibility with pre-v5 APIs, is marked for removal in v6.x.
  Fix: Avoid relying on `enableLegacyCallbacks`. Migrate your code to use the synchronous API calls as soon as possible to prepare for v6.x.

Install

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

Imports

• NodeCache
  wrong:

  const NodeCache = require('node-cache');

  correct:

  import NodeCache from 'node-cache';

  While CommonJS `require` is shown in examples, modern Node.js development typically uses ES Module `import`. The package still exports a default CommonJS module.
• NodeCache
  wrong:

  import { NodeCache } from 'node-cache';

  correct:

  const NodeCache = require('node-cache');

  The primary export is a default CommonJS export, so `require` syntax directly assigns the class. For ESM, a default import is used.
• NodeCacheEvents

  import { NodeCacheEvents } from 'node-cache';
  // Usage: myCache.on(NodeCacheEvents.EXPIRED, ...)

  Events emitted by the cache (e.g., 'expired', 'set', 'del') are exposed as constants for better type safety and discoverability.

Quickstart

Initializes NodeCache, sets and retrieves a value with a TTL, demonstrates handling missing keys, simulates caching an asynchronous operation, and shows the `take` method for atomic get-and-delete.

import NodeCache from 'node-cache';

const myCache = new NodeCache({ stdTTL: 60, checkperiod: 120, useClones: false });

myCache.set('myKey', 'myValue', 10); // Cache for 10 seconds

let value = myCache.get('myKey');
if (value) {
  console.log(`Retrieved: ${value}`);
} else {
  console.log('Key not found or expired.');
}

// Simulate an async operation and cache its result
async function fetchDataAndCache(key) {
  let cachedData = myCache.get(key);
  if (cachedData) {
    return cachedData;
  }
  console.log('Fetching fresh data...');
  const freshData = await new Promise(resolve => setTimeout(() => resolve({ id: 1, name: 'Fresh Data' }), 500));
  myCache.set(key, freshData, 30);
  return freshData;
}

fetchDataAndCache('asyncData').then(data => console.log('Async data:', data));

// Get and delete a key with a single operation (v5.1.0+)
const takenValue = myCache.take('myKey');
console.log(`Taken value: ${takenValue}`);
console.log(`Is myKey still in cache? ${myCache.has('myKey')}`);