alchemy 0.93.12 → 0.94.0

package/src/aws/ec2/utils.ts

@@ -6,7 +6,7 @@ import { logger } from "../../util/logger.ts";
 import { flattenParams } from "../../util/params.ts";
 import type { AwsClientProps } from "../client-props.ts";
 import { resolveAwsCredentials } from "../credentials.ts";
-import { getRegion } from "../utils.ts";
+import { awsEndpoint, getRegion } from "../utils.ts";
 
 /**
  * Shared EC2 utilities for all EC2 resources
@@ -100,8 +100,10 @@ export async function callEC2Api<T>(
   // Try the API call, and retry once with fresh credentials on auth failure
   for (let attempt = 1; attempt <= 2; attempt++) {
     try {
-      // Use the client's region instead of the global region
-      const url = `https://ec2.${client.region}.amazonaws.com/`;
+      // Use the client's region instead of the global region.
+      // Honour AWS_ENDPOINT_URL / AWS_ENDPOINT_URL_EC2 for emulators
+      // (LocalStack, moto, etc.) — matches AWS SDK v3 behaviour.
+      const url = `${awsEndpoint("ec2", client.region ?? "us-east-1")}/`;
 
       const body = new URLSearchParams({
         Action: action,

package/src/aws/utils.ts

@@ -14,13 +14,29 @@ export const getRegion: Provider<string> = loadConfig({
   default: "us-east-1",
 });
 
+/**
+ * Resolve the endpoint URL for an aws4fetch service request, honouring the
+ * same `AWS_ENDPOINT_URL_<SERVICE>` / `AWS_ENDPOINT_URL` env vars as the AWS
+ * SDK / CLI so aws4fetch-based resources can be pointed at LocalStack, moto,
+ * or any other emulator.
+ */
+export function awsEndpoint(service: string, region: string): string {
+  return (
+    process.env[
+      `AWS_ENDPOINT_URL_${service.toUpperCase().replace(/-/g, "_")}`
+    ] ??
+    process.env.AWS_ENDPOINT_URL ??
+    `https://${service}.${region}.amazonaws.com`
+  ).replace(/\/+$/, "");
+}
+
 /**
  * AWS Service Configuration
  */
 export interface AwsServiceConfig {
   service: string;
   version: string;
-  endpoint: (region: string) => string;
+  endpoint?: (region: string) => string;
 }
 
 /**
@@ -63,7 +79,9 @@ export function getAwsApiCaller<T = any>(
       for (let attempt = 1; attempt <= 2; attempt++) {
         try {
           const region = await getRegion();
-          const url = config.endpoint(region);
+          const url = config.endpoint
+            ? config.endpoint(region)
+            : `${awsEndpoint(config.service, region)}/`;
 
           const body = new URLSearchParams({
             Action: action,

package/src/cloudflare/artifacts.ts

@@ -0,0 +1,69 @@
+/**
+ * Properties for creating an Artifacts binding.
+ *
+ * Artifacts namespaces are created implicitly by Cloudflare when the first
+ * repository is created in the namespace, so this binding does not provision
+ * or delete a namespace resource.
+ */
+export interface ArtifactsProps {
+  /**
+   * Artifacts namespace name.
+   */
+  namespace: string;
+
+  dev?: {
+    /**
+     * Whether to run the Artifacts binding remotely in local development.
+     *
+     * Artifacts do not have a local emulator, so generated Wrangler config
+     * defaults this binding to remote mode.
+     *
+     * @default true
+     */
+    remote?: boolean;
+  };
+}
+
+/**
+ * Cloudflare Artifacts binding.
+ *
+ * Artifacts namespaces are implicit containers for repositories. Use this
+ * helper to bind a Worker to a namespace; repository lifecycle should be
+ * managed through the Artifacts runtime API, REST API, or Git endpoint.
+ *
+ * @example
+ * ```ts
+ * import { Artifacts, Worker } from "alchemy/cloudflare";
+ *
+ * await Worker("site-editor", {
+ *   entrypoint: "./src/worker.ts",
+ *   bindings: {
+ *     SITE_ARTIFACTS: Artifacts({ namespace: "my-sites" }),
+ *   },
+ * });
+ * ```
+ *
+ * @see https://developers.cloudflare.com/artifacts/
+ */
+export interface Artifacts {
+  type: "artifacts";
+  namespace: string;
+  dev?: {
+    remote?: boolean;
+  };
+}
+
+export function Artifacts(props: string | ArtifactsProps): Artifacts {
+  if (typeof props === "string") {
+    return {
+      type: "artifacts",
+      namespace: props,
+    };
+  }
+
+  return {
+    type: "artifacts",
+    namespace: props.namespace,
+    dev: props.dev,
+  };
+}

