alchemy 2.0.0-beta.2 → 2.0.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.3",
   "homepage": "https://alchemy.run",
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
@@ -20,6 +20,14 @@
   ],
   "type": "module",
   "sideEffects": false,
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "bun bundle && bun pm pack",
+    "bundle": "tsdown",
+    "bundle:watch": "tsdown --watch",
+    "publish:npm": "cp ../README.md . && bun publish && rm README.md",
+    "test:benchmark": "tsx --tsconfig tsconfig.test.json test/types.benchmark.ts"
+  },
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
@@ -123,6 +131,12 @@
       "worker": "./src/Cloudflare/*/index.ts",
       "import": "./lib/Cloudflare/*/index.js"
     },
+    "./GitHub": {
+      "types": "./src/GitHub/index.d.ts",
+      "bun": "./src/GitHub/index.ts",
+      "worker": "./src/GitHub/index.ts",
+      "import": "./lib/GitHub/index.js"
+    },
     "./Endpoint": {
       "types": "./src/Endpoint/index.d.ts",
       "bun": "./src/Endpoint/index.ts",
@@ -187,14 +201,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "dev": "tsdown --watch",
-    "build": "bun bundle && bun pm pack",
-    "bundle": "tsdown",
-    "bundle:watch": "tsdown --watch",
-    "publish:npm": "cp ../README.md . && bun publish && rm README.md",
-    "test:benchmark": "tsx --tsconfig tsconfig.test.json test/types.benchmark.ts"
-  },
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.31",
     "@ai-sdk/openai": "^3.0.23",
@@ -207,10 +213,12 @@
     "@distilled.cloud/core": "^0.10.0",
     "@effect/vitest": "4.0.0-beta.48",
     "@libsql/client": "^0.17.0",
+    "@octokit/rest": "^22.0.1",
     "@smithy/node-config-provider": "^4.0.0",
     "@smithy/shared-ini-file-loader": "^4.3.4",
     "@smithy/types": "^4.8.1",
     "@types/aws-lambda": "^8.10.152",
+    "@types/libsodium-wrappers": "^0.8.2",
     "ai": "^6.0.62",
     "aws4fetch": "^1.0.20",
     "capnp-es": "^0.0.14",
@@ -219,6 +227,7 @@
     "fast-xml-parser": "^5.3.4",
     "ignore": "^7.0.5",
     "jszip": "^3.10.1",
+    "libsodium-wrappers": "^0.8.3",
     "rolldown": "1.0.0-rc.13",
     "solid-js": "latest",
     "sonda": "^0.11.1",

package/src/Cloudflare/Container/Container.ts

@@ -48,6 +48,128 @@ export type Container = {
   interceptAllOutboundHttp(binding: Fetcher): Effect.Effect<void>;
 };
 
