{"id":46812,"library":"with-file-cache","title":"with-file-cache","description":"A filesystem-based caching library for JavaScript/TypeScript functions. Current stable version is 3.4.0, with a release cadence of roughly yearly major versions. It persists function results between restarts, supports waiting for in-progress results, works across workers, and allows custom serialization/deserialization. Unlike in-memory caches, it survives process restarts and can be shared among workers. It is ESM-only and ships TypeScript definitions.","status":"active","version":"3.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/sashee/with-file-cache","tags":["javascript","cache","typescript"],"install":[{"cmd":"npm install with-file-cache","lang":"bash","label":"npm"},{"cmd":"yarn add with-file-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add with-file-cache","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for filesystem operations (read/write cache files)","package":"node:fs","optional":false},{"reason":"Used for hashing cache keys if custom hash is provided","package":"node:crypto","optional":true}],"imports":[{"note":"Package is ESM-only and does not support CommonJS require().","wrong":"const withFileCache = require('with-file-cache')","symbol":"withFileCache","correct":"import { withFileCache } from 'with-file-cache'"},{"note":"withFileCache is a named export, not a default export. Default import will fail.","wrong":"import withFileCache from 'with-file-cache'","symbol":"withFileCache","correct":"import { withFileCache } from 'with-file-cache'"},{"note":"FileCacheOptions is a type and should be imported with 'import type' for proper tree-shaking.","wrong":"import { FileCacheOptions } from 'with-file-cache'","symbol":"type FileCacheOptions","correct":"import type { FileCacheOptions } from 'with-file-cache'"}],"quickstart":{"code":"import { withFileCache } from 'with-file-cache';\n\nconst addFileCache = withFileCache({ baseKey: () => '' });\n\nconst fn = addFileCache(async (name: string) => {\n  console.log(`Called fn with ${name}`);\n  return `Hello ${name}!`;\n}, { calcCacheKey: (arg) => arg });\n\nawait fn('Bob');\n// Called fn with Bob\nawait fn('Bob');\n// (cached, no log)\nawait fn('Joe');\n// Called fn with Joe","lang":"typescript","description":"Basic usage: creates a file-cached function that caches results based on the argument string. Second call with same argument hits cache."},"warnings":[{"fix":"Configure a custom cache directory using the cacheDir option in withFileCache.","message":"Cache files are stored in the current working directory by default. In a multi-worker environment, ensure workers share the same filesystem path and that the cache directory is not cleared unexpectedly.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Use Node 16+ and ensure your project is ESM (type: 'module' in package.json) or use dynamic import.","message":"Version 3.x dropped Node 12 and 14 support. It also switched to ESM-only, removing CommonJS compatibility.","severity":"breaking","affected_versions":">=3.0"},{"fix":"Provide serialize and deserialize options to handle complex data types.","message":"The serialize/deserialize functions must be synchronous if not using async, but they are expected to return a Buffer. If your function returns non-serializable values (e.g., class instances), you must provide custom serialization.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Combine arguments into a single unique string or object in calcCacheKey.","message":"Cache key collisions can occur if calcCacheKey returns non-unique keys. For functions with multiple arguments, return a composite key (e.g., array or string).","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Update baseKey to return a string (or a promise of string) to represent a base cache key.","message":"In version 2.x, the baseKey option was a synchronous string or number. In v3, it can be async and should return a string for hashing.","severity":"deprecated","affected_versions":">=3.0"}],"env_vars":null,"search_vec":"'3.4.0':18 'across':42 'allow':45 'among':61 'base':8 'cach':4,9,52,73 'cadenc':22 'current':14 'custom':46 'definit':71 'esm':66 'esm-on':65 'file':3 'filesystem':7 'filesystem-bas':6 'function':13,30 'in-memori':49 'in-progress':37 'javascript':72 'javascript/typescript':12 'librari':10 'major':26 'memori':51 'persist':29 'process':55 'progress':39 'releas':21 'restart':33,56 'result':31,40 'rough':24 'serialization/deserialization':47 'share':60 'ship':69 'stabl':15 'support':34 'surviv':54 'typescript':70,74 'unlik':48 'version':16,27 'wait':35 'with-file-cach':1 'work':41 'worker':43,62 'year':25","created_at":"2026-06-07T13:01:45.588174+00:00","updated_at":"2026-06-07T13:01:45.588174+00:00","problems":[{"fix":"Change to: import { withFileCache } from 'with-file-cache'","cause":"Using default import instead of named import.","error":"Error: withFileCache is not a function"},{"fix":"Call withFileCache({ baseKey: ... }) with at least baseKey provided.","cause":"withFileCache was called without required options object.","error":"TypeError: Cannot read properties of undefined (reading 'cacheDir')"},{"fix":"Switch to ESM by adding 'type': 'module' in package.json, or use dynamic import() with await.","cause":"Using require() in a CJS project; package is ESM-only.","error":"Error: The module \"./node_modules/with-file-cache/index.js\" is not a CommonJS module (ESM only)"},{"fix":"Provide calcCacheKey as a function that returns a cache key based on arguments.","cause":"calcCacheKey option was omitted or set to a non-function value.","error":"TypeError: calcCacheKey is not a function"}],"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/sashee/with-file-cache#readme","github":"https://github.com/sashee/with-file-cache","docs":null,"changelog":null,"pypi":null,"npm":"with-file-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}}