Improve ctx.cache ergonomics

[tewaro]

Allow cache to be imported from cloudflare:workers.

[ask-bonk]

I'm Bonk, and I've done a quick review of your PR.

This PR adds a cache export to cloudflare:workers that proxies through to the current request's CacheContext (i.e. ctx.cache), allowing module-level imports instead of threading the execution context.

Issues (ranked by severity)

1. Missing TypeScript type definitions for the new cache export — The runtime implementation exports cache from cloudflare:workers, but types/defines/rpc.d.ts (which defines the CloudflareWorkersModule namespace / cloudflare:workers module declaration) does not include a cache export. Users doing import { cache } from 'cloudflare:workers' will get a TypeScript compilation error even though it works at runtime. You need to add something like export const cache: CacheContext | undefined; to the CloudflareWorkersModule namespace in types/defines/rpc.d.ts (the CacheContext interface is already generated from C++ RTTI as a global ambient type) and then run just generate-types to update the snapshot.

2. Silent undefined return when accessed outside a request context — When getCurrentCache() is called outside an active IoContext (e.g., at module top-level), every property access on the cache proxy silently returns undefined. Compare with waitUntil, which throws when called outside a request. Silently returning undefined makes misuse harder to diagnose. Consider throwing an informative error instead, or document the intended behavior.

3. Proxy get trap calls getCurrentCache() on every property access — Each call to cache.purge(...) calls getCurrentCache() once in get (to look up the method), and operations like JSON.stringify(cache) or Object.keys(cache) call it multiple times across different traps. This is consistent with how the env proxy works, so it may be intentional, but worth noting.

[ask-bonk]

Review posted successfully on PR #6588. Here's a summary of my findings:

1. Missing TypeScript type definitions (highest severity) — types/defines/rpc.d.ts doesn't export cache from the cloudflare:workers module declaration, so users will get TS errors when importing it. Needs export const cache: CacheContext | undefined; added and just generate-types run.

2. Silent undefined on misuse — Unlike waitUntil which throws outside a request context, the cache proxy silently returns undefined for all property accesses when there's no active IoContext. This makes debugging harder.

3. Per-access overhead — getCurrentCache() is called on every proxy trap invocation, consistent with the env proxy pattern but worth noting.

github run

[codspeed-hq]

Merging this PR will not alter performance

✅ 72 untouched benchmarks
⏩ 129 skipped benchmarks¹

---

_{Comparing tewaro/ctx-cache-on-cloudflare-workers (61977ab) with main (432350d)}

Footnotes

1. 129 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[github-actions]

The generated output of @cloudflare/workers-types matches the snapshot in types/generated-snapshot 🎉