{"id":45755,"library":"persistent-cache","title":"persistent-cache","description":"A simple Node.js module to persistently store/cache arbitrary data to disk with optional memory mirroring for performance. Version 1.1.2 (latest) has low release activity with no recent updates. It provides both synchronous and asynchronous APIs for get, put, delete, and keys operations. Data is stored as files on disk, and cache entries can have a time-to-live duration. It is lightweight with no dependencies, but offers basic functionality compared to more feature-rich caching libraries like node-cache or lru-cache. Suitable for simple persistent storage needs, but has known issues with path handling and race conditions on concurrent access.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/LionC/persistent-cache","tags":["javascript","cache","persistent","data","storage","store"],"install":[{"cmd":"npm install persistent-cache","lang":"bash","label":"npm"},{"cmd":"yarn add persistent-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add persistent-cache","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The default export is a factory function that creates a cache instance. In CommonJS, use require('persistent-cache'). The library does not ship TypeScript types.","wrong":"const persistentCache = require('persistent-cache')","symbol":"persistentCache","correct":"import persistentCache from 'persistent-cache'"},{"note":"persistentCache is a factory function, not a constructor. Do not use 'new'.","wrong":"const cache = new persistentCache(options)","symbol":"Cache","correct":"const cache = persistentCache(options)"},{"note":"If using async put, a callback is expected. Omitting it may cause unexpected behavior or errors.","wrong":"cache.put('key', data)","symbol":"cache.put","correct":"cache.put('key', data, cb)"},{"note":"Async get takes a callback; sync counterpart is cache.getSync(key). Mixing them up is common.","wrong":"const data = cache.get('key')","symbol":"cache.get","correct":"cache.get('key', (err, data) => {})"},{"note":"Similar to get, keys is async; use keysSync for synchronous retrieval.","wrong":"const keys = cache.keys()","symbol":"cache.keys","correct":"cache.keys(cb)"}],"quickstart":{"code":"import persistentCache from 'persistent-cache';\n\nconst cache = persistentCache({ name: 'mycache', duration: 1000 * 60 * 60 });\n\n// Asynchronous put\ncache.put('key1', { hello: 'world' }, (err) => {\n  if (err) throw err;\n  console.log('Data stored');\n\n  // Asynchronous get\n  cache.get('key1', (err, data) => {\n    if (err) throw err;\n    console.log('Retrieved:', data);\n  });\n});\n\n// Synchronous put\ncache.putSync('key2', 'some string');\n\n// Synchronous get\nconst val = cache.getSync('key2');\nconsole.log('Sync retrieved:', val);\n\n// Get all keys\ncache.keys((err, keys) => {\n  if (err) throw err;\n  console.log('All keys:', keys);\n});\n\n// Delete a key\ncache.delete('key1', (err) => {\n  if (err) throw err;\n  console.log('Deleted key1');\n});\n\n// Remove entire cache storage\ncache.unlink((err) => {\n  if (err) throw err;\n  console.log('Cache unlinked');\n});","lang":"javascript","description":"Demonstrates basic usage: create cache with options, put/get data asynchronously and synchronously, list keys, delete entries, and unlink the entire cache."},"warnings":[{"fix":"Use a caching library designed for concurrency (e.g., redis, lru-cache with disk persistence) or implement file locking.","message":"Cache storage is file-based; concurrent access from multiple Node processes can cause race conditions or corrupted data.","severity":"gotcha","affected_versions":"<=1.1.2"},{"fix":"Always specify an explicit base option pointing to a writable path.","message":"The default base directory is the main module's directory (process.cwd()), which may not be writable in production or packaged apps.","severity":"gotcha","affected_versions":"<=1.1.2"},{"fix":"Call persistentCache(options) without the 'new' keyword.","message":"The constructor pattern 'new persistentCache(...)' is incorrectly used in some examples, but it is a factory function.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Wrap calls in try-catch or use promise wrappers. Consider using synchronous methods for simplicity.","message":"The callback for async methods (put, get, etc.) may not always be called if an error occurs before the operation starts.","severity":"gotcha","affected_versions":"<=1.1.2"},{"fix":"Ensure the base directory exists before creating a cache instance.","message":"The module does not create the base directory if it does not exist; it will throw an error.","severity":"gotcha","affected_versions":"<=1.1.2"}],"env_vars":null,"search_vec":"'1.1.2':22 'access':108 'activ':27 'api':38 'arbitrari':11 'asynchron':37 'basic':72 'cach':3,54,80,85,89,110 'compar':74 'concurr':107 'condit':105 'data':12,46,112 'delet':42 'depend':69 'disk':14,52 'durat':63 'entri':55 'featur':78 'feature-rich':77 'file':50 'function':73 'get':40 'handl':102 'issu':99 'javascript':109 'key':44 'known':98 'latest':23 'librari':81 'lightweight':66 'like':82 'live':62 'low':25 'lru':88 'lru-cach':87 'memori':17 'mirror':18 'modul':7 'need':95 'node':84 'node-cach':83 'node.js':6 'offer':71 'oper':45 'option':16 'path':101 'perform':20 'persist':2,9,93,111 'persistent-cach':1 'provid':33 'put':41 'race':104 'recent':30 'releas':26 'rich':79 'simpl':5,92 'storag':94,113 'store':48,114 'store/cache':10 'suitabl':90 'synchron':35 'time':60 'time-to-l':59 'updat':31 'version':21","created_at":"2026-06-07T12:56:34.064203+00:00","updated_at":"2026-06-07T12:56:34.064203+00:00","problems":[{"fix":"Verify the base and name options, ensure the directory is writable, and recreate the cache if necessary.","cause":"The cache directory or file does not exist. This can happen if the base directory is not correctly set or the cache is unlinked.","error":"Error: ENOENT: no such file or directory, open '.../cache/someKey'"},{"fix":"Create the cache using persistentCache(options) without the 'new' keyword.","cause":"The cache was not created correctly. Common mistake: calling 'new persistentCache()' instead of 'persistentCache()'.","error":"TypeError: cache.put is not a function"},{"fix":"Ensure data passed to put is serializable (no circular references, no functions).","cause":"Infinite recursion due to circular references in data passed to put. The library uses JSON.stringify internally.","error":"RangeError: Maximum call stack size exceeded"},{"fix":"Run 'npm install persistent-cache' in your project directory.","cause":"The package is not installed. This can happen when using the package without installing it first.","error":"Error: Cannot find module 'persistent-cache'"}],"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/LionC/persistent-cache#readme","github":"https://github.com/LionC/persistent-cache","docs":null,"changelog":null,"pypi":null,"npm":"persistent-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}}