alchemy 0.51.2 → 0.52.0

package/src/cloudflare/d1-database.ts

@@ -1,6 +1,6 @@
 import type { Context } from "../context.ts";
 import { Resource, ResourceKind } from "../resource.ts";
-import { bind, type Bound } from "../runtime/bind.ts";
+import { Scope } from "../scope.ts";
 import { logger } from "../util/logger.ts";
 import { CloudflareApiError, handleApiError } from "./api-error.ts";
 import {
@@ -9,8 +9,20 @@ import {
   type CloudflareApiOptions,
 } from "./api.ts";
 import { cloneD1Database } from "./d1-clone.ts";
+import { applyLocalD1Migrations } from "./d1-local-migrations.ts";
 import { applyMigrations, listMigrationsFiles } from "./d1-migrations.ts";
 
+const DEFAULT_MIGRATIONS_TABLE = "d1_migrations";
+
+type PrimaryLocationHint =
+  | "wnam"
+  | "enam"
+  | "weur"
+  | "eeur"
+  | "apac"
+  | "auto"
+  | (string & {});
+
 /**
  * Properties for creating or updating a D1 Database
  */
@@ -26,14 +38,7 @@ export interface D1DatabaseProps extends CloudflareApiOptions {
    * Optional primary location hint for the database
    * Indicates the primary geographical location data will be stored
    */
-  primaryLocationHint?:
-    | "wnam"
-    | "enam"
-    | "weur"
-    | "eeur"
-    | "apac"
-    | "auto"
-    | string;
+  primaryLocationHint?: PrimaryLocationHint;
 
   /**
    * Read replication configuration
@@ -102,20 +107,31 @@ export interface D1DatabaseProps extends CloudflareApiOptions {
      * @default false
      */
     remote?: boolean;
+
+    /**
+     * Set when `Scope.local` is true to force update to the database even if it was already deployed live.
+     * @internal
+     */
+    force?: boolean;
   };
 }
 
