alchemy 0.45.5 → 0.46.0

package/src/fs/file-system-state-store.ts

@@ -1,149 +1,6 @@
-import fs from "node:fs";
-import path from "node:path";
-import { ResourceScope } from "../resource.ts";
-import type { Scope } from "../scope.ts";
-import { deserialize, serialize } from "../serde.ts";
-import type { State, StateStore } from "../state.ts";
-import { ignore } from "../util/ignore.ts";
+import * as state from "../state/file-system-state-store.ts";
 
-const stateRootDir = path.join(process.cwd(), ".alchemy");
-const ALCHEMY_SEPERATOR_CHAR = process.platform === "win32" ? "-" : ":";
-
-export class FileSystemStateStore implements StateStore {
-  public readonly dir: string;
-  private initialized = false;
-  constructor(
-    public readonly scope: Scope,
-    options?: {
-      rootDir?: string;
-    },
-  ) {
-    this.dir = path.join(options?.rootDir ?? stateRootDir, ...scope.chain);
-  }
-
-  async init(): Promise<void> {
-    if (this.initialized) {
-      return;
-    }
-    this.initialized = true;
-    await fs.promises.mkdir(this.dir, { recursive: true });
-  }
-
-  async deinit(): Promise<void> {
-    await ignore("ENOENT", async () => {
-      const entries = await fs.promises.readdir(this.dir, {
-        withFileTypes: true,
-      });
-      const files = entries.filter((entry) => entry.isFile());
-      if (files.length > 0) {
-        throw new Error(
-          `Cannot deinit: directory "${this.dir}" contains files and cannot be deleted.`,
-        );
-      }
-      // Only folders (or empty), delete recursively
-      await fs.promises.rm(this.dir, { recursive: true, force: true });
-    });
-  }
-
-  async count(): Promise<number> {
-    return Object.keys(await this.list()).length;
-  }
-
-  async list(): Promise<string[]> {
-    try {
-      const files = await fs.promises.readdir(this.dir, {
-        withFileTypes: true,
-      });
-      return files
-        .filter((dirent) => dirent.isFile() && dirent.name.endsWith(".json"))
-        .map((dirent) => dirent.name.replace(/\.json$/, ""))
-        .map((key) => key.replaceAll(":", "/"));
-    } catch (error: any) {
-      if (error.code === "ENOENT") {
-        return [];
-      }
-      throw error;
-    }
-  }
-
-  async get(key: string): Promise<State | undefined> {
-    try {
-      const content = await fs.promises.readFile(this.getPath(key), "utf8");
-      const state = (await deserialize(
-        this.scope,
-        JSON.parse(content),
-      )) as State;
-      if (state.output === undefined) {
-        state.output = {} as any;
-      }
-      state.output[ResourceScope] = this.scope;
-      return state;
-    } catch (error: any) {
-      if (error.code === "ENOENT") {
-        return undefined;
-      }
-      throw error;
-    }
-  }
-
-  async set(key: string, value: State): Promise<void> {
-    await this.init();
-    const file = this.getPath(key);
-    await fs.promises.mkdir(path.dirname(file), { recursive: true });
-    await fs.promises.writeFile(
-      file,
-      JSON.stringify(await serialize(this.scope, value), null, 2),
-    );
-  }
-
-  async delete(key: string): Promise<void> {
-    try {
-      return await fs.promises.unlink(this.getPath(key));
-    } catch (error: any) {
-      if (error.code === "ENOENT") {
-        return;
-      }
-      throw error;
-    }
-  }
-
-  async all(): Promise<Record<string, State>> {
-    return this.getBatch(await this.list());
-  }
-
-  async getBatch(ids: string[]): Promise<Record<string, State>> {
-    return Object.fromEntries(
-      (
-        await Promise.all(
-          Array.from(ids).flatMap(async (id) => {
-            const s = await this.get(id);
-            if (s === undefined) {
-              return [] as const;
-            }
-            return [[id, s]] as const;
-          }),
-        )
-      ).flat(),
-    );
-  }
-
-  private getPath(key: string): string {
-    if (key.includes(":")) {
-      throw new Error(`ID cannot include colons: ${key}`);
-    }
-    if (key.includes("/")) {
-      //todo(michael): remove this next time we do a breaking change
-      //* windows doesn't support ":" in file paths, but we already use ":"
-      //* so now we use both to prevent breaking changes
-      key = key.replaceAll("/", ALCHEMY_SEPERATOR_CHAR);
-    }
-    //todo(michael): remove this next time we do a breaking change
-    //* windows doesn't support "*" in file paths, but we already use "*"
-    //* when making cloudflare routes containing "*"
-    //* so now we use "+" on windows but "*" on mac/linux to prevent breaking changes
-    if (process.platform === "win32") {
-      key = key.replaceAll("*", "+");
-    }
-    return path.join(this.dir, `${key}.json`);
-  }
-}
+/**
+ * @deprecated Use `FileSystemStateStore` from `alchemy/state` instead.
+ */
+export const FileSystemStateStore = state.FileSystemStateStore;

