alchemy 2.0.0-beta.50 → 2.0.0-beta.52

package/src/Cloudflare/Website/StaticSite.ts

@@ -1,11 +1,17 @@
+import * as Output from "alchemy/Output";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
+import { AlchemyContext } from "../../AlchemyContext.ts";
 import { Command, type CommandProps } from "../../Build/Command.ts";
+import { DevServer } from "../../Build/DevServer.ts";
 import type { InputProps } from "../../Input.ts";
 import * as Namespace from "../../Namespace.ts";
+import { effectClass } from "../../Util/effect.ts";
+import type { Providers } from "../Providers.ts";
 import type { AssetsConfig } from "../Workers/Assets.ts";
 import {
   Worker,
+  type NormalizedBindings,
   type WorkerAssetsConfig,
   type WorkerBindingProps,
   type WorkerProps,
@@ -19,13 +25,48 @@ export interface StaticSiteProps<Bindings extends WorkerBindingProps = {}>
    * Optional configuration for static asset routing behavior.
    * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
    */
-  assetsConfig?: AssetsConfig;
+
+  assets?: AssetsConfig;
+  /**
+   * Local dev configuration. When `alchemy dev` runs, the build command is
+   * skipped and `command` is spawned as a long-lived child process tied to
+   * the stack's scope. Alchemy does not proxy or interpret the process —
+   * the dev server's own URL (e.g. `http://localhost:5173`) is what you
+   * open in the browser.
+   *
+   * @example
+   * ```typescript
+   * Cloudflare.StaticSite("App", {
+   *   command: "npm run build",
+   *   outdir: "dist",
+   *   main: "./src/worker.ts",
+   *   dev: { command: "npm run dev" },
+   * });
+   * ```
+   */
   dev?: {
+    /**
+     * Shell command to run as the local dev server (e.g. `npm run dev`).
+     */
     command: string;
+    /**
+     * Working directory for {@link command}. Defaults to {@link CommandProps.cwd}
+     * (the build command's `cwd`), or `process.cwd()` if neither is set.
+     */
+    cwd?: string;
+    /**
+     * Override for the `url` output if alchemy fails to detect it from the stdout of the dev command
+     */
+    url?: string;
   };
 }
 
-export type StaticSite = ReturnType<typeof StaticSite>;
+type StaticSiteWorker<Bindings extends WorkerBindingProps> = Worker<{
+  [binding in keyof NormalizedBindings<
+    Bindings,
+    WorkerAssetsConfig
+  >]: NormalizedBindings<Bindings, WorkerAssetsConfig>[binding];
+}>;
 
 /**
  * A Cloudflare Worker that serves static assets built by a shell command.
@@ -68,7 +109,7 @@ export type StaticSite = ReturnType<typeof StaticSite>;
  * ```
  *
  * @section Asset Configuration
- * Use `assetsConfig` to control how Cloudflare handles routing for
+ * Use `assets` to control how Cloudflare handles routing for
  * your static files — HTML handling, not-found behavior, etc.
  *
  * @example SPA-style routing
@@ -77,7 +118,7 @@ export type StaticSite = ReturnType<typeof StaticSite>;
  *   command: "npm run build",
  *   outdir: "dist",
  *   main: "./src/worker.ts",
- *   assetsConfig: {
+ *   assets: {
  *     htmlHandling: "auto-trailing-slash",
  *     notFoundHandling: "single-page-application",
  *   },
@@ -113,54 +154,126 @@ export type StaticSite = ReturnType<typeof StaticSite>;
  *   },
  * });
  * ```
+ *
+ * @section Class Form
+ * Calling `StaticSite` with no arguments returns a constructor you can
+ * `extend` to declare the Worker as a named class. The class is both
+ * an `Effect` you can `yield*` to deploy and a type you can reference
+ * elsewhere — useful when other resources need to bind to this Worker.
+ *
+ * @example Declaring a Worker class
+ * ```typescript
+ * class Blog extends Cloudflare.StaticSite<Blog>()("Blog", {
+ *   command: "hugo --minify",
+ *   outdir: "public",
+ *   main: "./src/worker.ts",
+ * }) {}
+ *
+ * const site = yield* Blog;
+ * ```
  */
