alchemy 2.0.0-beta.30 → 2.0.0-beta.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "2.0.0-beta.30",
+  "version": "2.0.0-beta.31",
   "homepage": "https://alchemy.run",
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
@@ -148,6 +148,12 @@
       "worker": "./src/Cloudflare/*/index.ts",
       "import": "./lib/Cloudflare/*/index.js"
     },
+    "./Drizzle": {
+      "types": "./lib/Drizzle/index.d.ts",
+      "bun": "./src/Drizzle/index.ts",
+      "worker": "./src/Drizzle/index.ts",
+      "import": "./lib/Drizzle/index.js"
+    },
     "./Axiom": {
       "types": "./lib/Axiom/index.d.ts",
       "bun": "./src/Axiom/index.ts",
@@ -172,6 +178,18 @@
       "worker": "./src/Kubernetes/index.ts",
       "import": "./lib/Kubernetes/index.js"
     },
+    "./Neon": {
+      "types": "./lib/Neon/index.d.ts",
+      "bun": "./src/Neon/index.ts",
+      "worker": "./src/Neon/index.ts",
+      "import": "./lib/Neon/index.js"
+    },
+    "./Neon/*": {
+      "types": "./lib/Neon/*/index.d.ts",
+      "bun": "./src/Neon/*/index.ts",
+      "worker": "./src/Neon/*/index.ts",
+      "import": "./lib/Neon/*/index.js"
+    },
     "./Output": {
       "types": "./lib/Output.d.ts",
       "bun": "./src/Output.ts",
@@ -257,14 +275,16 @@
     "@ai-sdk/provider": "^3.0.8",
     "@aws-sdk/credential-providers": "^3.0.0",
     "@clack/prompts": "^0.11.0",
-    "@distilled.cloud/aws": "^0.15.2",
-    "@distilled.cloud/axiom": "^0.15.2",
-    "@distilled.cloud/cloudflare": "^0.15.2",
+    "@distilled.cloud/aws": "^0.16.7",
+    "@distilled.cloud/axiom": "^0.16.7",
+    "@distilled.cloud/cloudflare": "^0.16.8",
     "@distilled.cloud/cloudflare-rolldown-plugin": "0.3.0",
-    "@distilled.cloud/cloudflare-runtime": "0.1.2",
+    "@distilled.cloud/cloudflare-runtime": "0.2.1",
     "@distilled.cloud/cloudflare-vite-plugin": "0.2.0",
-    "@distilled.cloud/core": "^0.15.2",
-    "@effect/vitest": ">=4.0.0-beta.58 || >=4.0.0",
+    "@distilled.cloud/core": "^0.16.7",
+    "@distilled.cloud/neon": "^0.16.7",
+    "pg": "^8.13.0",
+    "@effect/vitest": ">=4.0.0-beta.60 || >=4.0.0",
     "@libsql/client": "^0.17.0",
     "@octokit/rest": "^22.0.1",
     "@smithy/node-config-provider": "^4.0.0",
@@ -298,10 +318,11 @@
   "devDependencies": {
     "@clack/prompts": "^0.11.0",
     "@cloudflare/workers-types": "^4.20250805.0",
-    "@effect/platform-bun": ">=4.0.0-beta.58 || >=4.0.0",
-    "@effect/platform-node": ">=4.0.0-beta.58 || >=4.0.0",
-    "@effect/platform-node-shared": ">=4.0.0-beta.58 || >=4.0.0",
+    "@effect/platform-bun": ">=4.0.0-beta.60 || >=4.0.0",
+    "@effect/platform-node": ">=4.0.0-beta.60 || >=4.0.0",
+    "@effect/platform-node-shared": ">=4.0.0-beta.60 || >=4.0.0",
     "@oxc-project/types": "^0.127.0",
+    "@types/pg": "^8.11.0",
     "@types/aws-lambda": "^8.10.152",
     "@types/bun": "latest",
     "@types/node": "latest",
@@ -309,7 +330,7 @@
     "@types/proper-lockfile": "^4.1.4",
     "@types/react": "^19.2.2",
     "better-auth": "^1.6.2",
-    "effect": ">=4.0.0-beta.58 || >=4.0.0",
+    "effect": ">=4.0.0-beta.60 || >=4.0.0",
     "react-devtools-core": "^7.0.1",
     "solid-js": "latest",
     "tsconfig-paths": "^4.2.0",
@@ -318,9 +339,12 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@effect/platform-bun": ">=4.0.0-beta.58 || >=4.0.0",
-    "@effect/platform-node": ">=4.0.0-beta.58 || >=4.0.0",
-    "effect": ">=4.0.0-beta.58 || >=4.0.0",
+    "@effect/platform-bun": ">=4.0.0-beta.60 || >=4.0.0",
+    "@effect/platform-node": ">=4.0.0-beta.60 || >=4.0.0",
+    "@effect/sql-pg": ">=4.0.0-beta.60 || >=4.0.0",
+    "drizzle-kit": ">=1.0.0-rc.1",
+    "drizzle-orm": ">=1.0.0-rc.1",
+    "effect": ">=4.0.0-beta.60 || >=4.0.0",
     "vite": "^8.0.7"
   },
   "peerDependenciesMeta": {
@@ -330,6 +354,15 @@
     "@effect/platform-bun": {
       "optional": true
     },
+    "@effect/sql-pg": {
+      "optional": true
+    },
+    "drizzle-kit": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }

package/src/AWS/ACM/Certificate.ts

@@ -338,16 +338,34 @@ export const CertificateProvider = () =>
           const tags = yield* listCertificateTags(certificate.CertificateArn);
           return toAttrs(olds!, certificate, tags);
         }),
