alchemy 0.15.4 → 0.15.6

package/src/cloudflare/kv-namespace.ts

@@ -3,8 +3,8 @@ import { Resource } from "../resource.js";
 import { withExponentialBackoff } from "../util/retry.js";
 import { handleApiError } from "./api-error.js";
 import {
-  type CloudflareApi,
   createCloudflareApi,
+  type CloudflareApi,
   type CloudflareApiOptions,
 } from "./api.js";
 
@@ -22,6 +22,22 @@ export interface KVNamespaceProps extends CloudflareApiOptions {
    * Only used for initial setup or updates
    */
   values?: KVPair[];
+
+  /**
+   * Whether to adopt an existing namespace with the same title if it exists
+   * If true and a namespace with the same title exists, it will be adopted rather than creating a new one
+   *
+   * @default false
+   */
+  adopt?: boolean;
+
+  /**
+   * Whether to delete the namespace.
+   * If set to false, the namespace will remain but the resource will be removed from state
+   *
+   * @default true
+   */
+  delete?: boolean;
 }
 
 /**
@@ -112,6 +128,24 @@ export interface KVNamespace
  *     }
  *   }]
  * });
+ *
+ * @example
+ * // Adopt an existing namespace if it already exists instead of failing
+ * const existingNamespace = await KVNamespace("existing-ns", {
+ *   title: "existing-namespace",
+ *   adopt: true,
+ *   values: [{
+ *     key: "config",
+ *     value: { setting: "updated-value" }
+ *   }]
+ * });
+ *
+ * @example
+ * // When removing from Alchemy state, keep the namespace in Cloudflare
+ * const preservedNamespace = await KVNamespace("preserve-ns", {
+ *   title: "preserved-namespace",
+ *   delete: false
+ * });
  */
 export const KVNamespace = Resource(
   "cloudflare::KVNamespace",
@@ -126,7 +160,7 @@ export const KVNamespace = Resource(
     if (this.phase === "delete") {
       // For delete operations, we need to check if the namespace ID exists in the output
       const namespaceId = this.output?.namespaceId;
-      if (namespaceId) {
+      if (namespaceId && props.delete !== false) {
         await deleteKVNamespace(api, namespaceId);
       }
 
@@ -145,10 +179,39 @@ export const KVNamespace = Resource(
     if (this.phase === "update" && namespaceId) {
       // Can't update a KV namespace title directly, just work with existing ID
     } else {
-      // TODO: if it already exists, then check the tags to see if we own it and continue
-      const { id } = await createKVNamespace(api, props);
-      createdAt = Date.now();
-      namespaceId = id;
+      try {
+        // Try to create the KV namespace
+        const { id } = await createKVNamespace(api, props);
+        createdAt = Date.now();
+        namespaceId = id;
+      } catch (error) {
+        // Check if this is a "namespace already exists" error and adopt is enabled
+        if (
+          props.adopt &&
+          error instanceof Error &&
+          error.message.includes("already exists")
+        ) {
+          console.log(`Namespace '${props.title}' already exists, adopting it`);
+          // Find the existing namespace by title
+          const existingNamespace = await findKVNamespaceByTitle(
+            api,
+            props.title,
+          );
+
+          if (!existingNamespace) {
+            throw new Error(
+              `Failed to find existing namespace '${props.title}' for adoption`,
+            );
+          }
+
+          // Use the existing namespace ID
+          namespaceId = existingNamespace.id;
+          createdAt = existingNamespace.createdAt || Date.now();
+        } else {
+          // Re-throw the error if adopt is false or it's not a "namespace already exists" error
+          throw error;
+        }
+      }
     }
 
     await insertKVRecords(api, namespaceId, props);
@@ -232,37 +295,100 @@ export async function insertKVRecords(
         return item;
       });
 
-      try {
-        await withExponentialBackoff(
-          async () => {
-            const bulkResponse = await api.put(
-              `/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
-              bulkPayload,
-            );
+      await withExponentialBackoff(
+        async () => {
+          const bulkResponse = await api.put(
+            `/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
+            bulkPayload,
+          );
+
+          if (!bulkResponse.ok) {
+            const errorData: any = await bulkResponse.json().catch(() => ({
+              errors: [{ message: bulkResponse.statusText }],
+            }));
+            const errorMessage =
+              errorData.errors?.[0]?.message || bulkResponse.statusText;
+
+            // Throw error to trigger retry
+            throw new Error(`Error writing KV batch: ${errorMessage}`);
+          }
+
+          return bulkResponse;
+        },
+        (error) => {
+          // Retry on "namespace not found" errors as they're likely propagation delays
+          return error.message?.includes("not found");
+        },
+        5, // 5 retry attempts
+        1000, // Start with 1 second delay
+      );
+    }
+  }
+}
 
-            if (!bulkResponse.ok) {
-              const errorData: any = await bulkResponse.json().catch(() => ({
-                errors: [{ message: bulkResponse.statusText }],
-              }));
-              const errorMessage =
-                errorData.errors?.[0]?.message || bulkResponse.statusText;
-
-              // Throw error to trigger retry
-              throw new Error(`Error writing KV batch: ${errorMessage}`);
-            }
-
-            return bulkResponse;
-          },
-          (error) => {
-            // Retry on "namespace not found" errors as they're likely propagation delays
-            return error.message?.includes("not found");
-          },
-          5, // 5 retry attempts
-          1000, // Start with 1 second delay
-        );
-      } catch (error: any) {
-        console.warn(error.message);
-      }
+/**
+ * Interface representing a KV namespace as returned by Cloudflare API
+ */
+interface CloudflareKVNamespace {
+  id: string;
+  title: string;
+  supports_url_encoding?: boolean;
+  created_on?: string;
+}
+
+/**
+ * Find a KV namespace by title with pagination support
+ */
+export async function findKVNamespaceByTitle(
+  api: CloudflareApi,
+  title: string,
+): Promise<{ id: string; createdAt?: number } | null> {
+  let page = 1;
+  const perPage = 100; // Maximum allowed by API
+  let hasMorePages = true;
+
+  while (hasMorePages) {
+    const response = await api.get(
+      `/accounts/${api.accountId}/storage/kv/namespaces?page=${page}&per_page=${perPage}`,
+    );
+
+    if (!response.ok) {
+      await handleApiError(response, "list", "kv_namespace", "all");
     }
+
+    const data = (await response.json()) as {
+      result: CloudflareKVNamespace[];
+      result_info: {
+        count: number;
+        page: number;
+        per_page: number;
+        total_count: number;
+      };
+      success: boolean;
+      errors: any[];
+    };
+
+    const namespaces = data.result;
+    const resultInfo = data.result_info;
+
+    // Look for a namespace with matching title
+    const match = namespaces.find((ns) => ns.title === title);
+    if (match) {
+      return {
+        id: match.id,
+        // Convert ISO string to timestamp if available, otherwise use current time
+        createdAt: match.created_on
+          ? new Date(match.created_on).getTime()
+          : undefined,
+      };
+    }
+
+    // Check if we've seen all pages
+    hasMorePages =
+      resultInfo.page * resultInfo.per_page < resultInfo.total_count;
+    page++;
   }
+
+  // No matching namespace found
+  return null;
 }

