alchemy 2.0.0-beta.35 → 2.0.0-beta.37

package/src/Cloudflare/Workers/Workflow.ts

@@ -50,12 +50,21 @@ export class WorkflowStep extends Context.Service<
  * Execute a named, durable workflow step. The effect is run inside the
  * Cloudflare step transaction so its result is automatically persisted
  * and replayed on retries.
+ *
+ * Any services the inner effect requires (e.g. `WorkerEnvironment` from a
+ * binding like `kv.put` / `kv.get`) are threaded through automatically by
+ * capturing the surrounding workflow body's context and providing it to
+ * the inner effect before it runs inside `step.do`.
  */
-export const task = <T>(
+export const task = <T, R = never>(
   name: string,
-  effect: Effect.Effect<T>,
-): Effect.Effect<T, never, WorkflowStep> =>
-  WorkflowStep.asEffect().pipe(Effect.flatMap((step) => step.do(name, effect)));
+  effect: Effect.Effect<T, never, R>,
+): Effect.Effect<T, never, WorkflowStep | R> =>
+  Effect.gen(function* () {
+    const step = yield* WorkflowStep;
+    const context = yield* Effect.context<R>();
+    return yield* step.do(name, effect.pipe(Effect.provide(context)));
+  });
 
 /**
  * Pause the workflow for the given duration.
@@ -103,20 +112,17 @@ export type WorkflowServices = WorkerServices | PlatformServices;
  */
 export interface WorkflowExport {
   readonly kind: "workflow";
-  readonly make: (
-    env: unknown,
-  ) => Effect.Effect<Effect.Effect<unknown, never, WorkflowRunServices>>;
+  readonly make: (env: unknown) => Effect.Effect<WorkflowImpl<any, any>>;
 }
 
 /**
- * A workflow body is an Effect that requires WorkflowRunServices
- * (event + step) to execute.
+ * A workflow implementation is a function from a typed `Input` payload to
+ * an Effect that produces the workflow's `Result`. The Effect requires
+ * `WorkflowRunServices` (event + step + env) to execute.
  */
-export type WorkflowBody<Result = unknown> = Effect.Effect<
-  Result,
-  never,
-  WorkflowRunServices
->;
+export type WorkflowImpl<Input = unknown, Result = unknown> = (
+  input: Input,
+) => Effect.Effect<Result, never, WorkflowRunServices>;
 
 export const isWorkflowExport = (value: unknown): value is WorkflowExport =>
   typeof value === "object" &&
