alchemy 2.0.0-beta.3 → 2.0.0-beta.31

package/src/Cloudflare/Workers/WorkerBundle.ts

@@ -0,0 +1,228 @@
+import cloudflareRolldown from "@distilled.cloud/cloudflare-rolldown-plugin";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import { flow } from "effect/Function";
+import type * as Path from "effect/Path";
+import * as Stream from "effect/Stream";
+import type * as rolldown from "rolldown";
+import * as Artifacts from "../../Artifacts.ts";
+import * as Bundle from "../../Bundle/Bundle.ts";
+import { findCwdForBundle } from "../../Bundle/TempRoot.ts";
+import { Self } from "../../Self.ts";
+import {
+  isDurableObjectExport,
+  type DurableObjectExport,
+} from "./DurableObjectNamespace.ts";
+import { isWorkflowExport, type WorkflowExport } from "./Workflow.ts";
+
+export interface WorkerBundleOptions {
+  id: string;
+  main: string;
+  compatibility: {
+    date: string;
+    flags: string[];
+  };
+  entry:
+    | {
+        kind: "external";
+      }
+    | {
+        kind: "effect";
+        exports: Record<string, DurableObjectExport | WorkflowExport>;
+      };
+  stack: { name: string; stage: string };
+}
+
+export const WorkerBundle = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const context = yield* Effect.context<FileSystem.FileSystem | Path.Path>();
+  const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
+
+  const makeOptions = Effect.fnUntraced(function* (
+    options: WorkerBundleOptions,
+  ) {
+    const realMain = yield* fs.realPath(options.main).pipe(
+      Effect.mapError(
+        (cause) =>
+          new Bundle.BundleError({
+            message: `Failed to find real path for bundle: ${options.main}`,
+            cause,
+          }),
+      ),
+    );
+    const inputOptions: rolldown.InputOptions = {
+      input: realMain,
+      cwd: yield* findCwdForBundle(realMain).pipe(
+        Effect.mapError(
+          (cause) =>
+            new Bundle.BundleError({
+              message: `Failed to find cwd for bundle: ${realMain}`,
+              cause,
+            }),
+        ),
+        Effect.provide(context),
+      ),
+      plugins: [
+        cloudflareRolldown({
+          compatibilityDate: options.compatibility.date,
+          compatibilityFlags: options.compatibility.flags,
+        }),
+        options.entry.kind === "effect"
+          ? virtualEntryPlugin(
+              makeEffectVirtualEntry(options.entry.exports, options.stack),
+            )
+          : undefined,
+      ],
+      checks: {
+        // Suppress unresolved import warnings for unrelated AWS packages
+        unresolvedImport: false,
+      },
+    };
+    const outputOptions: rolldown.OutputOptions = {
+      format: "esm",
+      sourcemap: "hidden",
+      minify: true,
+      keepNames: true,
+      dir: `.alchemy/bundles/${options.id}`,
+    };
+    return { inputOptions, outputOptions };
+  });
+
+  return {
+    build: flow(
+      makeOptions,
+      Effect.flatMap((resolved) =>
+        Bundle.build(resolved.inputOptions, resolved.outputOptions),
+      ),
+      Artifacts.cached("build"),
+    ),
+    watch: flow(
+      makeOptions,
+      Stream.fromEffect,
+      Stream.flatMap((resolved) =>
+        Bundle.watch(resolved.inputOptions, resolved.outputOptions),
+      ),
+    ),
+  };
+});
+
+export const makeEffectVirtualEntry = (
+  exports: Record<string, DurableObjectExport | WorkflowExport>,
+  stack: { name: string; stage: string },
+) => {
+  const doClasses: string[] = [];
+  const wfClasses: string[] = [];
+  for (const [className, entry] of Object.entries(exports)) {
+    if (isDurableObjectExport(entry)) {
+      doClasses.push(className);
+    } else if (isWorkflowExport(entry)) {
+      wfClasses.push(className);
+    }
+  }
+  const hasDoClasses = doClasses.length > 0;
+  const hasWfClasses = wfClasses.length > 0;
+  return (importPath: string) => `
+import * as Config from "effect/Config";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as Context from "effect/Context";
+import * as Stream from "effect/Stream";
+
+import { env, DurableObject${hasWfClasses ? ", WorkflowEntrypoint" : ""} } from "cloudflare:workers";
+import { MinimumLogLevel } from "effect/References";
+import { NodeServices } from "@effect/platform-node";
+import { Stack } from "alchemy/Stack";
+import { WorkerEnvironment, makeDurableObjectBridge${hasWfClasses ? ", makeWorkflowBridge" : ""}, ExportedHandlerMethods } from "alchemy/Cloudflare";
+
+import entry from "${importPath}";
+
+const tag = Context.Service("${Self.key}")
+const layer =
+  typeof entry?.build === "function"
+    ? entry
+    : Layer.effect(tag, typeof entry?.asEffect === "function" ? entry.asEffect() : entry);
+
+const platform = Layer.mergeAll(
+  NodeServices.layer,
+  FetchHttpClient.layer,
+  // TODO(sam): wire this up to telemetry more directly
+  Logger.layer([Logger.consolePretty()]),
+);
+
+const stack = Layer.succeed(
+  Stack,
+  {
+    name: "${stack.name}",
+    stage: "${stack.stage}",
+    bindings: {},
+    resources: {}
+  }
+);
+
+const exportsEffect = tag.asEffect().pipe(
+  Effect.tap(() => Console.log("BARR")),
+  Effect.tapError(() => Console.log("BARR")),
+  Effect.flatMap(func => func.RuntimeContext.exports),
+  Effect.provide(
+    layer.pipe(
+      Layer.provideMerge(stack),
+      Layer.provideMerge(platform),
+      Layer.provideMerge(
+        Layer.succeed(
+          ConfigProvider.ConfigProvider,
+          ConfigProvider.orElse(
+            ConfigProvider.fromUnknown({ ALCHEMY_PHASE: "runtime" }),
+            ConfigProvider.fromUnknown(env),
+          ),
+        ),
+      ),
+      Layer.provideMerge(Layer.succeed(WorkerEnvironment, env)),
+      Layer.provideMerge(
+        Layer.succeed(MinimumLogLevel, env.DEBUG ? "Debug" : "Info"),
+      ),
+    ),
+  ),
+  Effect.scoped,
+);
+
+// TODO(sam): we could kick this off during module init, but any I/O will break deploy
+// let exportsPromise = Effect.runPromise(exportsEffect);
+
+// for now, we delay initializing the worker until the first request
+let exportsPromise;
+
+// don't initialize the workerEffect during module init because Cloudflare does not allow I/O during module init
+// we cache it synchronously (??=) to guarnatee only one initialization ever happens
+const getExports = () => (exportsPromise ??= Effect.runPromise(exportsEffect))
+const getExport = (name) => getExports().then(exports => exports[name]?.make)
+const worker = () => getExports().then(exports => exports.default)
+
+export default Object.fromEntries(ExportedHandlerMethods.map(
+  method => [method, async (...args) => (await worker())[method](...args)])
+);
+
+// export class proxy stubs for Durable Objects and Workflows
+${[
+  ...(hasDoClasses
+    ? [
+        "const DurableObjectBridge = makeDurableObjectBridge(DurableObject, getExport);",
+        ...doClasses.map(
+          (id) => `export class ${id} extends DurableObjectBridge("${id}") {}`,
+        ),
+      ]
+    : []),
+  ...(hasWfClasses
+    ? [
+        "const WorkflowBridgeFn = makeWorkflowBridge(WorkflowEntrypoint, getExport);",
+        ...wfClasses.map(
+          (id) => `export class ${id} extends WorkflowBridgeFn("${id}") {}`,
+        ),
+      ]
+    : []),
+].join("\n")}
+`;
+};