package/src/cloudflare/route.ts

@@ -0,0 +1,268 @@
+import type { Context } from "../context.js";
+import { Resource } from "../resource.js";
+import { CloudflareApiError, handleApiError } from "./api-error.js";
+import {
+  createCloudflareApi,
+  type CloudflareApi,
+  type CloudflareApiOptions,
+} from "./api.js";
+import type { Worker } from "./worker.js";
+
+/**
+ * Properties for creating or updating a Route
+ */
+export interface RouteProps extends CloudflareApiOptions {
+  /**
+   * URL pattern for the route
+   * @example "example.com/*"
+   */
+  pattern: string;
+
+  /**
+   * Worker script for the route
+   * This can be a Worker resource or script name as a string
+   */
+  script: Worker | string;
+
+  /**
+   * Zone ID for the route
+   */
+  zoneId: string;
+}
+
+/**
+ * Output returned after Route creation/update
+ */
+export interface Route extends Resource<"cloudflare::Route">, RouteProps {
+  /**
+   * The unique ID of the route
+   */
+  id: string;
+
+  /**
+   * The URL pattern for the route
+   */
+  pattern: string;
+
+  /**
+   * The Worker script name for the route
+   */
+  script: string;
+
+  /**
+   * The Zone ID for the route
+   */
+  zoneId: string;
+}
+
+/**
+ * Creates and manages Cloudflare Worker Routes.
+ *
+ * Routes map URL patterns to Worker scripts, allowing you to control which
+ * requests are handled by your Workers.
+ *
+ * @example
+ * // Create a route that maps all requests on a domain to a Worker
+ * const basicRoute = await Route("main-route", {
+ *   pattern: "example.com/*",
+ *   script: "my-worker",
+ *   zoneId: "your-zone-id"
+ * });
+ *
+ * @example
+ * // Create a route using a Worker resource
+ * const worker = await Worker("api-worker", {
+ *   script: `
+ *     export default {
+ *       fetch(request, env) {
+ *         return new Response("Hello from API!");
+ *       }
+ *     }
+ *   `
+ * });
+ *
+ * const apiRoute = await Route("api-route", {
+ *   pattern: "api.example.com/*",
+ *   script: worker,
+ *   zoneId: "your-zone-id"
+ * });
+ *
+ * @see https://developers.cloudflare.com/workers/configuration/routes/
+ */
+export const Route = Resource(
+  "cloudflare::Route",
+  async function (
+    this: Context<Route>,
+    id: string,
+    props: RouteProps,
+  ): Promise<Route> {
+    const api = await createCloudflareApi(props);
+
+    // Get script name from script prop (either a string or a Worker resource)
+    const scriptName =
+      typeof props.script === "string" ? props.script : props.script.name;
+
+    // Get zone ID from props
+    const { zoneId } = props;
+
+    if (this.phase === "delete") {
+      console.log("Deleting Route:", props.pattern);
+
+      // Only delete if we have an ID
+      if (this.output?.id) {
+        await deleteRoute(api, zoneId, this.output.id);
+      }
+
+      // Return void (a deleted route has no content)
+      return this.destroy();
+    }
+
+    let routeData: CloudflareRouteResponse;
+
+    if (this.phase === "update" && this.output?.id) {
+      console.log("Updating Route:", props.pattern);
+
+      // Update existing route
+      routeData = await updateRoute(
+        api,
+        zoneId,
+        this.output.id,
+        props.pattern,
+        scriptName,
+      );
+    } else {
+      console.log("Creating Route:", props.pattern);
+
+      // Create new route
+      routeData = await createRoute(api, zoneId, props.pattern, scriptName);
+    }
+
+    // Return the route resource
+    return this({
+      id: routeData.result.id,
+      pattern: routeData.result.pattern,
+      script: routeData.result.script,
+      zoneId,
+    });
+  },
+);
+
+interface CloudflareRouteResponse {
+  result: {
+    id: string;
+    pattern: string;
+    script: string;
+  };
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+}
+
+/**
+ * Create a new route
+ */
+async function createRoute(
+  api: CloudflareApi,
+  zoneId: string,
+  pattern: string,
+  script: string,
+): Promise<CloudflareRouteResponse> {
+  const createResponse = await api.post(`/zones/${zoneId}/workers/routes`, {
+    pattern,
+    script,
+  });
+
+  if (!createResponse.ok) {
+    return await handleApiError(createResponse, "creating", "Route", pattern);
+  }
+
+  return (await createResponse.json()) as CloudflareRouteResponse;
+}
+
+/**
+ * Update a route
+ */
+async function updateRoute(
+  api: CloudflareApi,
+  zoneId: string,
+  routeId: string,
+  pattern: string,
+  script: string,
+): Promise<CloudflareRouteResponse> {
+  const updateResponse = await api.put(
+    `/zones/${zoneId}/workers/routes/${routeId}`,
+    {
+      pattern,
+      script,
+    },
+  );
+
+  if (!updateResponse.ok) {
+    return await handleApiError(updateResponse, "updating", "Route", pattern);
+  }
+
+  return (await updateResponse.json()) as CloudflareRouteResponse;
+}
+
+/**
+ * Delete a route
+ */
+async function deleteRoute(
+  api: CloudflareApi,
+  zoneId: string,
+  routeId: string,
+): Promise<void> {
+  const deleteResponse = await api.delete(
+    `/zones/${zoneId}/workers/routes/${routeId}`,
+  );
+
+  if (!deleteResponse.ok && deleteResponse.status !== 404) {
+    const errorData: any = await deleteResponse.json().catch(() => ({
+      errors: [{ message: deleteResponse.statusText }],
+    }));
+
+    throw new CloudflareApiError(
+      `Error deleting Route '${routeId}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`,
+      deleteResponse,
+    );
+  }
+}
+
+/**
+ * Get a route by ID
+ */
+export async function getRoute(
+  api: CloudflareApi,
+  zoneId: string,
+  routeId: string,
+): Promise<CloudflareRouteResponse> {
+  const response = await api.get(`/zones/${zoneId}/workers/routes/${routeId}`);
+
+  if (!response.ok) {
+    throw new CloudflareApiError(
+      `Failed to get route ${routeId}: ${response.statusText}`,
+      response,
+    );
+  }
+
+  return (await response.json()) as CloudflareRouteResponse;
+}
+
+/**
+ * List all routes for a zone
+ */
+export async function listRoutes(
+  api: CloudflareApi,
+  zoneId: string,
+): Promise<CloudflareRouteResponse> {
+  const response = await api.get(`/zones/${zoneId}/workers/routes`);
+
+  if (!response.ok) {
+    throw new CloudflareApiError(
+      `Failed to list routes: ${response.statusText}`,
+      response,
+    );
+  }
+
+  return (await response.json()) as CloudflareRouteResponse;
+}

