cache-hub

Zero-runtime-dependency caching and atomic state toolkit for Node.js services.

cache-hub provides an in-memory LRU + TTL cache, optional Redis integration, read-through caching, function-level caching, distributed invalidation, stable cache-key serialization, atomic state backends, and rate-limit state primitives behind a small CacheLike contract.

Chinese documentation: docs/README.zh-CN.md

Why cache-hub

Zero runtime dependencies - dependencies stays empty; Redis is an optional peer dependency.
Memory cache with LRU + TTL - O(1) operations with entry-count and memory-size limits.
Multi-level cache - L1 memory plus optional L2 remote cache, TTL-preserving backfill, timeout fallback, and configurable write policy.
Redis adapter - wraps ioredis as CacheLike; uses SCAN instead of KEYS for production-safe pattern operations.
Read-through caching - cache miss fetch, write-back, in-process de-duplication, and optional Redis lease de-duplication.
Function cache - cache any async function with withCache or the FunctionCache registry.
Tag invalidation - memory, Redis, multi-level, and distributed tag invalidation for grouped cache entries.
Distributed invalidation - Redis Pub/Sub broadcasts pattern and tag invalidation across service instances.
Stable key serialization - deterministic cache keys with sorted object keys, cycle handling, and special value sentinels.
Atomic state backends - memory and Redis counter primitives for high-concurrency state updates.
Rate-limit primitives - fixed-window, sliding-window, token-bucket, and leaky-bucket state stores for middleware authors.
Dual package format - ESM and CommonJS builds with subpath exports.

Installation

npm install cache-hub

Redis-backed features require ioredis:

npm install ioredis

ioredis is an optional peer dependency. Projects that only use memory caching do not need to install it.

Quick Start

Memory Cache

import { MemoryCache } from 'cache-hub';

const cache = new MemoryCache({
    maxEntries: 1000,
    defaultTtl: 60_000,
    enableStats: true,
});

await cache.set('user:1', { name: 'Alice' });

const user = await cache.get<{ name: string }>('user:1');
console.log(user?.name); // Alice

const stats = cache.getStats();
console.log(stats.hitRate); // 0..1

Read-through Cache

import { MemoryCache } from 'cache-hub';
import { readThrough } from 'cache-hub/read-through';

const cache = new MemoryCache({ defaultTtl: 30_000 });

const user = await readThrough(cache, 30_000, 'user:1', async () => {
    return db.findUser(1);
});

readThrough returns cached values immediately on hit. On miss, it runs the fetcher, writes non-undefined results back to cache, and shares one in-flight promise for concurrent calls with the same key.

Read-through with Redis Lease

Use readThroughWithLease when many Node.js processes may miss the same key at the same time. One process acquires the Redis lease and runs the fetcher; other processes wait briefly for the cache to be filled.

import { createRedisCacheAdapter } from 'cache-hub/redis';
import { createRedisLeaseStore } from 'cache-hub/lease';
import { readThroughWithLease } from 'cache-hub/read-through';

const cache = createRedisCacheAdapter('redis://localhost:6379');
const leaseStore = createRedisLeaseStore(cache);

const value = await readThroughWithLease({
    cache,
    ttlMs: 2_000,
    key: 'response:/users/1',
    leaseStore,
    leaseTtlMs: 1_000,
    waitForOwnerMs: 1_200,
    pollIntervalMs: 10,
    fetcher: async () => renderExpensiveResponse(),
});

await cache.close();

The default timeout behavior is onLeaseTimeout: 'fetch', which favors availability. Use onLeaseTimeout: 'throw' if duplicate origin fetches must be rejected instead of allowed.

Function Cache

import { MemoryCache } from 'cache-hub';
import { withCache } from 'cache-hub/function-cache';

const cache = new MemoryCache({ maxEntries: 500 });

const getUser = withCache(
    async (userId: number) => db.findUser(userId),
    {
        cache,
        ttl: 60_000,
        namespace: 'users',
        condition: (result) => result !== null,
    },
);

const user = await getUser(1);

The default key builder uses stableStringify. Long keys are compressed with a SHA-256 digest after the configured key length threshold.

Multi-level Cache

import { MemoryCache } from 'cache-hub';
import { MultiLevelCache } from 'cache-hub/multi-level';
import { createRedisCacheAdapter } from 'cache-hub/redis';

