Route rules

Route rules describe which routes should be cacheable and which policy should apply to those routes.

const apiCache = cache({
  name: "public-api",
  ttlSeconds: 120,
  rules: [{
    name: "products",
    path: "/api/products",
    methods: ["GET"],
    ttlSeconds: 60,
    staleWhileRevalidateSeconds: 30,
    vary: ["accept-language"],
    tags: ["products"],
    bypass: {
      query: ["preview"],
      headers: ["x-cache-bypass"],
      cookies: ["preview_session"],
    },
  }],
})

Rules keep cache policy visible in the app declaration. Layeron can use this metadata for compilation, routing surfaces, dashboards, and future automated gateway caching.

Rule Fields

Field	Description
name	Stable rule name for metadata and diagnostics.
path	Route path pattern covered by the rule.
methods	HTTP methods covered by the rule. Defaults to GET and HEAD.
ttlSeconds	Fresh lifetime for responses written under this rule.
staleWhileRevalidateSeconds	Optional stale serving window.
vary	Header names included in the key.
tags	Default invalidation tags for responses written by the rule.
bypass	Query params, headers, or cookies that should skip caching.

Instance Defaults

The cache instance provides defaults:

cache({
  name: "public-api",
  ttlSeconds: 120,
  staleWhileRevalidateSeconds: 30,
  vary: ["accept-language"],
  tags: ["public-api"],
  rules: [{
    name: "products",
    path: "/api/products",
    methods: ["GET"],
  }],
})

The products rule inherits TTL, stale-while-revalidate, vary, and tags from the instance.

Bypass Conditions

Use bypass controls for preview, debugging, and authenticated variants:

bypass: {
  query: ["preview", "no_cache"],
  headers: ["x-cache-bypass"],
  cookies: ["admin_session"],
}

Common bypass inputs:

• preview query parameters for CMS draft views.
• x-cache-bypass headers for operational debugging.
• Admin or preview cookies for editorial tools.

Manual Runtime Use

Rules and manual route calls work together. A route can still call the Cache runtime API directly:

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

  if (cached) {
    return cached
  }

  const response = Response.json({
    products: await listProducts(),
  })

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

  return response
})

Use explicit runtime calls when route code needs custom fetch, authorization, or write-through logic.