package/src/fs/index.ts

@@ -1,7 +1,6 @@
 export * from "./copy-file.ts";
 export * from "./file-collection.ts";
 export * from "./file-ref.ts";
-export * from "./file-system-state-store.ts";
 export * from "./file.ts";
 export * from "./folder.ts";
 export * from "./static-astro-file.ts";

package/src/llms.cloudflare.txt

@@ -41,8 +41,9 @@ ALCHEMY_STATE_STORE=cloudflare
 
 ### Commands
 ```bash
-bun ./alchemy.run.ts           # Deploy
-bun ./alchemy.run.ts --destroy # Destroy all resources
+bun alchemy deploy            # Deploy
+bun alchemy dev               # Local development
+bun alchemy destroy           # Destroy all resources
 ```
 
 ## Workers
@@ -107,7 +108,7 @@ declare module "cloudflare:workers" {
 ### Creating Durable Object Namespace
 ```typescript
 // Use 'new' instead of 'await' for DurableObjectNamespace
-const counter = new DurableObjectNamespace("counter", {
+const counter = DurableObjectNamespace("counter", {
   className: "Counter",
   sqlite: true, // Enable SQLite storage
 });
@@ -161,7 +162,7 @@ export default {
 const sharedCounter = host.bindings.SHARED_COUNTER;
 
 // Method 2: Reference by worker script name
-const counter = new DurableObjectNamespace("counter", {
+const counter = DurableObjectNamespace("counter", {
   className: "Counter",
   scriptName: "provider-worker"
 });
@@ -353,7 +354,7 @@ describe("Worker Tests", () => {
 ## Common Issues
 
 - **Missing finalize()**: Resources won't be cleaned up properly
-- **Wrong DurableObject syntax**: Use `new DurableObjectNamespace()` not `await`
+- **Wrong DurableObject syntax**: Use `DurableObjectNamespace()` not `await`
 - **Type errors**: Set up env.d.ts file for binding types
 - **State conflicts**: Use different stages/prefixes for different environments
 - **Resource adoption**: Use `adopt: true` when migrating existing resources

package/src/planetscale/password.ts

@@ -306,7 +306,7 @@ export const Password = Resource(
             this.output.cidrs.length === props.cidrs.length &&
             this.output.cidrs.every((cidr, i) => cidr === props.cidrs![i])))
       ) {
-        return this.replace();
+        return await this.replace();
       }
       const updateResponse = await api.patch(
         `/organizations/${props.organizationId}/databases/${databaseName}/branches/${branchName}/passwords/${this.output.id}`,

package/src/scope.ts

@@ -1,10 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import util from "node:util";
 import type { Phase } from "./alchemy.ts";
-import { D1StateStore } from "./cloudflare/d1-state-store.ts";
-import { DOStateStore } from "./cloudflare/do-state-store/index.ts";
 import { destroy, destroyAll } from "./destroy.ts";
-import { FileSystemStateStore } from "./fs/file-system-state-store.ts";
 import {
   ResourceFQN,
   ResourceID,
@@ -16,6 +13,8 @@ import {
   type ResourceProps,
 } from "./resource.ts";
 import type { State, StateStore, StateStoreType } from "./state.ts";
+import { D1StateStore } from "./state/d1-state-store.ts";
+import { FileSystemStateStore } from "./state/file-system-state-store.ts";
 import {
   createDummyLogger,
   createLoggerInstance,
@@ -499,10 +498,8 @@ export class Scope {
 
 const defaultStateStore: StateStoreType = (scope: Scope) => {
   switch (process.env.ALCHEMY_STATE_STORE) {
-    case "cloudflare-d1":
+    case "d1":
       return new D1StateStore(scope);
-    case "cloudflare":
-      return new DOStateStore(scope);
     default:
       return new FileSystemStateStore(scope);
   }

package/src/state/cloudflare-state-store.ts

@@ -0,0 +1,170 @@
+import { alchemy } from "../alchemy.ts";
+import { BUILD_DATE } from "../build-date.ts";
+import type { CloudflareApiOptions } from "../cloudflare/api.ts";
+import { createCloudflareApi } from "../cloudflare/api.ts";
+import { getInternalWorkerBundle } from "../cloudflare/bundle/internal-worker-bundle.ts";
+import { DurableObjectNamespace } from "../cloudflare/durable-object-namespace.ts";
+import { getWorkerSettings } from "../cloudflare/worker-metadata.ts";
+import {
+  enableWorkerSubdomain,
+  getAccountSubdomain,
+  getWorkerSubdomain,
+} from "../cloudflare/worker-subdomain.ts";
+import { putWorker } from "../cloudflare/worker.ts";
+import type { Scope } from "../scope.ts";
+import type { Secret } from "../secret.ts";
+import { logger } from "../util/logger.ts";
+import { memoize } from "../util/memoize.ts";
+import { StateStoreProxy } from "./proxy.ts";
+
+export interface CloudflareStateStoreOptions extends CloudflareApiOptions {
+  /**
+   * The name of the script to use for the state store.
+   * @default "alchemy-state-service"
+   */
+  scriptName?: string;
+  /**
+   * Whether to force the worker to be updated.
+   * This may be useful if you've lost the token for the state store and need to overwrite it.
+   * @default false
+   */
+  forceUpdate?: boolean;
+  /**
+   * The token to use for the state store.
+   * @default process.env.ALCHEMY_STATE_TOKEN
+   * @note You must use the same token for all deployments on your Cloudflare account.
+   */
+  stateToken?: Secret<string>;
+}
+
+/**
+ * A state store backed by a SQLite database in a Cloudflare Durable Object.
+ *
+ * @see {@link https://alchemy.run/guides/do-state-store DOStateStore}
+ */
+export class CloudflareStateStore extends StateStoreProxy {
+  constructor(
+    scope: Scope,
+    private readonly options: CloudflareStateStoreOptions = {},
+  ) {
+    super(scope);
+  }
+
+  async provision(): Promise<StateStoreProxy.Dispatch> {
+    const { url, token } = await provision(this.options);
+    return async (method, params) => {
+      const request: StateStoreProxy.Request<
+        typeof method,
+        { chain: string[] }
+      > = {
+        method,
+        params,
+        context: { chain: this.scope.chain },
+      };
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(request),
+      });
+      if (!response.headers.get("Content-Type")?.includes("application/json")) {
+        throw new Error(
+          `[CloudflareStateStore] "${method}" request failed with status ${response.status}: Expected JSON response, but got ${response.headers.get("Content-Type")}`,
+        );
+      }
+      const json = (await response.json()) as StateStoreProxy.Response<
+        typeof method
+      >;
+      if (!json.success) {
+        throw new Error(
+          `[CloudflareStateStore] "${method}" request failed with status ${response.status}: ${json.error}`,
+        );
+      }
+      return json.result;
+    };
+  }
+}
+
+const provision = memoize(async (options: CloudflareStateStoreOptions) => {
+  const scriptName = options.scriptName ?? "alchemy-state-service";
+  const token =
+    options.stateToken ??
+    (await alchemy.secret.env(
+      "ALCHEMY_STATE_TOKEN",
+      undefined,
+      "Missing token for DOStateStore. Please set ALCHEMY_STATE_TOKEN in the environment or set the `stateToken` option in the DOStateStore constructor.",
+    ));
+
+  const api = await createCloudflareApi(options);
+  const [bundle, settings, subdomain] = await Promise.all([
+    getInternalWorkerBundle("cloudflare-state-store"),
+    getWorkerSettings(api, scriptName),
+    getWorkerSubdomain(api, scriptName),
+  ]);
+  if (!settings || !settings.tags.includes(bundle.tag) || options.forceUpdate) {
+    logger.log(
+      `[CloudflareStateStore] ${settings ? "Updating" : "Creating"}...`,
+    );
+    await putWorker(api, {
+      workerName: scriptName,
+      compatibilityDate: BUILD_DATE,
+      format: "esm",
+      scriptBundle: {
+        entrypoint: bundle.file.name,
+        files: [bundle.file],
+        hash: bundle.tag,
+      },
+      compatibilityFlags: [],
+      bindings: {
+        STORE: DurableObjectNamespace(scriptName, {
+          className: "Store",
+          sqlite: true,
+        }),
+        STATE_TOKEN: token,
+      },
+      tags: [bundle.tag],
+    });
+  }
+  if (!subdomain.enabled) {
+    await enableWorkerSubdomain(api, scriptName);
+  }
+  const url = `https://${scriptName}.${await getAccountSubdomain(api)}.workers.dev`;
+  await pollUntilReady(() =>
+    fetch(url, {
+      method: "HEAD",
+      headers: { Authorization: `Bearer ${token.unencrypted}` },
+    }),
+  );
+  return { url, token: token.unencrypted };
+});
+
+async function pollUntilReady(fn: () => Promise<Response>) {
+  // This ensures the token is correct and the worker is ready to use.
+  let last: Response | undefined;
+  let delay = 1000;
+  for (let i = 0; i < 20; i++) {
+    const res = await fn();
+    if (res.ok) {
+      return;
+    }
+    if (res.status === 401) {
+      throw new Error(
+        "[CloudflareStateStore] The token is invalid. Please check your ALCHEMY_STATE_TOKEN environment variable, or set `forceUpdate: true` in the CloudflareStateStore constructor to overwrite the current token.",
+      );
+    }
+    if (!last) {
+      logger.log("[CloudflareStateStore] Waiting for deployment...");
+    }
+    last = res;
+    // Exponential backoff with jitter
+    const jitter = Math.random() * 0.1 * delay;
+    await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+    delay *= 1.5; // Increase the delay for next attempt
+    delay = Math.min(delay, 10000); // Cap at 10 seconds
+  }
+  throw new Error(
+    `[CloudflareStateStore] Failed to reach state store: ${last?.status} ${last?.statusText}`,
+  );
+}