-export function isD1Database(
-  resource: Resource,
-): resource is D1DatabaseResource {
+export function isD1Database(resource: Resource): resource is D1Database {
   return resource[ResourceKind] === "cloudflare::D1Database";
 }
 
 /**
  * Output returned after D1 Database creation/update
  */
-export type D1DatabaseResource = Resource<"cloudflare::D1Database"> &
-  D1DatabaseProps & {
+export type D1Database = Resource<"cloudflare::D1Database"> &
+  Pick<
+    D1DatabaseProps,
+    | "dev"
+    | "migrationsDir"
+    | "migrationsTable"
+    | "primaryLocationHint"
+    | "readReplication"
+  > & {
     type: "d1";
     /**
      * The unique ID of the database (UUID)
@@ -126,61 +142,8 @@ export type D1DatabaseResource = Resource<"cloudflare::D1Database"> &
      * The name of the database
      */
     name: string;
-
-    /**
-     * File size of the database
-     */
-    fileSize: number;
-
-    /**
-     * Number of tables in the database
-     */
-    numTables: number;
-
-    /**
-     * Version of the database
-     */
-    version: string;
-
-    /**
-     * Read replication configuration
-     */
-    readReplication?: {
-      /**
-       * Read replication mode
-       */
-      mode: "auto" | "disabled";
-    };
   };
 
-export type D1Database = D1DatabaseResource & Bound<D1DatabaseResource>;
-
-export async function D1Database(
-  id: string,
-  props: Omit<D1DatabaseProps, "migrationsFiles"> = {},
-): Promise<D1Database> {
-  const migrationsFiles = props.migrationsDir
-    ? await listMigrationsFiles(props.migrationsDir)
-    : [];
-
-  const db = await D1DatabaseResource(id, {
-    ...props,
-    migrationsFiles,
-  });
-  const binding = await bind(db);
-  return {
-    ...db,
-    batch: binding.batch,
-    exec: binding.exec,
-    prepare: binding.prepare,
-    withSession: binding.withSession,
-    /**
-     * @deprecated
-     */
-    dump: binding.dump,
-  };
-}
-
 /**
  * Creates and manages Cloudflare D1 Databases.
  *
@@ -257,13 +220,33 @@ export async function D1Database(
  *
  * @see https://developers.cloudflare.com/d1/
  */
-const D1DatabaseResource = Resource(
+export async function D1Database(
+  id: string,
+  props: Omit<D1DatabaseProps, "migrationsFiles"> = {},
+): Promise<D1Database> {
+  const migrationsFiles = props.migrationsDir
+    ? await listMigrationsFiles(props.migrationsDir)
+    : [];
+
+  return _D1Database(id, {
+    ...props,
+    migrationsFiles,
+    dev: {
+      ...(props.dev ?? {}),
+      // force local migrations to run even if the database was already deployed live
+      // this property will oscillate from true to false depending on the dev vs live deployment
+      force: Scope.current.local,
+    },
+  });
+}
+
+const _D1Database = Resource(
   "cloudflare::D1Database",
   async function (
-    this: Context<D1DatabaseResource>,
+    this: Context<D1Database>,
     id: string,
     props: D1DatabaseProps = {},
-  ): Promise<D1DatabaseResource> {
+  ): Promise<D1Database> {
     const api = await createCloudflareApi(props);
     const databaseName = props.name ?? id;
 
@@ -276,7 +259,33 @@ const D1DatabaseResource = Resource(
     }
     let dbData: CloudflareD1Response;
 
-    if (this.phase === "create") {
+    if (this.scope.local && !props.dev?.remote) {
+      if (props.migrationsFiles && props.migrationsFiles.length > 0) {
+        await applyLocalD1Migrations({
+          databaseId: this.output?.id ?? id,
+          migrationsTable: props.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE,
+          migrations: props.migrationsFiles,
+        });
+      }
+      return this({
+        type: "d1",
+        // we may not have an ID yet if we're creating a new database locally first
+        // so set it to the resource ID which we can later use to detect that a DB needs to be created during an `update`
+        id: this.output?.id ?? id,
+        name: databaseName,
+        readReplication: props.readReplication,
+        primaryLocationHint: props.primaryLocationHint,
+        migrationsDir: props.migrationsDir,
+        migrationsTable: props.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE,
+        dev: props.dev,
+      });
+    } else if (
+      this.phase === "create" ||
+      // this is true IFF the database was created locally before any live deployment
+      // in that case, we should still go through the create flow for "update"
+      // after that, the ID will remain the UUID for the lifetime of the database
+      this.output.id === id
+    ) {
       logger.log("Creating D1 database:", databaseName);
       try {
         dbData = await createDatabase(api, databaseName, props);
@@ -323,35 +332,33 @@ const D1DatabaseResource = Resource(
           throw error;
         }
       }
-    } else {
-      // Update operation
-      if (this.output?.id) {
-        // Only read_replication can be modified in update
-        if (
-          props.primaryLocationHint &&
-          props.primaryLocationHint !== this.output?.primaryLocationHint
-        ) {
-          throw new Error(
-            `Cannot update primaryLocationHint from '${this.output.primaryLocationHint}' to '${props.primaryLocationHint}' after database creation.`,
-          );
-        }
-        logger.log("Updating D1 database:", databaseName);
-        // Update the database with new properties
-        dbData = await updateDatabase(api, this.output.id, props);
-      } else {
-        // If no ID exists, fall back to creating a new database
-        logger.log(
-          "No existing database ID found, creating new D1 database:",
-          databaseName,
+    } else if (this.output?.id) {
+      // Only read_replication can be modified in update
+      if (
+        props.primaryLocationHint &&
+        props.primaryLocationHint !== this.output?.primaryLocationHint
+      ) {
+        throw new Error(
+          `Cannot update primaryLocationHint from '${this.output.primaryLocationHint}' to '${props.primaryLocationHint}' after database creation.`,
         );
-        dbData = await createDatabase(api, databaseName, props);
       }
+      logger.log("Updating D1 database:", databaseName);
+      // Update the database with new properties
+      dbData = await updateDatabase(api, this.output.id, props);
+    } else {
+      // If no ID exists, fall back to creating a new database
+      logger.log(
+        "No existing database ID found, creating new D1 database:",
+        databaseName,
+      );
+      dbData = await createDatabase(api, databaseName, props);
     }
 
     // Run migrations if provided
     if (props.migrationsFiles && props.migrationsFiles.length > 0) {
       try {
-        const migrationsTable = props.migrationsTable || "d1_migrations";
+        const migrationsTable =
+          props.migrationsTable || DEFAULT_MIGRATIONS_TABLE;
         const databaseId = dbData.result.uuid || this.output?.id;
 
         if (!databaseId) {
@@ -370,19 +377,19 @@ const D1DatabaseResource = Resource(
         throw migrationErr;
       }
     }
-
+    if (!dbData.result.uuid) {
+      // TODO(sam): why would this ever happen?
+      throw new Error("Database ID not found");
+    }
     return this({
       type: "d1",
-      id: dbData.result.uuid || "",
+      id: dbData.result.uuid!,
       name: databaseName,
-      dev: props.dev,
-      fileSize: dbData.result.file_size,
-      numTables: dbData.result.num_tables,
-      version: dbData.result.version,
       readReplication: dbData.result.read_replication,
       primaryLocationHint: props.primaryLocationHint,
-      accountId: api.accountId,
+      dev: props.dev,
       migrationsDir: props.migrationsDir,
+      migrationsTable: props.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE,
     });
   },
 );

package/src/cloudflare/d1-local-migrations.ts

@@ -0,0 +1,52 @@
+import * as mf from "miniflare";
+import path from "node:path";
+
+export interface D1LocalMigrationOptions {
+  databaseId: string;
+  migrationsTable: string;
+  migrations: { id: string; sql: string }[];
+}
+
+export const applyLocalD1Migrations = async (
+  options: D1LocalMigrationOptions,
+) => {
+  const miniflare = new mf.Miniflare({
+    script: "",
+    modules: true,
+    defaultPersistRoot: path.join(process.cwd(), ".alchemy/miniflare"),
+    d1Persist: true,
+    d1Databases: { DB: options.databaseId },
+    log: process.env.DEBUG ? new mf.Log(mf.LogLevel.DEBUG) : undefined,
+  });
+  try {
+    await miniflare.ready;
+    const db = await miniflare.getD1Database("DB");
+    const session = db.withSession("first-primary");
+    await session
+      .prepare(
+        `CREATE TABLE IF NOT EXISTS ${options.migrationsTable} (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
+    )`,
+      )
+      .run();
+    const appliedMigrations = await session
+      .prepare(
+        `SELECT name FROM ${options.migrationsTable} ORDER BY applied_at ASC`,
+      )
+      .all<{ name: string }>();
+    const insertRecord = session.prepare(
+      `INSERT INTO ${options.migrationsTable} (name) VALUES (?)`,
+    );
+    for (const migration of options.migrations) {
+      if (appliedMigrations.results.some((m) => m.name === migration.id)) {
+        continue;
+      }
+      await session.prepare(migration.sql).run();
+      await insertRecord.bind(migration.id).run();
+    }
+  } finally {
+    await miniflare.dispose();
+  }
+};

package/src/cloudflare/dispatch-namespace.ts

@@ -1,6 +1,5 @@
 import type { Context } from "../context.ts";
 import { Resource, ResourceKind } from "../resource.ts";
-import { bind } from "../runtime/bind.ts";
 import { logger } from "../util/logger.ts";
 import { CloudflareApiError, handleApiError } from "./api-error.ts";
 import {
@@ -37,14 +36,14 @@ export interface DispatchNamespaceProps extends CloudflareApiOptions {
 
 export function isDispatchNamespace(
   resource: Resource,
-): resource is DispatchNamespaceResource {
+): resource is DispatchNamespace {
   return resource[ResourceKind] === "cloudflare::DispatchNamespace";
 }
 
 /**
  * Output returned after Dispatch Namespace creation/update
  */
-export interface DispatchNamespaceResource
+export interface DispatchNamespace
   extends Resource<"cloudflare::DispatchNamespace">,
     Omit<DispatchNamespaceProps, "delete"> {
   type: "dispatch_namespace";
@@ -74,10 +73,6 @@ export interface DispatchNamespaceResource
   modifiedAt: number;
 }
 
-export type DispatchNamespace = DispatchNamespaceResource & {
-  get(name: string): Fetcher;
-};
-
 /**
  * A Cloudflare Dispatch Namespace enables routing worker requests to different scripts based on patterns.
  *
@@ -107,27 +102,13 @@ export type DispatchNamespace = DispatchNamespaceResource & {
  *   delete: false
  * });
  */
-
-export async function DispatchNamespace(
-  name: string,
-  props: DispatchNamespaceProps = {},
-): Promise<DispatchNamespace> {
-  const dispatchNamespace = await _DispatchNamespace(name, props);
-  const binding = await bind(dispatchNamespace);
-  return {
-    ...dispatchNamespace,
-    // Add runtime methods that dispatch namespaces have
-    get: binding.get,
-  };
-}
-
-const _DispatchNamespace = Resource(
+export const DispatchNamespace = Resource(
   "cloudflare::DispatchNamespace",
   async function (
-    this: Context<DispatchNamespaceResource>,
+    this: Context<DispatchNamespace>,
     id: string,
-    props: DispatchNamespaceProps,
-  ): Promise<DispatchNamespaceResource> {
+    props: DispatchNamespaceProps = {},
+  ): Promise<DispatchNamespace> {
     // Create Cloudflare API client with automatic account discovery
     const api = await createCloudflareApi(props);
 

package/src/cloudflare/event-source.ts

@@ -1,10 +1,10 @@
 import type { QueueConsumerSettings } from "./queue-consumer.ts";
-import type { QueueResource } from "./queue.ts";
+import type { Queue } from "./queue.ts";
 
 /**
  * Base interface for event sources that can be bound to a Worker
  */
-export type EventSource = QueueEventSource | QueueResource;
+export type EventSource = QueueEventSource | Queue;
 
 /**
  * Configuration for a Queue as an event source for a Worker
@@ -13,7 +13,7 @@ export interface QueueEventSource {
   /**
    * The queue to consume messages from
    */
-  readonly queue: QueueResource;
+  readonly queue: Queue;
 
   /**
    * Optional settings for configuring how the Worker consumes the queue

package/src/cloudflare/hyperdrive.ts

@@ -1,11 +1,9 @@
 import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
-import { tryGetBinding } from "../runtime/bind.ts";
 import type { Secret } from "../secret.ts";
 import { logger } from "../util/logger.ts";
 import { handleApiError } from "./api-error.ts";
 import { createCloudflareApi, type CloudflareApiOptions } from "./api.ts";
-import type { Bound } from "./bound.ts";
 
 /**
  * Origin configuration for a PostgreSQL or MySQL database connection
@@ -156,7 +154,7 @@ export interface HyperdriveProps extends CloudflareApiOptions {
  * Output returned after Cloudflare Hyperdrive creation/update.
  * IMPORTANT: The interface name MUST match the exported resource name.
  */
-export interface HyperdriveResource
+export interface Hyperdrive
   extends Resource<"cloudflare::Hyperdrive">,
     Omit<HyperdriveProps, "origin"> {
   /**
@@ -181,8 +179,6 @@ export interface HyperdriveResource
   type: "hyperdrive";
 }
 
-export type Hyperdrive = HyperdriveResource & Bound<HyperdriveResource>;
-
 /**
  * Represents a Cloudflare Hyperdrive configuration.
  *
@@ -261,24 +257,13 @@ export type Hyperdrive = HyperdriveResource & Bound<HyperdriveResource>;
  *   }
  * });
  */
-export async function Hyperdrive(
-  name: string,
-  props: HyperdriveProps,
-): Promise<Hyperdrive> {
-  const resource = await HyperdriveResource(name, props);
-  return {
-    ...resource,
-    ...tryGetBinding(resource),
-  } as Hyperdrive;
-}
-
-const HyperdriveResource = Resource(
+export const Hyperdrive = Resource(
   "cloudflare::Hyperdrive",
   async function (
-    this: Context<HyperdriveResource>,
+    this: Context<Hyperdrive>,
     id: string,
     props: HyperdriveProps,
-  ): Promise<HyperdriveResource> {
+  ): Promise<Hyperdrive> {
     const api = await createCloudflareApi(props);
     const configsPath = `/accounts/${api.accountId}/hyperdrive/configs`;
 

package/src/cloudflare/index.ts

@@ -55,6 +55,7 @@ export * from "./vectorize-metadata-index.ts";
 export * from "./version-metadata.ts";
 export * from "./vite.ts";
 export * from "./website.ts";
+export * from "./worker-ref.ts";
 export * from "./worker-stub.ts";
 export * from "./worker-subdomain.ts";
 export * from "./worker.ts";

package/src/cloudflare/kv-namespace.ts

@@ -1,6 +1,5 @@
 import type { Context } from "../context.ts";
 import { Resource, ResourceKind } from "../resource.ts";
-import { bind } from "../runtime/bind.ts";
 import { logger } from "../util/logger.ts";
 import { withExponentialBackoff } from "../util/retry.ts";
 import { handleApiError } from "./api-error.ts";
@@ -9,7 +8,6 @@ import {
   type CloudflareApi,
   type CloudflareApiOptions,
 } from "./api.ts";
-import type { Bound } from "./bound.ts";
 
 /**
  * Properties for creating or updating a KV Namespace
@@ -84,16 +82,14 @@ export interface KVPair {
   metadata?: any;
 }
 
-export function isKVNamespace(
-  resource: Resource,
-): resource is KVNamespaceResource {
+export function isKVNamespace(resource: Resource): resource is KVNamespace {
   return resource[ResourceKind] === "cloudflare::KVNamespace";
 }
 
 /**
  * Output returned after KV Namespace creation/update
  */
-export interface KVNamespaceResource
+export interface KVNamespace
   extends Resource<"cloudflare::KVNamespace">,
     Omit<KVNamespaceProps, "delete"> {
   type: "kv_namespace";
@@ -113,8 +109,6 @@ export interface KVNamespaceResource
   modifiedAt: number;
 }
 
-export type KVNamespace = KVNamespaceResource & Bound<KVNamespaceResource>;
-
 /**
  * A Cloudflare KV Namespace is a key-value store that can be used to store data for your application.
  *
@@ -169,30 +163,13 @@ export type KVNamespace = KVNamespaceResource & Bound<KVNamespaceResource>;
  *   delete: false
  * });
  */
-
-export async function KVNamespace(
-  name: string,
-  props: KVNamespaceProps = {},
-): Promise<KVNamespace> {
-  const kv = await _KVNamespace(name, props);
-  const binding = await bind(kv);
-  return {
-    ...kv,
-    delete: binding.delete,
-    get: binding.get,
-    getWithMetadata: binding.getWithMetadata,
-    list: binding.list,
-    put: binding.put,
-  };
-}
-
-const _KVNamespace = Resource(
+export const KVNamespace = Resource(
   "cloudflare::KVNamespace",
   async function (
-    this: Context<KVNamespaceResource>,
+    this: Context<KVNamespace>,
     id: string,
     props: KVNamespaceProps,
-  ): Promise<KVNamespaceResource> {
+  ): Promise<KVNamespace> {
     // Create Cloudflare API client with automatic account discovery
     const api = await createCloudflareApi(props);
 

package/src/cloudflare/pipeline.ts

@@ -1,6 +1,5 @@
 import type { Context } from "../context.ts";
 import { Resource, ResourceKind } from "../resource.ts";
-import { bind } from "../runtime/bind.ts";
 import type { Secret } from "../secret.ts";
 import { logger } from "../util/logger.ts";
 import { CloudflareApiError, handleApiError } from "./api-error.ts";
@@ -9,7 +8,6 @@ import {
   type CloudflareApi,
   type CloudflareApiOptions,
 } from "./api.ts";
-import type { Bound } from "./bound.ts";
 
 /**
  * Settings for compression of pipeline output
@@ -229,10 +227,14 @@ export interface PipelineRecord {
   [key: string]: any;
 }
 
+export function isPipeline(resource: Resource): resource is Pipeline {
+  return resource[ResourceKind] === "cloudflare::Pipeline";
+}
+
 /**
  * Output returned after Pipeline creation/update
  */
-export interface PipelineResource<_T extends PipelineRecord = PipelineRecord>
+export interface Pipeline<_T extends PipelineRecord = PipelineRecord>
   extends Resource<"cloudflare::Pipeline">,
     PipelineProps {
   /**
@@ -261,13 +263,6 @@ export interface PipelineResource<_T extends PipelineRecord = PipelineRecord>
   version: number;
 }
 
-export function isPipeline(resource: Resource): resource is PipelineResource {
-  return resource[ResourceKind] === "cloudflare::Pipeline";
-}
-
-export type Pipeline<T extends PipelineRecord = PipelineRecord> =
-  PipelineResource<T> & Bound<PipelineResource<T>>;
-
 /**
  * Creates and manages Cloudflare Pipelines.
  *
@@ -334,24 +329,10 @@ export type Pipeline<T extends PipelineRecord = PipelineRecord> =
  *
  * @see https://developers.cloudflare.com/pipelines/
  */
-export async function Pipeline<T extends PipelineRecord = PipelineRecord>(
-  name: string,
-  props: PipelineProps,
-): Promise<Pipeline<T>> {
-  const pipeline = await PipelineResource(name, props);
-  const binding = await bind(pipeline, {
-    bindThis: false,
-  });
-  return {
-    ...pipeline,
-    send: binding.send,
-  };
-}
-
-const PipelineResource = Resource("cloudflare::Pipeline", async function <
+export const Pipeline = Resource("cloudflare::Pipeline", async function <
   T extends PipelineRecord = PipelineRecord,
->(this: Context<PipelineResource<T>>, id: string, props: PipelineProps): Promise<
-  PipelineResource<T>
+>(this: Context<Pipeline<T>>, id: string, props: PipelineProps): Promise<
+  Pipeline<T>
 > {
   const api = await createCloudflareApi(props);
   const pipelineName = props.name ?? id;

package/src/cloudflare/queue-consumer.ts

@@ -7,7 +7,7 @@ import {
   type CloudflareApi,
   type CloudflareApiOptions,
 } from "./api.ts";
-import type { Queue, QueueResource } from "./queue.ts";
+import type { Queue } from "./queue.ts";
 
 /**
  * Settings for configuring a Queue Consumer
@@ -55,9 +55,9 @@ export interface QueueConsumerSettings {
  */
 export interface QueueConsumerProps extends CloudflareApiOptions {
   /**
-   * The {@link QueueResource} or Queue ID to consume
+   * The {@link Queue} or Queue ID to consume
    */
-  queue: string | QueueResource;
+  queue: string | Queue;
 
   /**
    * Name of the worker script that will consume the queue