alchemy 0.5.2 → 0.7.0

package/src/cloudflare/worker.ts

@@ -3,28 +3,28 @@ import * as fs from "fs/promises";
 import type { Context } from "../context";
 import { Bundle, type BundleProps } from "../esbuild/bundle";
 import { Resource } from "../resource";
-import { isSecret } from "../secret";
 import { getContentType } from "../util/content-type";
 import { withExponentialBackoff } from "../util/retry";
 import { slugify } from "../util/slugify";
-import { type CloudflareApi, createCloudflareApi } from "./api";
-import type { Assets } from "./assets";
 import {
-  type Bindings,
-  type WorkerBindingSpec,
-  isAssets,
-  isDurableObjectNamespace,
-} from "./bindings";
+  createCloudflareApi,
+  type CloudflareApi,
+  type CloudflareApiOptions,
+} from "./api";
+import { type Assets } from "./assets";
+import { type Bindings, type WorkerBindingSpec } from "./bindings";
 import type { Bound } from "./bound";
-import type { DurableObjectNamespace } from "./durable-object-namespace";
+import { type DurableObjectNamespace } from "./durable-object-namespace";
 import { isKVNamespace } from "./kv-namespace";
 import type { WorkerScriptMetadata } from "./worker-metadata";
 import type { SingleStepMigration } from "./worker-migration";
+import { upsertWorkflow, type Workflow } from "./workflow";
 
 /**
  * Properties for creating or updating a Worker
  */
