{"id":46375,"library":"simple-on-disk-cache","title":"simple-on-disk-cache","description":"A lightweight on-disk caching library for Node.js (v1.7.6) supporting locally mounted filesystems and remote filesystems like AWS S3. It provides time-based expiration policies with configurable default and per-item TTL. The library is ESM-only, ships TypeScript type definitions, and is actively maintained with a simple API. Alternatives like node-cache-manager or lru-cache offer in-memory or more complex caching, while this package focuses on simplicity and filesystem persistence.","status":"active","version":"1.7.6","language":"javascript","source_language":"en","source_url":"https://github.com/ehmpathy/simple-on-disk-cache","tags":["javascript","cache","disk","on-disk","filesystem","s3 cache","s3","local","locally mounted","typescript"],"install":[{"cmd":"npm install simple-on-disk-cache","lang":"bash","label":"npm"},{"cmd":"yarn add simple-on-disk-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add simple-on-disk-cache","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is ESM-only and does not support CommonJS require. Will throw if used with require().","wrong":"const { createCache } = require('simple-on-disk-cache')","symbol":"createCache","correct":"import { createCache } from 'simple-on-disk-cache'"},{"note":"The default export is not available; you must use named import.","wrong":"import createCache from 'simple-on-disk-cache'","symbol":"createCache","correct":"import { createCache } from 'simple-on-disk-cache'"},{"note":"CacheEntry is exported as a type, not a value. Use 'import type' for TypeScript.","wrong":"import { CacheEntry } from 'simple-on-disk-cache'","symbol":"type CacheEntry","correct":"import type { CacheEntry } from 'simple-on-disk-cache'"}],"quickstart":{"code":"import { createCache } from 'simple-on-disk-cache';\n\nconst { set, get } = createCache({\n  directoryToPersistTo: {\n    mounted: {\n      path: `${__dirname}/tmp`,\n    },\n  },\n});\n\nset('greeting', 'Hello, World!');\nconst greeting = get('greeting');\nconsole.log(greeting); // 'Hello, World!'\n\n// With custom expiration\nimport { createCache } from 'simple-on-disk-cache';\n\nconst { set: set2, get: get2 } = createCache({\n  directoryToPersistTo: {\n    mounted: { path: `${__dirname}/tmp` },\n  },\n  defaultSecondsUntilExpiration: 600, // 10 minutes\n});\n\nset2('key', 'value', { secondsUntilExpiration: Infinity }); // never expire\nconst value = get2('key');\nconsole.log(value); // 'value'","lang":"typescript","description":"Demonstrates creating a cache on a locally mounted filesystem, setting and getting a value, and using custom expiration."},"warnings":[{"fix":"Create the directory before calling createCache, e.g., with fs.mkdirSync.","message":"The cache directory must already exist. createCache does not create the directory automatically.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Only store JSON-serializable values.","message":"Cache entries are serialized with JSON.stringify, which cannot serialize functions, undefined, or circular references.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Check for undefined: const result = get('key'); if (result === undefined) { /* not found or expired */ }","message":"The get method returns undefined for expired or missing entries, not null. TypeScript strict null checks may require handling undefined explicitly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_REGION are available.","message":"The S3 configuration requires AWS credentials to be set in environment variables or ~/.aws/credentials. It does not accept explicit credentials in the config.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'activ':53 'altern':59 'api':58 'aw':24 'base':30 'cach':5,11,63,68,76,87,94 'complex':75 'configur':34 'default':35 'definit':50 'disk':4,10,88,91 'esm':45 'esm-on':44 'expir':31 'filesystem':19,22,84,92 'focus':80 'in-memori':70 'item':39 'javascript':86 'librari':12,42 'lightweight':7 'like':23,60 'local':17,96,97 'lru':67 'lru-cach':66 'maintain':54 'manag':64 'memori':72 'mount':18,98 'node':62 'node-cache-manag':61 'node.js':14 'offer':69 'on-disk':8,89 'packag':79 'per':38 'per-item':37 'persist':85 'polici':32 'provid':27 'remot':21 's3':25,93,95 'ship':47 'simpl':2,57 'simple-on-disk-cach':1 'simplic':82 'support':16 'time':29 'time-bas':28 'ttl':40 'type':49 'typescript':48,99 'v1.7.6':15","created_at":"2026-06-07T12:59:37.380870+00:00","updated_at":"2026-06-07T12:59:37.380870+00:00","problems":[{"fix":"Use import { createCache } from 'simple-on-disk-cache' instead of require.","cause":"Using CommonJS require with ESM-only package.","error":"TypeError: Cannot destructure property 'set' of (intermediate value)(...) as it is undefined."},{"fix":"Create the directory before creating the cache, e.g., with fs.mkdirSync('/path/to/dir', { recursive: true }).","cause":"The directory specified in directoryToPersistTo.mounted.path does not exist.","error":"Error: ENOENT: no such file or directory, open '.../tmp/...'"},{"fix":"Ensure the value is JSON-serializable. Avoid storing functions or objects with circular references.","cause":"Attempting to cache an object with circular references.","error":"TypeError: Converting circular structure to JSON"},{"fix":"Set environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or configure AWS CLI with aws configure.","cause":"AWS credentials not configured for S3 cache.","error":"CredentialsError: Missing credentials in config"}],"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/ehmpathy/simple-on-disk-cache","github":"https://github.com/ehmpathy/simple-on-disk-cache","docs":null,"changelog":null,"pypi":null,"npm":"simple-on-disk-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}}