+/**
+ * A Cloudflare Container that runs a long-lived process alongside a
+ * Durable Object.
+ *
+ * Containers always use the **Container Layer** pattern — the class
+ * and `.make()` must live in separate files. A Container must be
+ * bound to a Durable Object, and the DO imports the class to get a
+ * typed handle. If the class and `.make()` lived in the same file,
+ * the DO's bundle would pull in all of the container's runtime
+ * dependencies (process spawners, Node APIs, SDKs, etc.), which
+ * would bloat the bundle and likely break the Cloudflare Workers
+ * runtime. Keeping them separate ensures the bundler only includes
+ * the tiny class in the DO's output.
+ *
+ * See the {@link https://alchemy.run/concepts/platform | Platform
+ * concept} page for how this fits into the async / effect / layer
+ * progression.
+ *
+ * @section Container Layer
+ * Define the class and `.make()` in separate files. The class
+ * declares the container's identity, configuration, and typed
+ * shape. `.make()` provides the runtime implementation as a
+ * default export. Use `Container.of` to construct the typed
+ * shape — it ensures your implementation matches the methods
+ * declared on the class.
+ *
+ * @example Container class
+ * ```typescript
+ * // src/Sandbox.ts
+ * export class Sandbox extends Cloudflare.Container<
+ *   Sandbox,
+ *   {
+ *     exec: (cmd: string) => Effect.Effect<{
+ *       exitCode: number;
+ *       stdout: string;
+ *       stderr: string;
+ *     }>;
+ *   }
+ * >()(
+ *   "Sandbox",
+ *   { main: import.meta.filename },
+ * ) {}
+ * ```
+ *
+ * @example Container .make()
+ * ```typescript
+ * // src/Sandbox.runtime.ts
+ * export default Sandbox.make(
+ *   Effect.gen(function* () {
+ *     const cp = yield* ChildProcessSpawner;
+ *
+ *     return Sandbox.of({
+ *       exec: (cmd) =>
+ *         cp.spawn(ChildProcess.make(cmd, { shell: true })).pipe(
+ *           Effect.map(({ exitCode, stdout, stderr }) => ({
+ *             exitCode, stdout, stderr,
+ *           })),
+ *           Effect.scoped,
+ *         ),
+ *       fetch: Effect.succeed(
+ *         HttpServerResponse.text("Hello from 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.
+ *
+ * @example Stage-dependent configuration
+ * ```typescript
+ * export class Sandbox extends Cloudflare.Container<Sandbox>()(
+ *   "Sandbox",
+ *   Stack.useSync((stack) => ({
+ *     main: import.meta.filename,
+ *     instanceType: stack.stage === "prod" ? "standard-1" : "dev",
+ *     observability: { logs: { enabled: true } },
+ *   })),
+ * ) {}
+ * ```
+ *
+ * @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
+ * per-instance phase to start it. Because the DO only imports the
+ * class, the runtime implementation is completely excluded from the
+ * DO's bundle.
+ *
+ * @example Binding and starting a container
+ * ```typescript
+ * // init (outer Effect) — only imports the class
+ * const sandbox = yield* Cloudflare.Container.bind(Sandbox);
+ *
+ * // per-instance (inner Effect)
+ * return Effect.gen(function* () {
+ *   const container = yield* Cloudflare.start(sandbox);
+ *
+ *   return {
+ *     exec: (cmd: string) => container.exec(cmd),
+ *   };
+ * });
+ * ```
+ *
+ * @section HTTP Requests to Container Ports
+ * Use `getTcpPort` to get a `fetch` handle for a specific port on
+ * the running container. This lets you make HTTP requests to
+ * servers running inside the container process.
+ *
+ * @example Fetching from a container port
+ * ```typescript
+ * const container = yield* Cloudflare.start(sandbox);
+ * const { fetch } = yield* container.getTcpPort(3000);
+ *
+ * const response = yield* fetch(
+ *   HttpClientRequest.get("http://container/health"),
+ * );
+ * ```
+ */
 export const Container: Platform<
   ContainerApplication,
   ContainerServices,

package/src/Cloudflare/Container/ContainerApplication.ts

@@ -223,6 +223,9 @@ export type ContainerServices =
 
 export type ContainerShape = Main<ContainerServices>;
 
+/**
+ * @internal
+ */
 export interface ContainerApplication<Shape = unknown> extends Resource<
   ContainerTypeId,
   ContainerApplicationProps,

package/src/Cloudflare/Container/ContainerBinding.ts

@@ -8,7 +8,7 @@ import {
 import {
   DurableObjectNamespace,
   DurableObjectState,
-} from "../Workers/DurableObject.ts";
+} from "../Workers/DurableObjectNamespace.ts";
 import { Worker } from "../Workers/Worker.ts";
 import type { Container } from "./Container.ts";
 import type { ContainerApplication } from "./ContainerApplication.ts";

package/src/Cloudflare/Container/StartContainer.ts

@@ -6,7 +6,7 @@ import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
 import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
 import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
 import { type Fetcher } from "../Fetcher.ts";
-import { DurableObjectState } from "../Workers/DurableObject.ts";
+import { DurableObjectState } from "../Workers/DurableObjectNamespace.ts";
 import { type Container, ContainerError } from "./Container.ts";
 
 /**

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/R2/R2Bucket.ts

@@ -47,6 +47,49 @@ export type R2Bucket = Resource<
   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

@@ -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: {