-        create: Effect.fn(function* ({ id, instanceId, news, session }) {
-          const tags = {
-            ...(yield* createInternalTags(id)),
-            ...news.tags,
-          };
-
-          const existing = yield* findManagedCertificate(id, news);
-          const certificate =
-            existing ??
-            (yield* withAcmRegion(
+        reconcile: Effect.fn(function* ({
+          id,
+          instanceId,
+          news,
+          output,
+          session,
+        }) {
+          const internalTags = yield* createInternalTags(id);
+          const desiredTags = { ...internalTags, ...news.tags };
+
+          // Observe — find the live certificate. Domain + SAN combo plus
+          // alchemy-owned tags identify a certificate uniquely; if we have
+          // a cached ARN, prefer that as the fast path. ACM certificates
+          // can't be renamed, and most fields trigger replace via diff,
+          // so the only real ensure path is "request if no managed
+          // certificate exists".
+          let certificate = output?.certificateArn
+            ? yield* describeCertificate(output.certificateArn)
+            : undefined;
+          if (!certificate?.CertificateArn) {
+            certificate = yield* findManagedCertificate(id, news);
+          }
+
+          // Ensure — request a new certificate if none exists. The
+          // `IdempotencyToken` (derived from `instanceId`) makes the
+          // request safe to retry.
+          if (!certificate?.CertificateArn) {
+            certificate = yield* withAcmRegion(
               acm
                 .requestCertificate({
                   DomainName: news.domainName,
@@ -364,7 +382,7 @@ export const CertificateProvider = () =>
                   IdempotencyToken: instanceId
                     .replaceAll(/[^a-zA-Z0-9]/g, "")
                     .slice(0, 32),
-                  Tags: createTagsList(tags),
+                  Tags: createTagsList(desiredTags),
                 })
                 .pipe(
                   Effect.flatMap((response) =>
@@ -379,7 +397,8 @@ export const CertificateProvider = () =>
                         ),
                   ),
                 ),
-            ));
+            );
+          }
 
           if (!certificate?.CertificateArn) {
             return yield* Effect.fail(
@@ -387,64 +406,48 @@ export const CertificateProvider = () =>
             );
           }
 
-          yield* session.note(certificate.CertificateArn);
+          const certificateArn = certificate.CertificateArn;
+          yield* session.note(certificateArn);
 
+          // Sync DNS validation. If the user wired a hostedZoneId, ensure
+          // validation records are upserted and the cert reaches `ISSUED`.
+          // For an already-issued cert this is mostly a fast-path: we only
+          // wait for validation records when the cert isn't already issued.
           const shouldAutoValidate =
             (news.validationMethod ?? defaultValidationMethod) === "DNS" &&
             news.hostedZoneId !== undefined;
 
-          const finalCertificate = shouldAutoValidate
-            ? yield* Effect.gen(function* () {
-                const withRecords = yield* waitForValidationRecords(
-                  certificate.CertificateArn!,
-                );
-                yield* upsertValidationRecords(news.hostedZoneId!, withRecords);
-                return yield* waitForIssued(certificate.CertificateArn!);
-              })
-            : certificate;
+          if (shouldAutoValidate && certificate.Status !== "ISSUED") {
+            const withRecords = yield* waitForValidationRecords(certificateArn);
+            yield* upsertValidationRecords(news.hostedZoneId!, withRecords);
+            certificate = yield* waitForIssued(certificateArn);
+          }
 
-          const listedTags = yield* listCertificateTags(
-            certificate.CertificateArn,
-          );
-          return toAttrs(news, finalCertificate, listedTags);
-        }),
-        update: Effect.fn(function* ({ id, olds, news, output, session }) {
-          const oldTags = {
-            ...(yield* createInternalTags(id)),
-            ...olds.tags,
-          };
-          const newTags = {
-            ...(yield* createInternalTags(id)),
-            ...news.tags,
-          };
-          const { removed, upsert } = diffTags(oldTags, newTags);
+          // Sync tags — diff observed cloud tags against desired so
+          // adoption rewrites ownership tags correctly.
+          const observedTags = yield* listCertificateTags(certificateArn);
+          const { removed, upsert } = diffTags(observedTags, desiredTags);
 
           if (upsert.length > 0) {
             yield* withAcmRegion(
               acm.addTagsToCertificate({
-                CertificateArn: output.certificateArn,
+                CertificateArn: certificateArn,
                 Tags: upsert,
               }),
             );
           }
-
           if (removed.length > 0) {
             yield* withAcmRegion(
               acm.removeTagsFromCertificate({
-                CertificateArn: output.certificateArn,
+                CertificateArn: certificateArn,
                 Tags: removed.map((Key) => ({ Key })),
               }),
             );
           }
 
-          const detail = yield* describeCertificate(output.certificateArn);
-          if (!detail?.CertificateArn) {
-            return output;
-          }
-
-          yield* session.note(output.certificateArn);
-          const tags = yield* listCertificateTags(output.certificateArn);
-          return toAttrs(news, detail, tags);
+          // Re-read so the returned attributes reflect any tag mutation.
+          const finalTags = yield* listCertificateTags(certificateArn);
+          return toAttrs(news, certificate, finalTags);
         }),
         delete: Effect.fn(function* ({ output }) {
           yield* withAcmRegion(

package/src/AWS/ApiGateway/Account.ts

@@ -0,0 +1,146 @@
+import * as ag from "@distilled.cloud/aws/api-gateway";
+import * as Effect from "effect/Effect";
+import { isResolved } from "../../Diff.ts";
+import type { Input } from "../../Input.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import type { Providers } from "../Providers.ts";
+import { retryOnApiStatusUpdating } from "./common.ts";
+
+export interface AccountProps {
+  /**
+   * IAM role ARN for API Gateway to push logs to CloudWatch.
+   */
+  cloudwatchRoleArn?: string;
+}
+
+export interface Account extends Resource<
+  "AWS.ApiGateway.Account",
+  AccountProps,
+  {
+    cloudwatchRoleArn: string | undefined;
+    /**
+     * True when this stack last applied a desired `cloudwatchRoleArn` (including clearing it).
+     * Used so destroy does not remove a role the stack never configured.
+     */
+    managesCloudwatchRoleArn: boolean;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * Account-level settings for Amazon API Gateway in the current region
+ * (CloudWatch logging role, etc.).
+ *
+ * @section Account settings
+ * @example Set logging role
+ * ```typescript
+ * yield* ApiGateway.Account("Account", {
+ *   cloudwatchRoleArn: role.roleArn,
+ * });
+ * ```
+ */
+const AccountResource = Resource<Account>("AWS.ApiGateway.Account");
+
+export { AccountResource as Account };
+
+export const AccountProvider = () =>
+  Provider.effect(
+    AccountResource,
+    Effect.gen(function* () {
+      return {
+        diff: Effect.fn(function* ({ news: newsIn, olds, output }) {
+          if (!isResolved(newsIn)) return;
+          const news = newsIn as AccountProps;
+          const prevManages = output?.managesCloudwatchRoleArn ?? false;
+          const nextManages = news.cloudwatchRoleArn !== undefined;
+          if (nextManages) {
+            if (news.cloudwatchRoleArn !== olds.cloudwatchRoleArn) {
+              return { action: "update" } as const;
+            }
+          } else if (prevManages) {
+            return { action: "update" } as const;
+          }
+        }),
+        read: Effect.fn(function* ({ output }) {
+          const a = yield* ag
+            .getAccount({})
+            .pipe(
+              Effect.catchTag("NotFoundException", () =>
+                Effect.succeed(undefined),
+              ),
+            );
+          return {
+            cloudwatchRoleArn: a?.cloudwatchRoleArn,
+            managesCloudwatchRoleArn: output?.managesCloudwatchRoleArn ?? false,
+          };
+        }),
+        reconcile: Effect.fn(function* ({ news: newsIn, session }) {
+          if (!isResolved(newsIn)) {
+            return yield* Effect.die("Account props were not resolved");
+          }
+          const news = newsIn as AccountProps;
+
+          // Observe — read the current account-level CloudWatch role from
+          // API Gateway. The account settings resource is a singleton per
+          // region, so there is no `ensure` step: we always sync.
+          const observed = yield* ag
+            .getAccount({})
+            .pipe(
+              Effect.catchTag("NotFoundException", () =>
+                Effect.succeed(undefined),
+              ),
+            );
+          const observedRoleArn = observed?.cloudwatchRoleArn;
+
+          // Sync the cloudwatchRoleArn — observed ↔ desired. We treat
+          // `undefined` desired as "do not manage the field" so the user
+          // can opt out without us clobbering whatever was already set
+          // out of band.
+          const manages = news.cloudwatchRoleArn !== undefined;
+          if (manages) {
+            const desired = news.cloudwatchRoleArn;
+            if (desired !== observedRoleArn) {
+              yield* retryOnApiStatusUpdating(
+                ag.updateAccount({
+                  patchOperations: desired
+                    ? [
+                        {
+                          op: "replace",
+                          path: "/cloudwatchRoleArn",
+                          value: desired,
+                        },
+                      ]
+                    : [{ op: "remove", path: "/cloudwatchRoleArn" }],
+                }),
+              );
+              yield* session.note("Updated API Gateway account settings");
+            }
+          }
+
+          const final = yield* ag.getAccount({});
+          return {
+            cloudwatchRoleArn: final.cloudwatchRoleArn,
+            managesCloudwatchRoleArn: manages,
+          };
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+          if (output.managesCloudwatchRoleArn) {
+            yield* retryOnApiStatusUpdating(
+              ag
+                .updateAccount({
+                  patchOperations: [
+                    { op: "remove", path: "/cloudwatchRoleArn" },
+                  ],
+                })
+                .pipe(
+                  Effect.catchTag("BadRequestException", () => Effect.void),
+                ),
+            );
+            yield* session.note("Cleared API Gateway account CloudWatch role");
+          }
+        }),
+      };
+    }),
+  );

package/src/AWS/ApiGateway/ApiKey.ts

@@ -0,0 +1,276 @@
+import { Region } from "@distilled.cloud/aws/Region";
+import * as ag from "@distilled.cloud/aws/api-gateway";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Stream from "effect/Stream";
+import { deepEqual, isResolved } from "../../Diff.ts";
+import { createPhysicalName } from "../../PhysicalName.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import type { Providers } from "../Providers.ts";
+import { createInternalTags, hasAlchemyTags, tagRecord } from "../../Tags.ts";
+
+import { apiKeyArn, syncTags } from "./common.ts";
+
+export interface ApiKeyProps {
+  /**
+   * Friendly name for the API key.
+   *
+   * If omitted, Alchemy generates a deterministic physical name from the
+   * stack, stage, logical ID, and instance ID.
+   */
+  name?: string;
+  /**
+   * Human-readable description shown in API Gateway.
+   */
+  description?: string;
+  /**
+   * Whether clients can use the key.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Appends a distinct suffix to the generated key value when AWS generates it.
+   */
+  generateDistinctId?: boolean;
+  /**
+   * Write-only value when creating; never stored in resource state or outputs.
+   * Wrap with `Redacted.make` so state encoding preserves redaction.
+   */
+  value?: Redacted.Redacted<string>;
+  /**
+   * Stage associations to attach directly to this API key.
+   */
+  stageKeys?: ag.StageKey[];
+  /**
+   * External customer identifier associated with the key.
+   */
+  customerId?: string;
+  /**
+   * User-defined tags. Alchemy internal tags are merged automatically.
+   */
+  tags?: Record<string, string>;
+}
+
+export interface ApiKey extends Resource<
+  "AWS.ApiGateway.ApiKey",
+  ApiKeyProps,
+  {
+    id: string;
+    name: string | undefined;
+    enabled: boolean | undefined;
+    tags: Record<string, string>;
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * API Gateway API key for usage plans and `apiKeyRequired` methods.
+ *
+ * @section API keys
+ * @example Generated key
+ * ```typescript
+ * const key = yield* ApiGateway.ApiKey("PartnerKey", {
+ *   generateDistinctId: true,
+ * });
+ * ```
+ */
+const ApiKeyResource = Resource<ApiKey>("AWS.ApiGateway.ApiKey");
+
+export { ApiKeyResource as ApiKey };
+
+const resolvedValue = (value: Redacted.Redacted<string> | undefined) =>
+  value ? Redacted.value(value) : undefined;
+
+const generatedName = (id: string, props: ApiKeyProps) =>
+  props.name
+    ? Effect.succeed(props.name)
+    : createPhysicalName({
+        id,
+        maxLength: 128,
+      });
+
+const readByName = Effect.fn(function* (id: string, name: string) {
+  const keys = yield* ag.getApiKeys
+    .items({ nameQuery: name, limit: 500, includeValues: false })
+    .pipe(Stream.runCollect);
+
+  for (const key of keys) {
+    if (key.name !== name || !key.id) continue;
+    if (yield* hasAlchemyTags(id, key.tags)) {
+      return key;
+    }
+  }
+  return undefined;
+});
+
+export const ApiKeyProvider = () =>
+  Provider.effect(
+    ApiKeyResource,
+    Effect.gen(function* () {
+      const awsRegion = yield* Region;
+
+      return {
+        stables: ["id"] as const,
+        diff: Effect.fn(function* ({ news: newsIn, olds }) {
+          if (!isResolved(newsIn)) return;
+          const news = newsIn as ApiKeyProps;
+          if (
+            // API Gateway never returns the key value after create, so rotating
+            // a user-supplied value is modeled as replacement instead of patch.
+            resolvedValue(news.value) !== resolvedValue(olds.value) ||
+            news.customerId !== olds.customerId
+          ) {
+            return { action: "replace" } as const;
+          }
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.id) return undefined;
+          const k = yield* ag
+            .getApiKey({ apiKey: output.id, includeValue: false })
+            .pipe(
+              Effect.catchTag("NotFoundException", () =>
+                Effect.succeed(undefined),
+              ),
+            );
+          if (!k?.id) return undefined;
+          return {
+            id: k.id,
+            name: k.name,
+            enabled: k.enabled,
+            tags: tagRecord(k.tags),
+          };
+        }),
+        reconcile: Effect.fn(function* ({ id, news: newsIn, output, session }) {
+          if (!isResolved(newsIn)) {
+            return yield* Effect.die("ApiKey props were not resolved");
+          }
+          const news = newsIn as ApiKeyProps;
+          const name = yield* generatedName(id, news);
+          const internalTags = yield* createInternalTags(id);
+          const desiredTags = { ...news.tags, ...internalTags };
+
+          // Observe — find the API key. We try the cached id first, fall
+          // back to scanning by name with the alchemy ownership filter so
+          // the reconciler converges after an out-of-band recreate or an
+          // adoption that bypassed our id cache.
+          let observed = output?.id
+            ? yield* ag
+                .getApiKey({ apiKey: output.id, includeValue: false })
+                .pipe(
+                  Effect.catchTag("NotFoundException", () =>
+                    Effect.succeed(undefined),
+                  ),
+                )
+            : undefined;
+          if (!observed?.id) {
+            observed = yield* readByName(id, name);
+          }
+
+          // Ensure — create if missing. Tolerate `ConflictException` as a
+          // race with a peer reconciler or a stray key with the same name:
+          // re-look up by name and treat the alchemy-owned hit as observed.
+          if (!observed?.id) {
+            const created = yield* ag
+              .createApiKey({
+                name,
+                description: news.description,
+                enabled: news.enabled,
+                generateDistinctId: news.generateDistinctId,
+                value: resolvedValue(news.value),
+                stageKeys: news.stageKeys,
+                customerId: news.customerId,
+                tags: desiredTags,
+              })
+              .pipe(
+                Effect.catchTag("ConflictException", () =>
+                  Effect.gen(function* () {
+                    const existing = yield* readByName(id, name);
+                    if (existing) return existing;
+                    return yield* Effect.fail(
+                      new ag.ConflictException({
+                        message: `API key '${name}' already exists and is not managed by alchemy`,
+                      }),
+                    );
+                  }),
+                ),
+              );
+            if (!created.id)
+              return yield* Effect.die("createApiKey missing id");
+            yield* session.note(`Created API key ${created.id}`);
+            observed = yield* ag.getApiKey({
+              apiKey: created.id,
+              includeValue: false,
+            });
+          }
+
+          const apiKeyId = observed.id!;
+
+          // Sync mutable scalar fields — observed ↔ desired patch list.
+          const patches: ag.PatchOperation[] = [];
+          if (news.name !== undefined && news.name !== observed.name) {
+            patches.push({
+              op: "replace",
+              path: "/name",
+              value: news.name,
+            });
+          }
+          if (
+            news.description !== undefined &&
+            news.description !== observed.description
+          ) {
+            patches.push({
+              op: "replace",
+              path: "/description",
+              value: news.description,
+            });
+          }
+          if (news.enabled !== undefined && news.enabled !== observed.enabled) {
+            patches.push({
+              op: "replace",
+              path: "/enabled",
+              value: String(news.enabled),
+            });
+          }
+          if (patches.length > 0) {
+            yield* ag.updateApiKey({
+              apiKey: apiKeyId,
+              patchOperations: patches,
+            });
+          }
+
+          // Sync tags — diff observed cloud tags against desired so adoption
+          // converges without fighting whatever tag set was already there.
+          const observedTags = tagRecord(observed.tags);
+          if (!deepEqual(observedTags, desiredTags)) {
+            yield* syncTags({
+              resourceArn: apiKeyArn(awsRegion, apiKeyId),
+              oldTags: observedTags,
+              newTags: desiredTags,
+            });
+          }
+
+          yield* session.note(`Reconciled API key ${apiKeyId}`);
+          const final = yield* ag.getApiKey({
+            apiKey: apiKeyId,
+            includeValue: false,
+          });
+          if (!final.id) return yield* Effect.die("getApiKey missing id");
+          return {
+            id: final.id,
+            name: final.name,
+            enabled: final.enabled,
+            tags: tagRecord(final.tags),
+          };
+        }),
+        delete: Effect.fn(function* ({ output, session }) {
+          yield* ag
+            .deleteApiKey({ apiKey: output.id })
+            .pipe(Effect.catchTag("NotFoundException", () => Effect.void));
+          yield* session.note(`Deleted API key ${output.id}`);
+        }),
+      };
+    }),
+  );