{"id":45756,"library":"persistent-node-cache","title":"PersistentNodeCache","description":"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.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/kwertop/persistent-node-cache","tags":["javascript","fast","persistent","cache","caching","node","nodejs","recovery","restore","typescript"],"install":[{"cmd":"npm install persistent-node-cache","lang":"bash","label":"npm"},{"cmd":"yarn add persistent-node-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add persistent-node-cache","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core in-memory cache engine that PersistentNodeCache extends","package":"node-cache","optional":false}],"imports":[{"note":"Named export only; default import will not work with ESM/TypeScript","wrong":"import PersistentNodeCache from 'persistent-node-cache'","symbol":"PersistentNodeCache","correct":"import { PersistentNodeCache } from 'persistent-node-cache'"},{"note":"Type is exported from the main entry point for convenience, no separate type path needed","wrong":"import { CacheSerializer } from 'persistent-node-cache/types'","symbol":"CacheSerializer","correct":"import { CacheSerializer } from 'persistent-node-cache'"},{"note":"CommonJS require must destructure the named export; the package is ESM-first but still offers CJS compatibility","wrong":"const PersistentNodeCache = require('persistent-node-cache')","symbol":"PersistentNodeCache (CJS)","correct":"const { PersistentNodeCache } = require('persistent-node-cache')"}],"quickstart":{"code":"import { PersistentNodeCache } from 'persistent-node-cache';\nimport { CacheSerializer } from 'persistent-node-cache';\n\n// Create a cache (name required, period defaults to 1000ms)\nconst cache = new PersistentNodeCache('mycache', 1000, process.env.CACHE_DIR || '', {}, undefined);\n\n// Set a value with optional TTL (in seconds)\ncache.set('greeting', 'Hello, World!', 3600);\n\n// Retrieve value\nconst value = cache.get('greeting');\nconsole.log(value); // 'Hello, World!'\n\n// Delete key\ncache.del('greeting');\n\n// On next initialization, cache auto-restores (v1.2.0+)\nconst cache2 = new PersistentNodeCache('mycache');\nconsole.log(cache2.get('greeting')); // 'Hello, World!' if not deleted\n\n// Custom serializer example\nconst base64Serializer: CacheSerializer = {\n  serialize(item: any): Buffer {\n    return Buffer.from(Buffer.from(JSON.stringify(item)).toString('base64') + '\\n');\n  },\n  deserialize(bf: Buffer): any {\n    return JSON.parse(Buffer.from(bf.toString().trim(), 'base64').toString());\n  }\n};\nconst cache3 = new PersistentNodeCache('secure', 1000, '', {}, base64Serializer);\ncache3.set('secret', 'sensitive data');\nconsole.log(cache3.get('secret')); // 'sensitive data'","lang":"typescript","description":"Basic usage: create cache, set/get/delete keys, automatic restore, and custom serializer example."},"warnings":[{"fix":"Remove any .recover() calls. The cache auto-restores when constructed with the same cacheName. If using custom dir, pass the same dir option.","message":"In 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().","severity":"breaking","affected_versions":">=1.2.0"},{"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.","message":"Default serialization changed to JSON (previously Base64). Data persisted with v1.1.x may not be deserialized correctly under v1.2.0 without custom serializer.","severity":"breaking","affected_versions":">=1.2.0"},{"fix":"Initialize cache with the same cacheName and dir options; recovery happens automatically. Do not call .recover().","message":"The .recover() instance method is deprecated since v1.2.0 and will be removed in a future major version.","severity":"deprecated","affected_versions":">=1.2.0"},{"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).","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use distinct cacheName values for different logical caches. Do not share cacheName across separate instances.","message":"CacheName must be unique per cache instance. Reusing the same name across different caches will cause file corruption and data loss.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'21m':81 '550':75 '623':71 '668':72 'activ':86 'altern':60 'append':38 'append-on':37 'automat':52 'cach':8,15,27,64,94,95 'command':34 'compar':58 'crash':20 'customiz':47 'data':42 'default':49 'definit':90 'disk':17,29 'everi':32 'extend':12 'far':67 'fast':79,92 'file':40 'full':26 'get':80 'higher':68 'in-memori':5 'initi':57 'javascript':91 'json':50 'librari':9 'lightweight':3 'like':61 'log':31 'loss':43 'maintain':78,87 'memori':7 'minim':41 'node':14,96 'node-cach':13 'nodej':97 'npm':85 'offer':46 'ops/sec':73,76,82 'period':23 'persist':4,18,63,93 'persistent-cach':62 'persistentnodecach':1 'provid':66 're':56 're-initi':55 'recoveri':21,98 'releas':83 'restart':45 'restor':53,99 'serial':48 'set':69 'ship':88 'throughput':70 'typescript':89,100 'v1.2.0':10 'vs':74 'write':24,33","created_at":"2026-06-07T12:56:34.228495+00:00","updated_at":"2026-06-07T12:56:34.228495+00:00","problems":[{"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.","cause":"Missing installation or incorrect import path; package not found in node_modules or TypeScript cannot resolve types.","error":"Cannot find module 'persistent-node-cache' or its corresponding type declarations."},{"fix":"Remove .recover() calls. Recovery happens automatically on construction (v1.2.0+).","cause":"Upgraded from v1.1.x to v1.2.0 where recover() was removed; code still calls recover().","error":"TypeError: cache.recover is not a function"},{"fix":"Ensure the directory path exists and the process has write permissions. Use an absolute path or create the directory before initializing cache.","cause":"Custom dir specified in constructor does not exist or is not writable; cache cannot create backup files.","error":"Error: ENOENT: no such file or directory, open '...'"},{"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.","cause":"CacheName mismatch or dir omitted on recovery; backup files not found.","error":"Data in cache is lost after restart even with persistence enabled"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/kwertop/persistent-node-cache#readme","github":"https://github.com/kwertop/persistent-node-cache","docs":null,"changelog":null,"pypi":null,"npm":"persistent-node-cache","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}