package/src/Cloudflare/Workers/WorkerName.ts

@@ -0,0 +1,10 @@
+import * as Effect from "effect/Effect";
+import { createPhysicalName } from "../../PhysicalName.ts";
+
+export const createWorkerName = (id: string, name: string | undefined) =>
+  name
+    ? Effect.succeed(name)
+    : createPhysicalName({
+        id,
+        maxLength: 54,
+      }).pipe(Effect.map((name) => name.toLowerCase()));

package/src/Cloudflare/Workers/Workflow.ts

@@ -6,7 +6,7 @@ import type { PlatformServices } from "../../Platform.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { effectClass, taggedFunction } from "../../Util/effect.ts";
-import { Account } from "../Account.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import { Worker, WorkerEnvironment, type WorkerServices } from "./Worker.ts";
 
 type WorkflowTypeId = "Cloudflare.Workflow";
@@ -83,8 +83,17 @@ export const sleepUntil = (
 
 /**
  * The services available inside a workflow run body.
+ *
+ * `WorkerEnvironment` is provided to the body at runtime by the workflow
+ * export wrapper (see `make(env)` below), so users can access env bindings
+ * from inside workflow steps via `yield* WorkerEnvironment` — the type must
+ * reflect that or `yield* WorkerEnvironment` fails to type-check inside a
+ * body even though it succeeds at runtime.
  */
-export type WorkflowRunServices = WorkflowEvent | WorkflowStep;
+export type WorkflowRunServices =
+  | WorkflowEvent
+  | WorkflowStep
+  | WorkerEnvironment;
 
 export type WorkflowServices = WorkerServices | PlatformServices;
 
@@ -239,6 +248,36 @@ 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.
+ *
+ * ```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 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;
+ * });
+ * ```
+ *
  * @section Starting and Monitoring Instances
  * @example Creating an instance from a Worker
  * ```typescript
@@ -252,6 +291,70 @@ export class WorkflowScope extends Context.Service<
  * const handle = yield* workflow.get(instanceId);
  * const status = yield* handle.status();
  * ```
+ *
+ * @section Triggering from a Worker
+ * Wire the workflow into HTTP routes so callers can fire instances
+ * and poll for completion.
+ *
+ * @example Workflow start + status routes
+ * ```typescript
+ * // src/worker.ts
+ * const notifier = yield* MyWorkflow;
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     const request = yield* HttpServerRequest;
+ *
+ *     if (request.url.startsWith("/workflow/start/")) {
+ *       const id = request.url.split("/").pop()!;
+ *       const instance = yield* notifier.create({ id });
+ *       return HttpServerResponse.json({ instanceId: instance.id });
+ *     }
+ *
+ *     if (request.url.startsWith("/workflow/status/")) {
+ *       const id = request.url.split("/").pop()!;
+ *       const instance = yield* notifier.get(id);
+ *       return HttpServerResponse.json(yield* instance.status());
+ *     }
+ *
+ *     return HttpServerResponse.text("Not Found", { status: 404 });
+ *   }),
+ * };
+ * ```
+ *
+ * @section Testing Workflows
+ * Workflows run asynchronously, so tests start an instance and
+ * poll until it reaches a terminal status. A simple recipe with
+ * `alchemy/Test/Bun`:
+ *
+ * @example Polling for workflow completion
+ * ```typescript
+ * test(
+ *   "workflow completes",
+ *   Effect.gen(function* () {
+ *     const { url } = yield* stack;
+ *
+ *     const start = yield* HttpClient.post(`${url}/workflow/start/x`);
+ *     const { instanceId } = (yield* start.json) as { instanceId: string };
+ *
+ *     let status: { status: string } | undefined;
+ *     const deadline = Date.now() + 60_000;
+ *     while (Date.now() < deadline) {
+ *       const res = yield* HttpClient.get(
+ *         `${url}/workflow/status/${instanceId}`,
+ *       );
+ *       status = (yield* res.json) as { status: string };
+ *       if (status.status === "complete" || status.status === "errored") {
+ *         break;
+ *       }
+ *       yield* Effect.sleep("2 seconds");
+ *     }
+ *
+ *     expect(status?.status).toBe("complete");
+ *   }),
+ *   { timeout: 120_000 },
+ * );
+ * ```
  */
 export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
   ...args: [] | [name: string, impl: Effect.Effect<WorkflowBody>]
@@ -323,13 +426,14 @@ export const Workflow: WorkflowClass = taggedFunction(WorkflowScope, ((
           yield* worker.export(name, {
             kind: "workflow",
             make: (env: unknown) =>
-              Effect.succeed(body).pipe(
-                Effect.provideContext(services),
-                Effect.provideService(
-                  WorkerEnvironment,
-                  env as Record<string, any>,
+              Effect.succeed(
+                body.pipe(
+                  Effect.provideService(
+                    WorkerEnvironment,
+                    env as Record<string, any>,
+                  ),
                 ),
-              ),
+              ).pipe(Effect.provideContext(services)),
           } satisfies WorkflowExport);
 
           return self;
@@ -370,18 +474,23 @@ export const WorkflowProvider = () =>
   Provider.effect(
     WorkflowResource,
     Effect.gen(function* () {
-      const accountId = yield* Account;
+      const { accountId } = yield* CloudflareEnvironment;
       const putWorkflow = yield* workflows.putWorkflow;
       const deleteWorkflow = yield* workflows.deleteWorkflow;
 
       return WorkflowResource.Provider.of({
         stables: ["workflowId", "accountId"],
-        create: Effect.fnUntraced(function* ({ news }) {
+        reconcile: Effect.fnUntraced(function* ({ news, output }) {
+          const acct = output?.accountId ?? accountId;
           yield* Effect.logInfo(
-            `Cloudflare Workflow create: ${news.workflowName}`,
+            `Cloudflare Workflow reconcile: ${news.workflowName}`,
           );
+          // Cloudflare's `putWorkflow` is a true PUT-as-upsert: identical
+          // payloads converge to the same state and a missing workflow is
+          // created on the spot. There is no separate observe step needed
+          // — the API is naturally reconciler-shaped.
           const result = yield* putWorkflow({
-            accountId,
+            accountId: acct,
             workflowName: news.workflowName,
             className: news.className,
             scriptName: news.scriptName,
@@ -391,25 +500,7 @@ export const WorkflowProvider = () =>
             workflowName: result.name,
             className: result.className,
             scriptName: result.scriptName,
-            accountId,
-          };
-        }),
-        update: Effect.fnUntraced(function* ({ news, output }) {
-          yield* Effect.logInfo(
-            `Cloudflare Workflow update: ${news.workflowName}`,
-          );
-          const result = yield* putWorkflow({
-            accountId: output.accountId,
-            workflowName: news.workflowName,
-            className: news.className,
-            scriptName: news.scriptName,
-          });
-          return {
-            workflowId: result.id,
-            workflowName: result.name,
-            className: result.className,
-            scriptName: result.scriptName,
-            accountId: output.accountId,
+            accountId: acct,
           };
         }),
         delete: Effect.fnUntraced(function* ({ output }) {

package/src/Cloudflare/Workers/index.ts

@@ -1,12 +1,16 @@
 export * from "./Assets.ts";
 export * from "./ConfigProvider.ts";
 export * from "./DurableObjectNamespace.ts";
+export * from "./DurableObjectState.ts";
+export * from "./DurableObjectStorage.ts";
 export * from "./DynamicWorkerLoader.ts";
 export * from "./Fetch.ts";
 export * from "./HttpServer.ts";
 export * from "./InferEnv.ts";
+export * from "./LocalWorkerProvider.ts";
 export * from "./Request.ts";
 export * from "./Rpc.ts";
+export * from "./ScheduledEvents.ts";
 export * from "./WebSocket.ts";
 export * from "./Worker.ts";
 export * from "./Workflow.ts";

package/src/Cloudflare/index.ts

@@ -1,8 +1,18 @@
+export * from "./ApiToken/index.ts";
+export * from "./Artifacts/index.ts";
+export * from "./AiGateway/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 "./KV/index.ts";
 export * from "./Providers.ts";
+export * from "./Queue/index.ts";
 export * from "./R2/index.ts";
-export * from "./StageConfig.ts";
+export * from "./SecretsStore/index.ts";
+export * from "./StateStore/index.ts";
+export * from "./Tunnel/index.ts";
+export * from "./VpcService/index.ts";
 export * from "./Website/index.ts";
 export * from "./Workers/index.ts";

package/src/Construct.ts

@@ -12,8 +12,8 @@ import * as Namespace from "./Namespace.ts";
  * @section Creating Constructs
  * @example Simple Reusable Construct
  * ```typescript
- * import * as Construct from "alchemy-effect/Construct";
- * import { Bucket } from "alchemy-effect/AWS/S3";
+ * import * as Construct from "alchemy/Construct";
+ * import { Bucket } from "alchemy/AWS/S3";
  *
  * export const Logs = Construct.fn(function* (
  *   id: string,

package/src/Deploy.ts

@@ -0,0 +1,27 @@
+import * as Effect from "effect/Effect";
+import { AlchemyContext } from "./AlchemyContext.ts";
+import * as Apply from "./Apply.ts";
+import type { Input } from "./Input.ts";
+import * as Plan from "./Plan.ts";
+import { evalStack, type CompiledStack, type StackEffect } from "./Stack.ts";
+import { Stage } from "./Stage.ts";
+
+export const deploy = <A>({
+  stack,
+  stage,
+  dev,
+}: {
+  stack: StackEffect<CompiledStack<A>, Stage | AlchemyContext>;
+  stage: string;
+  dev?: boolean;
+}) =>
+  evalStack(
+    stack,
+    (stack) =>
+      Effect.gen(function* () {
+        const plan = yield* Plan.make(stack);
+        const output = yield* Apply.apply(plan);
+        return output as Input.Resolve<A>;
+      }),
+    { stage, dev },
+  );

package/src/Destroy.ts

@@ -1,16 +1,30 @@
-import * as Effect from "effect/Effect";
-import { apply } from "./Apply.ts";
-import { provideFreshArtifactStore } from "./Artifacts.ts";
+import { Effect } from "effect";
+import type { AlchemyContext } from "./AlchemyContext.ts";
+import * as Apply from "./Apply.ts";
 import * as Plan from "./Plan.ts";
-import { Stack } from "./Stack.ts";
+import type { CompiledStack, StackEffect } from "./Stack.ts";
+import { evalStack } from "./Stack.ts";
+import type { Stage } from "./Stage.ts";
 
-export const destroy = () =>
-  Stack.use((stack) =>
-    Plan.make({
-      name: stack.name,
-      stage: stack.stage,
-      resources: {},
-      bindings: {},
-      output: {},
-    }).pipe(Effect.flatMap(apply), provideFreshArtifactStore),
+export const destroy = ({
+  stack,
+  stage,
+  dev,
+}: {
+  stack: StackEffect<CompiledStack, Stage | AlchemyContext>;
+  stage: string;
+  dev?: boolean;
+}) =>
+  evalStack(
+    stack,
+    (stack) =>
+      Plan.make({
+        ...stack,
+        // zero these out (destroy will treat all as orphans)
+        // TODO(sam): probably better to have Plan.destroy and Plan.update
+        resources: {},
+        bindings: {},
+        output: {},
+      }).pipe(Effect.flatMap(Apply.apply)),
+    { stage, dev },
   );

package/src/Drizzle/Postgres.ts

@@ -0,0 +1,78 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import type { AnyRelations, EmptyRelations } from "drizzle-orm";
+import type { EffectPgDatabase } from "drizzle-orm/effect-postgres";
+import * as PgDrizzle from "drizzle-orm/effect-postgres";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { ExecutionContext } from "../ExecutionContext.ts";
+import { proxyChain } from "../Util/proxy-chain.ts";
+
+/**
+ * Open a Drizzle/Postgres database from a connection URL using the
+ * `drizzle-orm/effect-postgres` integration.
+ *
+ * Returns a chainable Proxy over `EffectPgDatabase` (via `proxyChain`) —
+ * every property read records a step, every call records args, and the
+ * chain is replayed against the resolved drizzle db when it's finally
+ * yielded as an Effect. Callers don't need a separate `yield* conn` step:
+ *
+ * ```typescript
+ * const db = yield* Drizzle.postgres(hd.connectionString);
+ *
+ * fetch: Effect.gen(function* () {
+ *   const rows = yield* db.select().from(users);
+ * });
+ * ```
+ *
+ * Behind the scenes the actual connect work is wrapped in `Effect.cached`,
+ * so the pool is built at most once per JS realm. Yielding the
+ * connection string is also deferred until first query, so deploy /
+ * plan-time invocations (where `WorkerEnvironment` isn't provided)
+ * never trigger a real connection attempt.
+ *
+ * The PgClient pool is built against an isolated, never-closing `Scope`
+ * so it outlives whatever scope this helper is yielded under. In a
+ * Cloudflare Worker the surrounding `Cloudflare.Worker` runs init
+ * inside `Effect.scoped`, which closes after returning the exports
+ * object — without an isolated scope, the pool's `end` finalizer
+ * would fire there and every subsequent request would see "Cannot
+ * use a pool after end".
+ *
+ * @binding
+ */
+
+export const postgres = <
+  TRelations extends AnyRelations = EmptyRelations,
+  E = never,
+  R = never,
+>(
+  connectionString: Effect.Effect<Redacted.Redacted<string>, E, R>,
+  config?: PgDrizzle.EffectDrizzlePgConfig<TRelations>,
+) =>
+  Effect.sync(function () {
+    const symbol = Symbol();
+
+    return proxyChain<
+      EffectPgDatabase<TRelations> & {
+        $client: PgClient.PgClient;
+      }
+    >(
+      Effect.gen(function* () {
+        const ctx = yield* ExecutionContext;
+        return yield* (ctx.cache[symbol] ??= yield* Effect.gen(function* () {
+          const pgCtx = yield* Layer.buildWithScope(
+            PgClient.layer({ url: yield* connectionString }),
+            ctx.scope,
+          );
+          return yield* PgDrizzle.makeWithDefaults(config).pipe(
+            Effect.provideContext(pgCtx),
+          );
+        }).pipe(Effect.cached));
+      }) as Effect.Effect<
+        EffectPgDatabase<TRelations> & {
+          $client: PgClient.PgClient;
+        }
+      >,
+    );
+  });