const local = new MemoryCache({ maxEntries: 500, defaultTtl: 30_000 });
const remote = createRedisCacheAdapter('redis://localhost:6379');

const cache = new MultiLevelCache({
    local,
    remote,
    remoteTimeoutMs: 50,
    backfillOnRemoteHit: true,
    writePolicy: 'both',
});

await cache.set('product:42', { name: 'Keyboard' }, 120_000);

const product = await cache.get<{ name: string }>('product:42');
console.log(product?.name); // Keyboard

await remote.close();

Distributed Invalidation

import { MemoryCache } from 'cache-hub';
import { DistributedCacheInvalidator } from 'cache-hub/distributed';

const local = new MemoryCache({ maxEntries: 1000 });

const invalidator = new DistributedCacheInvalidator({
    redisUrl: process.env.REDIS_URL ?? 'redis://localhost:6379',
    cache: local,
    channel: 'app:cache-invalidation',
});

await invalidator.invalidate('user:*');
await invalidator.invalidateTag('tenant:a');
await invalidator.close();

Calling invalidate(pattern) first invalidates the current instance and then broadcasts the same pattern to other subscribers. invalidateTag(tag) does the same for caches that support invalidateByTag.

Fixed-window Rate-limit Store

import { createMemoryFixedWindowRateLimitStore } from 'cache-hub/rate-limit';

const store = createMemoryFixedWindowRateLimitStore();

const result = store.increment('rl:user:42', 60_000, 100);

if (result.remaining === 0) {
    console.log(`Retry after ${result.retryAfterMs}ms`);
}

Redis-backed rate-limit state uses Lua scripts for atomic increment/decrement:

import { createRedisCacheAdapter } from 'cache-hub/redis';
import { createRedisFixedWindowRateLimitStore } from 'cache-hub/rate-limit';

const redisCache = createRedisCacheAdapter('redis://localhost:6379');
const store = createRedisFixedWindowRateLimitStore(redisCache);

await store.increment('rl:user:1', 60_000, 100);
await store.decrement('rl:user:1');
await store.resetPrefix('rl:user:');

await redisCache.close();

cache-hub/rate-limit is a low-level primitive for middleware authors. It does not impose a specific HTTP framework adapter.

Atomic State Backend

import { createRedisCacheAdapter } from 'cache-hub/redis';
import { createRedisAtomicStateBackend } from 'cache-hub/atomic';

const redisCache = createRedisCacheAdapter('redis://localhost:6379');
const atomic = createRedisAtomicStateBackend(redisCache);

const result = await atomic.incrementWithTtl('counter:tenant:42', 1, 60_000);

console.log(result.value, result.ttlMs);
await redisCache.close();

The Redis backend uses Lua scripts for atomic read-modify-write behavior. It is safe to use as a storage primitive for high-concurrency counters where plain get -> set would lose updates.

Module Reference

`cache-hub`

import { MemoryCache } from 'cache-hub';
import type { CacheLike, CacheStats, MemoryCacheOptions } from 'cache-hub';

`new MemoryCache(options?)`

Option	Type	Default	Description
`maxEntries`	`number`	`10000`	Maximum number of entries before LRU eviction.
`maxMemory`	`number`	`0`	Estimated max memory in bytes. `0` disables the memory limit.
`defaultTtl`	`number`	`0`	Default TTL in milliseconds. `0` means no expiration.
`cleanupInterval`	`number`	`0`	Periodic expired-entry cleanup interval in milliseconds.
`enableStats`	`boolean`	`true`	Enables hit/miss statistics.
`enableTags`	`boolean`	`false`	Enables tag indexes and `invalidateByTag`.
`enabled`	`boolean`	`true`	Disables cache reads/writes when set to `false`.

MemoryCache also exposes getRemainingTtl(key) and getRemainingTtlMany(keys). A non-expiring existing key returns null; a missing or expired key returns undefined.

`CacheLike`

Every cache implementation can be used through this interface:

