@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.

Cached Data Privacy Guidance

The adapter serializes the caller-provided cache envelope as-is. It does not redact, encrypt, or classify payload fields on your behalf. Callers must classify payloads before caching them and keep TTLs within the source system's privacy boundary.

The package exports REDIS_CACHE_ENTRY_PRIVACY_GUIDANCE for the baseline classes used by the cached-graph rollout:

| Class | Cacheable | Soft TTL | Hard TTL | Required handling | | --- | --- | ---: | ---: | --- | | public-reference | Yes | 60s | 900s | Keep only fields required by the consumer response. | | tenant-scoped-derived | Yes | 30s | 300s | Minimize fields and remove raw identifiers or free-text notes. | | sensitive-derived | Yes | 15s | 60s | Pseudonymize where possible and avoid auth/session material entirely. | | secret-or-regulated | No | 0s | 0s | Never cache tokens, credentials, recovery codes, raw claims, or unredacted PII. |

Use the guidance as a ceiling, not a default. If the authoritative system has a shorter retention boundary, the cache TTL must be shorter too.

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.