Single process

One process, one cache, nothing to operate. No Redis, no broker, no event bus.

This is the right setup when exactly one process reads and writes the data, or when each process is allowed to hold its own view of it for a bounded window.

What you get for free

You are not switching any of this on. It is already running.

The whole setup

There is no src/cache/redis.js and no src/cache/bus.js here. Those two files exist only once you have infrastructure to talk to. You write one file.

import { LazyLayersCache } from 'lazy-layers-cache'

export const cache = new LazyLayersCache({
  // Explicit, so the next reader knows the shared tier is off on purpose
  // rather than forgotten.
  l2: false,

  // Fallback lifetime for anything that does not set its own.
  ttlMs: 60 * 1000,

  levels: {
    // The only two dials L1 has. How many entries it holds, and how long
    // each one lives.
    L1: { maxEntries: 10_000, ttlMs: 30 * 1000 },
  },

  // Remember "this does not exist" briefly, so a missing row is not a free
  // pass to hammer the database.
  negativeCache: { ttlMs: 10 * 1000, maxEntries: 5_000 },

  // Give up on a loader that has stopped making progress.
  timeouts: { softMs: 800, hardMs: 5000 },

  // Serve the last known value while the origin is down.
  failSafe: { staleTtlMs: 30 * 1000 },
})

TypeScript users also want the value type in its own file, exactly as the quickstart lays it out.

export interface User {
  id: string
  email: string
  plan: 'free' | 'pro' | 'enterprise'
  updatedAt: string
}

Reading through it

getOrSet is the whole API surface you need. It checks L1 and then runs your loader.

import { cache } from '../cache/index.js'
import { db } from '../db.js'

export async function getUser(id) {
  return cache.getOrSet(`user:${id}`, async ({ signal } = {}) => {
    const row = await db.users.findById(id, { signal })
    return row ?? undefined   // undefined records a negative entry
  })
}

export async function updateUser(id, patch) {
  const updated = await db.users.update(id, patch)

  // After the write commits, never before. Until it commits the cached
  // value is still the truth.
  await cache.delete(`user:${id}`)

  return updated
}

The loader receives an AbortSignal that your timeouts actually fire. Pass it to your I/O or the timeout only stops the waiting, not the work.

Why these numbers

Choosing a TTL

The question is not how long you can cache something. It is how wrong it can be before someone notices.

Sizing L1

maxMemory defaults to 20% of effective host or container memory and is shared by built-in L1 stores in one process. maxEntries remains a separate count guard. LRU remains the replacement order, with bounded frequency and size signals used for admission when space is tight.

Plan for encoded payload bytes plus estimated key and metadata overhead and bounded fail-safe snapshots. Decoded values returned to application code are outside cache-owned accounting.

Measuring it

A cache you cannot measure is a cache you cannot tune.

import { cache } from './index.js'

let hits = 0
let misses = 0

cache.on((event) => {
  if (event.type === 'hit') hits++
  if (event.type === 'miss') misses++
})

setInterval(() => {
  const total = hits + misses
  if (total > 0) {
    console.log(`hit rate ${((hits / total) * 100).toFixed(1)}%`)
  }
  hits = 0
  misses = 0
}, 60_000)

A hit rate below roughly 50% usually means one of three things. maxEntries is too small and you are evicting hot keys, the TTL is shorter than your traffic pattern, or the keyspace is genuinely too wide to cache.

What you give up

Everything on this page costs you nothing to run, and here is the bill.

When you have outgrown it

Move on when any one of these is true.

Each of these is solved by adding a shared L2 and an event bus, which is one Redis connection and two more files.

Where to next