package/src/cloudflare/worker.ts

@@ -275,6 +275,12 @@ export interface Worker<B extends Bindings = Bindings>
  *   url: true
  * });
  *
+ * await Route("route", {
+ *   zoneId: zone.zoneId,
+ *   worker: api,
+ *   pattern: "api.example.com/*",
+ * });
+ *
  * @example
  * // Create a real-time chat worker using Durable Objects
  * // for state management:

package/src/cloudflare/wrangler.json.ts

@@ -95,7 +95,7 @@ export const WranglerJson = Resource(
 
     // Process bindings if they exist
     if (worker.bindings) {
-      processBindings(spec, worker.bindings, worker.eventSources);
+      processBindings(spec, worker.bindings, worker.eventSources, worker.name);
     }
 
     // Add environment variables as vars
@@ -170,6 +170,10 @@ export interface WranglerJsonSpec {
   kv_namespaces?: {
     binding: string;
     id: string;
+    /**
+     * The ID of the KV namespace used during `wrangler dev`
+     */
+    preview_id?: string;
   }[];
 
   /**
@@ -190,6 +194,10 @@ export interface WranglerJsonSpec {
   r2_buckets?: {
     binding: string;
     bucket_name: string;
+    /**
+     * The preview name of this R2 bucket at the edge.
+     */
+    preview_bucket_name?: string;
   }[];
 
   /**
@@ -246,6 +254,10 @@ export interface WranglerJsonSpec {
     database_id: string;
     database_name: string;
     migrations_dir?: string;
+    /**
+     * The ID of the D1 database used during `wrangler dev`
+     */
+    preview_database_id?: string;
   }[];
 
   /**
@@ -256,6 +268,15 @@ export interface WranglerJsonSpec {
     binding: string;
   };
 
+  /**
+   * Migrations
+   */
+  migrations?: {
+    tag: string;
+    new_sqlite_classes?: string[];
+    new_classes?: string[];
+  }[];
+
   /**
    * Workflow bindings
    */
