Registry / storage / persistent-node-cache

persistent-node-cache

JSON →
library1.2.0jsnpmunverified

A lightweight persistent in-memory cache library (v1.2.0) that extends node-cache with disk persistence and crash recovery. It periodically writes the full cache to disk and logs every write command in an append-only file, minimizing data loss on restart. Offers customizable serializers (default JSON) and automatic restoration on re-initialization. Compared to alternatives like persistent-cache, it provides far higher set throughput (623,668 ops/sec vs 550 ops/sec) while maintaining fast gets (21M+ ops/sec). Released on npm, actively maintained, ships TypeScript definitions.

npm install persistent-node-cache
INSTALL
IMPORT
SIG · PERSISTENT-NODE-CA
P
persistent-node-cache
storagejavascriptv1.2.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

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

PersistentNodeCache
import { PersistentNodeCache } from 'persistent-node-cache'
import PersistentNodeCache from 'persistent-node-cache'
Named export only; default import will not work with ESM/TypeScript
CacheSerializer
import { CacheSerializer } from 'persistent-node-cache'
import { CacheSerializer } from 'persistent-node-cache/types'
Type is exported from the main entry point for convenience, no separate type path needed
PersistentNodeCache (CJS)
const { PersistentNodeCache } = require('persistent-node-cache')
const PersistentNodeCache = require('persistent-node-cache')
CommonJS require must destructure the named export; the package is ESM-first but still offers CJS compatibility

Basic usage: create cache, set/get/delete keys, automatic restore, and custom serializer example.

import { PersistentNodeCache } from 'persistent-node-cache'; import { CacheSerializer } from 'persistent-node-cache'; // Create a cache (name required, period defaults to 1000ms) const cache = new PersistentNodeCache('mycache', 1000, process.env.CACHE_DIR || '', {}, undefined); // Set a value with optional TTL (in seconds) cache.set('greeting', 'Hello, World!', 3600); // Retrieve value const value = cache.get('greeting'); console.log(value); // 'Hello, World!' // Delete key cache.del('greeting'); // On next initialization, cache auto-restores (v1.2.0+) const cache2 = new PersistentNodeCache('mycache'); console.log(cache2.get('greeting')); // 'Hello, World!' if not deleted // Custom serializer example const base64Serializer: CacheSerializer = { serialize(item: any): Buffer { return Buffer.from(Buffer.from(JSON.stringify(item)).toString('base64') + '\n'); }, deserialize(bf: Buffer): any { return JSON.parse(Buffer.from(bf.toString().trim(), 'base64').toString()); } }; const cache3 = new PersistentNodeCache('secure', 1000, '', {}, base64Serializer); cache3.set('secret', 'sensitive data'); console.log(cache3.get('secret')); // 'sensitive data'
Debug
Known issues
breakingIn v1.2.0, cache recovery is now automatic; the recover() method is removed. Instances created with v1.1.x must be updated to initialize without calling recover().
fix
Remove any .recover() calls. The cache auto-restores when constructed with the same cacheName. If using custom dir, pass the same dir option.
affects: >=1.2.0
breakingDefault serialization changed to JSON (previously Base64). Data persisted with v1.1.x may not be deserialized correctly under v1.2.0 without custom serializer.
fix
If upgrading from v1.1.x, implement a custom serializer that matches the previous format, or migrate data by re-reading with old version and writing with new.
affects: >=1.2.0
deprecatedThe .recover() instance method is deprecated since v1.2.0 and will be removed in a future major version.
fix
Initialize cache with the same cacheName and dir options; recovery happens automatically. Do not call .recover().
affects: >=1.2.0
gotchaThe period option defaults to 1000 ms (1 second). On very high-write loads, this can cause significant disk I/O and block writes. Monitor disk usage and tune period accordingly.
fix
Increase period to a higher value (e.g., 5000 ms) if write throughput is critical. Alternatively, set period to 0 to disable periodic full dumps (only append-only log is used).
affects: >=1.0.0
gotchaCacheName must be unique per cache instance. Reusing the same name across different caches will cause file corruption and data loss.
fix
Use distinct cacheName values for different logical caches. Do not share cacheName across separate instances.
affects: >=1.0.0
Errors
Common errors & fixes
Cannot find module 'persistent-node-cache' or its corresponding type declarations.
Missing installation or incorrect import path; package not found in node_modules or TypeScript cannot resolve types.
fix
Run 'npm install persistent-node-cache'. Ensure TypeScript version is >=3.8 if using ESM imports, and that 'esModuleInterop' is not required for named imports.
TypeError: cache.recover is not a function
Upgraded from v1.1.x to v1.2.0 where recover() was removed; code still calls recover().
fix
Remove .recover() calls. Recovery happens automatically on construction (v1.2.0+).
Error: ENOENT: no such file or directory, open '...'
Custom dir specified in constructor does not exist or is not writable; cache cannot create backup files.
fix
Ensure the directory path exists and the process has write permissions. Use an absolute path or create the directory before initializing cache.
Data in cache is lost after restart even with persistence enabled
CacheName mismatch or dir omitted on recovery; backup files not found.
fix
Use the exact same cacheName and dir options both when creating and re-initializing the cache. For v1.2.0+, ensure automatic recovery is not overridden.
Upgrade
Version history
1.2.0latest on npm
Audit
Dependencies
node-cacherequiredCore in-memory cache engine that PersistentNodeCache extends
Agent activity
11 hits · last 30 days
node
10
Amazon
1
Resources