ioredis-cache-aside

Tiny cache-aside helper for ioredis that degrades gracefully when Redis is down. If Redis is unreachable, reads fall through to your source and writes are skipped — your app keeps serving instead of throwing.

No global client, no framework assumptions, one peer dependency. ~70 lines.

The problem

The cache-aside pattern is easy to write and easy to get subtly wrong:

const cached = await redis.get(key);
if (cached) return JSON.parse(cached);
const fresh = await fetchFromDb();
await redis.set(key, JSON.stringify(fresh)); // ← if Redis is down, this throws and 500s your request
return fresh;

You end up hand-rolling try/catch fallbacks and a SCAN loop for pattern invalidation in every project. This packages that once, correctly.

Install

npm install ioredis-cache-aside ioredis

Usage

import Redis from "ioredis";
import { createCache } from "ioredis-cache-aside";

const cache = createCache(new Redis(process.env.REDIS_URL), { ttl: 300 });

// Get-or-fetch. Caches the result; returns it from cache next time.
const user = await cache.cached(`user:${id}`, () => db.user.findUnique({ where: { id } }));

// After a mutation, drop the stale entries.
await cache.invalidate(`user:${id}`);
await cache.invalidatePattern("user:*"); // uses SCAN, not the blocking KEYS

Graceful degradation

If Redis throws (down, timeout, network blip), cached() simply runs your fetcher and returns the value. Caching is best-effort, never a hard dependency:

// Redis unreachable → no error, value still returned from the source
const value = await cache.cached("k", () => fetchFromSource());

API

| Method | Behavior | | --- | --- | | createCache(redis, { ttl? }) | Build a cache bound to your ioredis client. ttl defaults to 300s. | | cached(key, fetcher, ttl?) | Return cached JSON, else run fetcher, cache it, return it. | | invalidate(...keys) | Delete exact keys. | | invalidatePattern(pattern) | Delete every key matching a glob (via non-blocking SCAN). |

All methods swallow Redis errors so a cache outage never breaks the request path.

License

MIT © Keneth Baranduda