walkeros-using-store-cache

Using store-level cache

Overview

Flow.Store.cache wraps any store with a read-through, write-through cache tier. Reads check the cache first, fall through to the backing on miss, and populate every tier on the unwind. Writes go to the backing first, then to the cache best-effort.

The wrapping is transparent: a transformer wired to $store.crm does not know whether reads hit a memory cache, a GCS tier, or the underlying Sheets API.

Core principle: the cache is advisory. Backing is the source of truth. Failed cache operations degrade performance, never correctness.

TTL is owned by the cache layer, not the store. The store persists structured values; the cache wrapper manages expiry via the per-rule ttl. An expired entry is treated as a miss and re-fetched from the backing. Caching works over any structured backing.

A store's byte-native file mode (config.file: true) is for serving raw assets byte-exact, not for caching. The cache wraps structured stores, so flow_validate warns when a store sets both file: true and cache. Drop one: serve bytes with file: true and no cache, or cache a structured store with no file.

When to use this skill

• A transformer reads the same key many times across events (sessions, user lookups, product catalog enrichment)
• A store has rate limits or slow HTTP round-trips (Sheets, custom API, S3 metadata); @walkeros/server-store-api reads a third-party API, and its misses are not cached
• You need to deduplicate concurrent reads on a cold key (thundering herd)
• You want to compose multi-tier caches (memory → GCS → Sheets)

Minimal recipe: cache a Sheets store

The talk-demo use case. A sessions lookup runs on every event but most events in a session share the same key.

{
  "stores": {
    "sessions": {
      "package": "@walkeros/server-store-sheets",
      "config": {
        "credentials": "$secret.SHEETS_CREDENTIALS",
        "settings": {
          "id": "1AbC...",
          "sheet": "Sessions"
        }
      },
      "cache": { "rules": [{ "ttl": 300 }] }
    }
  },
  "transformers": {
    "sessionLookup": {
      "code": {
        "type": "session-lookup",
        "push": "$code:async (event, context) => { if (!event.user?.session) return; const session = await context.env.store.get(event.user.session); if (session) return { event: { ...event, data: { ...event.data, session } } }; }"
      },
      "env": { "store": "$store.sessions" }
    }
  }
}