with-file-cache

library3.4.0jsnpmunverified

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.

storage

npm install with-file-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WITH-FILE-CACHE

with-file-cache

storagejavascriptv3.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

withFileCache

✓ import { withFileCache } from 'with-file-cache'

✗ const withFileCache = require('with-file-cache')

Package is ESM-only and does not support CommonJS require().

withFileCache

✓ import { withFileCache } from 'with-file-cache'

✗ import withFileCache from 'with-file-cache'

withFileCache is a named export, not a default export. Default import will fail.

type FileCacheOptions

✓ import type { FileCacheOptions } from 'with-file-cache'

✗ import { FileCacheOptions } from 'with-file-cache'

FileCacheOptions is a type and should be imported with 'import type' for proper tree-shaking.

Basic usage: creates a file-cached function that caches results based on the argument string. Second call with same argument hits cache.

import { withFileCache } from 'with-file-cache'; const addFileCache = withFileCache({ baseKey: () => '' }); const fn = addFileCache(async (name: string) => { console.log(`Called fn with ${name}`); return `Hello ${name}!`; }, { calcCacheKey: (arg) => arg }); await fn('Bob'); // Called fn with Bob await fn('Bob'); // (cached, no log) await fn('Joe'); // Called fn with Joe

Debug

Known issues

gotchaCache 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.

fix

Configure a custom cache directory using the cacheDir option in withFileCache.

affects: >=1.0

breakingVersion 3.x dropped Node 12 and 14 support. It also switched to ESM-only, removing CommonJS compatibility.

fix

Use Node 16+ and ensure your project is ESM (type: 'module' in package.json) or use dynamic import.

affects: >=3.0

gotchaThe 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.

fix

Provide serialize and deserialize options to handle complex data types.

affects: >=1.0

gotchaCache key collisions can occur if calcCacheKey returns non-unique keys. For functions with multiple arguments, return a composite key (e.g., array or string).

fix

Combine arguments into a single unique string or object in calcCacheKey.

affects: >=1.0

deprecatedIn 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.

fix

Update baseKey to return a string (or a promise of string) to represent a base cache key.

affects: >=3.0

Errors

Common errors & fixes

Error: withFileCache is not a function

Using default import instead of named import.

fix

Change to: import { withFileCache } from 'with-file-cache'

TypeError: Cannot read properties of undefined (reading 'cacheDir')

withFileCache was called without required options object.

fix

Call withFileCache({ baseKey: ... }) with at least baseKey provided.

Error: The module "./node_modules/with-file-cache/index.js" is not a CommonJS module (ESM only)

Using require() in a CJS project; package is ESM-only.

fix

Switch to ESM by adding 'type': 'module' in package.json, or use dynamic import() with await.

TypeError: calcCacheKey is not a function

calcCacheKey option was omitted or set to a non-function value.

fix

Provide calcCacheKey as a function that returns a cache key based on arguments.

Upgrade

Version history

3.4.0latest on npm

Audit

Dependencies

node:fsrequiredUsed for filesystem operations (read/write cache files)

node:cryptooptionalUsed for hashing cache keys if custom hash is provided

Agent activity

32 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/sashee/with-file-cache ↗

packagewith-file-cache ↗

homepagehttps://github.com/sashee/with-file-cache#readme ↗