alchemy 2.0.0-beta.60 → 2.0.0-beta.62

package/lib/Cloudflare/Workers/Cache.d.ts

@@ -0,0 +1,71 @@
+import type * as cf from "@cloudflare/workers-types";
+import * as Effect from "effect/Effect";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
+import { Worker, WorkerExecutionContext, type CachePurgeError } from "./Worker.ts";
+export interface CacheOptions {
+    /**
+     * Whether Workers Cache checks the cache before invoking the Worker.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Share cached responses across Worker versions. By default the cache is
+     * scoped to a single version, so every deploy starts cold.
+     * @default false
+     */
+    crossVersionCache?: boolean;
+}
+/**
+ * Runtime client for Workers Cache, returned by `yield* Cloudflare.cache()`.
+ */
+export interface CacheClient {
+    /**
+     * Purge cached responses by `Cache-Tag`, path prefix, or everything.
+     */
+    purge(options: cf.CachePurgeOptions): Effect.Effect<cf.CachePurgeResult, CachePurgeError, RuntimeContext>;
+}
+/**
+ * Enable [Workers Cache](https://blog.cloudflare.com/workers-cache/) on the
+ * surrounding Worker and get the runtime cache client.
+ *
+ * Yielding `cache()` in an Effect-native Worker's init phase turns the cache
+ * on at deploy time (the equivalent of setting `cache: { enabled: true }` on
+ * the Worker's props) and returns a client whose `purge` drives the runtime
+ * `ctx.cache` API from your handlers.
+ *
+ * What gets cached is controlled by standard response headers —
+ * `Cache-Control` (including `stale-while-revalidate`), `Cache-Tag` for
+ * tag-based purging, and `Vary` for content negotiation.
+ *
+ * For async (non-Effect) Workers, set the `cache` prop on the Worker
+ * instead.
+ *
+ * @binding
+ * @product Workers
+ * @category Workers & Compute
+ * @example
+ * ```typescript
+ * Effect.gen(function* () {
+ *   // init: enable Workers Cache on this Worker
+ *   const { purge } = yield* Cloudflare.cache();
+ *
+ *   return {
+ *     fetch: Effect.gen(function* () {
+ *       const request = yield* HttpServerRequest;
+ *       if (request.url.startsWith("/invalidate")) {
+ *         yield* purge({ tags: ["products"] });
+ *         return HttpServerResponse.text("purged");
+ *       }
+ *       return HttpServerResponse.text("hello", {
+ *         headers: {
+ *           "Cache-Control": "public, max-age=300",
+ *           "Cache-Tag": "products",
+ *         },
+ *       });
+ *     }),
+ *   };
+ * })
+ * ```
+ */
+export declare const cache: (options?: CacheOptions) => Effect.Effect<CacheClient, never, Worker | WorkerExecutionContext>;
+//# sourceMappingURL=Cache.d.ts.map

package/lib/Cloudflare/Workers/Cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../../src/Cloudflare/Workers/Cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACrD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EACL,MAAM,EACN,sBAAsB,EACtB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,KAAK,CACH,OAAO,EAAE,EAAE,CAAC,iBAAiB,GAC5B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,gBAAgB,EAAE,eAAe,EAAE,cAAc,CAAC,CAAC;CACxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,KAAK,aACN,YAAY,KACrB,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,sBAAsB,CAoBhE,CAAC"}

package/lib/Cloudflare/Workers/Cache.js

