alchemy 2.0.0-beta.60 → 2.0.0-beta.61

package/src/Cloudflare/Workers/CronEventSource.ts

@@ -10,19 +10,193 @@ import { isWorkerEvent, 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 const cron = <Req = never>(
   expression: string,

package/src/Cloudflare/Workers/DurableObject.ts

@@ -230,7 +230,7 @@ export class DurableObjectScope extends Context.Service<
  * ```
  *
  * There are two ways to define a Durable Object. See the
- * {@link https://alchemy.run/concepts/platform | Platform concept} page
+ * [Functions & Servers](/infrastructure-as-effects/functions-and-servers) page
  * for the full explanation.
  *
  * - **Inline** — Effect implementation passed directly, single file.
@@ -518,6 +518,41 @@ export class DurableObjectScope extends Context.Service<
  * const value = yield* state.storage.get("counter");
  * ```
  *
+ * @section Background Work & Scopes
+ * Every RPC call and fetch into a Durable Object gets its own Effect
+ * `Scope`. When the method finishes, the bridge closes that scope and
+ * registers the close promise with workerd's `state.waitUntil` — so
+ * finalizers added with `Effect.addFinalizer` inside a method run *after*
+ * the result is returned to the caller, without blocking it, and the
+ * object stays alive until they settle.
+ *
+ * For ad-hoc background work, `state.waitUntil(effect)` forks an Effect
+ * with the caller's full context and keeps the object alive until it
+ * settles.
+ *
+ * Attach cleanup to method scopes, not the constructor (init) closure —
+ * the constructor runs once per in-memory instance under
+ * `blockConcurrencyWhile`, and its scope is not tied to any call.
+ *
+ * @example Responding before finishing the work
+ * ```typescript
+ * return {
+ *   record: Effect.fn(function* (entry: string) {
+ *     // runs after `record` returns; the DO stays alive until it settles
+ *     yield* Effect.addFinalizer(() =>
+ *       state.storage.put(`audit:${entry}`, Date.now()).pipe(Effect.ignore),
+ *     );
+ *     return "accepted" as const;
+ *   }),
+ *
+ *   refresh: Effect.fn(function* () {
+ *     // same idea, explicit form
+ *     yield* state.waitUntil(recomputeExpensiveView());
+ *     return "scheduled" as const;
+ *   }),
+ * };
+ * ```
+ *
  * @section WebSocket Hibernation
  * Durable Objects support WebSocket hibernation — the runtime can
  * evict the object from memory while keeping connections open. Use

package/src/Cloudflare/Workers/DurableObjectState.ts

@@ -14,6 +14,19 @@ export class DurableObjectState extends Context.Service<
     readonly id: cf.DurableObjectId;
     readonly storage: DurableObjectStorage;
     container?: cf.Container;
+    /**
+     * Run an Effect in the background without blocking the current event,
+     * keeping the Durable Object alive until it settles. The Effect runs with
+     * the caller's full context (services, tracing), and the resulting
+     * promise is registered with workerd's `state.waitUntil`.
+     */
+    waitUntil<A, E, R>(
+      effect: Effect.Effect<A, E, R>,
+    ): Effect.Effect<void, never, R | RuntimeContext>;
+    /**
+     * The raw workerd DurableObjectState, for interop with async APIs.
+     */
+    readonly raw: cf.DurableObjectState;
     blockConcurrencyWhile<T>(
       callback: () => Effect.Effect<T, never, RuntimeContext>,
     ): Effect.Effect<T, never, RuntimeContext>;
@@ -54,6 +67,18 @@ export const fromDurableObjectState = (
   id: state.id,
   container: state.container,
   storage: fromDurableObjectStorage(state.storage),
+  raw: state,
+  waitUntil: <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+    Effect.gen(function* () {
+      const context = yield* Effect.context<R>();
+      // Register the promise with workerd un-awaited — waitUntil extends the
+      // event's lifetime without blocking the caller.
+      yield* Effect.sync(() =>
+        state.waitUntil(
+          Effect.runPromise(effect.pipe(Effect.provide(context))),
+        ),
+      );
+    }),
   blockConcurrencyWhile: <T>(callback: () => Effect.Effect<T>) =>
     Effect.tryPromise(() =>
       state.blockConcurrencyWhile(() => Effect.runPromise(callback())),

package/src/Cloudflare/Workers/Fetch.ts

@@ -7,7 +7,7 @@ import * as Stream from "effect/Stream";
 import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
-import * as UrlParams from "effect/unstable/http/UrlParams";
+import * as Url from "effect/unstable/http/Url";
 import * as Binding from "../../Binding.ts";
 import { isWorker, type Worker, WorkerEnvironment } from "./Worker.ts";
 
@@ -70,7 +70,7 @@ const doFetch = (
   HttpClientResponse.HttpClientResponse,
   HttpClientError.RequestError
 > => {
-  const urlResult = UrlParams.makeUrl(
+  const urlResult = Url.make(
     request.url,
     request.urlParams,
     request.hash.pipe(Option.getOrUndefined),

package/src/Cloudflare/Workers/LocalWorkerProvider.ts

@@ -478,6 +478,7 @@ export const LocalWorkerProvider = () =>
             ]),
           ),
           domains: [url],
+          routes: [],
           crons: Array.from(
             new Set([...getCronBindings(bindings), ...(props.crons ?? [])]),
           ),
@@ -545,6 +546,7 @@ export const LocalWorkerProvider = () =>
             tags: [],
             durableObjectNamespaces,
             domains: url ? [url] : [],
+            routes: [],
             crons: Array.from(
               new Set([...getCronBindings(bindings), ...(news.crons ?? [])]),
             ),
@@ -576,6 +578,7 @@ export const LocalWorkerProvider = () =>
               durableObjectNamespaces: {},
               accountId,
               domains: [],
+              routes: [],
               crons: news.crons ?? [],
             } satisfies Worker["Attributes"];
           }