{"id":12941,"library":"cache-manager-fs-hash","title":"File System Store for Node Cache Manager","description":"cache-manager-fs-hash is a file system store for the `node-cache-manager` library, designed to persist key-value pairs to disk. The current stable version is 3.0.0, supporting Node.js versions 18 and above. While no explicit release cadence is stated, the project appears actively maintained. Its key differentiators include the ability to save any `JSON.stringify`-able data, efficient handling of `Buffer` objects (storing larger ones in separate files), and compatibility with Node.js's cluster module for multi-process environments. It employs `.lock` files to prevent race conditions during concurrent file access, ensuring data integrity. This makes it a suitable choice for applications requiring persistent, local caching without relying on external databases.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/rolandstarke/node-cache-manager-fs-hash","tags":["javascript","cache-manager","storage","filesystem","disk-store","key-value-store"],"install":[{"cmd":"npm install cache-manager-fs-hash","lang":"bash","label":"npm"},{"cmd":"yarn add cache-manager-fs-hash","lang":"bash","label":"yarn"},{"cmd":"pnpm add cache-manager-fs-hash","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used in conjunction with this package for a unified caching interface, although not a direct runtime dependency of the store itself.","package":"cache-manager","optional":true}],"imports":[{"note":"Preferred ESM named import for modern Node.js applications (>=18.0.0).","wrong":"const { DiskStore } = require('cache-manager-fs-hash');","symbol":"DiskStore","correct":"import { DiskStore } from 'cache-manager-fs-hash';"},{"note":"CommonJS named import, suitable for older Node.js or CJS modules.","wrong":"import { DiskStore } from 'cache-manager-fs-hash';","symbol":"DiskStore","correct":"const { DiskStore } = require('cache-manager-fs-hash');"},{"note":"TypeScript users should use a type import when only referencing the type, not the runtime value.","wrong":"import { DiskStore } from 'cache-manager-fs-hash';","symbol":"DiskStore","correct":"import type { DiskStore } from 'cache-manager-fs-hash';"}],"quickstart":{"code":"const { DiskStore } = require('cache-manager-fs-hash');\n\nconst diskStore = new DiskStore({\n    path: 'diskcache', // path for cached files (default: cache)\n    ttl: 60 * 60 * 1000, // time to live in milliseconds \n                         // (default: never expires)\n    zip: true, // zip files to save disk space (default: false)\n    hash: true // keys are hashed to generate filenames (default: true)\n});\n\n(async () => {\n    await diskStore.set('key', 'value');\n    console.log(await diskStore.get('key'));\n\n    await diskStore.set('objectKey', { data: 'complex value', timestamp: Date.now() });\n    console.log(await diskStore.get('objectKey'));\n\n    await diskStore.del('key');\n    console.log(await diskStore.get('key'));\n\n    await diskStore.set('key', 'value', 1000); // with custom TTL\n    console.log(await diskStore.ttl('key'));\n\n    // Clean up all stored files\n    await diskStore.reset();\n    console.log('Cache reset.');\n})();","lang":"javascript","description":"Demonstrates direct usage of DiskStore to set, get, delete, and manage cached items with various options."},"warnings":[{"fix":"Always set a `ttl` option when initializing `DiskStore` (e.g., `ttl: 60 * 60 * 1000` for 1 hour) or use `cache-manager`'s wrapper functions with explicit TTLs.","message":"By default, `ttl` is set to `0` (never expires). This can lead to uncontrolled disk space usage over time if not explicitly configured or managed.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Keep `hash: true` (the default) unless you have a very specific reason not to, and ensure your keys are safe for filenames if disabling hashing. Hashing helps obscure keys and ensures valid filenames.","message":"Setting `hash: false` will use the raw cache keys as filenames. This can expose sensitive data in filenames, lead to invalid filenames if keys contain special characters, and potentially create conflicts if keys are not unique and valid for the filesystem.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the specified cache directory exists and the Node.js process has full read/write/execute permissions for it. You might need to `sudo mkdir` and `sudo chown` the directory.","message":"The `path` option for the cache directory must have appropriate write/read permissions for the Node.js process. Incorrect permissions will result in `EACCES` or similar errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 18.0.0 or higher. If you need to support older Node.js versions, consider using an earlier major version of `cache-manager-fs-hash` (e.g., `2.x`).","message":"The `engines` field in `package.json` now requires Node.js version `18.0.0` or higher, which might break deployments on older Node.js runtimes. There were no explicit breaking changes noted in the provided documentation for the internal API of v3 compared to v2.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure that any data you intend to cache is fully JSON-serializable. For complex objects, implement a `toJSON()` method on your class or preprocess the object to remove/serialize non-standard types.","message":"The library internally uses `JSON.stringify` to store data. If you attempt to cache objects containing circular references or non-JSON-serializable types (e.g., functions, Symbols, complex class instances without custom `toJSON` methods), they will either fail to store or be stripped of their non-serializable parts.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Grant appropriate read/write/execute permissions to the Node.js user for the cache directory (`path` option). For example, `sudo chown -R nodeuser:nodegroup /path/to/diskcache`.","cause":"The Node.js process lacks write permissions for the specified cache directory or its parent.","error":"Error: EACCES: permission denied, open '/path/to/diskcache/some_file.lock'"},{"fix":"Use the correct named import: `import { DiskStore } from 'cache-manager-fs-hash';` for ESM, or `const { DiskStore } = require('cache-manager-fs-hash');` for CommonJS.","cause":"The `DiskStore` class was imported incorrectly, often due to trying to use a default import instead of a named import, or a CommonJS `require` in an ESM context.","error":"TypeError: DiskStore is not a constructor"},{"fix":"Before caching, ensure your object is free of circular references. You might need to serialize it manually or preprocess it to remove the circularity.","cause":"You attempted to cache an object that contains circular references, which `JSON.stringify` cannot handle.","error":"TypeError: Converting circular structure to JSON"},{"fix":"Enable hashing by setting `hash: true` (the default) to generate shorter, fixed-length filenames from your keys. Alternatively, ensure your cache keys are concise if `hash: false` is necessary.","cause":"This error can occur if `hash: false` is used, and a cache key results in a filename path that exceeds the operating system's maximum path length limit.","error":"Error: ENAMETOOLONG: name too long, open '...'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}