feat(cloudflare): Workers Cache support via cache prop on Worker

[sam-goodwin]

Adds support for Workers Cache — the Worker-owned edge cache that serves cached responses without invoking your Worker — mirroring the design already shipped for Effect-based Workers in #752 (Cloudflare.cache() / the cache prop, see https://alchemy.run/cloudflare/compute/cache/).

Usage

import { Worker } from "alchemy/cloudflare";

const worker = await Worker("my-worker", {
  entrypoint: "./src/worker.ts",
  cache: { enabled: true, crossVersionCache: true }, // or `cache: true`
});

Caching is controlled by standard response headers, and entries can be purged at runtime:

// src/worker.ts
export default {
  async fetch(request, env, ctx) {
    if (new URL(request.url).pathname === "/invalidate") {
      await ctx.cache.purge({ tags: ["products"] });
      return new Response("purged");
    }
    return Response.json(
      { hello: "world" },
      { headers: { "Cache-Control": "public, max-age=300", "Cache-Tag": "products" } },
    );
  },
};

What changed

• Worker gains cache?: boolean | WorkerCacheOptions ({ enabled?, crossVersionCache? }); true is shorthand for { enabled: true }.
• prepareWorkerMetadata maps it to cache_options: { enabled, cross_version_cache } in the upload metadata — the snake_case wire shape wrangler ≥ 4.69 uploads (verified live in feat(cloudflare/workers): add cache_options to putScript metadata distilled#364).
• Docs page at providers/cloudflare/cache.md.
• Tests (alchemy/test/cloudflare/cache.test.ts):
  • Deployed e2e: the worker returns a fresh UUID per invocation with Cache-Control: public, max-age=300 — repeat fetches must return the same UUID (served from cache without invoking the Worker), then ctx.cache.purge({ tags }) must produce a fresh one. Polls to absorb edge propagation.
  • Local: cache: true deploys in Miniflare and no-ops (Workers Cache is not emulated locally).

Notes for reviewers

• The deployed e2e has not been run in this session — every Cloudflare credential on this machine is stale (doppler CLOUDFLARE_API_KEY rejected, all OAuth refresh tokens invalid_grant). The local test and typecheck pass; the metadata wire shape matches what distilled#364 verified live.
• Generated wrangler.json intentionally does not emit a cache field yet: the repo pins wrangler 4.41, whose config schema predates cache (added in 4.69) and would warn on the unknown key.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/alchemy@1458

commit: f8dcff7

[github-actions]

🚀 Website Preview Deployed

Your website preview is ready!

Preview URL: https://0a8abd21-alchemy-website.alchemy-run.workers.dev

This preview was built from commit 5a2eb9d

---

_{🤖 This comment will be updated automatically when you push new commits to this PR.}

[waptik]

Package version from pr cannot be installed because it's unavailable