alchemy 2.0.0-beta.3 → 2.0.0-beta.4

package/src/Cloudflare/Workers/Worker.ts

@@ -2,6 +2,7 @@ import type * as cf from "@cloudflare/workers-types";
 import cloudflareRolldown from "@distilled.cloud/cloudflare-rolldown-plugin";
 import cloudflareVite from "@distilled.cloud/cloudflare-vite-plugin";
 import * as workers from "@distilled.cloud/cloudflare/workers";
+import * as zones from "@distilled.cloud/cloudflare/zones";
 import type * as Cause from "effect/Cause";
 import * as Context from "effect/Context";
 import * as Data from "effect/Data";
@@ -26,7 +27,7 @@ import { findCwdForBundle } from "../../Bundle/TempRoot.ts";
 import type { ScopedPlanStatusSession } from "../../Cli/Cli.ts";
 import { isResolved } from "../../Diff.ts";
 import type { HttpEffect } from "../../Http.ts";
-import type { Input, InputProps } from "../../Input.ts";
+import type { InputProps } from "../../Input.ts";
 import * as Output from "../../Output.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
 import {
@@ -47,10 +48,20 @@ import { fromCloudflareFetcher } from "../Fetcher.ts";
 import { CloudflareLogs } from "../Logs.ts";
 import type { Providers } from "../Providers.ts";
 import type { R2Bucket } from "../R2/R2Bucket.ts";
-import type { AssetsConfig, AssetsProps } from "./Assets.ts";
-import * as Assets from "./Assets.ts";
+import {
+  isAssets,
+  readAssets,
+  uploadAssets,
+  type Assets,
+  type AssetsConfig,
+  type AssetsProps,
+} from "./Assets.ts";
 import cloudflare_workers from "./cloudflare_workers.ts";
-import { isDurableObjectExport } from "./DurableObjectNamespace.ts";
+import {
+  isDurableObjectExport,
+  isDurableObjectNamespaceLike,
+  type DurableObjectNamespaceLike,
+} from "./DurableObjectNamespace.ts";
 import { workersHttpHandler } from "./HttpServer.ts";
 import { Request } from "./Request.ts";
 import { makeRpcStub } from "./Rpc.ts";
@@ -105,12 +116,12 @@ export interface AssetsWithHash {
   /**
    * Path to the assets directory.
    */
-  path: Input<string>;
+  path: string;
   /**
    * Pre-computed hash of the assets. When provided, this hash is used for diffing
    * to determine if the worker needs to be redeployed.
    */
-  hash: Input<string>;
+  hash: string;
   /**
    * Optional assets configuration.
    */
@@ -161,7 +172,11 @@ export type WorkerServices = Worker | WorkerEnvironment | Request;
 
 export type WorkerShape = Main<WorkerServices>;
 
-export type WorkerBindingResource = R2Bucket | D1Database;
+export type WorkerBindingResource =
+  | Assets
+  | R2Bucket
+  | D1Database
+  | DurableObjectNamespaceLike<any>;
 
 export type WorkerBindings = {
   [bindingName in string]: WorkerBindingResource;
@@ -173,8 +188,26 @@ export type WorkerBindingProps = {
     | Effect.Effect<WorkerBindingResource, any, any>;
 };
 
+type NormalizedBindings<
+  Bindings extends WorkerBindingProps = {},
+  AssetsConfig extends WorkerAssetsConfig | undefined = undefined,
+> = {
+  [B in keyof Bindings]: Bindings[B] extends Effect.Effect<
+    infer T extends WorkerBindingResource,
+    any,
+    any
+  >
+    ? T
+    : Extract<Bindings[B], WorkerBindingResource>;
+} & (undefined extends AssetsConfig ? {} : { ASSETS: Assets });
+
+export type WorkerAssetsConfig = string | AssetsProps | AssetsWithHash;
+
 export interface WorkerProps<
   Bindings extends WorkerBindingProps = any,
+  Assets extends WorkerAssetsConfig | undefined =
+    | WorkerAssetsConfig
+    | undefined,
 > extends PlatformProps {
   /**
    * Worker name override. If omitted, Alchemy derives a deterministic physical
@@ -192,11 +225,7 @@ export interface WorkerProps<
    * - An AssetsProps object with directory and config
    * - An object with path and hash (e.g., from a Build resource)
    */
-  assets?:
-    | string
-    | AssetsProps
-    | AssetsWithHash
-    | (AssetsWithHash & { [K: string]: any });
+  assets?: Assets;
   subdomain?: {
     enabled?: boolean;
     previewsEnabled?: boolean;
@@ -219,6 +248,12 @@ export interface WorkerProps<
   env?: Record<string, string | Redacted.Redacted<string>>;
   exports?: string[];
   bindings?: Bindings;
+  /**
+   * One or more custom hostnames (e.g. `"app.example.com"`) to bind to this
+   * Worker. The Cloudflare Zone is inferred from the hostname — the zone must
+   * already exist in the account.
+   */
+  domain?: string | string[];
   build?: {
     /**
      * Whether to generate a metafile for the worker bundle.
@@ -239,6 +274,7 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<
     tags: string[] | undefined;
     durableObjectNamespaces: Record<string, string>;
     accountId: string;
+    domains: { hostname: string; id: string; zoneId: string }[];
     hash?: {
       assets: string | undefined;
       bundle: string | undefined;
@@ -295,6 +331,10 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<
  * at runtime, and `Cloudflare.InferEnv` to extract a fully typed
  * `env` object from those bindings.
  *
+ * See the {@link https://alchemy.run/guides/async-worker | Async Workers Guide}
+ * for a comprehensive walkthrough of all binding types (R2, D1,
+ * Durable Objects, Assets, and more).
+ *
  * @example Defining an async Worker in your stack
  * ```typescript
  * // alchemy.run.ts
@@ -579,19 +619,24 @@ export const Worker: Platform<
   WorkerShape,
   WorkerExecutionContext
 > & {
-  <const Bindings extends WorkerBindingProps>(
+  <
+    const Bindings extends WorkerBindingProps,
+    const Assets extends WorkerAssetsConfig | undefined = undefined,
+    Req = never,
+  >(
     id: string,
-    props: InputProps<WorkerProps<Bindings>>,
+    props:
+      | InputProps<WorkerProps<Bindings, Assets>>
+      | Effect.Effect<InputProps<WorkerProps<Bindings, Assets>>, never, Req>,
   ): Effect.Effect<
     Worker<{
-      [B in keyof Bindings]: Bindings[B] extends Effect.Effect<
-        infer T extends WorkerBindingResource,
-        any,
-        any
-      >
-        ? T
-        : Extract<Bindings[B], WorkerBindingResource>;
-    }>
+      [binding in keyof NormalizedBindings<
+        Bindings,
+        Assets
+      >]: NormalizedBindings<Bindings, Assets>[binding];
+    }>,
+    never,
+    Req | Providers
   >;
 } = Platform(WorkerTypeId, {
   onCreate: Effect.fnUntraced(function* (
@@ -608,31 +653,45 @@ export const Worker: Platform<
           ? yield* bindingEff
           : bindingEff;
 
-        const bindingMeta: InputProps<WorkerBinding> | undefined =
-          binding.Type === "Cloudflare.D1Database"
+        const bindingMeta: InputProps<WorkerBinding> | undefined = isAssets(
+          binding,
+        )
+          ? {
+              type: "assets",
+              name: bindingName,
+            }
+          : isDurableObjectNamespaceLike(binding)
             ? {
-                type: "d1",
-                id: binding.databaseId,
+                type: "durable_object_namespace",
                 name: bindingName,
+                className: binding.className ?? binding.name,
               }
-            : binding.Type === "Cloudflare.R2Bucket"
+            : binding.Type === "Cloudflare.D1Database"
               ? {
-                  type: "r2_bucket",
+                  type: "d1",
+                  id: binding.databaseId,
                   name: bindingName,
-                  bucketName: binding.bucketName,
-                  jurisdiction: binding.jurisdiction.pipe(
-                    Output.map((jurisdiction) =>
-                      jurisdiction === "default" ? undefined : jurisdiction,
-                    ),
-                  ),
                 }
-              : // TODO(sam): handle others
-                undefined;
+              : binding.Type === "Cloudflare.R2Bucket"
+                ? {
+                    type: "r2_bucket",
+                    name: bindingName,
+                    bucketName: binding.bucketName,
+                    jurisdiction: binding.jurisdiction.pipe(
+                      Output.map((jurisdiction) =>
+                        jurisdiction === "default" ? undefined : jurisdiction,
+                      ),
+                    ),
+                  }
+                : // TODO(sam): handle others
+                  undefined;
 
         if (bindingMeta) {
           yield* resource.bind`${bindingName}`({
             bindings: [bindingMeta],
           });
+        } else {
+          return yield* Effect.die(`Unknown binding type: ${bindingName}`);
         }
       }
     }
@@ -857,7 +916,6 @@ export const WorkerProvider = () =>
       const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
       const stack = yield* Stack;
 
-      const { read, upload } = yield* Assets.Assets;
       const createScriptSubdomain = yield* workers.createScriptSubdomain;
       const createScriptTail = yield* workers.createScriptTail;
       const deleteScript = yield* workers.deleteScript;
@@ -867,6 +925,10 @@ export const WorkerProvider = () =>
       const getSubdomain = yield* workers.getSubdomain;
       const listScripts = yield* workers.listScripts;
       const putScript = yield* workers.putScript;
+      const putDomain = yield* workers.putDomain;
+      const listDomains = yield* workers.listDomains;
+      const deleteDomain = yield* workers.deleteDomain;
+      const listZones = yield* zones.listZones;
       const telemetry = yield* CloudflareLogs;
       const defaultCompatibilityDate = yield* Effect.promise(() =>
         // @ts-expect-error no types for workerd
@@ -893,6 +955,95 @@ export const WorkerProvider = () =>
               maxLength: 54,
             }).pipe(Effect.map((name) => name.toLowerCase()));
 
+      const normalizeDomains = (
+        domain: string | string[] | undefined,
+      ): string[] =>
+        domain === undefined
+          ? []
+          : Array.isArray(domain)
+            ? Array.from(new Set(domain))
+            : [domain];
+
+      /**
+       * Infer the Cloudflare Zone ID for a given hostname by listing the
+       * account's zones and matching the hostname against each zone's name —
+       * walking up the DNS label hierarchy until a match is found.
+       */
+      const inferZoneIdForHostname = (
+        hostname: string,
+        zoneCache: Map<string, string>,
+      ) =>
+        Effect.gen(function* () {
+          const cached = zoneCache.get(hostname);
+          if (cached) return cached;
+
+          const zoneList = yield* listZones({}).pipe(
+            Effect.map((response) => response.result ?? []),
+          );
+          for (const zone of zoneList) {
+            zoneCache.set(zone.name, zone.id);
+          }
+
+          const parts = hostname.split(".");
+          for (let i = 0; i < parts.length - 1; i++) {
+            const candidate = parts.slice(i).join(".");
+            const match = zoneList.find((z) => z.name === candidate);
+            if (match) {
+              zoneCache.set(hostname, match.id);
+              return match.id;
+            }
+          }
+          return yield* Effect.die(
+            `Could not infer Cloudflare Zone for hostname "${hostname}". ` +
+              "Ensure the parent zone exists in this account.",
+          );
+        });
+
+      const reconcileDomains = (
+        scriptName: string,
+        desired: string[],
+        previous: Worker["Attributes"]["domains"],
+      ) =>
+        Effect.gen(function* () {
+          const desiredSet = new Set(desired);
+          const toRemove = previous.filter((p) => !desiredSet.has(p.hostname));
+          yield* Effect.all(
+            toRemove.map((d) =>
+              deleteDomain({ accountId, domainId: d.id }).pipe(
+                Effect.catchTag("DomainNotFound", () => Effect.void),
+              ),
+            ),
+            { concurrency: "unbounded" },
+          );
+
+          if (desired.length === 0) return [];
+
+          const zoneCache = new Map<string, string>();
+          const applied = yield* Effect.all(
+            desired.map((hostname) =>
+              Effect.gen(function* () {
+                const zoneId = yield* inferZoneIdForHostname(
+                  hostname,
+                  zoneCache,
+                );
+                const res = yield* putDomain({
+                  accountId,
+                  hostname,
+                  service: scriptName,
+                  zoneId,
+                });
+                return {
+                  hostname,
+                  id: res.id ?? "",
+                  zoneId: res.zoneId ?? zoneId,
+                };
+              }),
+            ),
+            { concurrency: "unbounded" },
+          );
+          return applied;
+        });
+
       const createAlchemyWorkerTags = (id: string) => [
         `alchemy:stack:${stack.name}`,
         `alchemy:stage:${stack.stage}`,
@@ -974,7 +1125,9 @@ export const WorkerProvider = () =>
       const prepareAssets = Effect.fnUntraced(function* (
         assets: WorkerProps["assets"],
       ) {
-        if (!assets) return undefined;
+        if (!assets) {
+          return undefined;
+        }
 
         // Handle AssetsWithHash (from Build resource)
         // Props are resolved by Plan, so Input<string> values are already strings at runtime
@@ -983,7 +1136,7 @@ export const WorkerProvider = () =>
           "path" in assets &&
           "hash" in assets
         ) {
-          const result = yield* read({
+          const result = yield* readAssets({
             directory: assets.path as string,
             config: assets.config,
           });
@@ -994,7 +1147,7 @@ export const WorkerProvider = () =>
         }
 
         // Handle string path or AssetsProps
-        return yield* read(
+        return yield* readAssets(
           typeof assets === "string" ? { directory: assets } : assets,
         );
       });
@@ -1065,8 +1218,8 @@ import * as Stream from "effect/Stream";
 import { env, DurableObject${hasWfClasses ? ", WorkflowEntrypoint" : ""} } from "cloudflare:workers";
 import { MinimumLogLevel } from "effect/References";
 import { NodeServices } from "@effect/platform-node";
-import { Stack } from "alchemy-effect/Stack";
-import { WorkerEnvironment, makeDurableObjectBridge${hasWfClasses ? ", makeWorkflowBridge" : ""}, ExportedHandlerMethods } from "alchemy-effect/Cloudflare";
+import { Stack } from "alchemy/Stack";
+import { WorkerEnvironment, makeDurableObjectBridge${hasWfClasses ? ", makeWorkflowBridge" : ""}, ExportedHandlerMethods } from "alchemy/Cloudflare";
 
 import entry from "${importPath}";
 
@@ -1232,7 +1385,7 @@ ${[
         const [assets, bundle] = yield* Effect.all(
           [
             assetsDirectory
-              ? read({
+              ? readAssets({
                   directory: assetsDirectory,
                   config:
                     typeof props.assets === "object" && "config" in props.assets
@@ -1312,7 +1465,12 @@ ${[
             yield* Effect.logInfo(
               `Cloudflare Worker ${olds ? "update" : "create"}: uploading assets for ${name}`,
             );
-            const { jwt } = yield* upload(accountId, name, assets, session);
+            const { jwt } = yield* uploadAssets(
+              accountId,
+              name,
+              assets,
+              session,
+            );
             metadataAssets = {
               jwt,
               config: assets.config,
@@ -1586,6 +1744,18 @@ ${[
           );
           yield* setWorkerSubdomain(name, enable);
         }
+        const desiredDomains = normalizeDomains(news.domain);
+        const previousDomains = output?.domains ?? [];
+        if (desiredDomains.length > 0 || previousDomains.length > 0) {
+          yield* session.note(
+            `Reconciling custom domains (${desiredDomains.length}) ...`,
+          );
+        }
+        const domains = yield* reconcileDomains(
+          name,
+          desiredDomains,
+          previousDomains,
+        );
         return {
           workerId: worker.id ?? name,
           workerName: name,
@@ -1597,6 +1767,7 @@ ${[
           tags: settings.tags ?? metadata.tags,
           durableObjectNamespaces,
           accountId,
+          domains,
           hash,
         } satisfies Worker["Attributes"];
       });
@@ -1642,7 +1813,14 @@ ${[
           if (!output) {
             return;
           }
-          if (yield* hasChanged(id, news, output)) {
+          const newDomains = normalizeDomains(news.domain).sort();
+          const oldDomains = (output?.domains ?? [])
+            .map((d) => d.hostname)
+            .sort();
+          const domainsChanged =
+            newDomains.length !== oldDomains.length ||
+            newDomains.some((d, i) => d !== oldDomains[i]);
+          if (domainsChanged || (yield* hasChanged(id, news, output))) {
             return {
               action: "update",
               stables:
@@ -1771,6 +1949,7 @@ ${[
             tags: existingSettings?.tags ?? tags,
             durableObjectNamespaces,
             accountId,
+            domains: [],
           } satisfies Worker["Attributes"];
         }),
         read: Effect.fnUntraced(
@@ -1780,23 +1959,28 @@ ${[
             yield* Effect.logInfo(
               `Cloudflare Worker read: checking ${workerName}`,
             );
-            const [worker, subdomain, settings] = yield* Effect.all([
-              listScripts({
-                accountId,
-              }).pipe(
-                Effect.map((workers) =>
-                  workers.result.find((worker) => worker.id === workerName),
+            const [worker, subdomain, settings, domainsList] =
+              yield* Effect.all([
+                listScripts({
+                  accountId,
+                }).pipe(
+                  Effect.map((workers) =>
+                    workers.result.find((worker) => worker.id === workerName),
+                  ),
                 ),
-              ),
-              getScriptSubdomain({
-                accountId,
-                scriptName: workerName,
-              }),
-              getScriptSettings({
-                accountId,
-                scriptName: workerName,
-              }),
-            ]);
+                getScriptSubdomain({
+                  accountId,
+                  scriptName: workerName,
+                }),
+                getScriptSettings({
+                  accountId,
+                  scriptName: workerName,
+                }),
+                listDomains({
+                  accountId,
+                  service: workerName,
+                }).pipe(Effect.map((r) => r.result ?? [])),
+              ]);
             if (!worker) {
               yield* Effect.logInfo(
                 `Cloudflare Worker read: ${workerName} not found in script list`,
@@ -1818,6 +2002,11 @@ ${[
               durableObjectNamespaces: getDurableObjectNamespaces(
                 settings.bindings,
               ),
+              domains: domainsList.flatMap((d) =>
+                d.id && d.hostname && d.zoneId
+                  ? [{ id: d.id, hostname: d.hostname, zoneId: d.zoneId }]
+                  : [],
+              ),
             } satisfies Worker["Attributes"];
           },
           (effect) =>
@@ -1919,6 +2108,17 @@ ${[
           yield* Effect.logInfo(
             `Cloudflare Worker delete: deleting ${output.workerName}`,
           );
+          if (output.domains?.length) {
+            yield* Effect.all(
+              output.domains.map((d) =>
+                deleteDomain({
+                  accountId: output.accountId,
+                  domainId: d.id,
+                }).pipe(Effect.catchTag("DomainNotFound", () => Effect.void)),
+              ),
+              { concurrency: "unbounded" },
+            );
+          }
           yield* deleteScript({
             accountId: output.accountId,
             scriptName: output.workerName,

package/src/Cloudflare/Workers/index.ts

@@ -1,12 +1,15 @@
 export * from "./Assets.ts";
 export * from "./ConfigProvider.ts";
 export * from "./DurableObjectNamespace.ts";
+export * from "./DurableObjectState.ts";
+export * from "./DurableObjectStorage.ts";
 export * from "./DynamicWorkerLoader.ts";
 export * from "./Fetch.ts";
 export * from "./HttpServer.ts";
 export * from "./InferEnv.ts";
 export * from "./Request.ts";
 export * from "./Rpc.ts";
+export * from "./ScheduledEvents.ts";
 export * from "./WebSocket.ts";
 export * from "./Worker.ts";
 export * from "./Workflow.ts";

package/src/Construct.ts

@@ -12,8 +12,8 @@ import * as Namespace from "./Namespace.ts";
  * @section Creating Constructs
  * @example Simple Reusable Construct
  * ```typescript
- * import * as Construct from "alchemy-effect/Construct";
- * import { Bucket } from "alchemy-effect/AWS/S3";
+ * import * as Construct from "alchemy/Construct";
+ * import { Bucket } from "alchemy/AWS/S3";
  *
  * export const Logs = Construct.fn(function* (
  *   id: string,

package/src/GitHub/Secret.ts

@@ -53,11 +53,19 @@ export interface Secret extends Resource<
 /**
  * A GitHub Actions repository or environment secret.
  *
+ * `Secret` manages the lifecycle of an encrypted secret in GitHub Actions.
  * Secrets are encrypted using the repository's (or environment's) public
- * key before being stored. The resource is idempotent — calling it with
- * the same name will update the secret value in place.
+ * key via `libsodium` before being stored. The resource is idempotent —
+ * calling it with the same name will update the secret value in place.
+ *
+ * Authentication is resolved in order: explicit `token` prop,
+ * `GITHUB_ACCESS_TOKEN` env var, `GITHUB_TOKEN` env var. The token needs
+ * `repo` scope for private repositories or `public_repo` for public ones.
  *
  * @section Repository Secrets
+ * Store secrets accessible to all GitHub Actions workflows in the
+ * repository.
+ *
  * @example Create a Repository Secret
  * ```typescript
  * yield* GitHub.Secret("aws-role", {
@@ -69,6 +77,10 @@ export interface Secret extends Resource<
  * ```
  *
  * @section Environment Secrets
+ * Scope a secret to a specific GitHub Actions environment (e.g.
+ * `production`, `staging`). Environment secrets require environment
+ * protection rules to be satisfied before workflows can access them.
+ *
  * @example Create an Environment Secret
  * ```typescript
  * yield* GitHub.Secret("deploy-key", {
@@ -79,6 +91,42 @@ export interface Secret extends Resource<
  *   value: Redacted.make("my-secret-value"),
  * });
  * ```
+ *
+ * @section Wiring with Other Resources
+ * A common pattern is wiring the output of another resource — like an
+ * IAM role ARN or a database URL — directly into a GitHub secret so
+ * that CI workflows can use it.
+ *
+ * @example Store an IAM Role ARN for CI
+ * ```typescript
+ * const role = yield* AWS.IAM.Role("ci-role", { ... });
+ *
+ * yield* GitHub.Secret("ci-role-arn", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   name: "AWS_ROLE_ARN",
+ *   value: Redacted.make(role.roleArn),
+ * });
+ * ```
+ *
+ * @example Store Multiple Secrets
+ * ```typescript
+ * yield* GitHub.Secret("db-url", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   environment: "production",
+ *   name: "DATABASE_URL",
+ *   value: Redacted.make(database.connectionString),
+ * });
+ *
+ * yield* GitHub.Secret("api-key", {
+ *   owner: "my-org",
+ *   repository: "my-repo",
+ *   environment: "production",
+ *   name: "API_KEY",
+ *   value: Redacted.make(apiKey),
+ * });
+ * ```
  */
 export const Secret = Resource<Secret>("GitHub.Secret");
 
@@ -98,10 +146,7 @@ async function encryptValue(
 ): Promise<string> {
   const sodium = await import("libsodium-wrappers");
   await sodium.ready;
-  const binKey = sodium.from_base64(
-    publicKey,
-    sodium.base64_variants.ORIGINAL,
-  );
+  const binKey = sodium.from_base64(publicKey, sodium.base64_variants.ORIGINAL);
   const binMessage = sodium.from_string(plaintext);
   const encrypted = sodium.crypto_box_seal(binMessage, binKey);
   return sodium.to_base64(encrypted, sodium.base64_variants.ORIGINAL);
@@ -115,7 +160,7 @@ export const SecretProvider = () =>
       return { updatedAt: new Date().toISOString() };
     }),
 
-    update: Effect.fn(function* ({ news, olds, output }) {
+    update: Effect.fn(function* ({ news, olds }) {
       const octokit = createClient(news);
 
       const wasEnv = !!olds.environment;