-export const StaticSite = <
+export const StaticSite: {
+  <Self>(): {
+    <const Bindings extends WorkerBindingProps = {}, Req = never>(
+      id: string,
+      propsEff:
+        | InputProps<StaticSiteProps<Bindings>, "dev">
+        | Effect.Effect<
+            InputProps<StaticSiteProps<Bindings>, "dev">,
+            never,
+            Req
+          >,
+    ): Effect.Effect<Self, never, Req | Providers> & {
+      new (): StaticSiteWorker<Bindings>;
+    };
+  };
+  <const Bindings extends WorkerBindingProps = {}, Req = never>(
+    id: string,
+    propsEff:
+      | InputProps<StaticSiteProps<Bindings>, "dev">
+      | Effect.Effect<InputProps<StaticSiteProps<Bindings>, "dev">, never, Req>,
+  ): Effect.Effect<StaticSiteWorker<Bindings>, never, Req | Providers>;
+} = ((id?: any, propsEff?: any) =>
+  id === undefined
+    ? (id: string, propsEff: any) => effectClass(makeStaticSite(id, propsEff))
+    : makeStaticSite(id, propsEff)) as any;
+
+const makeStaticSite = <
   const Bindings extends WorkerBindingProps = {},
   Req = never,
 >(
   id: string,
   propsEff:
-    | InputProps<StaticSiteProps<Bindings>>
-    | Effect.Effect<InputProps<StaticSiteProps<Bindings>>, never, Req>,
+    | InputProps<StaticSiteProps<Bindings>, "dev">
+    | Effect.Effect<InputProps<StaticSiteProps<Bindings>, "dev">, never, Req>,
 ) =>
   Effect.gen(function* () {
     const props = Effect.isEffect(propsEff)
       ? propsEff
       : Effect.succeed(propsEff);
+    const { dev: isDevPhase } = yield* AlchemyContext;
 
-    // TODO(sam): local dev/hmr support?
-    const build = yield* Command(
-      "Build",
-      Effect.map(props, (props) => ({
-        command: props.command,
-        cwd: props.cwd,
-        memo: props.memo,
-        outdir: props.outdir,
-        env: props.env
-          ? Object.fromEntries(
-              Object.entries(props.env).flatMap(([k, v]) => {
-                if (v === undefined) return [];
-                if (typeof v === "string" || Redacted.isRedacted(v))
-                  return [[k, v]];
-                return [[k, JSON.stringify(v)]];
-              }),
-            )
-          : undefined,
-      })),
-    );
+    return yield* Effect.gen(function* () {
+      const resolved = yield* props;
+      const useDevServer = isDevPhase && resolved.dev !== undefined;
 
-    return yield* Worker<Bindings, WorkerAssetsConfig, Req>(
-      "Worker",
-      Effect.map(props, (props) => ({
-        ...props,
-        assets: {
-          path: build.outdir,
-          hash: build.hash,
-          config: props.assetsConfig,
-        },
-        // Omit the dev command from WorkerProps since it's different from WorkerProps["dev"].
-        // TODO: we'll need to update this when we add local dev support for StaticSite.
-        dev: undefined,
-      })),
-    );
+      // In dev mode with a dev.command, declare a DevCommand resource so
+      // the sidecar owns the process lifecycle (survives user-code HMR),
+      // skip the build, and tell Worker not to start a local instance.
+      let devUrl = yield* useDevServer
+        ? DevServer("Dev", {
+            command: resolved.dev!.command,
+            cwd:
+              resolved.dev!.cwd ??
+              (typeof resolved.cwd === "string" ? resolved.cwd : undefined),
+          }).pipe(
+            Effect.map((d) =>
+              Output.map(d.url, (url) => url ?? resolved.dev?.url ?? false),
+            ),
+          )
+        : Effect.succeed(false as const);
+
+      const build = useDevServer
+        ? undefined
+        : yield* Command("Build", {
+            command: resolved.command,
+            cwd: resolved.cwd,
+            memo: resolved.memo,
+            outdir: resolved.outdir,
+            env: resolved.env
+              ? Object.fromEntries(
+                  Object.entries(resolved.env).flatMap(([k, v]) => {
+                    if (v === undefined) return [];
+                    if (typeof v === "string" || Redacted.isRedacted(v))
+                      return [[k, v]];
+                    return [[k, JSON.stringify(v)]];
+                  }),
+                )
+              : undefined,
+          });
+
+      // Pure-static sites don't need a custom Worker entrypoint —
+      // delegate every request straight to the ASSETS binding. Only
+      // injected when the user provided neither `main` nor `script`.
+      const fallbackScript =
+        resolved.main == null && resolved.script == null
+          ? `export default { fetch: (request, env) => env.ASSETS.fetch(request) };`
+          : undefined;
+
+      return yield* Worker<Bindings, WorkerAssetsConfig, Req>("Worker", {
+        ...resolved,
+        assets: build
+          ? {
+              directory: build.outdir,
+              hash: build.hash,
+              ...resolved.assets,
+            }
+          : undefined,
+        // Opt out of the local Worker in dev when the external DevCommand
+        // is serving the content. The Worker resource still exists in
+        // state with a stub Attributes shape.
+        dev: useDevServer ? devUrl : undefined,
+        script: fallbackScript ?? resolved.script,
+      });
+    });
   }).pipe(Namespace.push(id));