-export interface WorkerProps<B extends Bindings = Bindings> {
+export interface WorkerProps<B extends Bindings = Bindings>
+  extends CloudflareApiOptions {
   /**
    * The worker script content (JavaScript or WASM)
    * One of script, entryPoint, or bundle must be provided
@@ -58,12 +58,6 @@ export interface WorkerProps<B extends Bindings = Bindings> {
    */
   name: string;
 
-  /**
-   * Routes to associate with this worker
-   * Format: example.com/* or *.example.com/*
-   */
-  routes?: string[];
-
   /**
    * Bindings to attach to the worker
    */
@@ -236,7 +230,7 @@ export const Worker = Resource(
     props: WorkerProps<B>
   ): Promise<Worker<B>> {
     // Create Cloudflare API client with automatic account discovery
-    const api = await createCloudflareApi();
+    const api = await createCloudflareApi(props);
 
     // Use the provided name
     const workerName = props.name;
@@ -262,10 +256,16 @@ export const Worker = Resource(
 
     // Find any assets bindings
     const assetsBindings: { name: string; assets: Assets }[] = [];
+    const workflowsBindings: Workflow[] = [];
+
     if (props.bindings) {
       for (const [bindingName, binding] of Object.entries(props.bindings)) {
-        if (isAssets(binding)) {
-          assetsBindings.push({ name: bindingName, assets: binding });
+        if (typeof binding === "object") {
+          if (binding.type === "assets") {
+            assetsBindings.push({ name: bindingName, assets: binding });
+          } else if (binding.type === "workflow") {
+            workflowsBindings.push(binding);
+          }
         }
       }
     }
@@ -293,15 +293,19 @@ export const Worker = Resource(
       assetUploadResult
     );
 
-    // Upload the worker script
     await putWorker(api, workerName, scriptContent, scriptMetadata);
 
+    for (const workflow of workflowsBindings) {
+      await upsertWorkflow(api, {
+        workflowName: workflow.workflowName,
+        className: workflow.className,
+        scriptName: workerName,
+      });
+    }
+
     // TODO: it is less than ideal that this can fail, resulting in state problem
     await this.set("bindings", props.bindings);
 
-    // Handle routes if requested
-    await setupRoutes(api, workerName, props.routes || []);
-
     // Handle worker URL if requested
     const workerUrl = await configureURL(
       this,
@@ -320,7 +324,6 @@ export const Worker = Resource(
       name: workerName,
       script: scriptContent,
       format: props.format || "esm", // Include format in the output
-      routes: props.routes || [],
       bindings: props.bindings ?? ({} as B),
       env: props.env,
       observability: scriptMetadata.observability,
@@ -354,35 +357,6 @@ async function deleteWorker<B extends Bindings>(
     );
   }
 
-  // Also remove any associated routes if they exist
-  if (ctx.output?.routes && ctx.output.routes.length > 0 && api.zoneId) {
-    // First get existing routes to find their IDs
-    const routesResponse = await api.get(`/zones/${api.zoneId}/workers/routes`);
-
-    if (!routesResponse.ok) {
-      throw new Error(
-        `Could not fetch routes for cleanup: ${routesResponse.status} ${routesResponse.statusText}`
-      );
-    }
-    const routesData: any = await routesResponse.json();
-    const existingRoutes = routesData.result || [];
-
-    for (const route of existingRoutes) {
-      if (ctx.output.routes.includes(route.pattern)) {
-        // Delete the route
-        const routeDeleteResponse = await api.delete(
-          `/zones/${api.zoneId}/workers/routes/${route.id}`
-        );
-
-        if (!routeDeleteResponse.ok) {
-          console.warn(
-            `Failed to delete route ${route.pattern}: ${routeDeleteResponse.status} ${routeDeleteResponse.statusText}`
-          );
-        }
-      }
-    }
-  }
-
   // Disable the URL if it was enabled
   if (ctx.output?.url) {
     try {
@@ -566,60 +540,79 @@ async function prepareWorkerMetadata<B extends Bindings>(
         service: binding.id,
       });
     } else if (binding.type === "durable_object_namespace") {
-      const stableId = binding.id;
-      const className = binding.className;
-
       meta.bindings.push({
         type: "durable_object_namespace",
         name: bindingName,
-        class_name: className,
+        class_name: binding.className,
         script_name: binding.scriptName,
         environment: binding.environment,
         namespace_id: binding.namespaceId,
       });
-
-      const oldBinding: DurableObjectNamespace | undefined = Object.values(
-        oldBindings ?? {}
-      )
-        ?.filter(isDurableObjectNamespace)
-        ?.find((b) => b.id === stableId);
-
-      if (!oldBinding) {
-        if (binding.sqlite) {
-          meta.migrations!.new_sqlite_classes!.push(className);
-        } else {
-          meta.migrations!.new_classes!.push(className);
-        }
-      } else if (oldBinding.className !== className) {
-        meta.migrations!.renamed_classes!.push({
-          from: oldBinding.className,
-          to: className,
-        });
-      }
+      configureClassMigration(binding, binding.id, binding.className);
     } else if (binding.type === "r2_bucket") {
       meta.bindings.push({
         type: "r2_bucket",
         name: bindingName,
         bucket_name: binding.name,
       });
-    } else if (isAssets(binding)) {
+    } else if (binding.type === "assets") {
       meta.bindings.push({
         type: "assets",
         name: bindingName,
       });
-    } else if (isSecret(binding)) {
+    } else if (binding.type === "secret") {
       meta.bindings.push({
         type: "secret_text",
         name: bindingName,
         text: binding.unencrypted,
       });
+    } else if (binding.type === "workflow") {
+      meta.bindings.push({
+        type: "workflow",
+        name: bindingName,
+        workflow_name: binding.workflowName,
+        class_name: binding.className,
+        // this should be set if the Workflow is in another script ...
+        // script_name: ??,
+      });
+      // it's unclear whether this is needed, but it works both ways
+      configureClassMigration(binding, binding.id, binding.className);
     } else {
       // @ts-expect-error - we should never reach here
       throw new Error(`Unsupported binding type: ${binding.type}`);
     }
   }
 
+  function configureClassMigration(
+    binding: DurableObjectNamespace | Workflow,
+    stableId: string,
+    className: string
+  ) {
+    const oldBinding: DurableObjectNamespace | Workflow | undefined =
+      Object.values(oldBindings ?? {})
+        ?.filter(
+          (b) =>
+            typeof b === "object" &&
+            (b.type === "durable_object_namespace" || b.type === "workflow")
+        )
+        ?.find((b) => b.id === stableId);
+
+    if (!oldBinding) {
+      if (binding.type === "durable_object_namespace" && binding.sqlite) {
+        meta.migrations!.new_sqlite_classes!.push(className);
+      } else {
+        meta.migrations!.new_classes!.push(className);
+      }
+    } else if (oldBinding.className !== className) {
+      meta.migrations!.renamed_classes!.push({
+        from: oldBinding.className,
+        to: className,
+      });
+    }
+  }
+
   // Convert env variables to plain_text bindings
+  // TODO(sam): remove Worker.env in favor of always bindings
   if (props.env) {
     for (const [key, value] of Object.entries(props.env)) {
       meta.bindings.push({
@@ -717,67 +710,6 @@ async function bundleWorkerScript<B extends Bindings>(props: WorkerProps) {
   }
 }
 
-async function setupRoutes(
-  api: CloudflareApi,
-  workerName: string,
-  routes: string[]
-) {
-  // Set up routes if provided
-  if (routes && routes.length > 0 && api.zoneId) {
-    // First get existing routes
-    const routesResponse = await api.get(`/zones/${api.zoneId}/workers/routes`);
-
-    if (!routesResponse.ok) {
-      throw new Error(
-        `Could not fetch routes: ${routesResponse.status} ${routesResponse.statusText}`
-      );
-    }
-    const routesData: any = await routesResponse.json();
-    const existingRoutes = routesData.result || [];
-
-    // For each desired route
-    for (const pattern of routes) {
-      const existingRoute = existingRoutes.find(
-        (r: any) => r.pattern === pattern
-      );
-
-      if (existingRoute) {
-        // Update if script name doesn't match
-        if (existingRoute.script !== workerName) {
-          const updateRouteResponse = await api.put(
-            `/zones/${api.zoneId}/workers/routes/${existingRoute.id}`,
-            {
-              pattern,
-              script: workerName,
-            }
-          );
-
-          if (!updateRouteResponse.ok) {
-            console.warn(
-              `Failed to update route ${pattern}: ${updateRouteResponse.status} ${updateRouteResponse.statusText}`
-            );
-          }
-        }
-      } else {
-        // Create new route
-        const createRouteResponse = await api.post(
-          `/zones/${api.zoneId}/workers/routes`,
-          {
-            pattern,
-            script: workerName,
-          }
-        );
-
-        if (!createRouteResponse.ok) {
-          throw new Error(
-            `Failed to create route ${pattern}: ${createRouteResponse.status} ${createRouteResponse.statusText}`
-          );
-        }
-      }
-    }
-  }
-}
-
 async function configureURL<B extends Bindings>(
   ctx: Context<Worker<B>>,
   api: CloudflareApi,
@@ -1006,8 +938,6 @@ async function uploadAssets(
       formData.append(fileHash, blob, fileHash);
     }
 
-    console.log(`Uploading ${totalBytes} bytes of assets`);
-
     // Upload this batch of files
     const uploadResponse = await api.post(
       `/accounts/${api.accountId}/workers/assets/upload?base64=true`,

package/src/cloudflare/workflow.ts

@@ -0,0 +1,79 @@
+import type { CloudflareApi } from "./api";
+import { handleApiError } from "./api-error";
+
+export interface WorkflowProps {
+  /**
+   * Name of the workflow
+   *
+   * @maxLength 64
+   * @minLength 1
+   * @default - className if provided, otherwise id
+   */
+  workflowName?: string;
+  /**
+   * Name of the class that implements the workflow
+   *
+   * @maxLength 255
+   * @minLength 1
+   * @default - workflowName if provided, otherwise id
+   */
+  className?: string;
+}
+
+export class Workflow<PARAMS = unknown> {
+  public readonly type: "workflow" = "workflow";
+  /**
+   * Phantom property to preserve workflow params at the type level.
+   *
+   * No value exists.
+   */
+  public readonly _PARAMS: PARAMS = undefined!;
+
+  public readonly workflowName: string;
+  public readonly className: string;
+
+  constructor(
+    public readonly id: string,
+    props: WorkflowProps = {}
+  ) {
+    this.workflowName = props.workflowName ?? props.className ?? id;
+    this.className = props.className ?? this.workflowName;
+  }
+}
+
+export interface WorkflowMetadata {
+  id: string; // uuid
+  class_name: string;
+  created_on: string; // date-time
+  modified_on: string; // date-time
+  name: string; // maxLength: 64, minLength: 1
+  script_name: string;
+  triggered_on: string; // date-time
+  version_id: string; // uuid
+}
+
+export async function upsertWorkflow(
+  api: CloudflareApi,
+  props: WorkflowProps & {
+    workflowName: string;
+    scriptName: string;
+  }
+) {
+  const response = await api.put(
+    `/accounts/${api.accountId}/workflows/${props.workflowName}`,
+    {
+      class_name: props.className,
+      script_name: props.scriptName,
+    }
+  );
+
+  if (!response.ok) {
+    await handleApiError(response, "create", "workflow", props.workflowName);
+  }
+
+  const body = (await response.json()) as {
+    result: WorkflowMetadata;
+  };
+
+  return body.result;
+}

package/src/cloudflare/zone.ts

@@ -1,6 +1,6 @@
 import type { Context } from "../context";
 import { Resource } from "../resource";
-import { createCloudflareApi } from "./api";
+import { createCloudflareApi, type CloudflareApiOptions } from "./api";
 import type {
   AlwaysUseHTTPSValue,
   AutomaticHTTPSRewritesValue,
@@ -24,18 +24,12 @@ import type {
 /**
  * Properties for creating or updating a Zone
  */
-export interface ZoneProps {
+export interface ZoneProps extends CloudflareApiOptions {
   /**
    * The domain name for the zone
    */
   name: string;
 
-  /**
-   * Account ID to use for the zone
-   * If not provided, will use the default account
-   */
-  accountId?: string;
-
   /**
    * The type of zone to create
    * "full" - Full zone implies that DNS is hosted with Cloudflare
@@ -305,12 +299,10 @@ export const Zone = Resource(
   async function (
     this: Context<Zone>,
     id: string,
-    props: ZoneProps,
+    props: ZoneProps
   ): Promise<Zone> {
     // Create Cloudflare API client with automatic account discovery
-    const api = await createCloudflareApi({
-      accountId: props.accountId,
-    });
+    const api = await createCloudflareApi(props);
 
     if (this.phase === "delete") {
       if (this.output?.id) {
@@ -322,7 +314,7 @@ export const Zone = Resource(
             errors: [{ message: deleteResponse.statusText }],
           }));
           throw new Error(
-            `Error deleting zone '${props.name}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`,
+            `Error deleting zone '${props.name}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`
           );
         }
       } else {
@@ -337,7 +329,7 @@ export const Zone = Resource(
 
       if (!response.ok) {
         throw new Error(
-          `Error getting zone '${props.name}': ${response.statusText}`,
+          `Error getting zone '${props.name}': ${response.statusText}`
         );
       }
 
@@ -385,13 +377,13 @@ export const Zone = Resource(
         if (response.status === 400 && body.includes("already exists")) {
           // Zone already exists, fetch it instead
           console.warn(
-            `Zone '${props.name}' already exists during Zone create, adopting it...`,
+            `Zone '${props.name}' already exists during Zone create, adopting it...`
           );
           const getResponse = await api.get(`/zones?name=${props.name}`);
 
           if (!getResponse.ok) {
             throw new Error(
-              `Error fetching existing zone '${props.name}': ${getResponse.statusText}`,
+              `Error fetching existing zone '${props.name}': ${getResponse.statusText}`
             );
           }
 
@@ -400,13 +392,13 @@ export const Zone = Resource(
           ).result;
           if (zones.length === 0) {
             throw new Error(
-              `Zone '${props.name}' does not exist, but the name is reserved for another user.`,
+              `Zone '${props.name}' does not exist, but the name is reserved for another user.`
             );
           }
           zoneData = zones[0];
         } else {
           throw new Error(
-            `Error creating zone '${props.name}': ${response.statusText}\n${body}`,
+            `Error creating zone '${props.name}': ${response.statusText}\n${body}`
           );
         }
       } else {
@@ -437,7 +429,7 @@ export const Zone = Resource(
         settings: await getZoneSettings(api, zoneData.id),
       });
     }
-  },
+  }
 );
 
 /**
@@ -446,7 +438,7 @@ export const Zone = Resource(
 async function updateZoneSettings(
   api: any,
   zoneId: string,
-  settings: ZoneProps["settings"],
+  settings: ZoneProps["settings"]
 ): Promise<void> {
   if (!settings) return;
 
@@ -480,7 +472,7 @@ async function updateZoneSettings(
           `/zones/${zoneId}/settings/${settingId}`,
           {
             value,
-          } as UpdateZoneSettingParams,
+          } as UpdateZoneSettingParams
         );
 
         if (!response.ok) {
@@ -490,10 +482,10 @@ async function updateZoneSettings(
             return;
           }
           throw new Error(
-            `Failed to update zone setting ${key}: ${response.statusText}`,
+            `Failed to update zone setting ${key}: ${response.statusText}`
           );
         }
-      }),
+      })
   );
 }
 
@@ -502,13 +494,13 @@ async function updateZoneSettings(
  */
 async function getZoneSettings(
   api: any,
-  zoneId: string,
+  zoneId: string
 ): Promise<Zone["settings"]> {
   const settingsResponse = await api.get(`/zones/${zoneId}/settings`);
 
   if (!settingsResponse.ok) {
     throw new Error(
-      `Failed to fetch zone settings: ${settingsResponse.status} ${settingsResponse.statusText}`,
+      `Failed to fetch zone settings: ${settingsResponse.status} ${settingsResponse.statusText}`
     );
   }
 

package/src/internal/docs/providers.ts

@@ -67,13 +67,6 @@ export async function Providers({
     .filter((dirent) => dirent.isDirectory() && !exclude.includes(dirent.name))
     .map((dirent) => path.join(dirent.parentPath, dirent.name));
 
-  // For each provider, list all files
-  if (filter === false) {
-    return [];
-  } else if (typeof filter === "number") {
-    providers = providers.slice(0, filter);
-  }
-
   if (parallel) {
     return await Promise.all(
       providers.map((provider) =>
@@ -152,7 +145,7 @@ async function generateProviderDocs({
       The ${provider} Service has the following resources:
       ${alchemy.files(files)}
 
-      A file is considered a "Resource" if it contains a const <ResourceName> = Resource(...) call or if it is a function that calls a Resource function, e.g. const TypeScriptFile = () => File(...).
+      A file is considered a "Resource" if it contains a const <ResourceName> = Resource(...) call or if it is a function that calls a Resource function, e.g. const TypeScriptFile = () => File(...), or it is the Workflow or DurableObject classes.
       A file is considered a "Client" if it exposes a wrapper around creating a SDK client or fetch.
       A file is considered a "Utility" if it contains utility functions that are not resources or clients.
       A file is considered a "Types" if it contains just type definitions and maybe helpers around working with those types.