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

package/src/Cloudflare/Workers/Compatibility.ts

@@ -3,10 +3,53 @@ import type { WorkerProps } from "./Worker.ts";
 // TODO: figure out why the later one from workerd breaks
 const DEFAULT_COMPATIBILITY_DATE = "2026-03-17";
 
-export const getCompatibility = (props: WorkerProps) => ({
-  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: WorkerProps) => {
+  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),
+  };
+};

package/src/Cloudflare/Workers/CronEventSource.ts

@@ -10,33 +10,208 @@ 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,
   process: (
     controller: cf.ScheduledController,
   ) => Effect.Effect<void, unknown, Req>,
-) => CronEventSource.use((source) => source(expression, process));
+): Effect.Effect<void, never, CronEventSource | Exclude<Req, RuntimeContext>> =>
+  CronEventSource.use((source) => source(expression, process));
 
 export type CronEventSourceService = <Req = never>(
   expression: string,
   process: (
     controller: cf.ScheduledController,
   ) => Effect.Effect<void, unknown, Req>,
-) => Effect.Effect<void, never, never>;
+) => Effect.Effect<void, never, Exclude<Req, RuntimeContext>>;
 
 export class CronEventSource extends Context.Service<
   CronEventSource,

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/DurableObjectBridge.ts

@@ -42,43 +42,44 @@ export const makeDurableObjectBridge =
       };
     },
   ) =>
-  (className: string) =>
-    class DurableObjectBridge extends DurableObject {
+  (className: string) => {
+    // One isolate-lifetime layer build shared by every activation of this DO
+    // class: `build` memoizes the built context, so re-activations (including
+    // hibernatable WebSocket wakes, which re-run the constructor) reuse it
+    // instead of rebuilding the layer stack.
+    const { build } = getWorkerExport<DurableObjectExport>({
+      entrypoint,
+      stack,
+      exportName: className,
+    });
+
+    return class DurableObjectBridge extends DurableObject {
       #state;
-      #globalContext;
-      #exported;
       #instance;
       constructor(state: cf.DurableObjectState, env: any) {
         super(state as any, env);
         this.#state = state;
 
-        const { globalContext, exported } =
-          getWorkerExport<DurableObjectExport>({
-            entrypoint,
-            stack,
-            exportName: className,
-          });
-
-        this.#globalContext = globalContext;
-        this.#exported = exported;
-
         this.#instance = state.blockConcurrencyWhile(() =>
-          this.#exported.pipe(
-            Effect.flatMap(({ constructor, services }) => {
-              const context = Layer.succeed(
+          build((promise) => void (state as any).waitUntil?.(promise)).then(
+            ({ context, export: exported }) => {
+              const { constructor, services } = exported;
+              const doContext = Layer.succeed(
                 DurableObjectState,
                 fromDurableObjectState(this.#state),
-              ).pipe(Layer.provideMerge(Layer.succeedContext(services)));
+              ).pipe(
+                Layer.provideMerge(Layer.succeedContext(services)),
+                Layer.provideMerge(Layer.succeedContext(context)),
+              );
               return constructor.pipe(
-                Effect.provide(context),
+                Effect.provide(doContext),
                 Effect.flatMap((instance) =>
-                  instance.pipe(Effect.provide(context)),
+                  instance.pipe(Effect.provide(doContext)),
                 ),
-                Effect.map((instance) => ({ instance, services })),
+                Effect.map((instance) => ({ instance, services, context })),
+                Effect.runPromise,
               );
-            }),
-            Effect.provide(this.#globalContext),
-            Effect.runPromise,
+            },
           ),
         );
 
@@ -116,11 +117,14 @@ export const makeDurableObjectBridge =
 
       async #execute(
         fn: (instance: DurableObjectShape) => Effect.Effect<any, any, any>,
-        onExit?: (exit: Exit.Exit<any, any>) => Promise<any>,
+        onExit?: (
+          exit: Exit.Exit<any, any>,
+          scope: Scope.Closeable,
+        ) => Promise<any>,
       ) {
         const scope = Scope.makeUnsafe();
 
-        const { instance, services } = await this.#instance;
+        const { instance, services, context } = await this.#instance;
 
         return fn(instance)
           .pipe(
@@ -131,17 +135,17 @@ export const makeDurableObjectBridge =
               ).pipe(
                 Layer.provideMerge(Layer.succeed(Scope.Scope, scope)),
                 Layer.provideMerge(Layer.succeedContext(services)),
-                Layer.provideMerge(this.#globalContext),
+                Layer.provideMerge(Layer.succeedContext(context)),
               ),
             ),
             Effect.runPromiseExit,
           )
-          .then(
-            onExit ??
-              ((exit) =>
-                exit._tag === "Success"
-                  ? Promise.resolve(exit.value)
-                  : Promise.reject(Cause.squash(exit.cause))),
+          .then((exit) =>
+            onExit
+              ? onExit(exit, scope)
+              : exit._tag === "Success"
+                ? Promise.resolve(exit.value)
+                : Promise.reject(Cause.squash(exit.cause)),
           )
           .finally(() =>
             isScopeEjected(scope)
@@ -194,3 +198,4 @@ export const makeDurableObjectBridge =
         );
       }
     } as any;
+  };

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/HttpServer.ts

@@ -3,7 +3,6 @@ import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
-import * as Scope from "effect/Scope";
 import * as EffectHttp from "effect/unstable/http/HttpEffect";
 import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
 import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
@@ -74,6 +73,4 @@ const toHandledWebResponse = <Req>(
     return yield* Deferred.await(webResponse);
   });
 
-const scopeEjected = Symbol.for("effect/http/HttpEffect/scopeEjected");
-
-export const isScopeEjected = (scope: Scope.Scope) => scopeEjected in scope;
+export { isScopeEjected } from "../../Http.ts";