package/src/state/d1-state-store.ts

@@ -0,0 +1,102 @@
+import { drizzle, type RemoteCallback } from "drizzle-orm/sqlite-proxy";
+import assert from "node:assert";
+import { extractCloudflareResult } from "../cloudflare/api-response.ts";
+import type { CloudflareApi, CloudflareApiOptions } from "../cloudflare/api.ts";
+import type { Scope } from "../scope.ts";
+import { memoize } from "../util/memoize.ts";
+import { MIGRATIONS_DIRECTORY } from "./migrations.ts";
+import { SQLiteStateStoreOperations } from "./operations.ts";
+import { StateStoreProxy } from "./proxy.ts";
+import * as schema from "./schema.ts";
+
+export interface D1StateStoreOptions extends CloudflareApiOptions {
+  databaseName?: string;
+}
+
+/**
+ * @deprecated Use `CloudflareStateStore` from `alchemy/state` instead.
+ */
+export class D1StateStore extends StateStoreProxy {
+  constructor(
+    scope: Scope,
+    private options: D1StateStoreOptions = {},
+  ) {
+    super(scope);
+  }
+
+  async provision(): Promise<StateStoreProxy.Dispatch> {
+    const db = await createDatabaseClient(this.options);
+    const operations = new SQLiteStateStoreOperations(db, {
+      chain: this.scope.chain,
+    });
+    return operations.dispatch.bind(operations);
+  }
+}
+
+const createDatabaseClient = memoize(async (options: D1StateStoreOptions) => {
+  const { createCloudflareApi } = await import("../cloudflare/api.ts");
+  const api = await createCloudflareApi(options);
+  const database = await upsertDatabase(
+    api,
+    options.databaseName ?? "alchemy-state",
+  );
+  const remoteCallback: RemoteCallback = async (sql, params) => {
+    const [result] = await extractCloudflareResult<
+      {
+        results: { columns: string[]; rows: any[][] };
+      }[]
+    >(
+      "execute D1 query",
+      api.post(
+        `/accounts/${api.accountId}/d1/database/${database.id}/raw`,
+        { sql, params },
+        {
+          headers: {
+            "Content-Type": "application/json",
+          },
+        },
+      ),
+    );
+    assert(result, "Missing result");
+    return {
+      rows: Object.values(result.results.rows),
+    };
+  };
+  return drizzle(remoteCallback, {
+    schema,
+  });
+});
+
+const upsertDatabase = async (api: CloudflareApi, databaseName: string) => {
+  const { listDatabases, createDatabase } = await import(
+    "../cloudflare/d1-database.ts"
+  );
+  const { applyMigrations, listMigrationsFiles } = await import(
+    "../cloudflare/d1-migrations.ts"
+  );
+  const migrate = async (databaseId: string) => {
+    await applyMigrations({
+      migrationsFiles: await listMigrationsFiles(MIGRATIONS_DIRECTORY),
+      migrationsTable: "migrations",
+      accountId: api.accountId,
+      databaseId,
+      api,
+      quiet: true,
+    });
+  };
+  const databases = await listDatabases(api, databaseName);
+  if (databases[0]) {
+    await migrate(databases[0].id);
+    return {
+      id: databases[0].id,
+    };
+  }
+  const res = await createDatabase(api, databaseName, {
+    readReplication: { mode: "disabled" },
+  });
+  assert(res.result.uuid, "Missing UUID for database");
+  await migrate(res.result.uuid);
+  return {
+    id: res.result.uuid,
+  };
+};