package/src/cloudflare/bindings.ts

@@ -8,6 +8,7 @@ import type { Ai } from "./ai.ts";
 import type { AiSearchNamespace } from "./ai-search-namespace.ts";
 import type { AiSearch } from "./ai-search.ts";
 import type { AnalyticsEngineDataset } from "./analytics-engine.ts";
+import type { Artifacts } from "./artifacts.ts";
 import type { Assets } from "./assets.ts";
 import type { Bound } from "./bound.ts";
 import type { BrowserRendering } from "./browser-rendering.ts";
@@ -54,6 +55,7 @@ export type Binding =
   | AiSearch
   | AiSearchNamespace
   | Assets
+  | Artifacts
   | Container
   | CloudflareSecret
   | CloudflareSecretRef
@@ -127,6 +129,7 @@ export type WorkerBindingSpec =
   | WorkerBindingAiSearch
   | WorkerBindingAiSearchNamespace
   | WorkerBindingAnalyticsEngine
+  | WorkerBindingArtifacts
   | WorkerBindingAssets
   | WorkerBindingBrowserRendering
   | WorkerBindingD1
@@ -206,6 +209,18 @@ export interface WorkerBindingAnalyticsEngine {
   dataset: string;
 }
 
+/**
+ * Artifacts binding type
+ */
+export interface WorkerBindingArtifacts {
+  /** The name of the binding */
+  name: string;
+  /** Type identifier for Artifacts binding */
+  type: "artifacts";
+  /** Artifacts namespace name */
+  namespace: string;
+}
+
 /**
  * Assets binding type
  */