interface CacheLike {
    get<T = any>(key: string): T | undefined | Promise<T | undefined>;
    set(key: string, value: any, ttl?: number, options?: CacheSetOptions): void | Promise<void>;
    del(key: string): boolean | Promise<boolean>;
    exists(key: string): boolean | Promise<boolean>;
    has(key: string): boolean | Promise<boolean>;
    clear(): void | Promise<void>;
    keys(pattern?: string): string[] | Promise<string[]>;
    getMany(keys: string[]): Record<string, any> | Promise<Record<string, any>>;
    setMany(entries: Record<string, any>, ttl?: number): boolean | Promise<boolean>;
    delMany(keys: string[]): number | Promise<number>;
    delPattern(pattern: string): number | Promise<number>;
    getRemainingTtl?(key: string): number | null | undefined | Promise<number | null | undefined>;
    getRemainingTtlMany?(keys: string[]): Record<string, number | null> | Promise<Record<string, number | null>>;
    invalidateByTag?(tag: string): void | number | Promise<void | number>;
    getStats?(): CacheStats;
    resetStats?(): void;
    destroy?(): void;
    setLockManager?(lm: LockManager): void;
}

`cache-hub/read-through`

import { readThrough, readThroughWithLease } from 'cache-hub/read-through';

function readThrough<V>(
    cache: CacheLike,
    ttl: number,
    key: string,
    fetcher: () => Promise<V>,
): Promise<V>;

ttl <= 0 runs the fetcher without writing to cache.
null is cached as a valid value.
undefined is treated as a miss signal and is not cached.
Same-key concurrent calls share one in-flight promise.
readThroughWithLease(options) adds a CacheLeaseStore for cross-process de-duplication. It is useful for short TTL response cache entries that may be regenerated by many workers at once.

readThroughWithLease options:

Option	Type	Default	Description
`cache`	`CacheLike`	required	Cache to read from and write to.
`key`	`string`	required	Cache key and lease resource key.
`ttlMs`	`number`	required	Cache TTL in milliseconds. `<= 0` bypasses cache and lease.
`fetcher`	`() => Promise<T>`	required	Origin function used on miss.
`leaseStore`	`CacheLeaseStore`	required	Lease store, usually created with `createRedisLeaseStore`.
`leaseTtlMs`	`number`	`min(ttlMs, 5000)`, at least `50`	Lease lifetime. Keep it longer than the normal fetch latency.
`waitForOwnerMs`	`number`	`leaseTtlMs + 25`	How long non-owner callers wait for cache fill.
`pollIntervalMs`	`number`	`10`	Cache polling interval while waiting.
`onLeaseTimeout`	`'fetch' \| 'throw'`	`'fetch'`	Fallback behavior when no owner fills the cache in time.

`cache-hub/multi-level`

import { MultiLevelCache } from 'cache-hub/multi-level';

new MultiLevelCache(options);

Option	Type	Default	Description
`local`	`CacheLike`	required	L1 local cache.
`remote`	`CacheLike`	`undefined`	Optional L2 remote cache.
`writePolicy`	`'both' \| 'local-first-async-remote'`	`'both'`	Write-through or local-first async write policy.
`backfillOnRemoteHit`	`boolean`	`true`	Backfills L1 after L2 hit. Preserves remote TTL when supported.
`remoteTimeoutMs`	`number`	`50`	L2 get timeout in milliseconds. Timeout falls back to L1 miss behavior.
`publish`	`(msg) => void`	`undefined`	Optional callback for distributed invalidation messages.
`remoteInvalidationErrors`	`'ignore' \| 'throw'`	`'ignore'`	Controls whether remote `invalidateByTag` errors are swallowed or rethrown.

`cache-hub/redis`

import { createRedisCacheAdapter } from 'cache-hub/redis';

const adapter = createRedisCacheAdapter('redis://localhost:6379');

Options:

Option	Type	Default	Description
`metaKeyPrefix`	`string`	`__cache-hub`	Prefix for Redis tag metadata keys. Use an app-specific prefix when several apps share a Redis database.
`scanCount`	`number`	`100`	SCAN / SSCAN count hint. Must be positive.
`deleteCommand`	`'del' \| 'unlink'`	`'del'`	Use `unlink` for asynchronous Redis memory reclamation on large values.

The Redis adapter implements CacheLike and adds:

Method	Description
`getRemainingTtl(key)`	Returns remaining TTL in milliseconds, `null` for non-expiring keys, and `undefined` for missing keys.
`getRemainingTtlMany(keys)`	Batch TTL lookup.
`invalidateByTag(tag)`	Deletes cache entries attached to a tag and returns the number of deleted business keys.
`close()`	Closes only the connection created by the adapter. Externally supplied ioredis instances are not closed.
`getRedisInstance()`	Returns the underlying ioredis instance for advanced use cases.