package/src/Cloudflare/Website/Vite.ts

@@ -1,16 +1,19 @@
 import * as Effect from "effect/Effect";
 import type { MemoOptions } from "../../Build/Memo.ts";
 import type { InputProps } from "../../Input.ts";
+import { effectClass } from "../../Util/effect.ts";
+import type { Providers } from "../Providers.ts";
+import type { AssetsConfig } from "../Workers/Assets.ts";
 import {
   Worker,
+  type NormalizedBindings,
   type WorkerAssetsConfig,
   type WorkerBindingProps,
   type WorkerProps,
 } from "../Workers/Worker.ts";
-
 export interface ViteProps<
   Bindings extends WorkerBindingProps = {},
-> extends Omit<WorkerProps<Bindings>, "vite" | "main"> {
+> extends Omit<WorkerProps<Bindings>, "vite" | "main" | "assets"> {
   /**
    * Root directory passed to Vite's `root` option.
    * Defaults to the current working directory (`process.cwd()`).
@@ -24,6 +27,11 @@ export interface ViteProps<
    * @see {@link MemoOptions}
    */
   memo?: MemoOptions;
+  /**
+   * Optional configuration for static asset routing behavior.
+   * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
+   */
+  assets?: AssetsConfig;
 }
 
 /**
@@ -106,27 +114,67 @@ export interface ViteProps<
  *   },
  * });
  * ```
+ *
+ * @section Class Form
+ * Calling `Vite` with no arguments returns a constructor you can
+ * `extend` to declare the Worker as a named class. The class is both
+ * an `Effect` you can `yield*` to deploy and a type you can reference
+ * elsewhere — useful when other resources need to bind to this Worker.
+ *
+ * @example Declaring a Worker class
+ * ```typescript
+ * class Website extends Cloudflare.Vite<Website>()("Website", {
+ *   compatibility: { flags: ["nodejs_compat"] },
+ * }) {}
+ *
+ * const site = yield* Website;
+ * ```
  */
-export const Vite = <
-  const Bindings extends WorkerBindingProps = {},
-  Req = never,
->(
-  id: string,
-  propsEff?:
-    | InputProps<ViteProps<Bindings>>
-    | Effect.Effect<InputProps<ViteProps<Bindings>>, never, Req>,
-) =>
-  Worker<Bindings, WorkerAssetsConfig, Req>(
-    id,
-    Effect.map(
-      Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff),
-      (props) => ({
-        ...props,
-        main: undefined!,
-        vite: {
-          rootDir: props?.rootDir,
-          memo: props?.memo,
-        },
-      }),
-    ),
-  );
+export const Vite: {
+  <Self>(): {
+    <const Bindings extends WorkerBindingProps = {}, Req = never>(
+      id: string,
+      propsEff?:
+        | InputProps<ViteProps<Bindings>>
+        | Effect.Effect<InputProps<ViteProps<Bindings>>, never, Req>,
+    ): Effect.Effect<Self, never, Req | Providers> & {
+      new (): Worker<{
+        [binding in keyof NormalizedBindings<
+          Bindings,
+          WorkerAssetsConfig
+        >]: NormalizedBindings<Bindings, WorkerAssetsConfig>[binding];
+      }>;
+    };
+  };
+  <const Bindings extends WorkerBindingProps = {}, Req = never>(
+    id: string,
+    propsEff?:
+      | InputProps<ViteProps<Bindings>>
+      | Effect.Effect<InputProps<ViteProps<Bindings>>, never, Req>,
+  ): Effect.Effect<
+    Worker<{
+      [binding in keyof NormalizedBindings<
+        Bindings,
+        WorkerAssetsConfig
+      >]: NormalizedBindings<Bindings, WorkerAssetsConfig>[binding];
+    }>,
+    never,
+    Req | Providers
+  >;
+} = ((id?: any, propsEff?: any) =>
+  id === undefined
+    ? (id: string, propsEff: any) => effectClass(Vite(id, propsEff))
+    : Worker(
+        id,
+        Effect.map(
+          Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff),
+          (props) => ({
+            ...props,
+            main: undefined!,
+            vite: {
+              rootDir: props?.rootDir,
+              memo: props?.memo,
+            },
+          }),
+        ),
+      )) as any;

