Overview

Layeron Cache (cache) gives your backend app a named edge cache built on Cloudflare Cache in your own Cloudflare account.

You declare the cache in application code. Layeron compiles the declaration into a Cache product Worker, Cloudflare Cache access, route metadata, and an internal Database product store for key, tag, event, and stats records.

import { backend } from "@layeron/core"
import { cache } from "@layeron/modules"

const app = backend()

const apiCache = cache({
  name: "public-api",
  namespace: "api",
  ttlSeconds: 120,
  staleWhileRevalidateSeconds: 30,
  vary: ["accept-language"],
  tags: ["public-api"],
})

app.use(apiCache)

With Cache, you can:

• Cache route responses and API reads at the Cloudflare edge.
• Use match, put, and delete from route handlers.
• Define TTL and stale-while-revalidate defaults once per cache instance.
• Vary cache entries by request headers such as accept-language.
• Attach invalidation tags to written responses.
• Purge entries by request, tag, or key prefix.
• Read counters for hits, misses, puts, deletes, and purges.
• Keep cache metadata inside the Layeron Database product boundary.

Common Workflows

Cache is designed around fast application paths:

• Cache read-heavy API routes after expensive database queries.
• Cache public JSON responses with predictable TTLs.
• Keep locale, content negotiation, and tenant-specific variants separated with vary.
• Attach tags such as products, product:123, or tenant:acme when writing entries.
• Purge affected entries after a write, import, webhook, or admin change.
• Inspect stats() during diagnostics.

Core Concepts

Cache has five central concepts:

• Cache instance: A named product instance declared with cache({ name }).
• Cache key: A deterministic URL derived from the request, instance namespace, method, and configured vary headers.
• TTL: The freshness window Cloudflare Cache can serve before revalidation.
• Tag: Metadata attached to written entries so a later purge can target a group of keys.
• State store: The internal Database product store that records keys, tags, events, and stats for the Cache product.

Runtime Model

The hot read path goes through Cloudflare Cache:

app.get("/api/products", async (request) => {
  const cached = await apiCache.match(request)

  if (cached) {
    return cached
  }

  const products = await loadProducts()
  const response = Response.json({ products })

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

  return response
})

Cache metadata is persisted through the Layeron Database product. Your app code works with the Cache API; Layeron handles the internal product call and resource placement.

What Cache Is Good For

Use Cache when the response is safe to reuse for a short period:

Workload	Recommended Pattern
Public product catalog	Cache list and detail routes, tag by collection and item ID.
CMS pages	Cache generated page JSON, purge by slug after publishing.
Search suggestions	Cache short-lived query results with a small TTL.
Feature metadata	Cache read-heavy configuration endpoints.
Localized content	Add accept-language to vary.

Next Steps

• Get started: Define a cache, cache route responses, add tags, purge entries, and read stats.
• Core concepts: Understand cache instances, keys, TTLs, stale behavior, tags, route rules, and state.
• Keys and vary: Build predictable keys across methods, query params, headers, and runtime calls.
• Route rules: Apply caching policy at the route layer.
• Invalidation: Remove entries with delete, request purge, tag purge, or prefix purge.
• Stats and observability: Inspect hit, miss, stale, bypass, and purge counters.
• Limits: Plan around cacheable responses, key cardinality, body sizes, tags, and stats timing.
• Examples: Adapt common response cache and webhook invalidation patterns.
• API reference: Review cache options, runtime methods, purge input, and stats result types.