@@ -295,8 +310,8 @@ export interface WorkerBindingJson {
   name: string;
   /** Type identifier for JSON binding */
   type: "json";
-  /** JSON value */
-  json: string;
+  /** JSON value, sent raw (not stringified) so the runtime injects native types */
+  json: unknown;
 }
 
 /**

package/src/cloudflare/bound.ts

@@ -5,6 +5,7 @@ import type { Ai as _Ai } from "./ai.ts";
 import type { AiSearchNamespace as _AiSearchNamespace } from "./ai-search-namespace.ts";
 import type { AiSearch as _AiSearch } from "./ai-search.ts";
 import type { AnalyticsEngineDataset as _AnalyticsEngineDataset } from "./analytics-engine.ts";
+import type { Artifacts as _Artifacts } from "./artifacts.ts";
 import type { Assets } from "./assets.ts";
 import type { Binding, Json, Self } from "./bindings.ts";
 import type { BrowserRendering } from "./browser-rendering.ts";
@@ -61,69 +62,71 @@ export type Bound<T extends Binding> = T extends _AiSearch
           ? BoundWorker<RPC>
           : T extends _Worker<any, infer RPC> | WorkerRef<infer RPC>
             ? BoundWorker<RPC>
-            : T extends { type: "service" }
-              ? Service
-              : T extends _R2Bucket
-                ? R2Bucket
-                : T extends _Hyperdrive | HyperdriveRef
-                  ? Hyperdrive
-                  : T extends Secret
-                    ? string
-                    : T extends CloudflareSecret | CloudflareSecretRef
-                      ? SecretsStoreSecret
-                      : T extends _EmailSender
-                        ? SendEmail
-                        : T extends SecretKey
-                          ? CryptoKey
-                          : T extends Assets
-                            ? Service
-                            : T extends _Workflow<infer P>
-                              ? Workflow<P>
-                              : T extends _D1Database
-                                ? D1Database
-                                : T extends DispatchNamespace
-                                  ? DispatchNamespace
-                                  : T extends _WorkerLoader
-                                    ? WorkerLoader
-                                    : T extends _VectorizeIndex
-                                      ? VectorizeIndex
-                                      : T extends _Queue<infer Body>
-                                        ? Queue<Body>
-                                        : T extends _AnalyticsEngineDataset
-                                          ? AnalyticsEngineDataset
-                                          : T extends _Pipeline<infer R>
-                                            ? Pipeline<R>
-                                            : T extends _RateLimit
-                                              ? RateLimit
-                                              : T extends string
-                                                ? T
-                                                : T extends BrowserRendering
-                                                  ? BrowserRun
-                                                  : T extends _Ai<infer M>
-                                                    ? Ai<M>
-                                                    : T extends _Images
-                                                      ? ImagesBinding
-                                                      : T extends _VersionMetadata
-                                                        ? WorkerVersionMetadata
-                                                        : T extends
-                                                              | _Worker.DevDomain
-                                                              | _Worker.DevUrl
-                                                          ? string
-                                                          : T extends Self
-                                                            ? Service
-                                                            : T extends Json<
-                                                                  infer T
-                                                                >
-                                                              ? T
-                                                              : T extends _Container<
-                                                                    infer Obj
+            : T extends _Artifacts
+              ? Artifacts
+              : T extends { type: "service" }
+                ? Service
+                : T extends _R2Bucket
+                  ? R2Bucket
+                  : T extends _Hyperdrive | HyperdriveRef
+                    ? Hyperdrive
+                    : T extends Secret
+                      ? string
+                      : T extends CloudflareSecret | CloudflareSecretRef
+                        ? SecretsStoreSecret
+                        : T extends _EmailSender
+                          ? SendEmail
+                          : T extends SecretKey
+                            ? CryptoKey
+                            : T extends Assets
+                              ? Service
+                              : T extends _Workflow<infer P>
+                                ? Workflow<P>
+                                : T extends _D1Database
+                                  ? D1Database
+                                  : T extends DispatchNamespace
+                                    ? DispatchNamespace
+                                    : T extends _WorkerLoader
+                                      ? WorkerLoader
+                                      : T extends _VectorizeIndex
+                                        ? VectorizeIndex
+                                        : T extends _Queue<infer Body>
+                                          ? Queue<Body>
+                                          : T extends _AnalyticsEngineDataset
+                                            ? AnalyticsEngineDataset
+                                            : T extends _Pipeline<infer R>
+                                              ? Pipeline<R>
+                                              : T extends _RateLimit
+                                                ? RateLimit
+                                                : T extends string
+                                                  ? T
+                                                  : T extends BrowserRendering
+                                                    ? BrowserRun
+                                                    : T extends _Ai<infer M>
+                                                      ? Ai<M>
+                                                      : T extends _Images
+                                                        ? ImagesBinding
+                                                        : T extends _VersionMetadata
+                                                          ? WorkerVersionMetadata
+                                                          : T extends
+                                                                | _Worker.DevDomain
+                                                                | _Worker.DevUrl
+                                                            ? string
+                                                            : T extends Self
+                                                              ? Service
+                                                              : T extends Json<
+                                                                    infer T
                                                                   >
-                                                                ? DurableObjectNamespace<
-                                                                    Obj &
-                                                                      Rpc.DurableObjectBranded
-                                                                  >
-                                                                : T extends _VpcService
-                                                                  ? Fetcher
-                                                                  : T extends undefined
-                                                                    ? undefined
-                                                                    : Service;
+                                                                ? T
+                                                                : T extends _Container<
+                                                                      infer Obj
+                                                                    >
+                                                                  ? DurableObjectNamespace<
+                                                                      Obj &
+                                                                        Rpc.DurableObjectBranded
+                                                                    >
+                                                                  : T extends _VpcService
+                                                                    ? Fetcher
+                                                                    : T extends undefined
+                                                                      ? undefined
+                                                                      : Service;

package/src/cloudflare/d1-database.ts

@@ -307,11 +307,21 @@ const _D1Database = Resource(
 
     if (local) {
       if (props.migrationsFiles?.length || props.importFiles?.length) {
+        const localMigrationsFiles = props.migrationsDir
+          ? await listSqlFiles(props.migrationsDir)
+          : [];
+        const localImportFiles = props.importFiles?.length
+          ? await Promise.all(
+              props.importFiles.map((file) =>
+                readSqlFile(this.scope.rootDir, file.id),
+              ),
+            )
+          : [];
         await applyLocalD1Migrations({
           databaseId: dev.id,
           migrationsTable: props.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE,
-          migrations: props.migrationsFiles ?? [],
-          imports: props.importFiles ?? [],
+          migrations: localMigrationsFiles,
+          imports: localImportFiles,
           rootDir: this.scope.rootDir,
         });
       }

package/src/cloudflare/hyperdrive.ts

@@ -47,6 +47,11 @@ export interface HyperdrivePublicOrigin {
    */
   scheme?: "postgres" | "mysql";
 
