alchemy 0.63.1 → 0.64.0

package/src/planetscale/password.ts

@@ -1,17 +1,17 @@
+import { isDeepStrictEqual } from "node:util";
 import { alchemy } from "../alchemy.ts";
 import type { Context } from "../context.ts";
 import { Resource } from "../resource.ts";
 import type { Secret } from "../secret.ts";
-import { logger } from "../util/logger.ts";
 import { lowercaseId } from "../util/nanoid.ts";
-import { PlanetScaleApi } from "./api.ts";
+import { PlanetScaleClient, type PlanetScaleProps } from "./api/client.gen.ts";
 import type { Branch } from "./branch.ts";
 import type { Database } from "./database.ts";
 
 /**
  * Properties for creating or updating a PlanetScale Branch
  */
-export interface PasswordProps {
+export interface PasswordProps extends PlanetScaleProps {
   /**
    * The name of the password
    *
@@ -21,7 +21,7 @@ export interface PasswordProps {
 
   /**
    * The organization ID where the password will be created
-   * Required when using string database name, optional when using Database resource
+   * Required when using string database name, optional when using Database or Branch resource
    */
   organizationId?: string;
 
@@ -34,15 +34,10 @@ export interface PasswordProps {
   /**
    * The branch where the password will be created
    * Can be either a branch name (string) or Branch resource
-   * Defaults to "main" if not provided
+   * @default "main"
    */
   branch?: string | Branch;
 
-  /**
-   * PlanetScale API token (overrides environment variable)
-   */
-  apiKey?: Secret;
-
   /**
    * The password
    */
@@ -265,109 +260,115 @@ export const Password = Resource(
     id: string,
     props: PasswordProps,
   ): Promise<Password> {
-    const apiKey =
-      props.apiKey?.unencrypted || process.env.PLANETSCALE_API_TOKEN;
-    if (!apiKey) {
-      throw new Error("PLANETSCALE_API_TOKEN environment variable is required");
-    }
     const nameSlug = this.isReplacement
       ? lowercaseId()
       : (this.output?.nameSlug ?? lowercaseId());
     const name = `${(props.name ?? this.output?.name ?? this.scope.createPhysicalName(id)).toLowerCase()}-${nameSlug}`;
 
-    const api = new PlanetScaleApi({ apiKey });
-    const branchName =
-      props.branch == null
-        ? "main"
-        : typeof props.branch === "string"
-          ? props.branch
-          : props.branch.name;
-    const databaseName =
+    const api = new PlanetScaleClient(props);
+    const database =
       typeof props.database === "string" ? props.database : props.database.name;
+    const branch =
+      typeof props.branch === "string"
+        ? props.branch
+        : (props.branch?.name ?? "main");
+    const organization =
+      props.organizationId ??
+      ((typeof props.branch !== "string" && props.branch?.organizationId) ||
+        (typeof props.database !== "string" && props.database.organizationId));
+
+    if (!organization) {
+      throw new Error("Organization ID is required");
+    }
 
     if (this.phase === "delete") {
-      try {
-        if (this.output?.name) {
-          const response = await api.delete(
-            `/organizations/${props.organizationId}/databases/${databaseName}/branches/${branchName}/passwords/${this.output.id}`,
-          );
+      if (this.output?.id) {
+        const res = await api.organizations.databases.branches.passwords.delete(
+          {
+            path: {
+              organization,
+              database,
+              branch,
+              id: this.output.id,
+            },
+            result: "full",
+          },
+        );
 
-          if (!response.ok && response.status !== 404) {
-            throw new Error(
-              `Failed to delete branch: ${response.statusText} ${await response.text()}`,
-            );
-          }
+        if (res.error && res.error.status !== 404) {
+          throw new Error(`Failed to delete branch "${branch}"`, {
+            cause: res.error,
+          });
         }
-      } catch (error) {
-        logger.error("Error deleting password:", error);
-        throw error;
       }
       return this.destroy();
     }
     if (this.phase === "update") {
+      // Only name and cidrs can be updated in place; all other properties require replacement.
       if (
-        this.output?.name === name &&
-        ((this.output?.cidrs === undefined && props.cidrs === undefined) ||
-          (Array.isArray(this.output?.cidrs) &&
-            Array.isArray(props.cidrs) &&
-            this.output.cidrs.length === props.cidrs.length &&
-            this.output.cidrs.every((cidr, i) => cidr === props.cidrs![i])))
+        diff({ ...props, name }, this.output).some(
+          (prop) => prop !== "name" && prop !== "cidrs",
+        )
       ) {
         return this.replace();
       }
-      const updateResponse = await api.patch(
-        `/organizations/${props.organizationId}/databases/${databaseName}/branches/${branchName}/passwords/${this.output.id}`,
-        {
+      await api.organizations.databases.branches.passwords.patch({
+        path: {
+          organization,
+          database,
+          branch,
+          id: this.output.id,
+        },
+        body: {
           name,
           cidrs: props.cidrs,
         },
-      );
-
-      if (!updateResponse.ok) {
-        throw new Error(
-          `Failed to update password: ${updateResponse.statusText} ${await updateResponse.text()}`,
-        );
-      }
+      });
 
       return this({
         ...this.output,
         ...props,
+        name,
       });
     }
 
-    try {
-      const createResponse = await api.post(
-        `/organizations/${props.organizationId}/databases/${databaseName}/branches/${branchName}/passwords`,
-        {
-          name,
-          role: props.role,
-          replica: props.replica,
-          ttl: props.ttl,
-          cidrs: props.cidrs,
-        },
-      );
-
-      if (!createResponse.ok) {
-        throw new Error(
-          `Failed to create password: ${createResponse.statusText} ${await createResponse.text()}`,
-        );
-      }
+    const data = await api.organizations.databases.branches.passwords.post({
+      path: {
+        organization,
+        database,
+        branch,
+      },
+      body: {
+        name,
+        role: props.role,
+        replica: props.replica,
+        ttl: props.ttl,
+        cidrs: props.cidrs,
+      },
+    });
 
-      const data = await createResponse.json<any>();
-
-      return this({
-        id: data.id,
-        expiresAt: data.expires_at,
-        host: data.access_host_url,
-        username: data.username,
-        password: alchemy.secret(data.plain_text),
-        nameSlug,
-        ...props,
-        name: `${props.name}-${nameSlug}`,
-      });
-    } catch (error) {
-      logger.error("Error managing password:", error);
-      throw error;
-    }
+    return this({
+      id: data.id,
+      expiresAt: data.expires_at,
+      host: data.access_host_url,
+      username: data.username,
+      password: alchemy.secret(data.plain_text),
+      nameSlug,
+      ...props,
+      name: `${props.name}-${nameSlug}`,
+    });
   },
 );
+
+/**
+ * Returns an array of keys in `b` that are different from `a`.
+ */
+const diff = <T>(a: T, b: NoInfer<T>) => {
+  const keys: (keyof T)[] = [];
+  for (const key in a) {
+    if (!isDeepStrictEqual(a[key], b[key])) {
+      keys.push(key);
+    }
+  }
+  return keys;
+};

package/src/planetscale/utils.ts

@@ -1,4 +1,4 @@
-import type { PlanetScaleApi } from "./api.ts";
+import type { PlanetScaleClient } from "./api/client.gen.ts";
 
 export type PlanetScaleClusterSize =
   | "PS_DEV"
@@ -25,165 +25,184 @@ export type PlanetScaleClusterSize =
  * Wait for a database to be ready with exponential backoff
  */
 export async function waitForDatabaseReady(
-  api: PlanetScaleApi,
-  organizationId: string,
-  databaseName: string,
-  branchName?: string,
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch?: 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;
-    }
-
-    if (Date.now() - startTime >= 60000) {
-      throw new Error(
-        `Timeout waiting for database ${databaseName} to be ready`,
-      );
-    }
-
-    await new Promise((resolve) => setTimeout(resolve, waitMs));
-    waitMs = Math.min(waitMs * 2, 1000); // Cap at 1s intervals
-  }
+  await poll({
+    description: `database "${database}" ${branch ? `branch "${branch}"` : ""} ready`,
+    fn: async () => {
+      if (branch) {
+        return await api.organizations.databases.branches.get({
+          path: { organization, database, name: branch },
+        });
+      }
+      return await api.organizations.databases.get({
+        path: { organization, name: database },
+      });
+    },
+    predicate: (item) => item.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;
-
-  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}`,
-      );
-    }
-
-    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;
-    }
-
-    if (Date.now() - start > 600_000) {
-      throw new Error(`Timeout waiting for keyspace "${keyspace}" to be ready`);
-    }
-
-    await new Promise((r) => setTimeout(r, delay));
-    delay = Math.min(delay * 2, 1_000);
-  }
+  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,
+  });
 }
 
 /**
- * Fix cluster size for a branch
+ * 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 fixClusterSize(
-  api: PlanetScaleApi,
-  organizationId: string,
-  databaseName: string,
-  branchName: string,
+export async function ensureProductionBranchClusterSize(
+  api: PlanetScaleClient,
+  organization: string,
+  database: string,
+  branch: string,
   expectedClusterSize: PlanetScaleClusterSize,
   isDBReady: boolean,
 ): Promise<void> {
   if (!isDBReady) {
-    await waitForDatabaseReady(api, organizationId, databaseName);
+    await waitForDatabaseReady(api, organization, database);
   }
 
   // 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>();
+  const branchData = await api.organizations.databases.branches.get({
+    path: {
+      organization,
+      database,
+      name: branch,
+    },
+  });
   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}`);
+      await waitForDatabaseReady(api, organization, database, branch);
     }
+    await api.organizations.databases.branches.promote.post({
+      path: {
+        organization,
+        database,
+        name: 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 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}`);
   }
-  const defaultKs = defaultKsData.name;
-  let currentSize = defaultKsData.cluster_name as PlanetScaleClusterSize;
 
   // 3. 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
   // 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,
     );
   }
 }
+
+/**
+ * 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",