alchemy 2.0.0-beta.22 → 2.0.0-beta.24

package/src/Build/Command.ts

@@ -143,12 +143,19 @@ export const CommandProvider = () =>
           if (!output) {
             return undefined;
           }
+          // Recompute the output path against the *current* cwd. State
+          // may have been written by a different machine (e.g. CI) and
+          // the absolute path baked into `output.outdir` won't exist
+          // locally. As long as the path resolved against this
+          // machine's cwd is present, return the refreshed output so
+          // downstream consumers (e.g. `Cloudflare.Worker` assets)
+          // don't try to read a stale, foreign-machine path.
           const outputPath = getOutputPath(olds);
           const exists = yield* fs.exists(outputPath);
           if (!exists) {
             return undefined;
           }
-          return output;
+          return { ...output, outdir: outputPath };
         }),
         create: Effect.fnUntraced(function* ({ news, session }) {
           const hash = yield* hashDirectory(news);

package/src/Bundle/Bundle.ts

@@ -1,8 +1,7 @@
-import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Path from "effect/Path";
 import * as Queue from "effect/Queue";
-import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import assert from "node:assert";
 import * as rolldown from "rolldown";
@@ -45,10 +44,32 @@ export interface BundleFile {
   readonly hash: string;
 }
 
-export class BundleError extends Data.TaggedError("BundleError")<{
-  readonly message: string;
-  readonly cause?: unknown;
-}> {}
+export class BundleError extends Schema.TaggedErrorClass<BundleError>()(
+  "BundleError",
+  {
+    message: Schema.String,
+    cause: Schema.optional(Schema.DefectWithStack),
+  },
+) {}
+
+export type BundleWatchEvent =
+  | BundleWatchEvent.Start
+  | BundleWatchEvent.Success
+  | BundleWatchEvent.Error;
+
+export declare namespace BundleWatchEvent {
+  interface Start {
+    readonly _tag: "Start";
+  }
+  interface Success {
+    readonly _tag: "Success";
+    readonly output: BundleOutput;
+  }
+  interface Error {
+    readonly _tag: "Error";
+    readonly error: BundleError;
+  }
+}
 
 /**
  * Build a bundle using rolldown from the given input options and output options.
@@ -93,8 +114,15 @@ export const watch = (
   inputOptions: rolldown.InputOptions,
   outputOptions?: rolldown.OutputOptions,
   extra?: BundleExtraOptions,
-): Stream.Stream<Result.Result<BundleOutput, BundleError>> =>
-  Stream.callback<Result.Result<rolldown.OutputBundle, BundleError>>((queue) =>
+): Stream.Stream<BundleWatchEvent> =>
+  Stream.callback<
+    | BundleWatchEvent.Start
+    | BundleWatchEvent.Error
+    | {
+        readonly _tag: "Success";
+        readonly output: rolldown.OutputBundle;
+      }
+  >((queue) =>
     Effect.acquireRelease(
       Effect.sync(() => {
         const watcher = rolldown.watch({
@@ -104,8 +132,16 @@ export const watch = (
             // The watcher event listener does not receive the bundle output, so we grab it using a plugin.
             {
               name: "alchemy:watch-bundle",
+              watchChange() {
+                Queue.offerUnsafe(queue, {
+                  _tag: "Start",
+                });
+              },
               generateBundle(_outputOptions, bundle) {
-                Queue.offerUnsafe(queue, Result.succeed(bundle));
+                Queue.offerUnsafe(queue, {
+                  _tag: "Success",
+                  output: bundle,
+                });
               },
             },
           ],
@@ -113,10 +149,10 @@ export const watch = (
         });
         watcher.on("event", (event) => {
           if (event.code === "ERROR") {
-            Queue.offerUnsafe(
-              queue,
-              Result.fail(bundleErrorFromUnknown(event.error)),
-            );
+            Queue.offerUnsafe(queue, {
+              _tag: "Error",
+              error: bundleErrorFromUnknown(event.error),
+            });
           } else if (event.code === "BUNDLE_END") {
             // This must be called to avoid resource leaks.
             event.result.close().catch(() => {});
@@ -127,23 +163,27 @@ export const watch = (
       (watcher) => Effect.promise(() => watcher.close()),
     ),
   ).pipe(
-    Stream.mapEffect((result) =>
+    Stream.mapEffect((event) =>
       Effect.gen(function* () {
-        if (result._tag === "Failure") {
-          return Result.fail(result.failure);
+        if (event._tag !== "Success") {
+          return event;
         }
-        return yield* bundleOutputFromRolldownOutputBundle(result.success).pipe(
-          Effect.map(Result.succeed),
-          Effect.catch((error) => Effect.succeed(Result.fail(error))),
+        return yield* bundleOutputFromRolldownOutputBundle(event.output).pipe(
+          Effect.map(
+            (output): BundleWatchEvent.Success => ({
+              _tag: "Success",
+              output,
+            }),
+          ),
+          Effect.catch((error) =>
+            Effect.succeed<BundleWatchEvent.Error>({
+              _tag: "Error",
+              error: bundleErrorFromUnknown(error),
+            }),
+          ),
         );
       }),
     ),
-    Stream.changesWith((left, right) => {
-      if (left._tag === "Success" && right._tag === "Success") {
-        return left.success.hash === right.success.hash;
-      }
-      return false;
-    }),
   );
 
 const ENTRY_MODULE_ID = "virtual:alchemy-entry";

package/src/Cloudflare/Container/Container.ts

@@ -118,8 +118,10 @@ export type Container = {
  * @section Configuration
  * The props object accepts `main` (entrypoint file), `instanceType`
  * (compute size), `runtime` (`"bun"` or `"node"`), and
- * `observability` settings. Use `Stack.useSync` to vary config by
- * stage.
+ * `observability` settings. Use `Stack.useSync` to read the
+ * surrounding stack at declaration time and pick a beefier
+ * `instanceType` in prod while keeping the cheap `dev` instance for
+ * preview environments.
  *
  * @example Stage-dependent configuration
  * ```typescript
@@ -133,6 +135,57 @@ export type Container = {
  * ) {}
  * ```
  *
+ * @section Stack-level wiring
+ * The `.make()` `export default` is the side-effect that registers
+ * the container's runtime. It must be reachable from your
+ * `alchemy.run.ts` so the bundler emits the runtime entrypoint.
+ * Provide it on the Stack's generator with `Effect.provide`.
+ *
+ * @example Wiring SandboxLive into the Stack
+ * ```typescript
+ * // alchemy.run.ts
+ * import SandboxLive from "./src/Sandbox.runtime.ts";
+ *
+ * export default Alchemy.Stack(
+ *   "MyApp",
+ *   { providers: Cloudflare.providers(), state: Cloudflare.state() },
+ *   Effect.gen(function* () {
+ *     const worker = yield* Worker;
+ *     return { url: worker.url };
+ *   }).pipe(Effect.provide(SandboxLive)),
+ * );
+ * ```
+ *
+ * @section Calling from a Durable Object
+ * Use `Cloudflare.Container.bind(Sandbox)` in the **outer** init
+ * phase of a Durable Object — only the class is imported, so the
+ * DO bundle stays tiny. Then `Cloudflare.start(sandbox)` in the
+ * **inner** per-instance phase ensures the container is running
+ * and gives you a typed handle that exposes every method declared
+ * on the container's shape **plus** a `getTcpPort` helper.
+ *
+ * @example Binding and starting a container from a DO
+ * ```typescript
+ * export default class Agent extends Cloudflare.DurableObjectNamespace<Agent>()(
+ *   "Agents",
+ *   Effect.gen(function* () {
+ *     // OUTER (init): only the class is referenced — the runtime
+ *     // implementation in `Sandbox.runtime.ts` is tree-shaken out
+ *     // of this DO's bundle.
+ *     const sandbox = yield* Cloudflare.Container.bind(Sandbox);
+ *
+ *     return Effect.gen(function* () {
+ *       // INNER (per-instance): start the container and expose RPC.
+ *       const container = yield* Cloudflare.start(sandbox);
+ *
+ *       return {
+ *         exec: (cmd: string) => container.exec(cmd),
+ *       };
+ *     });
+ *   }),
+ * ) {}
+ * ```
+ *
  * @section Starting from a Durable Object
  * Use `Cloudflare.Container.bind` in the outer init phase to bind
  * the container class, then `Cloudflare.start` in the inner

package/src/Cloudflare/D1/D1Export.ts

@@ -35,11 +35,7 @@ export const exportD1Database = (
 
     const poll = (
       currentBookmark?: string,
-    ): Effect.Effect<
-      ExportD1DatabaseResult,
-      d1.ExportDatabaseError,
-      never
-    > =>
+    ): Effect.Effect<ExportD1DatabaseResult, d1.ExportDatabaseError, never> =>
       Effect.gen(function* () {
         const data = yield* exportDb({
           accountId: options.accountId,

package/src/Cloudflare/D1/D1SqlFile.ts

@@ -29,9 +29,7 @@ export const listSqlFiles = (directory: string) =>
         return a.localeCompare(b);
       });
 
-    return yield* Effect.all(
-      sqlFiles.map((id) => readSqlFile(directory, id)),
-    );
+    return yield* Effect.all(sqlFiles.map((id) => readSqlFile(directory, id)));
   });
 
 /**

package/src/Cloudflare/Local/Sidecar.ts

@@ -0,0 +1,44 @@
+import {
+  ServeError,
+  type ServeResult,
+} from "@distilled.cloud/cloudflare-runtime/Server";
+import * as Worker from "@distilled.cloud/cloudflare-runtime/Worker";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { BundleError } from "../../Bundle/Bundle.ts";
+import * as RpcClient from "../../Sidecar/RpcClient.ts";
+import { defineSchema } from "../../Sidecar/RpcHandler.ts";
+import type { WorkerBinding } from "../Workers/Worker.ts";
+import type { WorkerBundleOptions } from "../Workers/WorkerBundle.ts";
+
+export interface ServeOptions extends WorkerBundleOptions {
+  name: string;
+  bindings: WorkerBinding[];
+  durableObjectNamespaces: Worker.DurableObjectNamespace[];
+}
+
+export const SidecarSchema = defineSchema<Sidecar["Service"]>({
+  serve: {
+    success: Schema.Struct({
+      name: Schema.String,
+      address: Schema.String,
+    }),
+    error: Schema.Union([ServeError, BundleError]),
+  },
+  stop: { success: Schema.Void, error: Schema.Never },
+});
+
+export class Sidecar extends RpcClient.RpcClientService<
+  Sidecar,
+  {
+    readonly serve: (
+      options: ServeOptions,
+    ) => Effect.Effect<ServeResult, ServeError | BundleError>;
+    readonly stop: (name: string) => Effect.Effect<void>;
+  }
+>()("Sidecar") {}
+
+export const SidecarLive = RpcClient.layer(Sidecar, {
+  main: import.meta.resolve("./SidecarServer.ts", import.meta.url),
+  schema: SidecarSchema,
+});

package/src/Cloudflare/Local/SidecarHandlers.ts

@@ -0,0 +1,182 @@
+import * as Server from "@distilled.cloud/cloudflare-runtime/Server";
+import type { WorkerModule } from "@distilled.cloud/cloudflare-runtime/WorkerModule";
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import * as Hash from "effect/Hash";
+import * as Layer from "effect/Layer";
+import * as Result from "effect/Result";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import * as Bundle from "../../Bundle/Bundle.ts";
+import { WorkerBundle } from "../Workers/WorkerBundle.ts";
+import { Sidecar, type ServeOptions } from "./Sidecar.ts";
+
+export const SidecarHandlers = Layer.effect(
+  Sidecar,
+  Effect.gen(function* () {
+    const bundle = yield* WorkerBundle;
+    const server = yield* Server.Server;
+
+    const rootScope = yield* Effect.scope;
+    const serverScopes = new Map<string, Scope.Closeable>();
+
+    const serveScoped = Effect.fnUntraced(function* (
+      worker: ServeOptions,
+      modules: WorkerModule[],
+    ) {
+      const scope = yield* Effect.flatMap(Effect.scope, Scope.fork);
+      const result = yield* server
+        .serve({
+          name: worker.id.toLowerCase(),
+          compatibilityDate: worker.compatibility.date,
+          compatibilityFlags: worker.compatibility.flags,
+          bindings: worker.bindings,
+          durableObjectNamespaces: worker.durableObjectNamespaces,
+          modules,
+        })
+        .pipe(Scope.provide(scope));
+      const previous = serverScopes.get(worker.name);
+      if (previous) {
+        yield* Effect.forkDetach(Scope.close(previous, Exit.void));
+      }
+      serverScopes.set(worker.name, scope);
+      return result;
+    });
+
+    const watchers = new Map<
+      string,
+      {
+        hash: number;
+        fiber: Fiber.Fiber<
+          Server.ServeResult,
+          Server.ServeError | Bundle.BundleError
+        >;
+        scope: Scope.Closeable;
+      }
+    >();
+
+    const serveFiber = Effect.fnUntraced(function* (worker: ServeOptions) {
+      const result = yield* Deferred.make<
+        Server.ServeResult,
+        Server.ServeError | Bundle.BundleError
+      >();
+      let start = Date.now();
+      yield* bundle.watch(worker).pipe(
+        Stream.mapEffect((event) =>
+          event._tag === "Error" && !Deferred.isDoneUnsafe(result)
+            ? Effect.fail(event.error)
+            : Effect.succeed(event),
+        ),
+        Stream.tap((event) => {
+          if (event._tag === "Start") {
+            start = Date.now();
+            if (Deferred.isDoneUnsafe(result)) {
+              return Effect.log(`[${worker.id}] Rebuilding`);
+            }
+          } else if (event._tag === "Error") {
+            return Effect.logError(`[${worker.id}] Bundle error`, event.error);
+          }
+          return Effect.void;
+        }),
+        Stream.filterMap((event) =>
+          event._tag === "Success"
+            ? Result.succeed(event.output)
+            : Result.failVoid,
+        ),
+        Stream.map(bundleOutputToWorkerModules),
+        Stream.mapEffect((modules) =>
+          serveScoped(worker, modules).pipe(
+            Effect.exit,
+            Effect.tap((exit) => {
+              const isDone = Deferred.isDoneUnsafe(result);
+              if (exit._tag === "Success") {
+                return Effect.log(
+                  `[${worker.id}] ${isDone ? "Updated" : "Started"} in ${Math.round(Date.now() - start)}ms`,
+                );
+              } else if (isDone) {
+                return Effect.logError(
+                  `[${worker.id}] Error`,
+                  Cause.squash(exit.cause),
+                );
+              }
+              return Effect.void;
+            }),
+            Effect.tap((exit) => Deferred.complete(result, exit)),
+          ),
+        ),
+        Stream.onExit((exit) =>
+          exit._tag === "Failure" && !Deferred.isDoneUnsafe(result)
+            ? Deferred.failCause(result, exit.cause)
+            : Effect.void,
+        ),
+        Stream.runDrain,
+        Effect.forkScoped,
+      );
+      return yield* Deferred.await(result);
+    });
+
+    return Sidecar.of({
+      serve: Effect.fn(function* (worker: ServeOptions) {
+        const hash = Hash.structure(worker);
+        const existing = watchers.get(worker.name);
+        if (existing) {
+          if (existing.hash === hash) {
+            yield* Effect.log(
+              `[${worker.id}] No changes, using existing watcher`,
+            );
+            return yield* Fiber.join(existing.fiber);
+          }
+          yield* Effect.log(
+            `[${worker.id}] Changes detected, interrupting existing watcher`,
+          );
+          yield* Fiber.interrupt(existing.fiber);
+          yield* Scope.close(existing.scope, Exit.void);
+          watchers.delete(worker.name);
+        }
+        const scope = yield* Scope.fork(rootScope);
+        const fiber = yield* serveFiber(worker).pipe(
+          Effect.forkDetach,
+          Scope.provide(scope),
+        );
+        watchers.set(worker.name, { hash, fiber, scope });
+        return yield* Fiber.join(fiber).pipe(
+          Effect.onExit((exit) =>
+            Effect.sync(() => {
+              if (exit._tag === "Failure") {
+                watchers.delete(worker.name);
+              }
+            }),
+          ),
+        );
+      }),
+      stop: Effect.fn(function* (name: string) {
+        const watcher = watchers.get(name);
+        if (watcher) {
+          yield* Fiber.interrupt(watcher.fiber);
+          yield* Scope.close(watcher.scope, Exit.void);
+          watchers.delete(name);
+        }
+      }),
+    });
+  }),
+);
+
+function bundleOutputToWorkerModules(
+  bundle: Bundle.BundleOutput,
+): WorkerModule[] {
+  const modules: WorkerModule[] = [];
+  for (const file of bundle.files) {
+    if (file.path.endsWith(".map") || file.content instanceof Uint8Array) {
+      continue;
+    }
+    modules.push({
+      name: file.path,
+      type: "ESModule",
+      content: file.content,
+    });
+  }
+  return modules;
+}

package/src/Cloudflare/Local/SidecarServer.ts

@@ -0,0 +1,57 @@
+import * as RuntimeServices from "@distilled.cloud/cloudflare-runtime/RuntimeServices";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import * as AlchemyContext from "../../AlchemyContext.ts";
+import { AuthProviders } from "../../Auth/AuthProvider.ts";
+import * as RpcServer from "../../Sidecar/RpcServer.ts";
+import {
+  httpServer,
+  PlatformServices,
+  runMain,
+} from "../../Util/PlatformServices.ts";
+import { CloudflareAuth } from "../Auth/AuthProvider.ts";
+import * as CloudflareEnvironment from "../CloudflareEnvironment.ts";
+import * as Credentials from "../Credentials.ts";
+import { Sidecar, SidecarSchema } from "./Sidecar.ts";
+import { SidecarHandlers } from "./SidecarHandlers.ts";
+
+const apiServices = Layer.merge(
+  Credentials.fromAuthProvider(),
+  CloudflareEnvironment.fromProfile(),
+).pipe(
+  Layer.provide(CloudflareAuth),
+  Layer.provide(Layer.succeed(AuthProviders, {})),
+);
+
+const runtimeServices = SidecarHandlers.pipe(
+  Layer.provide(
+    Layer.unwrap(
+      Effect.gen(function* () {
+        const { accountId } =
+          yield* CloudflareEnvironment.CloudflareEnvironment;
+        const { dotAlchemy } = yield* AlchemyContext.AlchemyContext;
+        const path = yield* Path.Path;
+        return RuntimeServices.layer({
+          accountId,
+          storage: path.join(dotAlchemy, "local"),
+        });
+      }),
+    ),
+  ),
+  Layer.provide(
+    Layer.mergeAll(apiServices, FetchHttpClient.layer, httpServer()),
+  ),
+);
+
+const services = Layer.provideMerge(
+  Layer.provideMerge(runtimeServices, RpcServer.layerServices(import.meta.url)),
+  PlatformServices,
+);
+
+RpcServer.makeRpcServer(Sidecar.asEffect(), SidecarSchema).pipe(
+  Effect.provide(services),
+  Effect.scoped,
+  runMain,
+);

package/src/Cloudflare/Queue/Queue.ts

@@ -49,12 +49,42 @@ export type Queue = Resource<
  * ```
  *
  * @section Binding to a Worker
+ * In an Effect-style Worker, use `Cloudflare.QueueBinding.bind` in
+ * the init phase and provide `Cloudflare.QueueBindingLive` in the
+ * runtime layer. The returned `QueueSender` exposes `send` and
+ * `sendBatch`.
+ *
  * @example Sending messages from a Worker
  * ```typescript
- * // In your Worker definition, add the queue to bindings:
- * const Worker = Cloudflare.Worker("Worker", {
- *   bindings: { MY_QUEUE: queue },
- * });
+ * import * as Cloudflare from "alchemy/Cloudflare";
+ * import * as Effect from "effect/Effect";
+ * import { HttpServerRequest } from "effect/unstable/http/HttpServerRequest";
+ * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
+ *
+ * export const Queue = Cloudflare.Queue("Queue");
+ *
+ * export default Cloudflare.Worker(
+ *   "Worker",
+ *   { main: import.meta.path },
+ *   Effect.gen(function* () {
+ *     const queue = yield* Cloudflare.QueueBinding.bind(Queue);
+ *
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         if (request.url === "/queue/send" && request.method === "POST") {
+ *           const text = yield* request.text;
+ *           yield* queue.send({ text, sentAt: Date.now() }).pipe(Effect.orDie);
+ *           return yield* HttpServerResponse.json(
+ *             { sent: { text } },
+ *             { status: 202 },
+ *           );
+ *         }
+ *         return HttpServerResponse.text("Not Found", { status: 404 });
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.QueueBindingLive)),
+ * );
  * ```
  */
 export const Queue = Resource<Queue>("Cloudflare.Queue")({

package/src/Cloudflare/Queue/QueueBinding.ts

@@ -26,6 +26,39 @@ export class QueueSendError extends Data.TaggedError("QueueSendError")<{
   cause?: unknown;
 }> {}
 
+/**
+ * Binding service that turns a {@link Queue} resource into a typed
+ * {@link QueueSender} you can call from a Worker's runtime Effect.
+ *
+ * @section Sending Messages
+ * Bind the queue in the Worker's init phase, then use `send` for
+ * single messages or `sendBatch` for many messages in one call.
+ * Messages can be any JSON-serializable value.
+ *
+ * @example Producer route
+ * ```typescript
+ * const queue = yield* Cloudflare.QueueBinding.bind(Queue);
+ *
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     yield* queue.send({ text: "hi", sentAt: Date.now() });
+ *     return HttpServerResponse.empty({ status: 202 });
+ *   }),
+ * };
+ * ```
+ *
+ * @example Sending a batch
+ * ```typescript
+ * yield* queue.sendBatch([
+ *   { body: { event: "click", id: 1 } },
+ *   { body: { event: "click", id: 2 } },
+ *   { body: "raw text", contentType: "text" },
+ * ]);
+ * ```
+ *
+ * Provide {@link QueueBindingLive} in the worker's runtime layer to
+ * resolve the underlying Cloudflare queue at request time.
+ */
 export class QueueBinding extends Binding.Service<
   QueueBinding,
   (queue: Queue) => Effect.Effect<QueueSender>