+  /**
+   * Connection query string, without the leading "?"
+   */
+  query?: string;
+
   /**
    * Database user
    */
@@ -90,6 +95,11 @@ export interface HyperdriveOriginWithAccess {
    */
   scheme?: "postgres" | "mysql";
 
+  /**
+   * Connection query string, without the leading "?"
+   */
+  query?: string;
+
   /**
    * Database user
    */
@@ -610,6 +620,7 @@ export const normalizeHyperdriveOrigin = (
       host: url.hostname,
       port: normalizePort(scheme, url.port),
       database: url.pathname.slice(1),
+      query: url.search?.slice(1) ?? "",
     };
   }
   const scheme = normalizeScheme(origin.scheme);
@@ -623,6 +634,7 @@ export const normalizeHyperdriveOrigin = (
     }),
     scheme,
     port: normalizePort(scheme, origin.port),
+    query: origin.query ?? "",
   };
 };
 
@@ -660,6 +672,6 @@ const toConnectionString = (
     "password" in origin ? origin.password : origin.access_client_secret,
   );
   return new Secret(
-    `${origin.scheme}://${origin.user}:${password}@${origin.host}:${origin.port}/${origin.database}`,
+    `${origin.scheme}://${origin.user}:${password}@${origin.host}:${origin.port}/${origin.database}${origin.query ? `?${origin.query}` : ""}`,
   );
 };

package/src/cloudflare/index.ts

@@ -20,6 +20,7 @@ export * from "./api-gateway-operation.ts";
 export * from "./api-schema.ts";
 export * from "./api-shield.ts";
 export * from "./api.ts";
+export * from "./artifacts.ts";
 export * from "./assets.ts";
 export * from "./astro/astro.ts";
 export * from "./bindings.ts";

package/src/cloudflare/miniflare/build-worker-options.ts

@@ -167,6 +167,11 @@ export const buildWorkerOptions = async (
         };
         break;
       }