package/src/{cloudflare/do-state-store/store.ts → state/dofs-state-store/index.ts}

@@ -1,14 +1,16 @@
 import { alchemy } from "../../alchemy.ts";
+import {
+  createCloudflareApi,
+  type CloudflareApiOptions,
+} from "../../cloudflare/api.ts";
+import { getAccountSubdomain } from "../../cloudflare/worker-subdomain.ts";
 import { ResourceScope } from "../../resource.ts";
 import type { Scope } from "../../scope.ts";
-import { serialize } from "../../serde.ts";
+import { deserialize, serialize } from "../../serde.ts";
 import type { State, StateStore } from "../../state.ts";
-import { deserialize } from "../../serde.ts";
-import { createCloudflareApi, type CloudflareApiOptions } from "../api.ts";
-import { getAccountSubdomain } from "../worker/shared.ts";
-import { DOStateStoreClient, upsertStateStoreWorker } from "./internal.ts";
+import { DOFSStateStoreClient, upsertStateStoreWorker } from "./store.ts";
 
-export interface DOStateStoreOptions extends CloudflareApiOptions {
+export interface DOFSStateStoreOptions extends CloudflareApiOptions {
   /**
    * The prefix to use for state keys.
    * Each app and stage has its own state store, so this is primarily for testing.
@@ -45,13 +47,18 @@ export interface DOStateStoreOptions extends CloudflareApiOptions {
       };
 }
 
-export class DOStateStore implements StateStore {
+/**
+ * A state store backed by a {@link https://www.npmjs.com/package/dofs Durable Object File System (DOFS)}.
+ *
+ * @deprecated This state store is no longer recommended for production use. Please use {@link https://alchemy.run/guides/cloudflare-state-store/ CloudflareStateStore} from `alchemy/state` instead, which offers better reliability and performance.
+ */
+export class DOFSStateStore implements StateStore {
   private prefix: string;
-  private client?: Promise<DOStateStoreClient>;
+  private client?: Promise<DOFSStateStoreClient>;
 
   constructor(
     private readonly scope: Scope,
-    private readonly options: DOStateStoreOptions = {},
+    private readonly options: DOFSStateStoreOptions = {},
   ) {
     this.prefix = [options.prefix ?? "alchemy", ...scope.chain, ""].join("/");
   }
@@ -61,7 +68,7 @@ export class DOStateStore implements StateStore {
       this.options.worker?.token ??
       (await alchemy.secret.env.ALCHEMY_STATE_TOKEN).unencrypted;
     if (this.options.worker && "url" in this.options.worker) {
-      const client = new DOStateStoreClient({
+      const client = new DOFSStateStoreClient({
         app: this.scope.appName ?? "alchemy",
         stage: this.scope.stage,
         url: this.options.worker.url,
@@ -75,11 +82,11 @@ export class DOStateStore implements StateStore {
       }
       if (res.status === 401) {
         throw new Error(
-          "A worker URL was provided to DOStateStore, but the token is incorrect. Correct the token or remove the worker URL to create a new worker.",
+          "A worker URL was provided to DOFSStateStore, but the token is incorrect. Correct the token or remove the worker URL to create a new worker.",
         );
       }
       throw new Error(
-        `A worker URL was provided to DOStateStore, but the worker status is ${res.status} ${res.statusText}.`,
+        `A worker URL was provided to DOFSStateStore, but the worker status is ${res.status} ${res.statusText}.`,
       );
     }
     const workerName = this.options.worker?.name ?? "alchemy-state";
@@ -98,7 +105,7 @@ export class DOStateStore implements StateStore {
         "Failed to access state store worker because the workers.dev subdomain is not available.",
       );
     }
-    const client = new DOStateStoreClient({
+    const client = new DOFSStateStoreClient({
       app: this.scope.appName ?? "alchemy",
       stage: this.scope.stage,
       url: `https://${workerName}.${subdomain}.workers.dev`,

package/src/{cloudflare/do-state-store/internal.ts → state/dofs-state-store/store.ts}

@@ -1,10 +1,10 @@
+import { handleApiError } from "../../cloudflare/api-error.ts";
+import type { CloudflareApi } from "../../cloudflare/api.ts";
+import { getInternalWorkerBundle } from "../../cloudflare/bundle/internal-worker-bundle.ts";
+import type { WorkerMetadata } from "../../cloudflare/worker-metadata.ts";
 import { logger } from "../../util/logger.ts";
 import { withExponentialBackoff } from "../../util/retry.ts";
-import { handleApiError } from "../api-error.ts";
-import type { CloudflareApi } from "../api.ts";
-import type { WorkerMetadata } from "../worker-metadata.ts";
-import { getWorkerTemplate } from "../worker/shared.ts";
-import type { DOStateStoreAPI } from "./types.ts";
+import type { DOStateStoreAPI } from "./api.ts";
 
 interface DOStateStoreClientOptions {
   app: string;
@@ -22,7 +22,7 @@ class StateStoreError extends Error {
   }
 }
 
-export class DOStateStoreClient {
+export class DOFSStateStoreClient {
   constructor(private readonly options: DOStateStoreClientOptions) {}
 
   async rpc<T extends keyof DOStateStoreAPI.API>(
@@ -141,13 +141,13 @@ export async function upsertStateStoreWorker(
     return;
   }
   const formData = new FormData();
-  const worker = await getWorkerTemplate("do-state-store");
-  formData.append(worker.name, worker);
+  const { file } = await getInternalWorkerBundle("dofs-state-store");
+  formData.append(file.name, file);
   formData.append(
     "metadata",
     new Blob([
       JSON.stringify({
-        main_module: worker.name,
+        main_module: file.name,
         compatibility_date: "2025-06-01",
         compatibility_flags: ["nodejs_compat"],
         bindings: [
@@ -222,21 +222,3 @@ async function getWorkerStatus(api: CloudflareApi, workerName: string) {
     tag: json.result.tags.find((tag) => tag.startsWith("alchemy-state-store:")),
   };
 }
-
-export async function getAccountSubdomain(api: CloudflareApi) {
-  const key = `subdomain:${api.accountId}`;
-  const cached = cache.get(key);
-  if (cached) {
-    return cached;
-  }
-  const res = await api.get(`/accounts/${api.accountId}/workers/subdomain`);
-  if (!res.ok) {
-    throw new Error(
-      `Failed to get account subdomain: ${res.status} ${res.statusText}: ${await res.text().catch(() => "unknown error")}`,
-    );
-  }
-  const json: { result: { subdomain: string } } = await res.json();
-  const subdomain = json.result.subdomain;
-  cache.set(key, subdomain);
-  return subdomain;
-}