package/src/Cloudflare/Workers/Assets.ts

@@ -32,9 +32,8 @@ export interface AssetReadResult {
   hash: string;
 }
 
-export interface AssetsProps {
+export interface AssetsProps extends AssetsConfig {
   directory: string;
-  config?: AssetsConfig;
 }
 
 export type ValidationError =
@@ -103,10 +102,13 @@ const createIgnoreMatcher = (patterns: string[]) => {
   return (file: string) => matcher.ignores(file);
 };
 
-export const readAssets = Effect.fnUntraced(function* (props: AssetsProps) {
+export const readAssets = Effect.fnUntraced(function* ({
+  directory,
+  ...config
+}: AssetsProps) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const resolvedDirectory = path.resolve(props.directory);
+  const resolvedDirectory = path.resolve(directory);
   const [files, ignore, _headers, _redirects] = yield* Effect.all([
     fs.readDirectory(resolvedDirectory, { recursive: true }),
     maybeReadString(path.join(resolvedDirectory, ".assetsignore")),
@@ -151,7 +153,7 @@ export const readAssets = Effect.fnUntraced(function* (props: AssetsProps) {
       if (count > MAX_ASSET_COUNT) {
         return yield* new TooManyAssetsError({
           message: `Too many assets (the maximum count is ${MAX_ASSET_COUNT}; this directory has ${count} assets)`,
-          directory: props.directory,
+          directory,
           count,
         });
       }
@@ -176,14 +178,14 @@ export const readAssets = Effect.fnUntraced(function* (props: AssetsProps) {
   // causes both unnecessary re-uploads and `NotFound` failures when
   // the previously-recorded path is gone.
   const hash = yield* sha256Object({
-    config: props.config,
+    config,
     manifest: sortedManifest,
     _headers,
     _redirects,
   });
   return {
-    directory: props.directory,
-    config: props.config,
+    directory,
+    config,
     manifest: sortedManifest,
     _headers,
     _redirects,

package/src/Cloudflare/Workers/DurableObjectChatPersistence.ts

@@ -0,0 +1,131 @@
+import * as Arr from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import {
+  BackingPersistence,
+  PersistenceError,
+  type BackingPersistenceStore,
+} from "effect/unstable/persistence/Persistence";
+import { DurableObjectState } from "./DurableObjectState.ts";
+
+/**
+ * A `BackingPersistence` layer (Effect AI persistence module) backed
+ * by the surrounding Durable Object's `state.storage`. Drop-in storage
+ * for `Persistence.layerResultPersisted({ storeId })` so chat history,
+ * cached AI responses, or any other persisted state lives in the DO
+ * SQLite store with `${storeId}:` key namespacing.
+ *
+ * Multiple `storeId`s can coexist within a single Durable Object —
+ * keys are namespaced with a `${storeId}:` prefix so they don't
+ * collide.
+ *
+ * :::caution
+ * TTL is currently ignored; Durable Object storage has no native TTL.
+ * If you need expiry, layer a TTL-aware backing store on top, or run
+ * a periodic `clear`.
+ * :::
+ *
+ * @binding
+ *
+ * @section Wiring it into a chat-backing DO
+ * @example Persisted chat history per DO instance
+ * `Persistence.layerResultPersisted({ storeId })` is the seam Effect
+ * AI exposes for cached/replayable AI calls. Layer
+ * `DurableObjectChatPersistence` underneath and every entry is stored
+ * in the DO's `state.storage` under the `alchemy.chat:` prefix.
+ * ```typescript
+ * import * as Cloudflare from "alchemy/Cloudflare";
+ * import * as Effect from "effect/Effect";
+ * import * as Layer from "effect/Layer";
+ * import { Chat, LanguageModel } from "effect/unstable/ai";
+ * import { Persistence } from "effect/unstable/persistence";
+ *
+ * export default class ChatBackend extends Cloudflare.DurableObjectNamespace<ChatBackend>()(
+ *   "ChatBackend",
+ *   Effect.gen(function* () {
+ *     return Effect.gen(function* () {
+ *       const persistence = yield* Persistence.layerResultPersisted({
+ *         storeId: "alchemy.chat",
+ *       }).pipe(Layer.provide(Cloudflare.DurableObjectChatPersistence));
+ *
+ *       return {
+ *         send: (threadId: string, prompt: string) =>
+ *           LanguageModel.generateText({ prompt }).pipe(Effect.provide(persistence)),
+ *       };
+ *     });
+ *   }),
+ * ) {}
+ * ```
+ *
+ * @section Multiple stores in the same DO
+ * @example Separate `storeId`s coexist
+ * Different `storeId`s namespace their keys with `${storeId}:`, so
+ * one DO can keep, say, chat history *and* an audit log in separate
+ * stores without colliding.
+ * ```typescript
+ * const aiPersistence = yield* Persistence.layerResultPersisted({
+ *   storeId: "alchemy.chat",
+ * }).pipe(Layer.provide(Cloudflare.DurableObjectChatPersistence));
+ *
+ * const auditPersistence = yield* Persistence.layerResultPersisted({
+ *   storeId: "alchemy.audit",
+ * }).pipe(Layer.provide(Cloudflare.DurableObjectChatPersistence));
+ * ```
+ */
+export const DurableObjectChatPersistence = Layer.effect(BackingPersistence)(
+  Effect.gen(function* () {
+    const state = yield* DurableObjectState;
+    const storage = state.storage;
+
+    const wrapErr = (op: string, key?: string) => (cause: unknown) =>
+      new PersistenceError({
+        message: `Failed to ${op}${key !== undefined ? ` key ${key}` : ""} in DurableObject storage`,
+        cause,
+      });
+
+    return BackingPersistence.of({
+      make: (storeId) =>
+        Effect.sync(() => {
+          const prefixed = (k: string) => `${storeId}:${k}`;
+          return {
+            get: (key) =>
+              storage
+                .get<object>(prefixed(key))
+                .pipe(Effect.mapError(wrapErr("get", key))),
+            getMany: (keys) =>
+              storage.get<object>(keys.map(prefixed)).pipe(
+                Effect.mapError(wrapErr("getMany")),
+                Effect.map(
+                  (map) =>
+                    keys.map((k) => map.get(prefixed(k))) as Arr.NonEmptyArray<
+                      object | undefined
+                    >,
+                ),
+              ),
+            set: (key, value, _ttl) =>
+              storage
+                .put(prefixed(key), value)
+                .pipe(Effect.mapError(wrapErr("set", key))),
+            setMany: (entries) =>
+              storage
+                .put(
+                  Object.fromEntries(entries.map(([k, v]) => [prefixed(k), v])),
+                )
+                .pipe(Effect.mapError(wrapErr("setMany"))),
+            remove: (key) =>
+              storage
+                .delete(prefixed(key))
+                .pipe(Effect.asVoid, Effect.mapError(wrapErr("remove", key))),
+            clear: storage.list({ prefix: `${storeId}:` }).pipe(
+              Effect.flatMap((map) => {
+                const ks = [...map.keys()];
+                if (ks.length === 0) return Effect.void;
+                return Effect.asVoid(storage.delete(ks));
+              }),
+              Effect.mapError(wrapErr("clear")),
+            ),
+          } satisfies BackingPersistenceStore;
+        }),
+    });
+  }),
+);

package/src/Cloudflare/Workers/DynamicWorkerLoader.ts

@@ -100,10 +100,10 @@ type BindEffect = ReturnType<typeof bindLoader>;
  * surrounding Worker and returns a {@link DynamicWorkerLoaderHandle} with
  * `.load()` — no separate `.bind(...)` step required.
  *
- * The divergence is achieved via `[Symbol.iterator]`: the object is not an
- * `Effect` (so `InferEnv` resolves it to the native
- * {@link DynamicWorkerLoaderBinding} in the `env` position), but it is iterable
- * as one when `yield*`-ed.
+ * The divergence is achieved via `[Symbol.iterator]`: the object is
+ * deliberately not an `Effect` (so `InferEnv` and the Worker `env` resolver
+ * keep it as the native {@link DynamicWorkerLoaderBinding} rather than
+ * `yield*`-ing it), but it is iterable as one when `yield*`-ed.
  */
 export interface DynamicWorkerLoader {
   kind: DynamicWorkerTypeId;

package/src/Cloudflare/Workers/InferEnv.ts

@@ -45,20 +45,22 @@ export type GetBindingType<T> =
                           : T extends Cloudflare.Images
                             ? ImagesBinding
                             : T extends Cloudflare.Browser
-                              ? Fetcher
+                              ? BrowserRun
                               : T extends Cloudflare.Hyperdrive
                                 ? Hyperdrive
-                                : T extends Cloudflare.DynamicWorkerLoader
-                                  ? Cloudflare.DynamicWorkerLoaderBinding
-                                  : T extends Cloudflare.DurableObjectNamespaceLike
-                                    ? DurableObjectNamespace<
-                                        Exclude<T["Shape"], undefined>
-                                      >
-                                    : T extends Redacted<any>
-                                      ? // redacteds are always stored as secret_text, so are always string
-                                        // we JSON.stringify when not a Redacted<string>
-                                        string
-                                      : T;
+                                : T extends Cloudflare.VersionMetadata
+                                  ? WorkerVersionMetadata
+                                  : T extends Cloudflare.DynamicWorkerLoader
+                                    ? Cloudflare.DynamicWorkerLoaderBinding
+                                    : T extends Cloudflare.DurableObjectNamespaceLike
+                                      ? DurableObjectNamespace<
+                                          Exclude<T["Shape"], undefined>
+                                        >
+                                      : T extends Redacted<any>
+                                        ? // redacteds are always stored as secret_text, so are always string
+                                          // we JSON.stringify when not a Redacted<string>
+                                          string
+                                        : T;
 
 /**
  * Cloudflare service-binding wire shape for an Effect-native Worker.