@plasius/graph-cache-redis

Redis-backed cache adapter implementing the graph cache store port.

Apache-2.0. ESM + CJS builds. TypeScript types included.

Requirements

• Node.js 24+ (matches .nvmrc and CI/CD)
• Redis-compatible server
• ioredis

Installation

npm install @plasius/graph-cache-redis ioredis

Exports

import {
  RedisCacheStore,
  type RedisLike,
  type RedisCacheStoreOptions,
} from "@plasius/graph-cache-redis";

Quick Start

import Redis from "ioredis";
import { RedisCacheStore } from "@plasius/graph-cache-redis";

const redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379");
const cacheStore = new RedisCacheStore({
  redis,
  namespace: "graph",
  maxCommandRetries: 2,
  retryDelayMs: 10,
  retryJitterRatio: 0.2,
  enableStaleFallback: true,
  telemetry,
});

await cacheStore.set("user:1", {
  key: "user:1",
  value: { id: 1 },
  fetchedAtEpochMs: Date.now(),
  policy: { softTtlSeconds: 30, hardTtlSeconds: 300 },
  version: 1,
  schemaVersion: "1",
  source: "user.profile",
  tags: ["user"],
}, { ttlSeconds: 300 });

const leaseOwner = await cacheStore.acquireStampedeLease("user:1", { ttlSeconds: 5 });
if (leaseOwner) {
  try {
    // perform a single-owner revalidation
  } finally {
    await cacheStore.releaseStampedeLease("user:1", leaseOwner);
  }
}

Development

npm run clean
npm install
npm run lint
npm run typecheck
npm run test:coverage
npm run build

Resilience Features

• Command retry controls for transient Redis failures.
• Stale fallback reads with hard TTL enforcement during read failover.
• Stampede lease primitives for single-owner refresh:
  • acquireStampedeLease
  • releaseStampedeLease
• Telemetry support (optional TelemetrySink) for:
  • command retries/errors,
  • stale fallback reads,
  • lease acquire/release outcomes.
• Integration-style tests cover:
  • failover stale reads,
  • reconnect retry path,
  • hard TTL stale expiry.

Architecture

• Package ADRs: docs/adrs
• Cross-package ADRs: plasius-ltd-site/docs/adrs/adr-0020 to adr-0024

License

Licensed under the Apache-2.0 License.