@@ -279,6 +300,7 @@ function processBindings(
   spec: WranglerJsonSpec,
   bindings: Bindings,
   eventSources: EventSource[] | undefined,
+  workerName: string,
 ): void {
   // Arrays to collect different binding types
   const kvNamespaces: { binding: string; id: string }[] = [];
@@ -314,6 +336,9 @@ function processBindings(
     consumers: [],
   };
 
+  const new_sqlite_classes: string[] = [];
+  const new_classes: string[] = [];
+
   const vectorizeIndexes: { binding: string; index_name: string }[] = [];
 
   for (const eventSource of eventSources ?? []) {
@@ -344,7 +369,7 @@ function processBindings(
       // Self(service) binding
       services.push({
         binding: bindingName,
-        service: bindingName,
+        service: workerName,
       });
     } else if (binding.type === "service") {
       // Service binding
@@ -370,6 +395,11 @@ function processBindings(
         script_name: doBinding.scriptName,
         environment: doBinding.environment,
       });
+      if (doBinding.sqlite) {
+        new_sqlite_classes.push(doBinding.className);
+      } else {
+        new_classes.push(doBinding.className);
+      }
     } else if (binding.type === "r2_bucket") {
       r2Buckets.push({
         binding: bindingName,
@@ -453,4 +483,14 @@ function processBindings(
   if (vectorizeIndexes.length > 0) {
     spec.vectorize_indexes = vectorizeIndexes;
   }
+
+  if (new_sqlite_classes.length > 0 || new_classes.length > 0) {
+    spec.migrations = [
+      {
+        tag: "v1",
+        new_sqlite_classes,
+        new_classes,
+      },
+    ];
+  }
 }

package/src/internal/docs/providers.ts

@@ -6,6 +6,14 @@ import { Document } from "../../ai/document.js";
 import { alchemy } from "../../alchemy.js";
 import { Folder } from "../../fs/folder.js";
 
+function getArg(arg: string) {
+  const idx = process.argv.findIndex((a) => a === arg);
+  return idx > -1 ? process.argv[idx + 1] : undefined;
+}
+
+const onlyProviderName = getArg("--provider");
+const onlyResourceName = getArg("--resource");
+
 export interface DocsProps {
   /**
    * The output directory for the docs.
@@ -117,7 +125,7 @@ async function generateProviderDocs({
         reasoningEffort: "high",
       },
     },
-    freeze: false,
+    freeze: onlyProviderName === undefined || onlyProviderName !== providerName,
     temperature: 0.1,
     schema: type({
       groups: type({
@@ -177,7 +185,8 @@ async function generateProviderDocs({
         providerDocsDir,
         `${g.filename.replace(".ts", "").replace(".md", "")}.md`,
       ),
-      freeze: false,
+      freeze:
+        onlyResourceName !== undefined && onlyResourceName !== g.identifier,
       model: {
         id: "claude-3-5-sonnet-latest",
         provider: "anthropic",

package/src/scope.ts

@@ -47,10 +47,15 @@ export class Scope {
 
   private isErrored = false;
 
-  constructor(private readonly options: ScopeOptions) {
+  constructor(options: ScopeOptions) {
     this.appName = options.appName;
     this.stage = options?.stage ?? DEFAULT_STAGE;
     this.scopeName = options.scopeName ?? null;
+    if (this.scopeName?.includes(":")) {
+      throw new Error(
+        `Scope name ${this.scopeName} cannot contain double colons`,
+      );
+    }
     this.parent = options.parent ?? Scope.get();
     this.quiet = options.quiet ?? this.parent?.quiet ?? false;
     if (this.parent && !this.scopeName) {