alchemy 2.0.0-beta.2 → 2.0.0-beta.test-export-fix-3

package/src/Cloudflare/D1/D1Database.ts

@@ -57,18 +57,37 @@ export type D1Database = Resource<
 /**
  * A Cloudflare D1 serverless SQL database built on SQLite.
  *
+ * D1 is a serverless relational database that runs at the edge. Create a
+ * database as a resource, then bind it to a Worker to run SQL queries.
+ *
  * @section Creating a Database
- * @example Basic Database
+ * @example Basic database
  * ```typescript
- * const db = yield* Database("my-db", {});
+ * const db = yield* Cloudflare.D1Database("my-db");
  * ```
  *
- * @example Database with Location Hint
+ * @example Database with location hint
  * ```typescript
- * const db = yield* Database("my-db", {
+ * const db = yield* Cloudflare.D1Database("my-db", {
  *   primaryLocationHint: "wnam",
  * });
  * ```
+ *
+ * @section Binding to a Worker
+ * @example Using D1 inside a Worker
+ * ```typescript
+ * const db = yield* Cloudflare.D1Connection.bind(MyDB);
+ *
+ * // Run a query
+ * const results = yield* db.prepare("SELECT * FROM users WHERE id = ?")
+ *   .bind(userId)
+ *   .all();
+ *
+ * // Execute a mutation
+ * yield* db.prepare("INSERT INTO users (id, name) VALUES (?, ?)")
+ *   .bind(newId, name)
+ *   .run();
+ * ```
  */
 export const D1Database = Resource<D1Database>("Cloudflare.D1Database");
 

package/src/Cloudflare/KV/KVNamespace.ts

@@ -30,6 +30,31 @@ export type KVNamespace = Resource<
   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,
 });

package/src/Cloudflare/Providers.ts

@@ -10,7 +10,6 @@ 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 * as Assets from "./Workers/Assets.ts";
 import * as Workers from "./Workers/index.ts";
 import * as Workflows from "./Workers/Workflow.ts";
 
@@ -60,11 +59,7 @@ export const providers = () =>
       ),
     ),
     Layer.provideMerge(
-      Layer.mergeAll(
-        Assets.AssetsProvider(),
-        Build.CommandProvider(),
-        RandomProvider(),
-      ),
+      Layer.mergeAll(Build.CommandProvider(), RandomProvider()),
     ),
     Layer.provideMerge(
       Layer.mergeAll(

package/src/Cloudflare/R2/R2Bucket.ts

@@ -6,7 +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 type * as Cloudflare from "../Providers.ts";
 import { R2BucketBinding } from "./R2BucketBinding.ts";
 
 export type R2BucketName = string;
@@ -44,9 +44,52 @@ export type R2Bucket = Resource<
     accountId: string;
   },
   never,
-  Providers
+  Cloudflare.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/Website/StaticSite.ts

@@ -3,10 +3,17 @@ import { Command, type CommandProps } from "../../Build/Command.ts";
 import type { InputProps } from "../../Input.ts";
 import * as Namespace from "../../Namespace.ts";
 import type { AssetsConfig } from "../Workers/Assets.ts";
-import { Worker, type WorkerProps } from "../Workers/Worker.ts";
+import {
+  Worker,
+  type WorkerAssetsConfig,
+  type WorkerBindingProps,
+  type WorkerProps,
+} from "../Workers/Worker.ts";
 
-export interface StaticSiteProps
-  extends Omit<WorkerProps, "assets">, Omit<CommandProps, "env"> {
+export interface StaticSiteProps<Bindings extends WorkerBindingProps = {}>
+  extends
+    Omit<WorkerProps<Bindings, WorkerAssetsConfig>, "assets">,
+    Omit<CommandProps, "env"> {
   /**
    * Optional configuration for static asset routing behavior.
    * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
@@ -19,12 +26,78 @@ export interface StaticSiteProps
 
 export type StaticSite = ReturnType<typeof StaticSite>;
 
-export const StaticSite = (id: string, props: InputProps<StaticSiteProps>) =>
+/**
+ * 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 = <const Bindings extends WorkerBindingProps = {}>(
+  id: string,
+  props: InputProps<StaticSiteProps<Bindings>>,
+) =>
   Effect.gen(function* () {
     // TODO(sam): local dev/hmr support?
-    const build = yield* Command("Build", props);
+    const build = yield* Command("Build", {
+      command: props.command,
+      cwd: props.cwd,
+      memo: props.memo,
+      outdir: props.outdir,
+      env: props.env,
+    });
 
-    const worker = yield* Worker("Worker", {
+    const worker = yield* Worker<Bindings, WorkerAssetsConfig>("Worker", {
       ...props,
       assets: {
         path: build.outdir,

package/src/Cloudflare/Website/Vite.ts

@@ -1,8 +1,15 @@
-import type { InputProps } from "../../Input.ts";
 import type { MemoOptions } from "../../Build/Memo.ts";
-import { Worker, type WorkerProps } from "../Workers/Worker.ts";
+import type { InputProps } from "../../Input.ts";
+import {
+  Worker,
+  type WorkerAssetsConfig,
+  type WorkerBindingProps,
+  type WorkerProps,
+} from "../Workers/Worker.ts";
 
-export interface ViteProps extends Omit<WorkerProps, "vite" | "main"> {
+export interface ViteProps<
+  Bindings extends WorkerBindingProps = {},
+> extends Omit<WorkerProps<Bindings>, "vite" | "main"> {
   /**
    * Root directory passed to Vite's `root` option.
    * Defaults to the current working directory (`process.cwd()`).
@@ -21,22 +28,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 +61,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: {
@@ -55,8 +106,11 @@ export interface ViteProps extends Omit<WorkerProps, "vite" | "main"> {
  * });
  * ```
  */
-export const Vite = (id: string, props: InputProps<ViteProps> = {}) =>
-  Worker(id, {
+export const Vite = <const Bindings extends WorkerBindingProps = {}>(
+  id: string,
+  props: InputProps<ViteProps<Bindings>> = {},
+) =>
+  Worker<Bindings, WorkerAssetsConfig>(id, {
     ...props,
     main: undefined!,
     vite: {