Pattern operations use SCAN with COUNT 100; KEYS is not used.

`cache-hub/lease`

import { createRedisLeaseStore } from 'cache-hub/lease';

const leaseStore = createRedisLeaseStore(redisCacheOrIoredis, {
    leaseKeyPrefix: 'my-app:cache-lease',
    ownerId: 'api-worker-1',
});

Option	Type	Default	Description
`leaseKeyPrefix`	`string`	`__cache-hub:lease`	Prefix for Redis lease keys.
`ownerId`	`string`	random UUID	Stable owner prefix included in lease tokens.

The Redis lease store uses SET key token NX PX ttlMs to acquire a lease and Lua scripts to release or renew only when the token still matches.

`cache-hub/function-cache`

import { FunctionCache, withCache } from 'cache-hub/function-cache';

const cachedFn = withCache(asyncFn, {
    cache,
    ttl: 60_000,
    namespace: 'users',
    keyBuilder: (...args) => `custom:${args.join(':')}`,
    condition: (result) => result !== null,
});

withCache(fn).invalidateAll() only deletes keys that were actually written by that wrapped function. It does not delete unrelated manual keys that happen to share the same prefix.

`cache-hub/distributed`

import { DistributedCacheInvalidator } from 'cache-hub/distributed';

const invalidator = new DistributedCacheInvalidator({
    cache,
    redisUrl: 'redis://localhost:6379',
});

Option	Description
`cache`	Required cache instance that receives `delPattern(pattern)` and, for tag messages, `invalidateByTag(tag)` calls.
`redisUrl`	Redis URL. Defaults to `redis://localhost:6379` when neither `redisUrl` nor `redis` is provided.
`redis`	Existing ioredis instance used for publishing.
`channel`	Pub/Sub channel. Defaults to `cache-hub:invalidate`.
`instanceId`	Unique instance id used to filter self-sent messages.

Methods:

Method	Description
`invalidate(pattern)`	Invalidates the current instance with `delPattern(pattern)` and broadcasts a backward-compatible pattern message.
`invalidatePattern(pattern)`	Alias for `invalidate(pattern)`.
`invalidateTag(tag)`	Invalidates the current instance with `invalidateByTag(tag)` and broadcasts a tag message.

`cache-hub/atomic`

import {
    createMemoryAtomicStateBackend,
    createRedisAtomicStateBackend,
} from 'cache-hub/atomic';

API	Description
`MemoryAtomicStateBackend`	Synchronous in-memory atomic counter backend.
`RedisAtomicStateBackend`	Async Redis atomic counter backend backed by Lua scripts.
`incrementWithTtl(key, amount, ttlMs)`	Atomically increments a counter and assigns TTL on first write.
`decrement(key, amount?)`	Atomically decrements a counter while preserving TTL.
`reset(key)`	Deletes one atomic state key.
`resetPrefix(prefix)`	Deletes keys under a literal prefix with SCAN.

`cache-hub/rate-limit`

import {
    createMemoryFixedWindowRateLimitStore,
    createMemoryRateLimitStateStore,
    createRedisFixedWindowRateLimitStore,
    createRedisRateLimitStateStore,
} from 'cache-hub/rate-limit';

API	Description
`MemoryFixedWindowRateLimitStore`	Synchronous in-memory fixed-window counter.
`RedisFixedWindowRateLimitStore`	Async Redis fixed-window counter backed by Lua scripts.
`MemoryRateLimitStateStore`	In-memory sliding-window, token-bucket, and leaky-bucket state primitives.
`RedisRateLimitStateStore`	Redis Lua-backed sliding-window, token-bucket, and leaky-bucket state primitives.
`increment(key, windowMs, limit, amount?)`	Increments the current window and returns hits, remaining quota, reset time, and retry-after.
`decrement(key, amount?)`	Rolls back a counter, useful when downstream work fails after reservation.
`checkSlidingWindow(key, windowMs, limit, cost?)`	Reserves sliding-window state and returns an opaque rollback token when allowed.
`consumeTokenBucket(key, capacity, refillPerSecond, cost?)`	Atomically consumes token-bucket capacity and returns retry timing.
`consumeLeakyBucket(key, capacity, leakPerSecond, cost?)`	Atomically consumes leaky-bucket capacity and returns retry timing.
`reset(key)`	Deletes one rate-limit key.
`resetPrefix(prefix)`	Deletes keys under a literal prefix with SCAN.