+      case "artifacts": {
+        throw new Error(
+          "Artifacts bindings are not supported in Alchemy local dev yet. Deploy the Worker or use generated Wrangler config with remote Artifacts bindings.",
+        );
+      }
       case "assets": {
         options.assets = {
           binding: key,

package/src/cloudflare/miniflare/miniflare-worker-proxy.ts

@@ -249,7 +249,9 @@ const writeMiniflareResponseToNode = (
   });
 
   if (res.body) {
-    Readable.fromWeb(res.body).pipe(out, { end: true });
+    const body = Readable.fromWeb(res.body);
+    body.on("error", () => out.destroy());
+    body.pipe(out, { end: true });
   } else {
     out.end();
   }

package/src/cloudflare/worker-metadata.ts

@@ -206,6 +206,17 @@ export interface WorkerMetadata {
     };
   };
   logpush?: boolean;
+  /**
+   * Workers Cache configuration.
+   *
+   * The wire shape matches what wrangler (>= 4.69) uploads.
+   *
+   * @see https://developers.cloudflare.com/workers/cache/configuration/
+   */
+  cache_options?: {
+    enabled: boolean;
+    cross_version_cache?: boolean;
+  };
   migrations?: SingleStepMigration;
   main_module?: string;
   body_part?: string;
@@ -355,6 +366,19 @@ export async function prepareWorkerMetadata(
       enabled: observability?.enabled !== false,
     },
     logpush: props.logpush ?? false,
+    cache_options:
+      props.cache != null
+        ? {
+            enabled:
+              typeof props.cache === "boolean"
+                ? props.cache
+                : (props.cache.enabled ?? true),
+            cross_version_cache:
+              typeof props.cache === "object"
+                ? props.cache.crossVersionCache
+                : undefined,
+          }
+        : undefined,
     // TODO(sam): base64 encode instead? 0 collision risk vs readability.
     tags: [
       // encode a mapping table of Durable Object stable ID -> binding name
@@ -516,6 +540,12 @@ export async function prepareWorkerMetadata(
         jurisdiction:
           binding.jurisdiction === "default" ? undefined : binding.jurisdiction,
       });
