alchemy 2.0.0-beta.59 → 2.0.0-beta.60

package/src/Cloudflare/Workers/WorkerRuntimeContext.ts

@@ -147,7 +147,7 @@ export const makeWorkerRuntimeContext = (id: string): WorkerRuntimeContext => {
       // layer the fetch path uses, then envelope-encodes the result so
       // `Effect.fail` round-trips as `RpcErrorEnvelope` and `Stream` as
       // `RpcStreamEnvelope` (consumers wrap the binding with
-      // `toPromiseApi`/`bindWorker` to decode).
+      // `toRpcAsync`/`bindWorker` to decode).
 
       return {
         ...exports,

package/src/Cloudflare/WorkersForPlatforms/DispatchNamespace.ts

@@ -93,14 +93,56 @@ export type DispatchNamespace = Resource<
  * ```
  *
  * @section Uploading user Workers
- * @example Upload a customer script into the namespace
+ * @example Upload a customer Worker into the namespace
+ * A {@link Cloudflare.Worker} deploys into the namespace as a "user worker"
+ * (rather than as a routable account-level script) when its `namespace` prop is
+ * set. Reference the namespace by its `name` output so it deploys first.
  * ```typescript
- * const script = yield* Cloudflare.DispatchNamespaceScript("CustomerA", {
+ * const namespace = yield* Cloudflare.WorkersForPlatforms.DispatchNamespace("Customers", {});
+ *
+ * const customerA = yield* Cloudflare.Worker("CustomerA", {
  *   namespace: namespace.name,
  *   script: `export default { fetch() { return new Response("hi"); } }`,
  * });
  * ```
  *
+ * @section Dispatching from a platform Worker
+ * @example Effect-native binding via `Get`
+ * `Cloudflare.WorkersForPlatforms.Get(namespace)` binds the namespace and
+ * returns an Effect-native client; `get(name)` resolves a user Worker by script
+ * name. Provide {@link GetBinding} on the Worker's runtime layer.
+ * ```typescript
+ * const dispatch = yield* Cloudflare.WorkersForPlatforms.Get(namespace);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     const request = yield* HttpServerRequest;
+ *     const userWorker = yield* dispatch.get("CustomerA");
+ *     return yield* Effect.promise(() => userWorker.fetch(request));
+ *   }),
+ * };
+ * ```
+ *
+ * @example Async binding via `env` + `InferEnv`
+ * Passing the namespace on a Worker's `env` binds it as a native
+ * `dispatch_namespace` binding; `Cloudflare.InferEnv` types `env.DISPATCH` as
+ * the runtime `DispatchNamespace`, so the async handler calls `.get(name)`
+ * directly.
+ * ```typescript
+ * const platform = Cloudflare.Worker("Platform", {
+ *   main: "./handler.ts",
+ *   env: { DISPATCH: namespace },
+ * });
+ * type Env = Cloudflare.InferEnv<typeof platform>;
+ *
+ * // handler.ts
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     return env.DISPATCH.get("CustomerA").fetch(request);
+ *   },
+ * };
+ * ```
+ *
  * @see https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/
  */
 export const DispatchNamespace = Resource<DispatchNamespace>(TypeId);

package/src/Cloudflare/WorkersForPlatforms/Get.ts

@@ -0,0 +1,87 @@
+/// <reference types="@cloudflare/workers-types" />
+
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Binding from "../../Binding.ts";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
+import type { DispatchNamespace as DispatchNamespaceResource } from "./DispatchNamespace.ts";
+
+/**
+ * Bind a {@link DispatchNamespace} to a Worker and obtain the Effect-native
+ * dynamic-dispatch client (`get`).
+ *
+ * `Get` is a single identifier that is simultaneously the binding's Context
+ * tag, its type, and the callable —
+ * `yield* Cloudflare.WorkersForPlatforms.Get(namespace)`.
+ *
+ * Provide {@link GetBinding} on the Worker's runtime layer to resolve the
+ * underlying `dispatch_namespace` binding at request time.
+ *
+ * @binding
+ * @product Workers for Platforms
+ * @category Workers & Compute
+ *
+ * @section Dispatching to user Workers
+ * @example Dispatch a request to a customer Worker
+ * Bind the namespace during the Worker's init phase, then look up and forward
+ * to a user Worker from a request handler.
+ * ```typescript
+ * const dispatch = yield* Cloudflare.WorkersForPlatforms.Get(namespace);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     const request = yield* HttpServerRequest;
+ *     const userWorker = yield* dispatch.get("customer-a");
+ *     return yield* Effect.promise(() => userWorker.fetch(request));
+ *   }),
+ * };
+ * ```
+ *
+ * @see https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/get-started/dynamic-dispatch/
+ */
+export interface Get extends Binding.Service<
+  Get,
+  "Cloudflare.WorkersForPlatforms.Get",
+  (
+    namespace: DispatchNamespaceResource,
+  ) => Effect.Effect<DispatchNamespaceClient>
+> {}
+
+export const Get = Binding.Service<Get>("Cloudflare.WorkersForPlatforms.Get");
+
+/** Error raised by dynamic-dispatch runtime operations. */
+export class DispatchNamespaceError extends Data.TaggedError(
+  "DispatchNamespaceError",
+)<{
+  /** Human-readable runtime error message. */
+  message: string;
+  /** Original error thrown by the Cloudflare runtime binding. */
+  cause: unknown;
+}> {}
+
+/**
+ * Effect-native client for a Workers for Platforms dispatch-namespace Worker
+ * binding.
+ *
+ * Wraps the runtime `DispatchNamespace` binding so the lookup returns an
+ * Effect tagged with {@link DispatchNamespaceError}. Use
+ * `Cloudflare.WorkersForPlatforms.Get(namespace)` inside a Worker's init
+ * phase.
+ */
+export interface DispatchNamespaceClient {
+  /** Effect resolving to the raw dispatch-namespace runtime binding. */
+  raw: Effect.Effect<DispatchNamespace, never, RuntimeContext>;
+  /**
+   * Look up a user Worker in the dispatch namespace by script name and obtain
+   * a `Fetcher` to send it requests.
+   *
+   * @param name Name of the user Worker script.
+   * @param args Arguments passed to the user Worker script.
+   * @param options Options for the dynamic-dispatch invocation.
+   */
+  get(
+    name: string,
+    args?: { [key: string]: any },
+    options?: DynamicDispatchOptions,
+  ): Effect.Effect<Fetcher, DispatchNamespaceError, RuntimeContext>;
+}

package/src/Cloudflare/WorkersForPlatforms/GetBinding.ts

@@ -0,0 +1,63 @@
+/// <reference types="@cloudflare/workers-types" />
+
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { Worker, WorkerEnvironment } from "../Workers/Worker.ts";
+import type { DispatchNamespace as DispatchNamespaceResource } from "./DispatchNamespace.ts";
+import {
+  type DispatchNamespaceClient,
+  DispatchNamespaceError,
+  Get,
+} from "./Get.ts";
+
+/**
+ * Implementation of the {@link Get} binding that uses a native
+ * `dispatch_namespace` Worker binding.
+ */
+export const GetBinding = Layer.effect(
+  Get,
+  Effect.gen(function* () {
+    const env = yield* WorkerEnvironment;
+    const host = yield* Worker;
+
+    return Effect.fn(function* (namespace: DispatchNamespaceResource) {
+      if (!globalThis.__ALCHEMY_RUNTIME__) {
+        yield* host.bind`${namespace}`({
+          bindings: [
+            {
+              type: "dispatch_namespace",
+              name: namespace.LogicalId,
+              namespace: namespace.name,
+            },
+          ],
+        });
+      }
+
+      const raw = Effect.sync(
+        // Lazy — the WorkerEnvironment binding is not populated until runtime.
+        () => (env as Record<string, DispatchNamespace>)[namespace.LogicalId]!,
+      );
+
+      const self: DispatchNamespaceClient = {
+        raw,
+        get: (name, args, options) =>
+          raw.pipe(
+            Effect.flatMap((ns) =>
+              Effect.try({
+                try: () => ns.get(name, args, options),
+                catch: (error) =>
+                  new DispatchNamespaceError({
+                    message:
+                      error instanceof Error
+                        ? error.message
+                        : "Unknown dispatch namespace runtime error",
+                    cause: error,
+                  }),
+              }),
+            ),
+          ),
+      };
+      return self;
+    });
+  }),
+);

package/src/Cloudflare/WorkersForPlatforms/index.ts

@@ -1 +1,3 @@
 export * from "./DispatchNamespace.ts";
+export * from "./Get.ts";
+export * from "./GetBinding.ts";

package/src/Cloudflare/Workflows/Workflow.ts

@@ -5,6 +5,7 @@ import * as Effect from "effect/Effect";
 import * as Stream from "effect/Stream";
 import { AlchemyContext } from "../../AlchemyContext.ts";
 import { ExecutionContext } from "../../ExecutionContext.ts";
+import type { Input } from "../../Input.ts";
 import { ALCHEMY_PHASE } from "../../Phase.ts";
 import type { PlatformServices } from "../../Platform.ts";
 import * as Provider from "../../Provider.ts";
@@ -149,6 +150,52 @@ export const isWorkflowExport = (value: unknown): value is WorkflowExport =>
   "kind" in value &&
   (value as any).kind === "workflow";
 
+/**
+ * Props for the reference (async) form of {@link Workflow}. Used when binding
+ * a Workflow class to a plain async Worker (one without an Effect runtime) via
+ * the Worker's `env`. Mirrors `DurableObjectProps`.
+ */
+export interface WorkflowRefProps {
+  /**
+   * Name of the exported `WorkflowEntrypoint` class.
+   *
+   * @default name
+   */
+  className?: string;
+  /**
+   * Worker script that hosts the Workflow class. Omit this when the workflow
+   * is hosted by the Worker that declares the binding.
+   */
+  scriptName?: Input<string>;
+}
+
+/**
+ * A lightweight reference to a Workflow, produced by the props-only form of
+ * {@link Workflow} (`Workflow(name, { className })`). Carries just enough
+ * metadata to emit the `workflow` binding for an async Worker and to drive
+ * the `putWorkflow` lifecycle. Mirrors `DurableObjectLike`.
+ */
+export interface WorkflowLike<Params = unknown> {
+  kind: TypeId;
+  name: string;
+  /** @internal phantom */
+  workflowName?: string;
+  /** @internal phantom */
+  className?: string;
+  /** @internal phantom */
+  scriptName?: Input<string>;
+  /** @internal phantom */
+  Params?: Params;
+}
+
+/**
+ * Type guard for the reference (async) form of a Workflow.
+ */
+export const isWorkflowLike = (value: unknown): value is WorkflowLike =>
+  typeof value === "object" &&
+  value !== null &&
+  (value as { kind?: unknown }).kind === TypeId;
+
 /**
  * Type guard for workflow binding metadata in the Worker binding contract.
  */
@@ -204,6 +251,10 @@ export interface WorkflowClass extends Effect.Effect<
       new (_: never): WorkflowImpl<Input, Result>;
     };
   };
+  <Params = unknown>(
+    name: string,
+    props?: WorkflowRefProps,
+  ): WorkflowLike<Params>;
   <Input = unknown, Result = unknown, InitReq = never>(
     name: string,
     impl: Effect.Effect<WorkflowImpl<Input, Result>, ConfigError, InitReq>,
@@ -244,7 +295,7 @@ export class WorkflowScope extends Context.Service<
  * ```
  *
  * @resource
