@takazudo/zfb-adapter-cloudflare 2.22.1 → 3.1.0

package/README.md

@@ -29,7 +29,6 @@ In `zfb.config.json`:
 
 ```json
 {
-  "framework": "preact",
   "adapter": "@takazudo/zfb-adapter-cloudflare"
 }
 ```

package/dist/index.d.ts

@@ -3,8 +3,10 @@
  * `ExecutionContext` interface. We do not depend on `@cloudflare/workers-types`
  * at the type level here because that would force every consumer of this
  * package to install it; instead we keep a minimal structural shape and
- * let users widen it via the generic on [`getCloudflareContext`] when
- * they need richer bindings.
+ * let consumers describe a compatible richer shape with the second generic
+ * on [`getCloudflareContext`] when they need additional execution-context
+ * bindings. That type is supplied by the caller; it is not detected or
+ * validated at runtime.
  */
 export interface CloudflareExecutionContext {
     /** Extends the lifetime of the request beyond the response. */
@@ -13,14 +15,15 @@ export interface CloudflareExecutionContext {
     passThroughOnException(): void;
 }
 /**
- * Per-request Cloudflare context. `Env` defaults to `unknown` so the
- * caller can narrow it at the call site (recommended) or leave it open.
+ * Per-request Cloudflare context. `Env` defaults to `unknown` and `Ctx` to
+ * the minimal execution-context shape. Consumers can supply narrower or
+ * richer types at the call site when they know the runtime shape.
  */
-export interface CloudflareContext<Env = unknown> {
+export interface CloudflareContext<Env = unknown, Ctx extends CloudflareExecutionContext = CloudflareExecutionContext> {
     /** CF env bindings (secrets, KV, D1, …) wired up via wrangler.toml. */
     readonly env: Env;
-    /** ExecutionContext for waitUntil / passThroughOnException. */
-    readonly ctx: CloudflareExecutionContext;
+    /** ExecutionContext for waitUntil / passThroughOnException and any declared extensions. */
+    readonly ctx: Ctx;
     /** The original Request, useful when handlers want headers / URL. */
     readonly request: Request;
 }
@@ -28,14 +31,16 @@ export interface CloudflareContext<Env = unknown> {
  * Establish a Cloudflare context for the duration of `fn`. Used by the
  * `_worker.js` wrapper; not normally called by user code.
  */
-export declare function runWithCloudflareContext<T>(context: CloudflareContext, fn: () => T): T;
+export declare function runWithCloudflareContext<T, C extends CloudflareContext = CloudflareContext>(context: C, fn: () => T): T;
 /**
  * Read the current Cloudflare context. Throws if called outside a
  * Cloudflare request scope (e.g. from a build-time SSG render). Catch
  * the error and gate on `prerender = false` if you need a route to work
  * in both modes.
  *
- * The `Env` generic narrows the bindings shape — passing it is
- * recommended so TypeScript catches typos like `env.ANTRHOPIC_KEY`.
+ * `Env` describes the bindings available to the caller, while `Ctx` can
+ * describe a compatible richer execution context. These generic arguments
+ * are caller assertions: this function does not inspect runtime bindings or
+ * feature-detect optional properties. Guard optional fields before use.
  */
-export declare function getCloudflareContext<Env = unknown>(): CloudflareContext<Env>;
+export declare function getCloudflareContext<Env = unknown, Ctx extends CloudflareExecutionContext = CloudflareExecutionContext>(): CloudflareContext<Env, Ctx>;

package/dist/index.js

@@ -68,8 +68,10 @@ export function runWithCloudflareContext(context, fn) {
  * the error and gate on `prerender = false` if you need a route to work
  * in both modes.
  *
- * The `Env` generic narrows the bindings shape — passing it is
- * recommended so TypeScript catches typos like `env.ANTRHOPIC_KEY`.
+ * `Env` describes the bindings available to the caller, while `Ctx` can
+ * describe a compatible richer execution context. These generic arguments
+ * are caller assertions: this function does not inspect runtime bindings or
+ * feature-detect optional properties. Guard optional fields before use.
  */
 export function getCloudflareContext() {
     const c = getStorage().getStore();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,qEAAqE;AACrE,kBAAkB;AAClB,EAAE;AACF,sEAAsE;AACtE,uEAAuE;AACvE,iEAAiE;AACjE,EAAE;AACF,wCAAwC;AACxC,EAAE;AACF,6EAA6E;AAC7E,EAAE;AACF,oCAAoC;AACpC,+CAA+C;AAC/C,kFAAkF;AAClF,yDAAyD;AACzD,MAAM;AACN,EAAE;AACF,wEAAwE;AACxE,qBAAqB;AACrB,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,oDAAoD;AACpD,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,yEAAyE;AACzE,4DAA4D;AAC5D,EAAE;AACF,sEAAsE;AACtE,yEAAyE;AACzE,mEAAmE;AACnE,yEAAyE;AACzE,qEAAqE;AACrE,uEAAuE;AACvE,uEAAuE;AACvE,6CAA6C;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA8BrD,uDAAuD;AACvD,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAM7C;;;;;;GAMG;AACH,SAAS,UAAU;IACjB,MAAM,CAAC,GAAG,UAAuC,CAAC;IAClD,IAAI,GAAG,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAI,iBAAiB,EAAqB,CAAC;QACjD,CAAC,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;IACvB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAI,OAA0B,EAAE,EAAW;IACjF,OAAO,UAAU,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC;IAClC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CACb,6FAA6F;YAC3F,yFAAyF;YACzF,gGAAgG,CACnG,CAAC;IACJ,CAAC;IACD,OAAO,CAA2B,CAAC;AACrC,CAAC","sourcesContent":["// `@takazudo/zfb-adapter-cloudflare` — Cloudflare Workers Static Assets\n// adapter for the zfb framework (also deployable to Cloudflare Pages\n// advanced mode).\n//\n// This entry (`./`) is the **Workers-runtime** surface. It is safe to\n// bundle into a Cloudflare Worker and does not depend on any Node-only\n// built-ins beyond `node:async_hooks` (which workerd polyfills).\n//\n// Usage in a `prerender = false` route:\n//\n//   import { getCloudflareContext } from \"@takazudo/zfb-adapter-cloudflare\";\n//\n//   export const prerender = false;\n//   export default async function ApiRoute() {\n//     const { env, ctx } = getCloudflareContext<{ ANTHROPIC_API_KEY: string }>();\n//     // env.ANTHROPIC_API_KEY, ctx.waitUntil(...), etc.\n//   }\n//\n// For Node-only build helpers (e.g. `emitWorker`), import the `./build`\n// sub-entry instead:\n//\n//   import { emitWorker } from \"@takazudo/zfb-adapter-cloudflare/build\";\n//\n// ## Why AsyncLocalStorage on a globalThis registry\n//\n// Cloudflare Workers can process multiple requests concurrently in the\n// same isolate. A naïve `globalThis.__env = env` write would race across\n// requests. AsyncLocalStorage gives us a per-request scope that survives\n// `await` points without interfering with sibling requests.\n//\n// We register the storage instance on `globalThis` under a stable key\n// (`__zfb_cf_adapter_als__`) so the wrapper at `_worker.js` and the user\n// pages bundled together can share the same instance even when the\n// adapter module ends up duplicated in the final bundle graph (e.g. when\n// the wrapper file is emitted side-by-side with the inner bundle and\n// each pulls in its own copy of this module). Module-instance identity\n// is the property AsyncLocalStorage relies on; the registry pattern is\n// what makes it survive bundler duplication.\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\n/**\n * Cloudflare execution context — minimal projection of the workerd\n * `ExecutionContext` interface. We do not depend on `@cloudflare/workers-types`\n * at the type level here because that would force every consumer of this\n * package to install it; instead we keep a minimal structural shape and\n * let users widen it via the generic on [`getCloudflareContext`] when\n * they need richer bindings.\n */\nexport interface CloudflareExecutionContext {\n  /** Extends the lifetime of the request beyond the response. */\n  waitUntil(promise: Promise<unknown>): void;\n  /** Falls through to the static origin on uncaught exceptions. */\n  passThroughOnException(): void;\n}\n\n/**\n * Per-request Cloudflare context. `Env` defaults to `unknown` so the\n * caller can narrow it at the call site (recommended) or leave it open.\n */\nexport interface CloudflareContext<Env = unknown> {\n  /** CF env bindings (secrets, KV, D1, …) wired up via wrangler.toml. */\n  readonly env: Env;\n  /** ExecutionContext for waitUntil / passThroughOnException. */\n  readonly ctx: CloudflareExecutionContext;\n  /** The original Request, useful when handlers want headers / URL. */\n  readonly request: Request;\n}\n\n/** Stable globalThis key the registry pattern uses. */\nconst STORAGE_KEY = \"__zfb_cf_adapter_als__\";\n\ninterface RegistryGlobal {\n  [STORAGE_KEY]?: AsyncLocalStorage<CloudflareContext>;\n}\n\n/**\n * Acquire (or lazily create) the singleton AsyncLocalStorage instance.\n *\n * Stored on `globalThis` under a stable key so the wrapper at\n * `_worker.js` and the user bundle share state even if the adapter\n * module ends up duplicated in the final module graph.\n */\nfunction getStorage(): AsyncLocalStorage<CloudflareContext> {\n  const g = globalThis as unknown as RegistryGlobal;\n  let als = g[STORAGE_KEY];\n  if (!als) {\n    als = new AsyncLocalStorage<CloudflareContext>();\n    g[STORAGE_KEY] = als;\n  }\n  return als;\n}\n\n/**\n * Establish a Cloudflare context for the duration of `fn`. Used by the\n * `_worker.js` wrapper; not normally called by user code.\n */\nexport function runWithCloudflareContext<T>(context: CloudflareContext, fn: () => T): T {\n  return getStorage().run(context, fn);\n}\n\n/**\n * Read the current Cloudflare context. Throws if called outside a\n * Cloudflare request scope (e.g. from a build-time SSG render). Catch\n * the error and gate on `prerender = false` if you need a route to work\n * in both modes.\n *\n * The `Env` generic narrows the bindings shape — passing it is\n * recommended so TypeScript catches typos like `env.ANTRHOPIC_KEY`.\n */\nexport function getCloudflareContext<Env = unknown>(): CloudflareContext<Env> {\n  const c = getStorage().getStore();\n  if (!c) {\n    throw new Error(\n      \"[zfb-adapter-cloudflare] getCloudflareContext() called outside a Cloudflare request scope. \" +\n        \"This usually means the route was rendered at build time (SSG) instead of dispatched by \" +\n        \"the Worker. Add `export const prerender = false;` to the page if it needs Cloudflare bindings.\",\n    );\n  }\n  return c as CloudflareContext<Env>;\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,qEAAqE;AACrE,kBAAkB;AAClB,EAAE;AACF,sEAAsE;AACtE,uEAAuE;AACvE,iEAAiE;AACjE,EAAE;AACF,wCAAwC;AACxC,EAAE;AACF,6EAA6E;AAC7E,EAAE;AACF,oCAAoC;AACpC,+CAA+C;AAC/C,kFAAkF;AAClF,yDAAyD;AACzD,MAAM;AACN,EAAE;AACF,wEAAwE;AACxE,qBAAqB;AACrB,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,oDAAoD;AACpD,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,yEAAyE;AACzE,4DAA4D;AAC5D,EAAE;AACF,sEAAsE;AACtE,yEAAyE;AACzE,mEAAmE;AACnE,yEAAyE;AACzE,qEAAqE;AACrE,uEAAuE;AACvE,uEAAuE;AACvE,6CAA6C;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAoCrD,uDAAuD;AACvD,MAAM,WAAW,GAAG,wBAAwB,CAAC;AAM7C;;;;;;GAMG;AACH,SAAS,UAAU;IACjB,MAAM,CAAC,GAAG,UAAuC,CAAC;IAClD,IAAI,GAAG,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,GAAG,GAAG,IAAI,iBAAiB,EAAqB,CAAC;QACjD,CAAC,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;IACvB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAU,EACV,EAAW;IAEX,OAAO,UAAU,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB;IAIlC,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC;IAClC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,IAAI,KAAK,CACb,6FAA6F;YAC3F,yFAAyF;YACzF,gGAAgG,CACnG,CAAC;IACJ,CAAC;IACD,OAAO,CAAgC,CAAC;AAC1C,CAAC","sourcesContent":["// `@takazudo/zfb-adapter-cloudflare` — Cloudflare Workers Static Assets\n// adapter for the zfb framework (also deployable to Cloudflare Pages\n// advanced mode).\n//\n// This entry (`./`) is the **Workers-runtime** surface. It is safe to\n// bundle into a Cloudflare Worker and does not depend on any Node-only\n// built-ins beyond `node:async_hooks` (which workerd polyfills).\n//\n// Usage in a `prerender = false` route:\n//\n//   import { getCloudflareContext } from \"@takazudo/zfb-adapter-cloudflare\";\n//\n//   export const prerender = false;\n//   export default async function ApiRoute() {\n//     const { env, ctx } = getCloudflareContext<{ ANTHROPIC_API_KEY: string }>();\n//     // env.ANTHROPIC_API_KEY, ctx.waitUntil(...), etc.\n//   }\n//\n// For Node-only build helpers (e.g. `emitWorker`), import the `./build`\n// sub-entry instead:\n//\n//   import { emitWorker } from \"@takazudo/zfb-adapter-cloudflare/build\";\n//\n// ## Why AsyncLocalStorage on a globalThis registry\n//\n// Cloudflare Workers can process multiple requests concurrently in the\n// same isolate. A naïve `globalThis.__env = env` write would race across\n// requests. AsyncLocalStorage gives us a per-request scope that survives\n// `await` points without interfering with sibling requests.\n//\n// We register the storage instance on `globalThis` under a stable key\n// (`__zfb_cf_adapter_als__`) so the wrapper at `_worker.js` and the user\n// pages bundled together can share the same instance even when the\n// adapter module ends up duplicated in the final bundle graph (e.g. when\n// the wrapper file is emitted side-by-side with the inner bundle and\n// each pulls in its own copy of this module). Module-instance identity\n// is the property AsyncLocalStorage relies on; the registry pattern is\n// what makes it survive bundler duplication.\n\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\n/**\n * Cloudflare execution context — minimal projection of the workerd\n * `ExecutionContext` interface. We do not depend on `@cloudflare/workers-types`\n * at the type level here because that would force every consumer of this\n * package to install it; instead we keep a minimal structural shape and\n * let consumers describe a compatible richer shape with the second generic\n * on [`getCloudflareContext`] when they need additional execution-context\n * bindings. That type is supplied by the caller; it is not detected or\n * validated at runtime.\n */\nexport interface CloudflareExecutionContext {\n  /** Extends the lifetime of the request beyond the response. */\n  waitUntil(promise: Promise<unknown>): void;\n  /** Falls through to the static origin on uncaught exceptions. */\n  passThroughOnException(): void;\n}\n\n/**\n * Per-request Cloudflare context. `Env` defaults to `unknown` and `Ctx` to\n * the minimal execution-context shape. Consumers can supply narrower or\n * richer types at the call site when they know the runtime shape.\n */\nexport interface CloudflareContext<\n  Env = unknown,\n  Ctx extends CloudflareExecutionContext = CloudflareExecutionContext,\n> {\n  /** CF env bindings (secrets, KV, D1, …) wired up via wrangler.toml. */\n  readonly env: Env;\n  /** ExecutionContext for waitUntil / passThroughOnException and any declared extensions. */\n  readonly ctx: Ctx;\n  /** The original Request, useful when handlers want headers / URL. */\n  readonly request: Request;\n}\n\n/** Stable globalThis key the registry pattern uses. */\nconst STORAGE_KEY = \"__zfb_cf_adapter_als__\";\n\ninterface RegistryGlobal {\n  [STORAGE_KEY]?: AsyncLocalStorage<CloudflareContext>;\n}\n\n/**\n * Acquire (or lazily create) the singleton AsyncLocalStorage instance.\n *\n * Stored on `globalThis` under a stable key so the wrapper at\n * `_worker.js` and the user bundle share state even if the adapter\n * module ends up duplicated in the final module graph.\n */\nfunction getStorage(): AsyncLocalStorage<CloudflareContext> {\n  const g = globalThis as unknown as RegistryGlobal;\n  let als = g[STORAGE_KEY];\n  if (!als) {\n    als = new AsyncLocalStorage<CloudflareContext>();\n    g[STORAGE_KEY] = als;\n  }\n  return als;\n}\n\n/**\n * Establish a Cloudflare context for the duration of `fn`. Used by the\n * `_worker.js` wrapper; not normally called by user code.\n */\nexport function runWithCloudflareContext<T, C extends CloudflareContext = CloudflareContext>(\n  context: C,\n  fn: () => T,\n): T {\n  return getStorage().run(context, fn);\n}\n\n/**\n * Read the current Cloudflare context. Throws if called outside a\n * Cloudflare request scope (e.g. from a build-time SSG render). Catch\n * the error and gate on `prerender = false` if you need a route to work\n * in both modes.\n *\n * `Env` describes the bindings available to the caller, while `Ctx` can\n * describe a compatible richer execution context. These generic arguments\n * are caller assertions: this function does not inspect runtime bindings or\n * feature-detect optional properties. Guard optional fields before use.\n */\nexport function getCloudflareContext<\n  Env = unknown,\n  Ctx extends CloudflareExecutionContext = CloudflareExecutionContext,\n>(): CloudflareContext<Env, Ctx> {\n  const c = getStorage().getStore();\n  if (!c) {\n    throw new Error(\n      \"[zfb-adapter-cloudflare] getCloudflareContext() called outside a Cloudflare request scope. \" +\n        \"This usually means the route was rendered at build time (SSG) instead of dispatched by \" +\n        \"the Worker. Add `export const prerender = false;` to the page if it needs Cloudflare bindings.\",\n    );\n  }\n  return c as CloudflareContext<Env, Ctx>;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zfb-adapter-cloudflare",
-  "version": "2.22.1",
+  "version": "3.1.0",
   "private": false,
   "type": "module",
   "description": "Content-site engine on the web's Request/Response model — prerender to static HTML, serve on Cloudflare Workers, or run as a local content server inside your app. One Rust binary. Cloudflare adapter: Workers Static Assets (Pages-compatible).",
@@ -64,8 +64,10 @@
   },
   "scripts": {
     "build": "tsc && cp src/worker-wrapper.mjs dist/worker-wrapper.mjs && cp src/emit-worker.mjs dist/emit-worker.mjs",
-    "test": "vitest run",
+    "test": "pnpm typecheck:consumer && vitest run && pnpm test:packed-types",
+    "test:packed-types": "pnpm build && node scripts/check-packed-types.mjs",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && pnpm typecheck:consumer",
+    "typecheck:consumer": "tsc --project tsconfig.consumer.json --noEmit"
   }
 }