@@ -0,0 +1,64 @@
+import * as Effect from "effect/Effect";
+import * as Namespace from "../../Namespace.js";
+import { Worker, WorkerExecutionContext, } from "./Worker.js";
+/**
+ * Enable [Workers Cache](https://blog.cloudflare.com/workers-cache/) on the
+ * surrounding Worker and get the runtime cache client.
+ *
+ * Yielding `cache()` in an Effect-native Worker's init phase turns the cache
+ * on at deploy time (the equivalent of setting `cache: { enabled: true }` on
+ * the Worker's props) and returns a client whose `purge` drives the runtime
+ * `ctx.cache` API from your handlers.
+ *
+ * What gets cached is controlled by standard response headers —
+ * `Cache-Control` (including `stale-while-revalidate`), `Cache-Tag` for
+ * tag-based purging, and `Vary` for content negotiation.
+ *
+ * For async (non-Effect) Workers, set the `cache` prop on the Worker
+ * instead.
+ *
+ * @binding
+ * @product Workers
+ * @category Workers & Compute
+ * @example
+ * ```typescript
+ * Effect.gen(function* () {
+ *   // init: enable Workers Cache on this Worker
+ *   const { purge } = yield* Cloudflare.cache();
+ *
+ *   return {
+ *     fetch: Effect.gen(function* () {
+ *       const request = yield* HttpServerRequest;
+ *       if (request.url.startsWith("/invalidate")) {
+ *         yield* purge({ tags: ["products"] });
+ *         return HttpServerResponse.text("purged");
+ *       }
+ *       return HttpServerResponse.text("hello", {
+ *         headers: {
+ *           "Cache-Control": "public, max-age=300",
+ *           "Cache-Tag": "products",
+ *         },
+ *       });
+ *     }),
+ *   };
+ * })
+ * ```
+ */
+export const cache = (options) => Effect.gen(function* () {
+    const host = yield* Worker;
+    const exec = yield* WorkerExecutionContext;
+    if (!globalThis.__ALCHEMY_RUNTIME__) {
+        yield* Namespace.push(host.LogicalId, host.bind("Cache", {
+            cache: {
+                enabled: options?.enabled ?? true,
+                crossVersionCache: options?.crossVersionCache,
+            },
+        }));
+    }
+    return {
+        // `exec` is the init-phase deferred context; purge resolves the live
+        // per-event context from the calling handler's fiber.
+        purge: (purgeOptions) => exec.cache.purge(purgeOptions),
+    };
+});
+//# sourceMappingURL=Cache.js.map

