Layercache

    Documentation

    Welcome to the Layercache documentation.

    Layercache stacks memory, Redis, and disk behind a single API with stampede prevention, tag invalidation, stale-while-revalidate, and full observability.

    How It Works

    Every read follows the same path:

    1. Check L1 Memory first (fastest, in-process).
    2. If miss, check L2 Redis (shared across instances).
    3. If miss, check L3 Disk (persistent fallback).
    4. If all miss, run the origin fetcher once (single-flight).
    5. Backfill upper layers so next reads return faster.

    Layercache keeps responses stable under pressure with stale serving, circuit breakers, and timeout guards.

    Version 5.0 Highlights

    Layercache 5.0 is a major release because it hardens cache isolation so authenticated responses are never served across users:

    • Breaking: createTrpcCacheMiddleware and cacheGraphqlResolver now require a keyResolver — the allowImplicitContextCaching option is removed. Implicit path+input or argument-only keys could not distinguish authenticated callers.
    • Express and Hono middlewares bypass implicit URL-only caching when requests carry authentication headers (authorization, cookie, set-cookie, x-api-key, x-session-id, x-auth-token, x-forwarded-user), so one user's authenticated response is never served to another. Provide a keyResolver to opt back in for safe keys.
    • RedisInvalidationBus supports requireSignature to fail fast when a signing secret is missing, preventing forged invalidation messages on shared Redis channels.
    • The test suite is split into unit and real-Redis Vitest projects, and docker-compose Redis uses the configurable REDIS_PORT.

    Read the migration guide before upgrading an existing deployment.

    Version 4.0 Highlights

    Layercache 4.0 makes missing values unambiguous and hardens production coordination boundaries:

    • Public cache reads return undefined on misses while preserving intentional cached null values.
    • Read-through fetchers cache null by default; cacheNullValues: false retains legacy null-as-absence behavior.
    • Structured wrap() keys use the collision-resistant j2: schema, and write ordering plus generation cleanup have finite limits.
    • Snapshot commits, signed invalidation, HTTP credential handling, destructive CLI patterns, and playground isolation are hardened.
    • Regression coverage includes the merged scheduler, snapshot, invalidation, and epoch rollover fixes.

    Read the migration guide before upgrading an existing deployment.

    • Getting Started — Install and configure your first cache stack
    • Tutorial — 10-step walkthrough of production features
    • API Reference — Complete method and option documentation
    • Integrations — Express, Fastify, NestJS, Hono, tRPC, GraphQL