alchemy 2.0.0-beta.1 → 2.0.0-beta.3

package/src/Cloudflare/KV/KVNamespace.ts

@@ -5,9 +5,10 @@ import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { Account } from "../Account.ts";
+import type { Providers } from "../Providers.ts";
 import { KVNamespaceBinding } from "./KVNamespaceBinding.ts";
 
-export type NamespaceProps = {
+export type KVNamespaceProps = {
   /**
    * A human-readable string name for the namespace.
    * If omitted, a unique name will be generated.
@@ -18,20 +19,47 @@ export type NamespaceProps = {
 
 export type KVNamespace = Resource<
   "Cloudflare.KVNamespace",
-  NamespaceProps,
+  KVNamespaceProps,
   {
     title: string;
     namespaceId: string;
     supportsUrlEncoding: boolean | undefined;
     accountId: string;
-  }
+  },
+  never,
+  Providers
 >;
 
+/**
+ * A Cloudflare Workers KV namespace for key-value storage at the edge.
+ *
+ * KV provides eventually-consistent, low-latency reads with global
+ * replication. Create a namespace as a resource, then bind it to a Worker
+ * to get/put values at runtime.
+ *
+ * @section Creating a Namespace
+ * @example Basic KV namespace
+ * ```typescript
+ * const kv = yield* Cloudflare.KVNamespace("MyKV");
+ * ```
+ *
+ * @section Binding to a Worker
+ * @example Using KV inside a Worker
+ * ```typescript
+ * const kv = yield* Cloudflare.KVNamespace.bind(MyKV);
+ *
+ * // Read a value
+ * const value = yield* kv.get("my-key");
+ *
+ * // Write a value
+ * yield* kv.put("my-key", "hello world");
+ * ```
+ */
 export const KVNamespace = Resource<KVNamespace>("Cloudflare.KVNamespace")({
   bind: KVNamespaceBinding.bind,
 });
 
-export const NamespaceProvider = () =>
+export const KVNamespaceProvider = () =>
   Provider.effect(
     KVNamespace,
     Effect.gen(function* () {

package/src/Cloudflare/Providers.ts

@@ -1,75 +1,77 @@
 import * as Auth from "@distilled.cloud/cloudflare/Auth";
-import { pipe } from "effect/Function";
 import * as Layer from "effect/Layer";
-import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 import * as Socket from "effect/unstable/socket/Socket";
-import { CommandProvider } from "../Build/Command.ts";
-import { RandomProvider } from "../Random.ts";
+import { Command } from "../Build/Command.ts";
+import * as Build from "../Build/index.ts";
+import * as Provider from "../Provider.ts";
+import { Random, RandomProvider } from "../Random.ts";
 import * as Account from "./Account.ts";
-import { ContainerProvider } from "./Container/ContainerApplication.ts";
+import * as Containers from "./Container/index.ts";
 import * as D1 from "./D1/index.ts";
 import * as KV from "./KV/index.ts";
 import * as R2 from "./R2/index.ts";
-import { AssetsProvider } from "./Workers/Assets.ts";
-import { WorkerProvider } from "./Workers/Worker.ts";
-import { WorkflowProvider } from "./Workers/Workflow.ts";
+import * as Assets from "./Workers/Assets.ts";
+import * as Workers from "./Workers/index.ts";
+import * as Workflows from "./Workers/Workflow.ts";
 
-// export type Providers = Extract<Layer.Success<_providers>, Provider<any>>;
+export { Credentials } from "@distilled.cloud/cloudflare/Credentials";
 
-export interface Providers extends Layer.Layer<
-  Layer.Success<_providers>,
-  Layer.Error<_providers>,
-  Layer.Services<_providers>
-> {}
+export class Providers extends Provider.ProviderCollection<Providers>()(
+  "Cloudflare",
+) {}
+
+export type ProviderRequirements = Layer.Services<ReturnType<typeof providers>>;
 
 /**
  * Cloudflare providers, bindings, and credentials for Worker-based stacks.
  */
-export const providers: () => Providers = () => _providers();
-
-type _providers = ReturnType<typeof _providers>;
-const _providers = () =>
-  pipe(
-    resources(),
-    Layer.provideMerge(bindings()),
-    Layer.provideMerge(utils()),
-    Layer.provideMerge(credentials()),
+export const providers = () =>
+  Layer.effect(
+    Providers,
+    Provider.collection([
+      Command,
+      Containers.Container,
+      D1.D1ConnectionPolicy,
+      D1.D1Database,
+      KV.KVNamespace,
+      KV.KVNamespaceBindingPolicy,
+      R2.R2Bucket,
+      R2.R2BucketBindingPolicy,
+      Random,
+      Workers.BindWorkerPolicy,
+      Workers.FetchPolicy,
+      Workers.Worker,
+      Workflows.WorkflowResource,
+    ]),
+  ).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        Containers.ContainerProvider(),
+        D1.D1ConnectionPolicyLive,
+        D1.DatabaseProvider(),
+        KV.KVNamespaceBindingPolicyLive,
+        KV.KVNamespaceProvider(),
+        R2.R2BucketBindingPolicyLive,
+        R2.R2BucketProvider(),
+        Workers.BindWorkerPolicyLive,
+        Workers.FetchPolicyLive,
+        Workers.WorkerProvider(),
+        Workflows.WorkflowProvider(),
+      ),
+    ),
+    Layer.provideMerge(
+      Layer.mergeAll(
+        Assets.AssetsProvider(),
+        Build.CommandProvider(),
+        RandomProvider(),
+      ),
+    ),
+    Layer.provideMerge(
+      Layer.mergeAll(
+        Account.fromStageConfig(),
+        Auth.fromEnv(),
+        Socket.layerWebSocketConstructorGlobal,
+      ),
+    ),
     Layer.orDie,
   );
-
-/**
- * Cloudflare account credentials and auth context.
- */
-export const credentials = () =>
-  Layer.mergeAll(
-    Account.fromStageConfig(),
-    Layer.provideMerge(Auth.fromEnv(), FetchHttpClient.layer),
-  );
-
-/**
- * All Cloudflare resource providers.
- */
-export const resources = () =>
-  Layer.mergeAll(
-    CommandProvider(),
-    RandomProvider(),
-    ContainerProvider(),
-    WorkerProvider(),
-    WorkflowProvider(),
-    D1.DatabaseProvider(),
-    KV.NamespaceProvider(),
-    R2.R2BucketProvider(),
-  );
-
-/**
- * All Cloudflare binding policies.
- */
-export const bindings = () =>
-  Layer.mergeAll(
-    D1.D1ConnectionPolicyLive,
-    R2.R2BucketBindingPolicyLive,
-    KV.KVNamespaceBindingPolicyLive,
-  );
-
-const utils = () =>
-  Layer.mergeAll(AssetsProvider(), Socket.layerWebSocketConstructorGlobal);

package/src/Cloudflare/R2/R2Bucket.ts

@@ -6,6 +6,7 @@ import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { Account } from "../Account.ts";
+import type { Providers } from "../Providers.ts";
 import { R2BucketBinding } from "./R2BucketBinding.ts";
 
 export type R2BucketName = string;
@@ -41,9 +42,54 @@ export type R2Bucket = Resource<
     jurisdiction: R2Bucket.Jurisdiction;
     location: R2Bucket.Location | undefined;
     accountId: string;
-  }
+  },
+  never,
+  Providers
 >;
 
+/**
+ * A Cloudflare R2 object storage bucket with S3-compatible API.
+ *
+ * R2 provides zero-egress-fee object storage. Create a bucket as a resource,
+ * then bind it to a Worker to read and write objects at runtime.
+ *
+ * @section Creating a Bucket
+ * @example Basic R2 bucket
+ * ```typescript
+ * const bucket = yield* Cloudflare.R2Bucket("MyBucket");
+ * ```
+ *
+ * @example Bucket with location hint
+ * ```typescript
+ * const bucket = yield* Cloudflare.R2Bucket("MyBucket", {
+ *   locationHint: "wnam",
+ * });
+ * ```
+ *
+ * @section Binding to a Worker
+ * @example Reading and writing objects
+ * ```typescript
+ * const bucket = yield* Cloudflare.R2Bucket.bind(MyBucket);
+ *
+ * // Write an object
+ * yield* bucket.put("hello.txt", "Hello, World!");
+ *
+ * // Read an object
+ * const object = yield* bucket.get("hello.txt");
+ * if (object) {
+ *   const text = yield* object.text();
+ * }
+ * ```
+ *
+ * @example Streaming upload with content length
+ * ```typescript
+ * const bucket = yield* Cloudflare.R2Bucket.bind(MyBucket);
+ *
+ * yield* bucket.put("upload.bin", request.stream, {
+ *   contentLength: Number(request.headers["content-length"] ?? 0),
+ * });
+ * ```
+ */
 export const R2Bucket = Resource<R2Bucket>("Cloudflare.R2Bucket")({
   bind: R2BucketBinding.bind,
 });

package/src/Cloudflare/R2/R2BucketBinding.ts

@@ -142,7 +142,7 @@ export class R2BucketBinding extends Binding.Service<
 export const R2BucketBindingLive = Layer.effect(
   R2BucketBinding,
   Effect.gen(function* () {
-    const bind = yield* BucketBindingPolicy;
+    const bind = yield* R2BucketBindingPolicy;
 
     return Effect.fn(function* (bucket: R2Bucket) {
       yield* bind(bucket);
@@ -306,37 +306,32 @@ export const R2BucketBindingLive = Layer.effect(
   }),
 );
 
-export class BucketBindingPolicy extends Binding.Policy<
-  BucketBindingPolicy,
+export class R2BucketBindingPolicy extends Binding.Policy<
+  R2BucketBindingPolicy,
   (bucket: R2Bucket) => Effect.Effect<void>
 >()("Cloudflare.R2Bucket") {}
 
-export const R2BucketBindingPolicyLive = BucketBindingPolicy.layer.succeed(
-  (host, bucket) => R2BucketClient(host, bucket),
-);
-
-export const R2BucketClient = Effect.fn(function* (
-  host: ResourceLike,
-  bucket: R2Bucket,
-) {
-  if (isWorker(host)) {
-    yield* host.bind`${bucket}`({
-      bindings: [
-        {
-          type: "r2_bucket",
-          name: bucket.LogicalId,
-          bucketName: bucket.bucketName,
-          jurisdiction: bucket.jurisdiction.pipe(
-            Output.map((jurisdiction) =>
-              jurisdiction === "default" ? undefined : jurisdiction,
+export const R2BucketBindingPolicyLive = R2BucketBindingPolicy.layer.succeed(
+  Effect.fnUntraced(function* (host: ResourceLike, bucket: R2Bucket) {
+    if (isWorker(host)) {
+      yield* host.bind`${bucket}`({
+        bindings: [
+          {
+            type: "r2_bucket",
+            name: bucket.LogicalId,
+            bucketName: bucket.bucketName,
+            jurisdiction: bucket.jurisdiction.pipe(
+              Output.map((jurisdiction) =>
+                jurisdiction === "default" ? undefined : jurisdiction,
+              ),
             ),
-          ),
-        },
-      ],
-    });
-  } else {
-    return yield* Effect.die(
-      new Error(`BucketBinding does not support runtime '${host.Type}'`),
-    );
-  }
-});
+          },
+        ],
+      });
+    } else {
+      return yield* Effect.die(
+        new Error(`BucketBinding does not support runtime '${host.Type}'`),
+      );
+    }
+  }),
+);

package/src/Cloudflare/Website/StaticSite.ts

@@ -19,6 +19,63 @@ export interface StaticSiteProps
 
 export type StaticSite = ReturnType<typeof StaticSite>;
 
+/**
+ * A Cloudflare Worker that serves static assets built by a shell command.
+ *
+ * `StaticSite` runs a build command (e.g. `npm run build`), content-hashes
+ * the output directory, and deploys the result as a Cloudflare Worker with
+ * static assets. Use this when your site has its own build step that
+ * produces a directory of files — Hugo, Zola, Eleventy, or any custom
+ * pipeline.
+ *
+ * For Vite-based projects, prefer `Cloudflare.Vite` which handles
+ * building automatically.
+ *
+ * @resource
+ *
+ * @section Basic Usage
+ * Point `command` at your build script and `outdir` at where it writes
+ * output. Alchemy runs the command, hashes the output, and deploys it.
+ *
+ * @example Deploying a Hugo site
+ * ```typescript
+ * const site = yield* Cloudflare.StaticSite("Blog", {
+ *   command: "hugo --minify",
+ *   outdir: "public",
+ * });
+ * ```
+ *
+ * @section Asset Configuration
+ * Use `assetsConfig` to control how Cloudflare handles routing for
+ * your static files — HTML handling, not-found behavior, etc.
+ *
+ * @example SPA-style routing
+ * ```typescript
+ * const site = yield* Cloudflare.StaticSite("App", {
+ *   command: "npm run build",
+ *   outdir: "dist",
+ *   assetsConfig: {
+ *     htmlHandling: "auto-trailing-slash",
+ *     notFoundHandling: "single-page-application",
+ *   },
+ * });
+ * ```
+ *
+ * @section Custom Rebuild Scope
+ * By default, all non-gitignored files are hashed to decide whether
+ * the build should re-run. Use `memo` to narrow the scope.
+ *
+ * @example Narrowing the memo scope
+ * ```typescript
+ * const site = yield* Cloudflare.StaticSite("Docs", {
+ *   command: "npm run build",
+ *   outdir: "dist",
+ *   memo: {
+ *     include: ["content/**", "templates/**", "config.toml"],
+ *   },
+ * });
+ * ```
+ */
 export const StaticSite = (id: string, props: InputProps<StaticSiteProps>) =>
   Effect.gen(function* () {
     // TODO(sam): local dev/hmr support?

package/src/Cloudflare/Website/Vite.ts

@@ -21,22 +21,31 @@ export interface ViteProps extends Omit<WorkerProps, "vite" | "main"> {
 /**
  * A Cloudflare Worker deployed from a Vite project.
  *
- * `Vite` uses the Cloudflare Vite plugin to build both the server bundle and
- * client assets in a single `vite build` invocation — no manual `main`
- * entrypoint, build command, output directory, or Wrangler configuration
- * required.
+ * `Vite` uses the Cloudflare Vite plugin to build both the server bundle
+ * and client assets in a single `vite build` invocation — no manual
+ * `main` entrypoint, build command, output directory, or Wrangler
+ * configuration required.
  *
  * Input files are content-hashed (respecting `.gitignore` by default) so
  * unchanged projects skip the build and deploy entirely.
  *
+ * @resource
+ *
  * @section Deploying a Static Site
- * @example Basic Static Site
+ * For a pure static site (no SSR), a single call is all you need.
+ * Vite builds the project and Alchemy deploys the output as a
+ * Cloudflare Worker with static assets.
+ *
+ * @example Static Vite site
  * ```typescript
  * const site = yield* Cloudflare.Vite("Website");
  * ```
  *
- * @section Deploying a TanStack Start App
- * @example TanStack Start with SSR
+ * @section SSR Frameworks
+ * For SSR frameworks like TanStack Start, SolidStart, or Nuxt, enable
+ * `nodejs_compat` so the server bundle can use Node.js APIs.
+ *
+ * @example TanStack Start
  * ```typescript
  * const app = yield* Cloudflare.Vite("TanStackStart", {
  *   compatibility: {
@@ -45,8 +54,43 @@ export interface ViteProps extends Omit<WorkerProps, "vite" | "main"> {
  * });
  * ```
  *
+ * @example SolidStart with worker-first routing
+ * ```typescript
+ * const app = yield* Cloudflare.Vite("SolidStart", {
+ *   compatibility: {
+ *     flags: ["nodejs_compat"],
+ *   },
+ *   assets: {
+ *     config: { runWorkerFirst: true },
+ *   },
+ * });
+ * ```
+ *
+ * @section Single-Page Applications
+ * For SPAs (React, Vue, etc.), configure asset handling so all
+ * routes fall back to `index.html`.
+ *
+ * @example Vue SPA
+ * ```typescript
+ * const app = yield* Cloudflare.Vite("Vue", {
+ *   compatibility: {
+ *     flags: ["nodejs_compat"],
+ *   },
+ *   assets: {
+ *     config: {
+ *       htmlHandling: "auto-trailing-slash",
+ *       notFoundHandling: "single-page-application",
+ *     },
+ *   },
+ * });
+ * ```
+ *
  * @section Custom Rebuild Scope
- * @example Narrow the Memo Scope
+ * By default, every non-gitignored file is hashed to decide whether
+ * a rebuild is needed. Use `memo` to narrow the scope when your
+ * project has large directories that don't affect the build output.
+ *
+ * @example Narrowing the memo scope
  * ```typescript
  * const site = yield* Cloudflare.Vite("Docs", {
  *   memo: {