package/lib/Cloudflare/Workers/Cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cache.js","sourceRoot":"","sources":["../../../src/Cloudflare/Workers/Cache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EACL,MAAM,EACN,sBAAsB,GAEvB,MAAM,aAAa,CAAC;AA4BrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,OAAsB,EAC8C,EAAE,CACtE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC;IAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,sBAAsB,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC;QACpC,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,CACnB,IAAI,CAAC,SAAS,EACd,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;YACjB,KAAK,EAAE;gBACL,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,IAAI;gBACjC,iBAAiB,EAAE,OAAO,EAAE,iBAAiB;aAC9C;SACF,CAAC,CACH,CAAC;IACJ,CAAC;IACD,OAAO;QACL,qEAAqE;QACrE,sDAAsD;QACtD,KAAK,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC;KACxD,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/lib/Cloudflare/Workers/Compatibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Compatibility.d.ts","sourceRoot":"","sources":["../../../src/Cloudflare/Workers/Compatibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK/C,eAAO,MAAM,gBAAgB,UAAW,WAAW;IACjD,IAAI;IACJ,KAAK;CAIL,CAAC"}
+{"version":3,"file":"Compatibility.d.ts","sourceRoot":"","sources":["../../../src/Cloudflare/Workers/Compatibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAyB/C,eAAO,MAAM,gBAAgB,UAAW,WAAW;;;CA6BlD,CAAC"}

package/lib/Cloudflare/Workers/Compatibility.js

@@ -1,10 +1,46 @@
 // TODO: figure out why the later one from workerd breaks
 const DEFAULT_COMPATIBILITY_DATE = "2026-03-17";
-export const getCompatibility = (props) => ({
-    date: props.compatibility?.date ?? DEFAULT_COMPATIBILITY_DATE,
-    flags: [
-        ...(props.compatibility?.flags ?? []),
-        ...(props.isExternal ? [] : ["nodejs_compat"]),
-    ].filter((value, index, self) => self.indexOf(value) === index),
-});
+/**
+ * The Effect worker bridge builds its layer stack once per isolate and shares
+ * the in-flight build promise across concurrent events. Awaiting a promise
+ * created under another event's request context is only sound with workerd's
+ * corrected cross-request promise semantics (default-on since compatibility
+ * date 2024-10-14): continuations are scheduled back into the promise's
+ * origin context instead of running in whichever request happens to resolve
+ * them. A user pinning an older compatibility date must not silently revert
+ * the bridge to the broken semantics, so the flag is forced for
+ * alchemy-bundled workers — and explicitly disabling it is a deploy-time
+ * error.
+ */
+const CROSS_REQUEST_PROMISE_RESOLUTION = "handle_cross_request_promise_resolution";
+// The date the flag became default-on. Cloudflare rejects a script that
+// specifies a flag its compatibility date already defaults on ("does not
+// need to be specified anymore"), so it is only appended for older dates.
+const CROSS_REQUEST_PROMISE_RESOLUTION_DEFAULT_ON = "2024-10-14";
+export const getCompatibility = (props) => {
+    const userFlags = props.compatibility?.flags ?? [];
+    if (!props.isExternal &&
+        userFlags.includes(`no_${CROSS_REQUEST_PROMISE_RESOLUTION}`)) {
+        throw new Error(`The "no_${CROSS_REQUEST_PROMISE_RESOLUTION}" compatibility flag is not supported: ` +
+            "the alchemy Worker runtime shares its layer build across concurrent " +
+            "requests, which requires workerd's corrected cross-request promise " +
+            "semantics. Remove the flag from `compatibility.flags`.");
+    }
+    const date = props.compatibility?.date ?? DEFAULT_COMPATIBILITY_DATE;
+    return {
+        date,
+        flags: [
+            ...userFlags,
+            ...(props.isExternal
+                ? []
+                : [
+                    "nodejs_compat",
+                    // ISO dates compare lexically.
+                    ...(date < CROSS_REQUEST_PROMISE_RESOLUTION_DEFAULT_ON
+                        ? [CROSS_REQUEST_PROMISE_RESOLUTION]
+                        : []),
+                ]),
+        ].filter((value, index, self) => self.indexOf(value) === index),
+    };
+};
 //# sourceMappingURL=Compatibility.js.map

package/lib/Cloudflare/Workers/Compatibility.js.map

@@ -1 +1 @@
-{"version":3,"file":"Compatibility.js","sourceRoot":"","sources":["../../../src/Cloudflare/Workers/Compatibility.ts"],"names":[],"mappings":"AAEA,yDAAyD;AACzD,MAAM,0BAA0B,GAAG,YAAY,CAAC;AAEhD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAkB,EAAE,EAAE,CAAC,CAAC;IACvD,IAAI,EAAE,KAAK,CAAC,aAAa,EAAE,IAAI,IAAI,0BAA0B;IAC7D,KAAK,EAAE;QACL,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE,CAAC;QACrC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;KAC/C,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC;CAChE,CAAC,CAAC"}
+{"version":3,"file":"Compatibility.js","sourceRoot":"","sources":["../../../src/Cloudflare/Workers/Compatibility.ts"],"names":[],"mappings":"AAEA,yDAAyD;AACzD,MAAM,0BAA0B,GAAG,YAAY,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,gCAAgC,GACpC,yCAAyC,CAAC;AAE5C,wEAAwE;AACxE,yEAAyE;AACzE,0EAA0E;AAC1E,MAAM,2CAA2C,GAAG,YAAY,CAAC;AAEjE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAkB,EAAE,EAAE;IACrD,MAAM,SAAS,GAAG,KAAK,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE,CAAC;IACnD,IACE,CAAC,KAAK,CAAC,UAAU;QACjB,SAAS,CAAC,QAAQ,CAAC,MAAM,gCAAgC,EAAE,CAAC,EAC5D,CAAC;QACD,MAAM,IAAI,KAAK,CACb,WAAW,gCAAgC,yCAAyC;YAClF,sEAAsE;YACtE,qEAAqE;YACrE,wDAAwD,CAC3D,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,aAAa,EAAE,IAAI,IAAI,0BAA0B,CAAC;IACrE,OAAO;QACL,IAAI;QACJ,KAAK,EAAE;YACL,GAAG,SAAS;YACZ,GAAG,CAAC,KAAK,CAAC,UAAU;gBAClB,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC;oBACE,eAAe;oBACf,+BAA+B;oBAC/B,GAAG,CAAC,IAAI,GAAG,2CAA2C;wBACpD,CAAC,CAAC,CAAC,gCAAgC,CAAC;wBACpC,CAAC,CAAC,EAAE,CAAC;iBACR,CAAC;SACP,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC;KAChE,CAAC;AACJ,CAAC,CAAC"}

package/lib/Cloudflare/Workers/CronEventSource.d.ts

@@ -2,26 +2,201 @@ import type * as cf from "@cloudflare/workers-types";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import { RuntimeContext } from "../../RuntimeContext.ts";
 import { Worker } from "./Worker.ts";
 /**
  * Subscribe to Cloudflare Cron Triggers with an Effect handler.
  *
- * This wires both pieces of a scheduled Worker:
+ * A single call wires both pieces of a scheduled Worker:
+ *
+ * - **Deploy-time**: attaches the cron expression to the host Worker's
+ *   Cron Triggers.
+ * - **Runtime**: registers a `scheduled` listener that runs your Effect on
+ *   each fire. The handler receives Cloudflare's `ScheduledController`,
+ *   which has three members:
+ *   - `controller.scheduledTime` — the fire time in milliseconds since the
+ *     Unix epoch.
+ *   - `controller.cron` — the cron expression that fired.
+ *   - `controller.noRetry()` — opts the invocation out of Cloudflare's
+ *     retry-on-failure. Only meaningful when the scheduled invocation can
+ *     actually fail — see the failure & retry section below.
+ *
+ *   Each member has its own section below with an Effect example first and
+ *   an async example second.
+ *
+ * Requires `CronEventSourceLive` provided on the Worker's Effect.
+ *
+ * **Failure & retry semantics**: a failing handler won't crash the Worker —
+ * the event source catches the failure and moves on. That also means
+ * Cloudflare never observes a failed invocation, so its platform-level
+ * retry (and `controller.noRetry()`) never comes into play here. Express
+ * retry declaratively with `Effect.retry` inside the handler, and log or
+ * report errors if you need visibility into failed runs. In async Workers
+ * the opposite holds: a `scheduled` handler that throws (or rejects) marks
+ * the invocation failed and Cloudflare may retry it — call
+ * `controller.noRetry()` before rethrowing to suppress that.
+ *
+ * Async (non-Effect) Workers don't use `cron` — they attach schedules with
+ * the Worker's `crons` prop and export their own `scheduled` handler from
+ * the entry module (each section below includes the async variant). Pass
+ * `crons: []` to remove all Cron Triggers from a Worker.
  *
- * - **Runtime**: registers a `scheduled` listener on the Worker.
- * - **Deploy-time**: attaches the cron expression to the host Worker.
  * @binding
  * @product Workers
  * @category Workers & Compute
- * @example
+ *
+ * @section Declare a schedule
+ * @example Effect-native Worker (recommended)
+ * ```typescript
+ * import * as Cloudflare from "alchemy/Cloudflare";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
+ *
+ * export default Cloudflare.Worker(
+ *   "Worker",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     yield* Cloudflare.Workers.cron("0 12 * * *", () =>
+ *       Effect.log("cron fired"),
+ *     );
+ *
+ *     return {
+ *       fetch: Effect.succeed(HttpServerResponse.text("ok")),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.Workers.CronEventSourceLive)),
+ * );
+ * ```
+ *
+ * @example Async Worker — `crons` prop + exported `scheduled` handler
+ * ```typescript
+ * // alchemy.run.ts — attach the cron expressions at deploy time
+ * export const Worker = Cloudflare.Worker("Worker", {
+ *   main: "./src/worker.ts",
+ *   crons: ["0 12 * * *"],
+ * });
+ *
+ * // src/worker.ts — the entry module handles the fires itself
+ * export default {
+ *   async scheduled(controller: ScheduledController) {
+ *     console.log("cron fired");
+ *   },
+ * };
+ * ```
+ *
+ * @section `controller.scheduledTime` — the fire time
+ * @example Effect: record each fire on a Durable Object
+ * ```typescript
+ * export default class Worker extends Cloudflare.Worker<Worker>()(
+ *   "Worker",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const counters = yield* CronCounter;
+ *
+ *     yield* Cloudflare.Workers.cron("0 * * * *", (controller) =>
+ *       counters.getByName("default").record(controller.scheduledTime),
+ *     );
+ *
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const { times } = yield* counters.getByName("default").snapshot();
+ *         return yield* HttpServerResponse.json({ times });
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.Workers.CronEventSourceLive)),
+ * ) {}
+ * ```
+ *
+ * @example Async: use the fire time as an idempotency key
+ * ```typescript
+ * // scheduledTime is the time the fire was *scheduled* for (not when it
+ * // ran), so it is stable across retries of the same fire — a natural
+ * // idempotency key for at-most-once side effects.
+ * export default {
+ *   async scheduled(controller: ScheduledController, env: WorkerEnv) {
+ *     const key = `run:${controller.scheduledTime}`;
+ *     if (await env.RUNS.get(key)) return;
+ *     await syncFeeds();
+ *     await env.RUNS.put(key, "done");
+ *   },
+ * };
+ * ```
+ *
+ * @section `controller.cron` — dispatch multiple schedules
+ * @example Effect: one handler per expression
+ * ```typescript
+ * // Each handler only runs for fires of its own expression — the listener
+ * // checks controller.cron, so a midnight fire never runs the hourly handler.
+ * yield* Cloudflare.Workers.cron("0 * * * *", () => syncFeeds);
+ * yield* Cloudflare.Workers.cron("0 0 * * *", () => purgeExpired);
+ * ```
+ *
+ * @example Async: switch on `controller.cron`
  * ```typescript
- * yield* Cloudflare.Workers.cron("0 12 * * *", (controller) =>
- *   Effect.log(`scheduled at ${controller.scheduledTime}`),
+ * export const Worker = Cloudflare.Worker("Worker", {
+ *   main: "./src/worker.ts",
+ *   crons: ["0 * * * *", "0 0 * * *"],
+ * });
+ *
+ * // src/worker.ts — one scheduled handler receives every fire
+ * export default {
+ *   async scheduled(controller: ScheduledController) {
+ *     switch (controller.cron) {
+ *       case "0 * * * *":
+ *         await syncFeeds();
+ *         break;
+ *       case "0 0 * * *":
+ *         await purgeExpired();
+ *         break;
+ *     }
+ *   },
+ * };
+ * ```
+ *
+ * @section `controller.noRetry()` — failure & retry control
+ * @example Effect: bound retries with `Effect.retry`
+ * ```typescript
+ * import * as Schedule from "effect/Schedule";
+ *
+ * // The event source reports the invocation as successful even when the
+ * // handler fails, so Cloudflare's platform retry rarely engages for Effect
+ * // handlers — Effect.retry is the primary retry control. Calling
+ * // controller.noRetry() once retries are exhausted defensively covers
+ * // anything that can still mark the invocation failed (e.g. a failing
+ * // waitUntil task).
+ * yield* Cloudflare.Workers.cron("0 * * * *", (controller) =>
+ *   syncFeeds.pipe(
+ *     Effect.retry({ schedule: Schedule.exponential("1 second"), times: 3 }),
+ *     Effect.tapError((error) =>
+ *       Effect.logError("syncFeeds failed permanently", error).pipe(
+ *         Effect.andThen(Effect.sync(() => controller.noRetry())),
+ *       ),
+ *     ),
+ *   ),
  * );
  * ```
+ *
+ * @example Async: suppress retry for permanent failures
+ * ```typescript
+ * // src/worker.ts — a thrown error marks the invocation failed and
+ * // Cloudflare may retry it; noRetry() opts this fire out of that.
+ * export default {
+ *   async scheduled(controller: ScheduledController) {
+ *     try {
+ *       await syncFeeds();
+ *     } catch (error) {
+ *       if (isPermanentFailure(error)) {
+ *         controller.noRetry();
+ *       }
+ *       throw error; // still recorded as a failed invocation
+ *     }
+ *   },
+ * };
+ * ```
+ *
+ * @see https://developers.cloudflare.com/workers/configuration/cron-triggers/
  */
-export declare const cron: <Req = never>(expression: string, process: (controller: cf.ScheduledController) => Effect.Effect<void, unknown, Req>) => Effect.Effect<void, never, CronEventSource>;
-export type CronEventSourceService = <Req = never>(expression: string, process: (controller: cf.ScheduledController) => Effect.Effect<void, unknown, Req>) => Effect.Effect<void, never, never>;
+export declare const cron: <Req = never>(expression: string, process: (controller: cf.ScheduledController) => Effect.Effect<void, unknown, Req>) => Effect.Effect<void, never, CronEventSource | Exclude<Req, RuntimeContext>>;
+export type CronEventSourceService = <Req = never>(expression: string, process: (controller: cf.ScheduledController) => Effect.Effect<void, unknown, Req>) => Effect.Effect<void, never, Exclude<Req, RuntimeContext>>;
 declare const CronEventSource_base: Context.ServiceClass<CronEventSource, "Cloudflare.Workers.CronEventSource", CronEventSourceService>;
 export declare class CronEventSource extends CronEventSource_base {
 }

package/lib/Cloudflare/Workers/CronEventSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CronEventSource.d.ts","sourceRoot":"","sources":["../../../src/Cloudflare/Workers/CronEventSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACrD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAItC,OAAO,EAAiB,MAAM,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,IAAI,GAAI,GAAG,GAAG,KAAK,cAClB,MAAM,WACT,CACP,UAAU,EAAE,EAAE,CAAC,mBAAmB,KAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,gDACyB,CAAC;AAElE,MAAM,MAAM,sBAAsB,GAAG,CAAC,GAAG,GAAG,KAAK,EAC/C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CACP,UAAU,EAAE,EAAE,CAAC,mBAAmB,KAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,KACnC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;;AAEvC,qBAAa,eAAgB,SAAQ,oBAGI;CAAG;AAE5C,eAAO,MAAM,mBAAmB,kDAkC/B,CAAC"}
+{"version":3,"file":"CronEventSource.d.ts","sourceRoot":"","sources":["../../../src/Cloudflare/Workers/CronEventSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACrD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,EAAiB,MAAM,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8LG;AACH,eAAO,MAAM,IAAI,GAAI,GAAG,GAAG,KAAK,cAClB,MAAM,WACT,CACP,UAAU,EAAE,EAAE,CAAC,mBAAmB,KAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,KACrC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,CACd,CAAC;AAE/D,MAAM,MAAM,sBAAsB,GAAG,CAAC,GAAG,GAAG,KAAK,EAC/C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CACP,UAAU,EAAE,EAAE,CAAC,mBAAmB,KAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,KACnC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;;AAE9D,qBAAa,eAAgB,SAAQ,oBAGI;CAAG;AAE5C,eAAO,MAAM,mBAAmB,kDAkC/B,CAAC"}

package/lib/Cloudflare/Workers/CronEventSource.js

@@ -7,19 +7,193 @@ import { isWorkerEvent, Worker } from "./Worker.js";
 /**
  * Subscribe to Cloudflare Cron Triggers with an Effect handler.
  *
- * This wires both pieces of a scheduled Worker:
+ * A single call wires both pieces of a scheduled Worker:
+ *
+ * - **Deploy-time**: attaches the cron expression to the host Worker's
+ *   Cron Triggers.
+ * - **Runtime**: registers a `scheduled` listener that runs your Effect on
+ *   each fire. The handler receives Cloudflare's `ScheduledController`,
+ *   which has three members:
+ *   - `controller.scheduledTime` — the fire time in milliseconds since the
+ *     Unix epoch.
+ *   - `controller.cron` — the cron expression that fired.
+ *   - `controller.noRetry()` — opts the invocation out of Cloudflare's
+ *     retry-on-failure. Only meaningful when the scheduled invocation can
+ *     actually fail — see the failure & retry section below.
+ *
+ *   Each member has its own section below with an Effect example first and
+ *   an async example second.
+ *
+ * Requires `CronEventSourceLive` provided on the Worker's Effect.
+ *
+ * **Failure & retry semantics**: a failing handler won't crash the Worker —
+ * the event source catches the failure and moves on. That also means
+ * Cloudflare never observes a failed invocation, so its platform-level
+ * retry (and `controller.noRetry()`) never comes into play here. Express
+ * retry declaratively with `Effect.retry` inside the handler, and log or
+ * report errors if you need visibility into failed runs. In async Workers
+ * the opposite holds: a `scheduled` handler that throws (or rejects) marks
+ * the invocation failed and Cloudflare may retry it — call
+ * `controller.noRetry()` before rethrowing to suppress that.
+ *
+ * Async (non-Effect) Workers don't use `cron` — they attach schedules with
+ * the Worker's `crons` prop and export their own `scheduled` handler from
+ * the entry module (each section below includes the async variant). Pass
+ * `crons: []` to remove all Cron Triggers from a Worker.
  *
- * - **Runtime**: registers a `scheduled` listener on the Worker.
- * - **Deploy-time**: attaches the cron expression to the host Worker.
  * @binding
  * @product Workers
  * @category Workers & Compute
- * @example
+ *
+ * @section Declare a schedule
+ * @example Effect-native Worker (recommended)
+ * ```typescript
+ * import * as Cloudflare from "alchemy/Cloudflare";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
+ *
+ * export default Cloudflare.Worker(
+ *   "Worker",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     yield* Cloudflare.Workers.cron("0 12 * * *", () =>
+ *       Effect.log("cron fired"),
+ *     );
+ *
+ *     return {
+ *       fetch: Effect.succeed(HttpServerResponse.text("ok")),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.Workers.CronEventSourceLive)),
+ * );
+ * ```
+ *
+ * @example Async Worker — `crons` prop + exported `scheduled` handler
+ * ```typescript
+ * // alchemy.run.ts — attach the cron expressions at deploy time
+ * export const Worker = Cloudflare.Worker("Worker", {
+ *   main: "./src/worker.ts",
+ *   crons: ["0 12 * * *"],
+ * });
+ *
+ * // src/worker.ts — the entry module handles the fires itself
+ * export default {
+ *   async scheduled(controller: ScheduledController) {
+ *     console.log("cron fired");
+ *   },
+ * };
+ * ```
+ *
+ * @section `controller.scheduledTime` — the fire time
+ * @example Effect: record each fire on a Durable Object
+ * ```typescript
+ * export default class Worker extends Cloudflare.Worker<Worker>()(
+ *   "Worker",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const counters = yield* CronCounter;
+ *
+ *     yield* Cloudflare.Workers.cron("0 * * * *", (controller) =>
+ *       counters.getByName("default").record(controller.scheduledTime),
+ *     );
+ *
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const { times } = yield* counters.getByName("default").snapshot();
+ *         return yield* HttpServerResponse.json({ times });
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.Workers.CronEventSourceLive)),
+ * ) {}
+ * ```
+ *
+ * @example Async: use the fire time as an idempotency key
+ * ```typescript
+ * // scheduledTime is the time the fire was *scheduled* for (not when it
+ * // ran), so it is stable across retries of the same fire — a natural
+ * // idempotency key for at-most-once side effects.
+ * export default {
+ *   async scheduled(controller: ScheduledController, env: WorkerEnv) {
+ *     const key = `run:${controller.scheduledTime}`;
+ *     if (await env.RUNS.get(key)) return;
+ *     await syncFeeds();
+ *     await env.RUNS.put(key, "done");
+ *   },
+ * };
+ * ```
+ *
+ * @section `controller.cron` — dispatch multiple schedules
+ * @example Effect: one handler per expression
+ * ```typescript
+ * // Each handler only runs for fires of its own expression — the listener
+ * // checks controller.cron, so a midnight fire never runs the hourly handler.
+ * yield* Cloudflare.Workers.cron("0 * * * *", () => syncFeeds);
+ * yield* Cloudflare.Workers.cron("0 0 * * *", () => purgeExpired);
+ * ```
+ *
+ * @example Async: switch on `controller.cron`
  * ```typescript
- * yield* Cloudflare.Workers.cron("0 12 * * *", (controller) =>
- *   Effect.log(`scheduled at ${controller.scheduledTime}`),
+ * export const Worker = Cloudflare.Worker("Worker", {
+ *   main: "./src/worker.ts",
+ *   crons: ["0 * * * *", "0 0 * * *"],
+ * });
+ *
+ * // src/worker.ts — one scheduled handler receives every fire
+ * export default {
+ *   async scheduled(controller: ScheduledController) {
+ *     switch (controller.cron) {
+ *       case "0 * * * *":
+ *         await syncFeeds();
+ *         break;
+ *       case "0 0 * * *":
+ *         await purgeExpired();
+ *         break;
+ *     }
+ *   },
+ * };
+ * ```
+ *
+ * @section `controller.noRetry()` — failure & retry control
+ * @example Effect: bound retries with `Effect.retry`
+ * ```typescript
+ * import * as Schedule from "effect/Schedule";
+ *
+ * // The event source reports the invocation as successful even when the
+ * // handler fails, so Cloudflare's platform retry rarely engages for Effect
+ * // handlers — Effect.retry is the primary retry control. Calling
+ * // controller.noRetry() once retries are exhausted defensively covers
+ * // anything that can still mark the invocation failed (e.g. a failing
+ * // waitUntil task).
+ * yield* Cloudflare.Workers.cron("0 * * * *", (controller) =>
+ *   syncFeeds.pipe(
+ *     Effect.retry({ schedule: Schedule.exponential("1 second"), times: 3 }),
+ *     Effect.tapError((error) =>
+ *       Effect.logError("syncFeeds failed permanently", error).pipe(
+ *         Effect.andThen(Effect.sync(() => controller.noRetry())),
+ *       ),
+ *     ),
+ *   ),
  * );
  * ```
+ *
+ * @example Async: suppress retry for permanent failures
+ * ```typescript
+ * // src/worker.ts — a thrown error marks the invocation failed and
+ * // Cloudflare may retry it; noRetry() opts this fire out of that.
+ * export default {
+ *   async scheduled(controller: ScheduledController) {
+ *     try {
+ *       await syncFeeds();
+ *     } catch (error) {
+ *       if (isPermanentFailure(error)) {
+ *         controller.noRetry();
+ *       }
+ *       throw error; // still recorded as a failed invocation
+ *     }
+ *   },
+ * };
+ * ```
+ *
+ * @see https://developers.cloudflare.com/workers/configuration/cron-triggers/
  */
 export const cron = (expression, process) => CronEventSource.use((source) => source(expression, process));
 export class CronEventSource extends Context.Service()("Cloudflare.Workers.CronEventSource") {

package/lib/Cloudflare/Workers/CronEventSource.js.map

@@ -1 +1 @@
-{"version":3,"file":"CronEventSource.js","sourceRoot":"","sources":["../../../src/Cloudflare/Workers/CronEventSource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,UAAkB,EAClB,OAEsC,EACtC,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;AASlE,MAAM,OAAO,eAAgB,SAAQ,OAAO,CAAC,OAAO,EAGjD,CAAC,oCAAoC,CAAC;CAAG;AAE5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC,MAAM,CAC7C,eAAe,EACf,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC;IAC3B,OAAO,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,EACxB,UAAkB,EAClB,OAEsC;QAEtC,2EAA2E;QAC3E,wEAAwE;QACxE,sEAAsE;QACtE,0EAA0E;QAC1E,IAAI,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC;YACpC,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,CACnB,IAAI,CAAC,SAAS,EACd,IAAI,CAAC,IAAI,CAAC,QAAQ,UAAU,GAAG,EAAE;gBAC/B,KAAK,EAAE,CAAC,UAAU,CAAC;aACpB,CAAC,CACH,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,cAAc,CAA+B,CAAC;QAClE,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAY,CAAC,KAAK,EAAE,EAAE;YACrC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW;gBAAE,OAAO;YAEhE,MAAM,UAAU,GAAG,KAAK,CAAC,KAA+B,CAAC;YACzD,IAAI,UAAU,CAAC,IAAI,KAAK,UAAU;gBAAE,OAAO;YAE3C,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACxE,CAAC,CAAC,CAAC;IACL,CAAC,CAA2B,CAAC;AAC/B,CAAC,CAAC,CACH,CAAC"}
+{"version":3,"file":"CronEventSource.js","sourceRoot":"","sources":["../../../src/Cloudflare/Workers/CronEventSource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8LG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,UAAkB,EAClB,OAEsC,EACsC,EAAE,CAC9E,eAAe,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;AAS/D,MAAM,OAAO,eAAgB,SAAQ,OAAO,CAAC,OAAO,EAGjD,CAAC,oCAAoC,CAAC;CAAG;AAE5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC,MAAM,CAC7C,eAAe,EACf,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC;IAC3B,OAAO,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,EACxB,UAAkB,EAClB,OAEsC;QAEtC,2EAA2E;QAC3E,wEAAwE;QACxE,sEAAsE;QACtE,0EAA0E;QAC1E,IAAI,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC;YACpC,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,CACnB,IAAI,CAAC,SAAS,EACd,IAAI,CAAC,IAAI,CAAC,QAAQ,UAAU,GAAG,EAAE;gBAC/B,KAAK,EAAE,CAAC,UAAU,CAAC;aACpB,CAAC,CACH,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,cAAc,CAA+B,CAAC;QAClE,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAY,CAAC,KAAK,EAAE,EAAE;YACrC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW;gBAAE,OAAO;YAEhE,MAAM,UAAU,GAAG,KAAK,CAAC,KAA+B,CAAC;YACzD,IAAI,UAAU,CAAC,IAAI,KAAK,UAAU;gBAAE,OAAO;YAE3C,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACxE,CAAC,CAAC,CAAC;IACL,CAAC,CAA2B,CAAC;AAC/B,CAAC,CAAC,CACH,CAAC"}