`cache-hub/stringify`

import { stableStringify } from 'cache-hub/stringify';

stableStringify({ b: 2, a: 1 }); // '{"a":1,"b":2}'
stableStringify(NaN); // '"__NaN__"'

stableStringify sorts object keys, handles cycles, supports custom serializers, and keeps cache keys deterministic across processes.

Redis Defaults

Redis-backed examples use:

redis://localhost:6379

This URL means local Redis on port 6379 with no password. If your Redis requires authentication, use the standard Redis URL form:

redis://:password@host:6379

For tests, set REDIS_URL when you need a non-default endpoint:

REDIS_URL=redis://127.0.0.1:6379 npm run test:integration

Testing

# All Vitest tests; Redis integration tests run when Redis is reachable
npm test

# Coverage
npm run test:coverage

# Redis integration tests only
npm run test:integration

# Skip Redis integration tests explicitly
SKIP_INTEGRATION=true npm run test:integration

npm test runs the full Vitest suite. Redis integration cases execute when a reachable Redis server is available; otherwise they log a skip message. Integration tests require ioredis in the development environment. The package keeps ioredis as an optional peer dependency for consumers and as a dev dependency for real integration coverage.

Coverage target: statements, branches, functions, and lines all at 100%.

Benchmarking

# Build first, then print benchmark tables
npm run benchmark

# Print JSON to stdout
npm run benchmark -- --json

# Write JSON to a file
npm run benchmark -- --json --output benchmark-results.json

The benchmark script focuses on direct library hot paths. Treat the numbers as local performance signals, not as a replacement for production HTTP middleware or real Redis network benchmarks.

Build

# Type check only
npm run typecheck

# Build ESM, CommonJS, and declaration files
npm run build

Build output:

dist/
├── esm/
├── cjs/
└── types/

The package exposes matching ESM, CJS, and type declaration paths for every public subpath export.

Node.js Support

Node.js	Status
18 LTS	Supported
20 LTS	Supported
22 LTS	Supported

cache-hub requires Node.js >=18.0.0.

Troubleshooting

Symptom	Check
`redis-adapter requires ioredis`	Install `ioredis` in the consuming project: `npm install ioredis`.
Redis tests are skipped	Confirm Redis is running and `REDIS_URL` points to the reachable endpoint.
Redis auth fails	Use `redis://:password@host:6379` or pass an already configured ioredis instance.
Pattern deletes are slower than expected	`delPattern` and `keys` use SCAN for safety; this avoids blocking Redis like KEYS.
Cache misses after storing `undefined`	`undefined` is the miss signal. Use `null` or a sentinel object for cacheable empty results.
Tag invalidation does not remove Redis entries	Confirm entries were written with `set(key, value, ttl, { tags })` and that all instances use the same `metaKeyPrefix`.
Expired Redis keys still appear in tag metadata	This is expected; `invalidateByTag` cleans stale members lazily while scanning the tag.
Too many origin fetches after short TTL expiry	Use `readThroughWithLease` with a Redis lease store and set `leaseTtlMs` longer than normal fetch latency.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github/workflows		.github/workflows
bugs		bugs
changelogs		changelogs
docs		docs
scripts		scripts
src		src
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.integration.config.ts		vitest.integration.config.ts

Folders and files

Latest commit

History

Repository files navigation

cache-hub

Table of Contents

Why cache-hub

Installation

Quick Start

Memory Cache

Read-through Cache

Read-through with Redis Lease

Function Cache

Multi-level Cache

Tags

Distributed Invalidation

Fixed-window Rate-limit Store

Atomic State Backend

Module Reference

cache-hub

new MemoryCache(options?)

CacheLike

cache-hub/read-through

cache-hub/multi-level

cache-hub/redis

cache-hub/lease

cache-hub/function-cache

cache-hub/distributed

cache-hub/atomic

cache-hub/rate-limit

cache-hub/stringify

Redis Defaults

Testing

Benchmarking

Build

Node.js Support

Troubleshooting

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`cache-hub`

`new MemoryCache(options?)`

`CacheLike`

`cache-hub/read-through`

`cache-hub/multi-level`

`cache-hub/redis`

`cache-hub/lease`

`cache-hub/function-cache`

`cache-hub/distributed`

`cache-hub/atomic`

`cache-hub/rate-limit`

`cache-hub/stringify`

Packages