cacheables

library3.0.1jsnpmunverified

Cacheables is a small, typed in-memory cache library (v3.0.1) written in TypeScript with zero dependencies. It wraps async functions with `remember()`, supporting five cache policies including stale-while-revalidate and concurrency-safe deduplication. A key differentiator is multilayer storage: stack a fast L1 memory bucket with any L2 (filesystem, Redis, S3) and cascading reads backfill missing layers. Fully typed with a generic TView projection. Released monthly on GitHub. Supports browser and Node.js >=18. ESM-only since v3.

storage

npm install cacheables

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CACHEABLES

cacheables

storagejavascriptv3.0.1

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.

Cacheable

✓ import { Cacheable } from 'cacheables'

✗ const cacheables = require('cacheables')

Cacheables is ESM-only since v3. CommonJS require will not work.

MemoryBucket

✓ import { MemoryBucket } from 'cacheables'

✗ import MemoryBucket from 'cacheables'

MemoryBucket is a named export, not default.

IBucket

✓ import type { IBucket } from 'cacheables'

✗ import { IBucket } from 'cacheables'

IBucket is a TypeScript interface; use `import type` for runtime removal.

CacheableOptions

✓ import type { CacheableOptions } from 'cacheables'

Type-only import for options type.

Shows basic usage: create a Cacheable instance with a MemoryBucket and max-age policy, then use remember() to cache an async fetch call.

import { Cacheable, MemoryBucket } from 'cacheables'; const cache = new Cacheable('weather', { buckets: [new MemoryBucket()], policy: 'max-age', maxAge: 5000, }); const apiUrl = 'https://goweather.herokuapp.com/weather/Karlsruhe'; const getWeather = () => cache.remember( () => fetch(apiUrl).then(r => r.json()), 'karlsruhe' ); const weather1 = await getWeather(); // miss, fetches const weather2 = await getWeather(); // hit, cached console.log(weather1, weather2);

Debug

Known issues

breakingESM-only: Cacheables v3 drops CommonJS support. Requires Node >=18 and "type":"module" or .mjs extension.

fix

Switch to ESM imports. For Node <18 use v2.x.

affects: >=3.0.0

breakingAPI change: The constructor signature changed from v2's single Bucket argument to v3's options object with required 'buckets' array and 'namespace' as first argument.

fix

Use new Cacheable('namespace', { buckets: [new MemoryBucket()] }).

affects: >=3.0.0

breakingRemoved 'maxEntries' and 'maxSize' options from v2; use external eviction logic.

fix

Implement your own eviction or use a different bucket that supports limits.

affects: >=3.0.0

deprecated'cache-only' policy is now the default; explicit 'cache-only' string is still allowed but unnecessary.

fix

Omit the policy option to use default 'cache-only'.

affects: >=3.0.0

gotchaConstructor throws 'At least one bucket is required' if buckets array is empty.

fix

Always provide at least one bucket in the 'buckets' array.

affects: >=3.0.0

Errors

Common errors & fixes

Error: At least one bucket is required

Cacheable constructor called with empty buckets array.

fix

Pass at least one bucket, e.g., `new Cacheable('ns', { buckets: [new MemoryBucket()] })`.

ERR_REQUIRE_ESM: require() of ES Module /node_modules/cacheables/dist/index.js not supported

Using CommonJS require() on an ESM-only package (v3+).

fix

Use ESM imports or downgrade to v2.x.

TypeError: cache.remember is not a function

Importing default export instead of named export { Cacheable }.

fix

Use named import: `import { Cacheable } from 'cacheables'`.

Property 'cache-only' does not exist on type...

Using v2 API with v3: passing policy as string without options object.

fix

Use constructor with options object: `new Cacheable('ns', { policy: 'cache-only', buckets: [...] })`.

Upgrade

Version history

3.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/grischaerbe/cacheables ↗

packagecacheables ↗

homepagehttps://github.com/grischaerbe/cacheables#readme ↗