alchemy 0.63.1 → 0.65.0

package/src/planetscale/utils.ts

@@ -1,4 +1,5 @@
-import type { PlanetScaleApi } from "./api.ts";
+import type { PlanetScaleClient } from "./api/client.gen.ts";
+import type { DatabaseBranch } from "./api/types.gen.ts";
 
 export type PlanetScaleClusterSize =
   | "PS_DEV"
@@ -22,168 +23,328 @@ export type PlanetScaleClusterSize =
   | (string & {});
 
 /**
- * Wait for a database to be ready with exponential backoff
+ * Ensures that the given cluster size is in the correct format.
  */
-export async function waitForDatabaseReady(
-  api: PlanetScaleApi,
-  organizationId: string,
-  databaseName: string,
-  branchName?: string,
-): Promise<void> {
-  const startTime = Date.now();
-  let waitMs = 100;
-  const branchSuffix = branchName ? `/branches/${branchName}` : "";
-  while (true) {
-    const response = await api.get(
-      `/organizations/${organizationId}/databases/${databaseName}${branchSuffix}`,
-    );
-
-    if (!response.ok) {
-      throw new Error(`Failed to check database state: ${response.statusText}`);
-    }
-
-    const data = await response.json<any>();
-    if (data.ready === true) {
-      return;
-    }
+export function sanitizeClusterSize(input: {
+  size: PlanetScaleClusterSize;
+  kind?: "mysql" | "postgresql";
+  arch?: "x86" | "arm";
+  region?: string;
+}): string {
+  // NAS-backed Postgres cluster sizes are formatted as `PS_<size>_<provider>_<arch>`,
+  // where <provider> is either "AWS" or "GCP", and <arch> is either "ARM" or "X86".
+  // Postgres clusters backed by PlanetScale Metal are more complex (e.g. "M6_160_AWS_INTEL_D_METAL_118"),
+  // so to avoid messing with those, we just check for AWS or GCP in the size.
+  if (input.kind === "postgresql" && !input.size.match(/(AWS|GCP)/)) {
+    // Infer the provider from the region.
+    // Not all AWS regions start with "aws-", but all GCP regions start with "gcp-".
+    const provider = input.region?.startsWith("gcp") ? "GCP" : "AWS";
+    const arch = (input.arch ?? "x86").toUpperCase();
+    return `${input.size}_${provider}_${arch}`;
+  }
+  return input.size;
+}
 
-    if (Date.now() - startTime >= 60000) {
-      throw new Error(
-        `Timeout waiting for database ${databaseName} to be ready`,
-      );
-    }
+/**
+ * Polls a branch until it is ready.
+ */
+export async function waitForBranchReady(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch: string,
+): Promise<DatabaseBranch> {
+  return await poll({
+    description: `branch "${branch}" ready`,
+    fn: () =>
+      api.organizations.databases.branches.get({
+        path: { organization, database, name: branch },
+      }),
+    predicate: (branch) => branch.ready,
+  });
+}
 
-    await new Promise((resolve) => setTimeout(resolve, waitMs));
-    waitMs = Math.min(waitMs * 2, 1000); // Cap at 1s intervals
-  }
+/**
+ * Polls a database until it is ready.
+ */
+export async function waitForDatabaseReady(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+): Promise<void> {
+  await poll({
+    description: `database "${database}" ready`,
+    fn: () =>
+      api.organizations.databases.get({
+        path: { organization, name: database },
+      }),
+    predicate: (database) => database.ready,
+  });
 }
 
 /**
- * Wait for a keyspace to be ready
+ * Polls a keyspace until it is finished resizing.
  */
 export async function waitForKeyspaceReady(
-  api: PlanetScaleApi,
-  org: string,
-  db: string,
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
   branch: string,
   keyspace: string,
 ): Promise<void> {
-  const start = Date.now();
-  let delay = 100;
+  await poll({
+    description: `keyspace "${keyspace}" ready`,
+    fn: () =>
+      api.organizations.databases.branches.keyspaces.resizes.list({
+        path: { organization, database, branch, name: keyspace },
+      }),
+    predicate: (response) =>
+      response.data.every((item) => item.state !== "resizing"),
+    initialDelay: 100,
+    maxDelay: 1000,
+  });
+}
 
-  while (true) {
-    const res = await api.get(
-      `/organizations/${org}/databases/${db}/branches/${branch}/keyspaces/${keyspace}/resizes`,
-    );
-    if (!res.ok) {
-      throw new Error(
-        `Error fetching keyspace "${keyspace}": ${res.statusText}`,
+/**
+ * Ensure a branch is production and has the correct cluster size.
+ * If a branch is not production, it will be promoted to production because
+ * cluster sizes can only be configured for production branches.
+ */
+export async function ensureProductionBranchClusterSize(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch: string,
+  kind: "mysql" | "postgresql",
+  expectedClusterSize: PlanetScaleClusterSize,
+): Promise<void> {
+  switch (kind) {
+    case "mysql": {
+      // Vitess databases must be promoted before resizing
+      await ensureProductionBranch(api, organization, database, branch);
+      await ensureMySQLClusterSize(
+        api,
+        organization,
+        database,
+        branch,
+        expectedClusterSize,
       );
+      break;
     }
-
-    const ks = await res.json<{
-      data: [
-        {
-          state: string;
-        },
-      ];
-    }>();
-    // once it's fully ready, we can proceed
-    if (ks.data.every((item) => item.state !== "resizing")) {
-      return;
+    case "postgresql": {
+      // Postgres databases must be resized first before promoting, otherwise 500 error
+      await ensurePostgresClusterSize(
+        api,
+        organization,
+        database,
+        branch,
+        expectedClusterSize,
+      );
+      await ensureProductionBranch(api, organization, database, branch);
+      break;
     }
+  }
+}
 
-    if (Date.now() - start > 600_000) {
-      throw new Error(`Timeout waiting for keyspace "${keyspace}" to be ready`);
+/**
+ * Checks if a branch is production and promotes it if it is not.
+ */
+async function ensureProductionBranch(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  name: string,
+): Promise<void> {
+  const data = await api.organizations.databases.branches.get({
+    path: {
+      organization,
+      database,
+      name,
+    },
+  });
+  if (!data.production) {
+    if (!data.ready) {
+      await waitForBranchReady(api, organization, database, name);
     }
-
-    await new Promise((r) => setTimeout(r, delay));
-    delay = Math.min(delay * 2, 1_000);
+    await api.organizations.databases.branches.promote.post({
+      path: { organization, database, name },
+    });
   }
 }
 
 /**
- * Fix cluster size for a branch
+ * Ensures that a MySQL branch has the correct cluster size.
  */
-export async function fixClusterSize(
-  api: PlanetScaleApi,
-  organizationId: string,
-  databaseName: string,
-  branchName: string,
+async function ensureMySQLClusterSize(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch: string,
   expectedClusterSize: PlanetScaleClusterSize,
-  isDBReady: boolean,
 ): Promise<void> {
-  if (!isDBReady) {
-    await waitForDatabaseReady(api, organizationId, databaseName);
-  }
-
-  // 1. Ensure branch is production
-  let branchRes = await api.get(
-    `/organizations/${organizationId}/databases/${databaseName}/branches/${branchName}`,
-  );
-  if (!branchRes.ok) {
-    throw new Error(`Unable to get branch data: ${branchRes.statusText}`);
-  }
-  let branchData = await branchRes.json<any>();
-  if (!branchData.production) {
-    if (!branchData.ready) {
-      await waitForDatabaseReady(api, organizationId, databaseName, branchName);
-    }
-    const promoteRes = await api.post(
-      `/organizations/${organizationId}/databases/${databaseName}/branches/${branchName}/promote`,
-    );
-    if (!promoteRes.ok) {
-      throw new Error(`Unable to promote branch: ${promoteRes.statusText}`);
-    }
+  // 1. Load default keyspace
+  const keyspaces = await api.organizations.databases.branches.keyspaces.list({
+    path: {
+      organization,
+      database,
+      branch,
+    },
+  });
+  const defaultKeyspace = keyspaces.data.find((x) => x.name === database); // Default keyspace is always the same name as the database
+  if (!defaultKeyspace) {
+    throw new Error(`No default keyspace found for branch ${branch}`);
   }
-  // 2. Load default keyspace
-  const ksListRes = await api.get(
-    `/organizations/${organizationId}/databases/${databaseName}/branches/${branchName}/keyspaces`,
-  );
-  if (!ksListRes.ok) {
-    throw new Error(`Failed to list keyspaces: ${ksListRes.statusText}`);
-  }
-  const ksList = (await ksListRes.json<any>()).data as Array<{
-    name: string;
-    cluster_name: string;
-  }>;
-  const defaultKsData = ksList.find((x) => x.name === databaseName); // Default keypsace is always the same name as the database
-  if (ksList.length === 0 || !defaultKsData) {
-    throw new Error(`No default keyspace found for branch ${branchName}`);
-  }
-  const defaultKs = defaultKsData.name;
-  let currentSize = defaultKsData.cluster_name as PlanetScaleClusterSize;
 
-  // 3. Wait until any in-flight resize is done
+  // 2. Wait until any in-flight resize is done
   await waitForKeyspaceReady(
     api,
-    organizationId,
-    databaseName,
-    branchName,
-    defaultKs,
+    organization,
+    database,
+    branch,
+    defaultKeyspace.name,
   );
 
-  // 4. If size mismatch, trigger resize and wait again
+  // 3. If size mismatch, trigger resize and wait again
   // Ideally this would use the undocumented Keyspaces API, but there seems to be a missing oauth scope that we cannot add via the console yet
-  if (currentSize !== expectedClusterSize) {
-    const resizeRes = await api.patch(
-      `/organizations/${organizationId}/databases/${databaseName}/branches/${branchName}/cluster`,
-      { cluster_size: expectedClusterSize },
-    );
-    if (!resizeRes.ok) {
-      const text = await resizeRes.text();
-      throw new Error(
-        `Failed to start resize: ${resizeRes.statusText} ${text}`,
-      );
-    }
+  if (defaultKeyspace.cluster_name !== expectedClusterSize) {
+    await api.organizations.databases.branches.cluster.patch({
+      path: {
+        organization,
+        database,
+        name: branch,
+      },
+      body: { cluster_size: expectedClusterSize },
+    });
 
     // Poll until the resize completes
     await waitForKeyspaceReady(
       api,
-      organizationId,
-      databaseName,
-      branchName,
-      defaultKs,
+      organization,
+      database,
+      branch,
+      defaultKeyspace.name,
     );
   }
 }
+
+/**
+ * Ensures that a Postgres branch has the correct cluster size.
+ */
+async function ensurePostgresClusterSize(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch: string,
+  expectedClusterSize: PlanetScaleClusterSize,
+): Promise<void> {
+  const data = await api.organizations.databases.branches.get({
+    path: {
+      organization,
+      database,
+      name: branch,
+    },
+  });
+  if (data.cluster_name === expectedClusterSize) {
+    return;
+  }
+  await waitForPendingPostgresChanges(api, organization, database, branch);
+  const change = await api.organizations.databases.branches.changes.patch({
+    path: {
+      organization,
+      database,
+      branch,
+    },
+    body: {
+      cluster_size: expectedClusterSize,
+    },
+  });
+  await waitForPendingPostgresChanges(
+    api,
+    organization,
+    database,
+    branch,
+    change.id,
+  );
+}
+
+/**
+ * Polls for a pending Postgres change to be completed.
+ */
+async function waitForPendingPostgresChanges(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch: string,
+  changeId?: string,
+) {
+  await poll({
+    description: `changes for branch "${branch}"`,
+    fn: () =>
+      api.organizations.databases.branches.changes.list({
+        path: { organization, database, branch },
+      }),
+    predicate: (response) =>
+      response.data.every(
+        (change) =>
+          change.state === "completed" ||
+          change.state === "canceled" ||
+          (changeId && change.id === changeId),
+      ),
+  });
+}
+
+/**
+ * Polls a function until it returns a result that satisfies the predicate.
+ */
+async function poll<T>(input: {
+  /**
+   * A description of the operation being polled.
+   */
+  description: string;
+
+  /**
+   * The function to poll.
+   */
+  fn: () => Promise<T>;
+
+  /**
+   * A predicate that determines if the operation has completed.
+   */
+  predicate: (result: T) => boolean;
+
+  /**
+   * The initial delay between polls.
+   * @default 250ms
+   */
+  initialDelay?: number;
+
+  /**
+   * The maximum delay between polls.
+   * @default 2_500ms (2.5 seconds)
+   */
+  maxDelay?: number;
+
+  /**
+   * The timeout for the poll in milliseconds.
+   * @default 1_000_000 (~16 minutes)
+   */
+  timeout?: number;
+}): Promise<T> {
+  const start = Date.now();
+  let delay = input.initialDelay ?? 250;
+  while (true) {
+    const result = await input.fn();
+    if (input.predicate(result)) {
+      return result;
+    }
+    if (Date.now() - start >= (input.timeout ?? 1_000_000)) {
+      throw new Error(
+        `Timed out waiting for ${input.description} after ${Math.round(
+          (input.timeout ?? 1_000_000) / 1000,
+        )}s`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    delay = Math.min(delay * 2, input.maxDelay ?? 5_000);
+  }
+}

package/src/scope.ts

@@ -288,6 +288,11 @@ export class Scope {
     this.dataMutex = new AsyncMutex();
   }
 
+  public async has(id: string, type?: string): Promise<boolean> {
+    const state = await this.state.get(id);
+    return state !== undefined && (type === undefined || state.kind === type);
+  }
+
   public createPhysicalName(id: string, delimiter = "-"): string {
     const app = this.appName;
     const stage = this.stage;
@@ -489,9 +494,9 @@ export class Scope {
     return null;
   }
 
-  public async finalize(force?: boolean) {
+  public async finalize(options?: { force?: boolean; noop?: boolean }) {
     const shouldForce =
-      force ||
+      options?.force ||
       this.parent === undefined ||
       this?.parent?.scopeName === this.root.scopeName;
     if (this.phase === "read") {
@@ -520,7 +525,10 @@ export class Scope {
         await this.destroyPendingDeletions();
         await Promise.all(
           Array.from(this.children.values()).map((child) =>
-            child.finalize(shouldForce),
+            child.finalize({
+              force: shouldForce,
+              noop: options?.noop,
+            }),
           ),
         );
       }
@@ -541,6 +549,7 @@ export class Scope {
         quiet: this.quiet,
         strategy: this.destroyStrategy,
         force: shouldForce,
+        noop: options?.noop,
       });
       this.rootTelemetryClient?.record({
         event: "app.success",

package/src/secret.ts

@@ -17,8 +17,6 @@ function nextName() {
   return `alchemy:anonymous-secret-${i++}`;
 }
 
-const SecretSymbol = Symbol.for("alchemy::Secret");
-
 /**
  * Internal wrapper for sensitive values like API keys and credentials.
  * When stored in alchemy state files, the value is automatically encrypted
@@ -55,8 +53,6 @@ const SecretSymbol = Symbol.for("alchemy::Secret");
  * }
  */
 export class Secret<T = string> {
-  [SecretSymbol] = true;
-
   /**
    * @internal
    */

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

@@ -47,13 +47,13 @@ export class CloudflareStateStore extends StateStoreProxy {
   options: CloudflareStateStoreOptions & { stateToken: Secret<string> };
   constructor(scope: Scope, options: CloudflareStateStoreOptions = {}) {
     super(scope);
-    const stateToken =
-      options.stateToken ?? alchemy.secret(process.env.ALCHEMY_STATE_TOKEN);
-    if (!stateToken) {
+    if (!options.stateToken && !process.env.ALCHEMY_STATE_TOKEN) {
       throw new Error(
-        "Missing token for DOStateStore. Please set ALCHEMY_STATE_TOKEN in the environment or set the `stateToken` option in the DOStateStore constructor.",
+        "Missing token for CloudflareStateStore. Please set ALCHEMY_STATE_TOKEN in the environment or set the `stateToken` option in the CloudflareStateStore constructor. See https://alchemy.run/guides/cloudflare-state-store/",
       );
     }
+    const stateToken =
+      options.stateToken ?? alchemy.secret(process.env.ALCHEMY_STATE_TOKEN);
     this.options = {
       ...options,
       stateToken: stateToken,

package/src/test/bun.ts

@@ -53,9 +53,9 @@ type test = {
    */
   skipIf(condition: boolean): test;
 
-  beforeAll(fn: (scope: Scope) => Promise<void>): void;
+  beforeAll(fn: (scope: Scope) => Promise<void>, timeout?: number): void;
 
-  afterAll(fn: (scope: Scope) => Promise<void>): void;
+  afterAll(fn: (scope: Scope) => Promise<void>, timeout?: number): void;
 
   /**
    * Current test scope

package/src/test/vitest.ts

@@ -57,9 +57,9 @@ type test = {
    */
   skipIf(condition: boolean): test;
 
-  beforeAll(fn: (scope: Scope) => Promise<void>): void;
+  beforeAll(fn: (scope: Scope) => Promise<void>, timeout?: number): void;
 
-  afterAll(fn: (scope: Scope) => Promise<void>): void;
+  afterAll(fn: (scope: Scope) => Promise<void>, timeout?: number): void;
 
   /**
    * Current test scope
@@ -134,12 +134,12 @@ export function test(
     password: process.env.ALCHEMY_PASSWORD,
   });
 
-  test.beforeAll = (fn: (scope: Scope) => Promise<void>) => {
-    return beforeAll(() => scope.run(() => fn(scope)));
+  test.beforeAll = (fn: (scope: Scope) => Promise<void>, timeout?: number) => {
+    return beforeAll(() => scope.run(() => fn(scope)), timeout);
   };
 
-  test.afterAll = (fn: (scope: Scope) => Promise<void>) => {
-    return afterAll(() => scope.run(() => fn(scope)));
+  test.afterAll = (fn: (scope: Scope) => Promise<void>, timeout?: number) => {
+    return afterAll(() => scope.run(() => fn(scope)), timeout);
   };
 
   return test as test;

package/src/util/content-type.ts

@@ -11,10 +11,10 @@ const mimeTypes: Record<string, string> = {
   ".jpeg": "image/jpeg",
   ".jpg": "image/jpeg",
   ".js.map": "application/source-map",
-  ".js": "application/javascript",
+  ".js": "text/javascript",
   ".json": "application/json",
   ".md": "text/markdown",
-  ".mjs": "application/javascript+module",
+  ".mjs": "text/javascript",
   ".mp3": "audio/mpeg",
   ".mp4": "video/mp4",
   ".otf": "font/otf",