node-cache

library5.1.2jsnpmunverified

node-cache is a simple, fast, and internal in-memory caching module for Node.js applications, designed to function similarly to memcached but within a single Node.js process. It supports setting key-value pairs with optional time-to-live (TTL) expiration, allowing for automatic invalidation and deletion of stale data. The current stable version is 5.1.2, actively maintained with regular updates addressing bug fixes and minor features, as evidenced by recent 5.x releases. A major breaking change in v5.0.0 removed callback support, shifting entirely to synchronous operations (with an opt-in legacy callback option for migration), and dropped the `lodash` dependency, improving performance and reducing the bundle size. It differentiates itself by its straightforward API and focus on local process caching, suitable for scenarios where a full-fledged external caching solution like Redis or Memcached is overkill. Keys can be strings or numbers, and the cache can be configured with standard TTLs, periodic cleanup, and an option to store references vs. clones of values, balancing performance and data isolation.

database

npm install node-cache

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-CACHE

node-cache

databasejavascriptv5.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NodeCache

✓ import NodeCache from 'node-cache';

✗ const NodeCache = require('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

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

✗ import { NodeCache } from '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.

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')}`);

Debug

Known issues

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

affects: >=5.0.0

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

affects: >=5.0.0

breakingIn 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)`.

affects: >=4.0.0

gotchaThe `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.

affects: >=4.0.0

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

affects: >=4.1.0

deprecatedThe `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.

affects: >=5.0.0

Errors

Common errors & fixes

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

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

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)

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)

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.

Upgrade

Version history

5.1.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/node-cache/node-cache ↗

packagehttps://www.npmjs.com/package/node-cache ↗