@@ -141,24 +147,24 @@ export const isWorkflowBinding = (binding: {
  * Handle returned to the caller at deploy/bind time. Allows starting
  * workflow instances and checking their status from the Api layer.
  */
-export interface WorkflowHandle<Params = unknown> {
+export interface WorkflowHandle<Input = unknown, Result = unknown> {
   Type: WorkflowTypeId;
   name: string;
-  create(params?: Params): Effect.Effect<WorkflowInstance>;
-  get(instanceId: string): Effect.Effect<WorkflowInstance>;
+  create(input: Input): Effect.Effect<WorkflowInstance<Result>>;
+  get(instanceId: string): Effect.Effect<WorkflowInstance<Result>>;
 }
 
-export interface WorkflowInstance {
+export interface WorkflowInstance<Result = unknown> {
   id: string;
-  status(): Effect.Effect<WorkflowInstanceStatus>;
+  status(): Effect.Effect<WorkflowInstanceStatus<Result>>;
   pause(): Effect.Effect<void>;
   resume(): Effect.Effect<void>;
   terminate(): Effect.Effect<void>;
 }
 
-export interface WorkflowInstanceStatus {
+export interface WorkflowInstanceStatus<Result = unknown> {
   status: string;
-  output?: unknown;
+  output?: Result;
   error?: { name: string; message: string } | null;
 }
 
@@ -168,22 +174,22 @@ export interface WorkflowClass extends Effect.Effect<
   WorkflowHandle
 > {
   <_Self>(): {
-    <Result = unknown, InitReq = never>(
+    <Input = unknown, Result = unknown, InitReq = never>(
       name: string,
-      impl: Effect.Effect<WorkflowBody<Result>, never, InitReq>,
+      impl: Effect.Effect<WorkflowImpl<Input, Result>, never, InitReq>,
     ): Effect.Effect<
-      WorkflowHandle,
+      WorkflowHandle<Input, Result>,
       never,
       Worker | Exclude<InitReq, WorkflowServices>
     > & {
-      new (_: never): WorkflowBody<Result>;
+      new (_: never): WorkflowImpl<Input, Result>;
     };
   };
-  <Result = unknown, InitReq = never>(
+  <Input = unknown, Result = unknown, InitReq = never>(
     name: string,
-    impl: Effect.Effect<WorkflowBody<Result>, never, InitReq>,
+    impl: Effect.Effect<WorkflowImpl<Input, Result>, never, InitReq>,
   ): Effect.Effect<
-    WorkflowHandle,
+    WorkflowHandle<Input, Result>,
     never,
     Worker | Exclude<InitReq, WorkflowServices>
   >;
@@ -200,18 +206,18 @@ export class WorkflowScope extends Context.Service<
  *
  * A Workflow follows the same two-phase pattern as Workers and Durable
  * Objects. The outer `Effect.gen` resolves shared dependencies. The inner
- * `Effect.gen` is the workflow body — it reads the triggering event and
- * runs steps using `task`, `sleep`, and `sleepUntil`.
+ * `Effect.fn` is the workflow body — a function from a typed `input`
+ * payload to an Effect that runs steps using `task`, `sleep`, and
+ * `sleepUntil`.
  *
  * ```typescript
  * Effect.gen(function* () {
  *   // Phase 1: resolve dependencies
  *   const notifier = yield* NotificationService;
  *
- *   return Effect.gen(function* () {
+ *   return Effect.fn(function* (input: { orderId: string }) {
  *     // Phase 2: workflow body (durable steps)
- *     const event = yield* Cloudflare.WorkflowEvent;
- *     const result = yield* Cloudflare.task("process", doWork(event.payload));
+ *     const result = yield* Cloudflare.task("process", doWork(input.orderId));
  *     yield* Cloudflare.sleep("cooldown", "10 seconds");
  *     return result;
  *   });
@@ -226,9 +232,8 @@ export class WorkflowScope extends Context.Service<
  * export default class MyWorkflow extends Cloudflare.Workflow<MyWorkflow>()(
  *   "MyWorkflow",
  *   Effect.gen(function* () {
- *     return Effect.gen(function* () {
- *       const event = yield* Cloudflare.WorkflowEvent;
- *       return { received: event.payload };
+ *     return Effect.fn(function* (input: { name: string }) {
+ *       return { received: input.name };
  *     });
  *   }),
  * ) {}
@@ -248,33 +253,31 @@ export class WorkflowScope extends Context.Service<
  * yield* Cloudflare.sleep("cooldown", "30 seconds");
  * ```
  *
- * @example Accessing env bindings inside a step
- * `Cloudflare.WorkerEnvironment` is the same service available
- * inside a Worker — it gives you typed access to env bindings (KV,
- * R2, etc.) from inside a workflow body. Wrap any side-effecting
- * call in `task` so the result is persisted across replays.
+ * @example Accessing env bindings inside a task
+ * Bind a resource (e.g. `KVNamespace`, `R2Bucket`) in the workflow's
+ * outer init phase to get a typed Effect-native client, then use it
+ * directly inside `task`. `task` threads the binding's service
+ * requirement (`WorkerEnvironment`) through automatically so the inner
+ * Effect needs no extra plumbing.
  *
  * ```typescript
  * Effect.gen(function* () {
- *   const env = yield* Cloudflare.WorkerEnvironment;
- *   const event = yield* Cloudflare.WorkflowEvent;
- *   const { roomId, message } = event.payload as {
- *     roomId: string;
- *     message: string;
- *   };
+ *   const kv = yield* Cloudflare.KVNamespace.bind(KV);
+ *
+ *   return Effect.fn(function* (input: { roomId: string; message: string }) {
+ *     const { roomId, message } = input;
  *
- *   const stored = yield* Cloudflare.task(
- *     "kv-roundtrip",
- *     Effect.tryPromise({
- *       try: async () => {
- *         await env.KV.put(`workflow:${roomId}`, message);
- *         return await env.KV.get(`workflow:${roomId}`);
- *       },
- *       catch: (cause) =>
- *         cause instanceof Error ? cause : new Error(String(cause)),
- *     }).pipe(Effect.orDie),
- *   );
- *   return stored;
+ *     const stored = yield* Cloudflare.task(
+ *       "kv-roundtrip",
+ *       Effect.gen(function* () {
+ *         const key = `workflow:${roomId}`;
+ *         yield* kv.put(key, message);
+ *         return yield* kv.get(key);
+ *       }).pipe(Effect.orDie),
+ *     );
+ *
+ *     return stored;
+ *   });
  * });
  * ```
  *
@@ -357,7 +360,7 @@ export class WorkflowScope extends Context.Service<
  * ```
  */
 export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
-  ...args: [] | [name: string, impl: Effect.Effect<WorkflowBody>]
+  ...args: [] | [name: string, impl: Effect.Effect<WorkflowImpl<any, any>>]
 ) =>
   args.length === 0
     ? Workflow
@@ -404,11 +407,11 @@ export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
             }),
           );
 
-          const self: WorkflowHandle = {
+          const self: WorkflowHandle<any, any> = {
             Type: WorkflowTypeId,
             name,
-            create: (params?: unknown) =>
-              Effect.tryPromise(() => binding.create({ params })).pipe(
+            create: (input: unknown) =>
+              Effect.tryPromise(() => binding.create({ params: input })).pipe(
                 Effect.map(wrapInstance),
                 Effect.orDie,
               ),
@@ -419,21 +422,22 @@ export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
               ),
           };
 
-          const body = yield* impl.pipe(
+          const fn = yield* impl.pipe(
             Effect.provideService(WorkflowScope, self as any),
           );
 
           yield* worker.export(name, {
             kind: "workflow",
             make: (env: unknown) =>
-              Effect.succeed(
-                body.pipe(
+              Effect.succeed(((input: unknown) =>
+                fn(input).pipe(
                   Effect.provideService(
                     WorkerEnvironment,
                     env as Record<string, any>,
                   ),
-                ),
-              ).pipe(Effect.provideContext(services)),
+                )) as WorkflowImpl<any, any>).pipe(
+                Effect.provideContext(services),
+              ),
           } satisfies WorkflowExport);
 
           return self;
@@ -520,13 +524,13 @@ export const WorkflowProvider = () =>
 // Helpers
 // ---------------------------------------------------------------------------
 
-const wrapInstance = (raw: any): WorkflowInstance => ({
+const wrapInstance = <Result>(raw: any): WorkflowInstance<Result> => ({
   id: raw.id,
   status: () =>
     Effect.tryPromise(() => raw.status()).pipe(
       Effect.map((s: any) => ({
         status: s.status as string,
-        output: s.output,
+        output: s.output as Result,
         error: s.error,
       })),
       Effect.orDie,

package/src/Cloudflare/Workers/index.ts

@@ -1,5 +1,6 @@
 export * from "./Assets.ts";
 export * from "./ConfigProvider.ts";
+export * from "./CronEventSource.ts";
 export * from "./DurableObjectNamespace.ts";
 export * from "./DurableObjectState.ts";
 export * from "./DurableObjectStorage.ts";

package/src/Cloudflare/index.ts

@@ -1,11 +1,13 @@
 export * from "./ApiToken/index.ts";
 export * from "./Artifacts/index.ts";
 export * from "./AiGateway/index.ts";
+export * from "./AnalyticsEngine/index.ts";
 export * from "./CloudflareEnvironment.ts";
 export * from "./Container/index.ts";
 export * from "./D1/index.ts";
 export * from "./EdgeSession.ts";
 export * from "./Hyperdrive/index.ts";
+export * from "./Images/index.ts";
 export * from "./KV/index.ts";
 export * from "./Providers.ts";
 export * from "./Queue/index.ts";

package/src/Deploy.ts

@@ -1,4 +1,5 @@
 import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
 import { AlchemyContext } from "./AlchemyContext.ts";
 import * as Apply from "./Apply.ts";
 import type { Input } from "./Input.ts";
@@ -10,10 +11,13 @@ export const deploy = <A>({
   stack,
   stage,
   dev,
+  scope,
 }: {
   stack: StackEffect<CompiledStack<A>, Stage | AlchemyContext>;
   stage: string;
   dev?: boolean;
+  /** See {@link evalStack} — when set, scoped resources outlive `deploy`. */
+  scope?: Scope.Scope;
 }) =>
   evalStack(
     stack,
@@ -23,5 +27,5 @@ export const deploy = <A>({
         const output = yield* Apply.apply(plan);
         return output as Input.Resolve<A>;
       }),
-    { stage, dev },
+    { stage, dev, scope },
   );

package/src/Destroy.ts

@@ -1,4 +1,5 @@
 import { Effect } from "effect";
+import type * as Scope from "effect/Scope";
 import type { AlchemyContext } from "./AlchemyContext.ts";
 import * as Apply from "./Apply.ts";
 import * as Plan from "./Plan.ts";
@@ -10,10 +11,13 @@ export const destroy = ({
   stack,
   stage,
   dev,
+  scope,
 }: {
   stack: StackEffect<CompiledStack, Stage | AlchemyContext>;
   stage: string;
   dev?: boolean;
+  /** See {@link evalStack} — when set, scoped resources outlive `destroy`. */
+  scope?: Scope.Scope;
 }) =>
   evalStack(
     stack,
@@ -26,5 +30,5 @@ export const destroy = ({
         bindings: {},
         output: {},
       }).pipe(Effect.flatMap(Apply.apply)),
-    { stage, dev },
+    { stage, dev, scope },
   );

package/src/Output.ts

@@ -5,7 +5,7 @@ import { pipe } from "effect/Function";
 import type { Pipeable } from "effect/Pipeable";
 import * as Redacted from "effect/Redacted";
 import { SingleShotGen } from "effect/Utils";
-import { getRefMetadata, isRef, ref as stageRef, type Ref } from "./Ref.ts";
+import { getRefMetadata, isRef, type Ref } from "./Ref.ts";
 import { isResource, type Resource, type ResourceLike } from "./Resource.ts";
 import { RuntimeContext } from "./RuntimeContext.ts";
 import { Stack } from "./Stack.ts";
@@ -82,9 +82,11 @@ export type Expr<A = any, Req = any> =
   | ApplyExpr<any, A, Req>
   | EffectExpr<any, A, Req>
   | LiteralExpr<A>
+  | NamedExpr<A, Req>
   | PropExpr<A, keyof A, Req>
   | ResourceExpr<A, Req>
-  | RefExpr<A>;
+  | RefExpr<A>
+  | StackRefExpr<A>;
 
 export abstract class BaseExpr<A = any, Req = any> implements Output<A, Req> {
   declare readonly kind: any;
@@ -255,6 +257,36 @@ export class EffectExpr<A, B, Req = never, Req2 = never> extends BaseExpr<
   }
 }
 
+export const isNamedExpr = <A = any, Req = any>(
+  node: any,
+): node is NamedExpr<A, Req> => node?.kind === "NamedExpr";
+
+/**
+ * Wraps another `Expr` and overrides its `toString()` / inspect output.
+ *
+ * `BaseExpr.asEffect()` derives the binding id from `this.toString()`, so
+ * wrapping an expression in `NamedExpr` makes that derived id stable and
+ * caller-controlled (e.g. an env var name like `"API_KEY"`).
+ */
+export class NamedExpr<A, Req = never> extends BaseExpr<A, Req> {
+  readonly kind = "NamedExpr";
+  constructor(
+    public readonly expr: Expr<A, Req>,
+    public readonly bindingName: string,
+  ) {
+    super();
+    return proxy(this);
+  }
+  [inspect](): string {
+    return this.bindingName;
+  }
+}
+
+export const named = <A, Req>(
+  expr: Output<A, Req>,
+  name: string,
+): Output<A, Req> => new NamedExpr(expr as Expr<A, Req>, name) as any;
+
 export const all = <Outs extends (Output | Expr)[]>(...outs: Outs) =>
   new AllExpr(outs as any) as unknown as All<Outs>;
 
@@ -309,6 +341,48 @@ export class RefExpr<A> extends BaseExpr<A, never> {
   }
 }
 
+export const isStackRefExpr = <A = any>(node: any): node is StackRefExpr<A> =>
+  node?.kind === "StackRefExpr";
+
+/**
+ * A reference to the persisted output of a Stack at `(stack, stage)`.
+ *
+ * Resolved at evaluation time by reading `state.getOutput({ stack,
+ * stage })`. Distinct from {@link RefExpr}, which references a
+ * single resource's attributes within a stack/stage. `stage` may be
+ * `undefined`, in which case it falls back to the current stage.
+ */
+export class StackRefExpr<A> extends BaseExpr<A, never> {
+  readonly kind = "StackRefExpr";
+  constructor(
+    public readonly stack: string,
+    public readonly stage: string | undefined,
+  ) {
+    super();
+    return proxy(this);
+  }
+  [inspect](): string {
+    return `stackRef(${this.stack}${
+      this.stage ? `, { stage: ${this.stage} }` : ""
+    })`;
+  }
+}
+
+/**
+ * Build an `Output<A>` referencing the persisted output of another
+ * Stack. The returned Effect resolves to a lazy `Output<A>` whose
+ * value is read from the state store at plan/apply time.
+ *
+ * Returns `Effect<Output<A>>` (not `Output<A>` directly) so that
+ * `yield* Output.stackRef(...)` reads ergonomically inside an Effect
+ * generator and lines up with `Resource.ref` and `Stack.stage.<name>`.
+ */
+export const stackRef = <A>(
+  stack: string,
+  options: { stage?: string } = {},
+): Effect.Effect<Output<A, never>> =>
+  Effect.succeed(new StackRefExpr<A>(stack, options.stage) as any);
+
 export const filter = <Outs extends any[]>(...outs: Outs) =>
   outs.filter(isOutput) as unknown as Filter<Outs>;
 
@@ -353,7 +427,32 @@ function proxy(self: any): any {
       prop === ExprSymbol || prop === inspect ? true : prop in self,
     get: (target, prop) =>
       prop === Symbol.toPrimitive
-        ? (hint: string) => (hint === "number" ? Number.NaN : self.toString())
+        ? (hint: string) => {
+            // Any JS-level coercion of an unresolved Output produces a
+            // placeholder that *looks* like a real value but isn't:
+            //
+            //   - `string` / `default` hints (`${output}`, `output + ""`,
+            //     `==` against a primitive) previously fell through to
+            //     `self.toString()` and returned the inspect form
+            //     (e.g. "tunnel.tunnelId"). The bogus string flowed
+            //     into resource props and into the cloud — only
+            //     surfacing as an opaque downstream error (see PR
+            //     description for a real Cloudflare DNS landing).
+            //
+            //   - `number` hint (`+output`, `output * 2`,
+            //     `Math.max(0, output)`) previously returned NaN, which
+            //     propagates silently through arithmetic and lands as
+            //     "the API rejected a NaN field" much later.
+            //
+            // All three hints fail loud at the coercion site with a
+            // pointer to the right composition API.
+            throw new Error(
+              `Cannot coerce Output<${self[inspect]()}> to a ` +
+                `${hint === "number" ? "number" : "string"} via JS coercion. ` +
+                `Use Output.interpolate\`...\` or Output.map(output, fn) ` +
+                `to compose Outputs — the value isn't known until deploy time.`,
+            );
+          }
         : prop === ExprSymbol
           ? self
           : prop === inspect
@@ -445,6 +544,8 @@ export const evaluate: <A, Req = never>(
         );
       } else if (isPropExpr(expr)) {
         return (yield* evaluate(expr.expr, upstream))?.[expr.identifier];
+      } else if (isNamedExpr(expr)) {
+        return yield* evaluate(expr.expr, upstream);
       } else if (isRefExpr(expr)) {
         const state = yield* State.State;
         const stack = expr.stack ?? (yield* Stack).name;
@@ -465,6 +566,22 @@ export const evaluate: <A, Req = never>(
           );
         }
         return resource.attr;
+      } else if (isStackRefExpr(expr)) {
+        const state = yield* State.State;
+        const stack = expr.stack;
+        const stage = expr.stage ?? (yield* Stage);
+        const output = yield* state.getOutput({ stack, stage });
+        if (output == null) {
+          return yield* Effect.fail(
+            new InvalidReferenceError({
+              message: `Reference to stack '${stack}' at stage '${stage}' not found. Have you deployed stage '${stage}' of '${stack}'?`,
+              stack,
+              stage,
+              resourceId: stack,
+            }),
+          );
+        }
+        return output;
       }
     }
     if (Array.isArray(expr)) {
@@ -483,14 +600,6 @@ export const evaluate: <A, Req = never>(
     return expr;
   }) as Effect.Effect<any>;
 
-export const ref = <R extends ResourceLike>(
-  resourceId: R["LogicalId"],
-  options?: {
-    stage?: string;
-    stack?: string;
-  },
-) => of(stageRef({ id: resourceId, ...options }));
-
 export const hasOutputs = (value: any): value is Output<any, any> =>
   Object.keys(upstreamAny(value)).length > 0;
 
@@ -531,7 +640,7 @@ export const upstream = <E extends Output<any, any>>(expr: E): any => {
     return upstream(expr.expr);
   } else if (isAllExpr(expr)) {
     return Object.assign({}, ...expr.outs.map((out) => upstream(out)));
-  } else if (isEffectExpr(expr) || isApplyExpr(expr)) {
+  } else if (isEffectExpr(expr) || isApplyExpr(expr) || isNamedExpr(expr)) {
     return upstream(expr.expr);
   } else if (Array.isArray(expr)) {
     return expr.map(upstream).reduce(toObject, {});