+    } else if (binding.type === "artifacts") {
+      meta.bindings.push({
+        type: "artifacts",
+        name: bindingName,
+        namespace: binding.namespace,
+      });
     } else if (binding.type === "send_email") {
       meta.bindings.push({
         type: "send_email",
@@ -597,7 +627,9 @@ export async function prepareWorkerMetadata(
       meta.bindings.push({
         type: "json",
         name: bindingName,
-        json: JSON.stringify(binding.json),
+        // send the raw value (like wrangler does) so the runtime injects the
+        // native type; stringifying here would inject a string instead
+        json: binding.json,
       });
     } else if (binding.type === "analytics_engine") {
       meta.bindings.push({

package/src/cloudflare/worker.ts

@@ -249,6 +249,21 @@ export interface BaseWorkerProps<
    */
   assets?: AssetsConfig;
 
+  /**
+   * Enable Workers Cache — a Worker-owned edge cache in front of this Worker.
+   *
+   * When enabled, Cloudflare checks the cache before invoking the Worker and
+   * serves matching responses directly from the edge. Caching is controlled
+   * with standard response headers (`Cache-Control`, `Cache-Tag`, `Vary`) and
+   * entries can be purged at runtime with `ctx.cache.purge()`.
+   *
+   * Pass `true` as shorthand for `{ enabled: true }`.
+   *
+   * @see https://developers.cloudflare.com/workers/cache/
+   * @default undefined - Workers Cache is disabled
+   */
+  cache?: boolean | WorkerCacheOptions;
+
   /**
    * Cron expressions for the trigger.
    *
@@ -431,6 +446,31 @@ export interface BaseWorkerProps<
   tailConsumers?: Array<Worker | { service: string }>;
 }
 
+/**
+ * Configuration for Workers Cache — the edge cache that sits in front of a
+ * Worker's `fetch()` invocations.
+ *
+ * @see https://developers.cloudflare.com/workers/cache/configuration/
+ */
+export interface WorkerCacheOptions {
+  /**
+   * If Workers Cache is enabled for this Worker
+   *
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Whether cached responses may be reused across Worker versions.
+   *
+   * By default the cache is scoped to a single Worker version, so every
+   * deployment starts cold. Enable this when responses are version-agnostic.
+   *
+   * @default false
+   */
+  crossVersionCache?: boolean;
+}
+
 export interface WorkerObservability {
   /**
    * If observability is enabled for this Worker
@@ -1601,7 +1641,7 @@ async function provisionResources<B extends Bindings>(
             // In local dev mode, queue.id is "" (no Cloudflare API call).
             // Use queue.dev.id (resource ID, e.g. "email-queue") to avoid
             // all consumers colliding on the same "-consumer" resource ID.
-            // See: https://github.com/alchemy-run/alchemy/issues/1363
+            // See: https://github.com/alchemy-run/alchemy-async/issues/1363
             const queueConsumerId = options.local
               ? eventSource.queue.dev?.id || eventSource.queue.id
               : eventSource.queue.id;

package/src/cloudflare/wrangler.json.ts

@@ -264,6 +264,11 @@ async function processBindings(
   const kvNamespaces: WranglerJsonConfig["kv_namespaces"] = [];
   const durableObjects: WranglerJsonConfig["durable_objects"]["bindings"] = [];
   const r2Buckets: WranglerJsonConfig["r2_buckets"] = [];
+  const artifacts: {
+    binding: string;
+    namespace: string;
+    remote?: boolean;
+  }[] = [];
   const services: WranglerJsonConfig["services"] = [];
   const sendEmailBindings: WranglerJsonConfig["send_email"] = [];
   const secrets: string[] = [];
@@ -422,6 +427,12 @@ async function processBindings(
         allowed_sender_addresses: binding.allowedSenderAddresses,
         ...(binding.dev?.remote ? { remote: true } : {}),
       });
+    } else if (binding.type === "artifacts") {
+      artifacts.push({
+        binding: bindingName,
+        namespace: binding.namespace,
+        remote: binding.dev?.remote ?? true,
+      });
     } else if (binding.type === "secret") {
       // Secret binding
       secrets.push(bindingName);
@@ -598,6 +609,14 @@ async function processBindings(
     spec.r2_buckets = r2Buckets;
   }
 
+  if (artifacts.length > 0) {
+    (
+      spec as WranglerJsonSpec & {
+        artifacts?: typeof artifacts;
+      }
+    ).artifacts = artifacts;
+  }
+
   if (services.length > 0) {
     spec.services = services;
   }

package/src/cloudflare/zone.ts

@@ -415,7 +415,7 @@ export const Zone = Resource(
 
     // Add a small delay to ensure settings are propagated
     // TODO(michael): do we need this?
-    // https://github.com/alchemy-run/alchemy/issues/681
+    // https://github.com/alchemy-run/alchemy-async/issues/681
     await new Promise((resolve) => setTimeout(resolve, 2000));
 
     // Update Bot Management configuration if provided

package/src/scope.ts

@@ -324,7 +324,7 @@ export class Scope {
       destroyStrategy ?? this.parent?.destroyStrategy ?? "sequential";
     if (this.local) {
       this.logger.warnOnce(
-        "Development mode is in beta. Please report any issues to https://github.com/alchemy-run/alchemy/issues.",
+        "Development mode is in beta. Please report any issues to https://github.com/alchemy-run/alchemy-async/issues.",
       );
     }
 
@@ -652,7 +652,7 @@ export class Scope {
         throw e;
       })) ?? [];
 
-    //todo(michael): remove once we deprecate doss; see: https://github.com/alchemy-run/alchemy/issues/585
+    //todo(michael): remove once we deprecate doss; see: https://github.com/alchemy-run/alchemy-async/issues/585
     let hasCorruptedResources = false;
     if (pendingDeletions) {
       for (const { resource, oldProps } of pendingDeletions) {