- * @product Workers
+ * @product Workflows
  * @category Workers & Compute
  *
  * @section Defining a Workflow
@@ -346,6 +397,70 @@ export class WorkflowScope extends Context.Service<
  * };
  * ```
  *
+ * @section Binding in an Async Worker
+ * When using an Async Worker (plain `async fetch` handler, no Effect
+ * runtime), declare Workflows in the `env` prop of the Worker resource.
+ * Pass a `Workflow` reference with a `className` matching the exported
+ * `WorkflowEntrypoint` subclass in your worker source file. If `className`
+ * is omitted, it defaults to the binding name. Use `Cloudflare.InferEnv`
+ * to get a fully typed `env` object that includes the workflow binding.
+ *
+ * @example Declaring a Workflow binding in the stack
+ * ```typescript
+ * // alchemy.run.ts
+ * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
+ *
+ * export const Worker = Cloudflare.Worker("Worker", {
+ *   main: "./src/worker.ts",
+ *   env: {
+ *     MY_WORKFLOW: Cloudflare.Workflow<{ value: string }>("MyWorkflow", {
+ *       className: "MyWorkflow",
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * @example Using the Workflow from a plain async handler
+ * ```typescript
+ * // src/worker.ts
+ * import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+ * import type { WorkerEnv } from "../alchemy.run.ts";
+ *
+ * export class MyWorkflow extends WorkflowEntrypoint<WorkerEnv, { value: string }> {
+ *   async run(event: Readonly<WorkflowEvent<{ value: string }>>, step: WorkflowStep) {
+ *     return await step.do("greet", async () => `Hello, ${event.payload.value}!`);
+ *   }
+ * }
+ *
+ * export default {
+ *   async fetch(request: Request, env: WorkerEnv) {
+ *     const instance = await env.MY_WORKFLOW.create({ params: { value: "world" } });
+ *     return Response.json({ instanceId: instance.id });
+ *   },
+ * };
+ * ```
+ *
+ * @section Cross-Script Binding in an Async Worker
+ * Async Workers can also bind to a Workflow hosted by another Worker
+ * script. The host Worker declares and exports the `WorkflowEntrypoint`
+ * class. The consumer Worker declares a `Workflow` with `scriptName` set
+ * to the host Worker's script name. Cross-script references are bindings
+ * only — Alchemy does not drive `putWorkflow` for the foreign class, so
+ * deploy the host first.
+ *
+ * @example Consumer Worker binds to the host script
+ * ```typescript
+ * const consumer = yield* Cloudflare.Worker("Consumer", {
+ *   main: "./src/consumer.ts",
+ *   env: {
+ *     MY_WORKFLOW: Cloudflare.Workflow("MyWorkflow", {
+ *       className: "MyWorkflow",
+ *       scriptName: host.workerName,
+ *     }),
+ *   },
+ * });
+ * ```
+ *
  * @section Testing Workflows
  * Workflows run asynchronously, so tests start an instance and
  * poll until it reaches a terminal status. A simple recipe with
@@ -381,91 +496,105 @@ export class WorkflowScope extends Context.Service<
  * ```
  */
 export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
-  ...args: [] | [name: string, impl: Effect.Effect<WorkflowImpl<any, any>>]
-) =>
-  args.length === 0
-    ? Workflow
-    : effectClass(
-        Effect.gen(function* () {
-          const [name, impl] = args;
-          const worker = yield* Worker;
-
-          // Add the workflow binding to the Worker metadata
-          yield* worker.bind`${name}`({
-            bindings: [
-              {
-                type: "workflow",
-                name,
-                workflowName: name,
-                className: name,
-              },
-            ],
-          });
+  ...args:
+    | []
+    | [name: string, impl: Effect.Effect<WorkflowImpl<any, any>>]
+    | [name: string, props?: WorkflowRefProps]
+) => {
+  if (args.length === 0) {
+    return Workflow;
+  }
+  const [name, second] = args;
+  if (!Effect.isEffect(second)) {
+    // Props-only (async) reference form: returns a plain `WorkflowLike` that an
+    // async Worker binds via `env`. `WorkerAsyncBindings` emits the `workflow`
+    // binding and drives `putWorkflow` for locally-hosted workflows.
+    const props = second as WorkflowRefProps | undefined;
+    return {
+      kind: TypeId,
+      name,
+      workflowName: name,
+      className: props?.className ?? name,
+      scriptName: props?.scriptName,
+    } satisfies WorkflowLike;
+  }
+  const impl = second;
+  return effectClass(
+    Effect.gen(function* () {
+      const worker = yield* Worker;
 
-          // Create the Workflow API resource (putWorkflow / deleteWorkflow)
-          yield* WorkflowResource(name, {
+      // Add the workflow binding to the Worker metadata
+      yield* worker.bind`${name}`({
+        bindings: [
+          {
+            type: "workflow",
+            name,
             workflowName: name,
             className: name,
-            scriptName: worker.workerName,
-          });
-
-          const services =
-            yield* Effect.context<Effect.Services<typeof impl>>();
-
-          const binding = yield* Effect.all([
-            WorkerEnvironment,
-            ALCHEMY_PHASE,
-          ]).pipe(
-            Effect.flatMap(([env, phase]) => {
-              if (env === undefined || phase === "plan") {
-                return Effect.succeed(undefined as any);
-              }
-              const wf = env[name];
-              if (!wf) {
-                return Effect.die(
-                  new Error(`Workflow '${name}' not found in env`),
-                );
-              }
-              return Effect.succeed(wf);
-            }),
-          );
+          },
+        ],
+      });
 
-          const self: WorkflowHandle<any, any> = {
-            Type: TypeId,
-            name,
-            create: (input: unknown) =>
-              Effect.tryPromise(() => binding.create({ params: input })).pipe(
-                Effect.map(wrapInstance),
-                Effect.orDie,
-              ),
-            get: (instanceId: string) =>
-              Effect.tryPromise(() => binding.get(instanceId)).pipe(
-                Effect.map(wrapInstance),
-                Effect.orDie,
-              ),
-          };
+      // Create the Workflow API resource (putWorkflow / deleteWorkflow)
+      yield* WorkflowResource(name, {
+        workflowName: name,
+        className: name,
+        scriptName: worker.workerName,
+      });
 
-          const fn = yield* impl.pipe(
-            Effect.provideService(WorkflowScope, self as any),
-          );
+      const services = yield* Effect.context<Effect.Services<typeof impl>>();
 
-          yield* worker.export(name, {
-            kind: "workflow",
-            make: (env: unknown) =>
-              Effect.succeed(((input: unknown) =>
-                fn(input).pipe(
-                  Effect.provideService(
-                    WorkerEnvironment,
-                    env as Record<string, any>,
-                  ),
-                )) as WorkflowImpl<any, any>).pipe(
-                Effect.provideContext(services),
+      const binding = yield* Effect.all([
+        WorkerEnvironment,
+        ALCHEMY_PHASE,
+      ]).pipe(
+        Effect.flatMap(([env, phase]) => {
+          if (env === undefined || phase === "plan") {
+            return Effect.succeed(undefined as any);
+          }
+          const wf = env[name];
+          if (!wf) {
+            return Effect.die(new Error(`Workflow '${name}' not found in env`));
+          }
+          return Effect.succeed(wf);
+        }),
+      );
+
+      const self: WorkflowHandle<any, any> = {
+        Type: TypeId,
+        name,
+        create: (input: unknown) =>
+          Effect.tryPromise(() => binding.create({ params: input })).pipe(
+            Effect.map(wrapInstance),
+            Effect.orDie,
+          ),
+        get: (instanceId: string) =>
+          Effect.tryPromise(() => binding.get(instanceId)).pipe(
+            Effect.map(wrapInstance),
+            Effect.orDie,
+          ),
+      };
+
+      const fn = yield* impl.pipe(
+        Effect.provideService(WorkflowScope, self as any),
+      );
+
+      yield* worker.export(name, {
+        kind: "workflow",
+        make: (env: unknown) =>
+          Effect.succeed(((input: unknown) =>
+            fn(input).pipe(
+              Effect.provideService(
+                WorkerEnvironment,
+                env as Record<string, any>,
               ),
-          } satisfies WorkflowExport);
+            )) as WorkflowImpl<any, any>).pipe(Effect.provideContext(services)),
+      } satisfies WorkflowExport);
 
-          return self;
-        }),
-      )) as any);
+      return self;
+    }),
+  );
+}) as any);
 
 // ---------------------------------------------------------------------------
 // WorkflowResource -- manages the Cloudflare Workflows API lifecycle

package/src/Command/Build.ts

@@ -2,9 +2,11 @@ import * as Effect from "effect/Effect";
 import * as Equal from "effect/Equal";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
+import * as Redacted from "effect/Redacted";
 import { havePropsChanged, isResolved } from "../Diff.ts";
 import * as Provider from "../Provider.ts";
 import { Resource } from "../Resource.ts";
+import { sha256Object } from "../Util/sha256.ts";
 import {
   CommandError,
   CommandExecutor,
@@ -109,6 +111,21 @@ export interface Build extends Resource<
  */
 export const Build = Resource<Build>("Command.Build");
 
+/**
+ * Resolves `Redacted` env values to their plain string so that a change in a
+ * secret's value still busts the memo hash (the hash is one-way, so the secret
+ * itself is never recoverable from state).
+ */
+const resolveEnv = (env: CommandProps["env"]) =>
+  env
+    ? Object.fromEntries(
+        Object.entries(env).map(([key, value]) => [
+          key,
+          Redacted.isRedacted(value) ? Redacted.value(value) : value,
+        ]),
+      )
+    : undefined;
+
 export const BuildProvider = () =>
   Provider.effect(
     Build,
@@ -135,10 +152,24 @@ export const BuildProvider = () =>
               ? { input: undefined, output: undefined }
               : yield* Effect.all(
                   {
+                    // Fold the resolved command + env into the input hash so
+                    // two builds that share the same source tree + `outdir`
+                    // but differ in their command or environment (e.g.
+                    // per-stage builds baking different `EXPO_PUBLIC_*` /
+                    // API ids) are never judged reusable. Without this the
+                    // second build silently reuses the first's stale output.
                     input: hashDirectory({
                       cwd,
                       memo: props.memo === true ? {} : props.memo,
-                    }),
+                    }).pipe(
+                      Effect.flatMap((files) =>
+                        sha256Object({
+                          files,
+                          command: props.command,
+                          env: resolveEnv(props.env),
+                        }),
+                      ),
+                    ),
                     output: hashDirectory({
                       cwd: outdir,
                       memo: {