Core concepts

Layeron Cache gives application code one product API while Layeron manages the Cloudflare Cache runtime and product metadata behind it.

Cache Instance

A cache(...) declaration creates one logical Cache product instance:

const apiCache = cache({
  name: "public-api",
  namespace: "storefront",
  ttlSeconds: 60,
})

The cache instance uses Layeron’s platform identity model. In this example, the identity is storefront/public-api. See Namespaces for defaults and naming rules.

Use separate instances when different product areas need separate defaults, stats, or invalidation behavior.

Cache Key

The cache key is the value sent to Cloudflare Cache. Layeron derives it from:

• The request URL with sorted query parameters.
• The HTTP method.
• The instance namespace.
• The configured vary headers and their request values.

const key = apiCache.key(request, {
  vary: ["accept-language"],
})

Tags are invalidation metadata. They are stored with written entries and used by purge({ tags }).

TTL

ttlSeconds controls the fresh lifetime for written responses:

const apiCache = cache({
  name: "public-api",
  ttlSeconds: 120,
})

You can override the TTL per write:

await apiCache.put(request, response.clone(), {
  ttlSeconds: 30,
})

Layeron writes a Cache-Control header for Cloudflare Cache using this TTL.

Stale While Revalidate

staleWhileRevalidateSeconds adds a stale serving window:

const apiCache = cache({
  name: "public-api",
  ttlSeconds: 60,
  staleWhileRevalidateSeconds: 30,
})

This maps to the response Cache-Control header so Cloudflare Cache can serve a recent stale response while revalidation work runs.

Vary

vary controls which request headers become part of the key:

const apiCache = cache({
  name: "localized-content",
  vary: ["accept-language"],
})

Good vary dimensions are stable and low-cardinality. Common examples include accept-language, accept, and a small tenant header controlled by your app.

Tags

Tags group written entries for invalidation:

await apiCache.put(request, response.clone(), {
  tags: ["products", "product:123"],
})

await apiCache.purge({
  tags: ["product:123"],
})

Use broad tags for list pages and precise tags for detail pages. A product detail response might carry both products and product:123.

Route Rules

Route rules declare cache policy for routes:

cache({
  name: "public-api",
  rules: [{
    name: "products",
    path: "/api/products",
    methods: ["GET"],
    ttlSeconds: 60,
    tags: ["products"],
    bypass: {
      query: ["preview"],
      headers: ["x-cache-bypass"],
    },
  }],
})

Rules are metadata Layeron can compile into runtime policy and dashboard surfaces. Manual route code can still call match, put, delete, purge, and stats.

State Store

Cache stores hot responses in Cloudflare Cache. Product metadata is persisted through the Layeron Database product:

Data	Purpose
Keys	Track cached request keys for prefix and request purges.
Tags	Map tags to cached keys for tag purges.
Events	Record puts, deletes, and purges for diagnostics.
Stats	Count hits, misses, puts, deletes, and purges.

The Database product boundary keeps Cache independent from direct D1 usage while preserving Layeron’s resource graph and product Worker model.