promise-cachex

library2.0.0jsnpmunverified

A lightweight promise-based caching library for JavaScript and TypeScript (v2.0.0, actively maintained). It caches asynchronous promises and synchronous values, eliminating redundant requests and preventing race conditions. Features include TTL expiry, LRU eviction for bounded caches, automatic cleanup of expired entries, and pending promise protection (unresolved promises are never evicted). Differentiators: promise-aware (stores pending promises), supports both async and sync values, bounded cache with LRU, and TypeScript-first with built-in types. Released monthly on npm.

storage devops

npm install promise-cachex

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PROMISE-CACHEX

promise-cachex

storagejavascriptv2.0.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.

PromiseCacheX

✓ import { PromiseCacheX } from 'promise-cachex'

✗ import PromiseCacheX from 'promise-cachex'

Named export only; default import is not available. Works with both ESM and CJS, but ESM is preferred.

CacheOptions

✓ import { CacheOptions, PromiseCacheX } from 'promise-cachex'

✗ import { Options } from 'promise-cachex'

CacheOptions is a type exported for configuring cache instance. Ensure TypeScript is used if importing types.

PromiseCacheX (CommonJS)

✓ const { PromiseCacheX } = require('promise-cachex')

✗ const PromiseCacheX = require('promise-cachex')

In CJS, destructure the named export. Default require will not work.

Basic usage: create a cache with 5s TTL and 2s cleanup interval, then fetch and cache a promise.

import { PromiseCacheX } from 'promise-cachex'; const cache = new PromiseCacheX({ ttl: 5000, cleanupInterval: 2000 }); async function fetchData() { return new Promise((resolve) => setTimeout(() => resolve('cached data'), 1000)); } (async () => { const result1 = await cache.get('key1', fetchData, { ttl: 5000 }); console.log(result1); // 'cached data' const result2 = await cache.get('key1', fetchData, { ttl: 5000 }); console.log(result2); // Returns cached value immediately })();

Debug

Known issues

breakingIn v2.0.0, construction options changed: `expireAfter` renamed to `ttl`, `maxAge` removed. Check your configuration.

fix

Use `ttl` and `cleanupInterval` options. See README for new option names.

affects: <2.0.0

breakingIn v2.0.0, the `get` method no longer accepts a callback function for custom key generation; it now takes a factory function or value directly.

fix

Pass a synchronous factory function or static value as the second argument to `cache.get`.

affects: <2.0.0

gotchaPending promises are protected from eviction, causing cache to temporarily exceed `maxEntries` if all entries have unresolved promises. This may lead to higher memory usage.

fix

Ensure promises resolve in a timely manner or increase `maxEntries` to accommodate potential overflow.

affects: >=2.0.0

gotchaTTL of 0 means no expiry; the item will persist indefinitely unless evicted by LRU or manually deleted.

fix

Set TTL to a positive number for auto-expiry, or use `maxEntries` for bounded cache.

affects: >=2.0.0

deprecatedIn v2.0.0, the `size()` method is now synchronous, but in older versions it was asynchronous. The asynchronous call will break in v2.

fix

Use `cache.size()` synchronously in v2. If migrating from v1, remove any `await`.

affects: <2.0.0

Errors

Common errors & fixes

TypeError: PromiseCacheX is not a constructor

CommonJS require used incorrectly; default import used instead of named import.

fix

Use `const { PromiseCacheX } = require('promise-cachex');`

import { PromiseCacheX } from 'promise-cachex' (module not found)

Missing dependency or incorrect import path.

fix

Run `npm install promise-cachex` and ensure package.json contains the dependency.

TypeError: cache.get is not a function

Cache instance not properly created or imported incorrectly.

fix

Ensure `cache` is an instance of `PromiseCacheX` and imported correctly.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

Resources

githubhttps://github.com/alexalexiuc/promise-cachex ↗

packagepromise-cachex ↗

homepagehttps://github.com/alexalexiuc/promise-cachex#readme ↗