alchemy 2.0.0-beta.53 → 2.0.0-beta.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "2.0.0-beta.53",
+  "version": "2.0.0-beta.54",
   "homepage": "https://alchemy.run",
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
@@ -294,9 +294,9 @@
     "@distilled.cloud/aws": "^0.24.5",
     "@distilled.cloud/axiom": "^0.24.5",
     "@distilled.cloud/cloudflare": "^0.24.5",
-    "@distilled.cloud/cloudflare-rolldown-plugin": "0.10.11",
-    "@distilled.cloud/cloudflare-runtime": "0.10.11",
-    "@distilled.cloud/cloudflare-vite-plugin": "0.10.11",
+    "@distilled.cloud/cloudflare-rolldown-plugin": "0.10.12",
+    "@distilled.cloud/cloudflare-runtime": "0.10.12",
+    "@distilled.cloud/cloudflare-vite-plugin": "0.10.12",
     "@distilled.cloud/core": "^0.24.5",
     "@distilled.cloud/neon": "^0.24.5",
     "@distilled.cloud/planetscale": "^0.24.5",
@@ -326,16 +326,16 @@
   },
   "devDependencies": {
     "@clack/prompts": "^0.11.0",
-    "@cloudflare/workers-types": "^4.20250805.0",
     "@cloudflare/puppeteer": "^1.1.0",
+    "@cloudflare/workers-types": "^4.20250805.0",
     "@effect/platform-bun": ">=4.0.0-beta.78 || >=4.0.0",
     "@effect/platform-node": ">=4.0.0-beta.78 || >=4.0.0",
     "@effect/platform-node-shared": ">=4.0.0-beta.78 || >=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",
+    "@types/pg": "^8.11.0",
     "@types/picomatch": "^4.0.0",
     "@types/react": "^19.2.2",
     "@types/ws": "^8.18.1",

package/src/Cloudflare/Hyperdrive/Hyperdrive.ts

@@ -9,6 +9,7 @@ import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import { generateLocalId, isLiveId } from "../LocalRuntime.ts";
 import type { Providers } from "../Providers.ts";
 import { HyperdriveBinding } from "./HyperdriveBinding.ts";
 
@@ -182,7 +183,7 @@ export const HyperdriveProvider = () =>
       if (oldName !== name) {
         return { action: "replace" } as const;
       }
-      if (!isHyperdriveId(output?.hyperdriveId)) {
+      if (!isLiveId(output?.hyperdriveId)) {
         return { action: "update" };
       }
     }),
@@ -193,7 +194,7 @@ export const HyperdriveProvider = () =>
         return output;
       }
 
-      if (isHyperdriveId(output?.hyperdriveId)) {
+      if (isLiveId(output?.hyperdriveId)) {
         return yield* hyperdrive
           .getConfig({
             accountId: output.accountId,
@@ -248,7 +249,7 @@ export const HyperdriveProvider = () =>
       const ctx = yield* AlchemyContext;
       if (ctx.dev) {
         return {
-          hyperdriveId: output?.hyperdriveId ?? `dev:${crypto.randomUUID()}`,
+          hyperdriveId: output?.hyperdriveId ?? generateLocalId(),
           name,
           accountId: output?.accountId ?? accountId,
           origin: news.origin,
@@ -268,7 +269,7 @@ export const HyperdriveProvider = () =>
       // to update; otherwise we createConfig and fall back to "find by
       // name then update" if Cloudflare reports the name is already in
       // use (race or a cold-start adoption).
-      const synced = isHyperdriveId(output?.hyperdriveId)
+      const synced = isLiveId(output?.hyperdriveId)
         ? yield* hyperdrive.updateConfig({
             accountId: output.accountId,
             hyperdriveId: output.hyperdriveId,
@@ -304,7 +305,7 @@ export const HyperdriveProvider = () =>
       };
     }),
     delete: Effect.fn(function* ({ output }) {
-      if (!isHyperdriveId(output.hyperdriveId)) return;
+      if (!isLiveId(output.hyperdriveId)) return;
 
       yield* hyperdrive
         .deleteConfig({
@@ -341,9 +342,6 @@ export const defaultPort = (scheme: HyperdriveScheme): number =>
 const unwrap = (v: string | Redacted.Redacted<string>): string =>
   Redacted.isRedacted(v) ? Redacted.value(v) : v;
 
-const isHyperdriveId = (maybeId: string | undefined): maybeId is string =>
-  typeof maybeId === "string" && !maybeId.startsWith("dev:");
-
 /**
  * Build the request body shape that the distilled `createConfig`/`updateConfig`
  * methods accept. Secrets are unwrapped here because the distilled TS types

package/src/Cloudflare/Local.ts

@@ -3,10 +3,10 @@ import * as RpcServer from "../Local/RpcServer.ts";
 import { CloudflareAuth } from "./Auth/AuthProvider.ts";
 import * as CloudflareEnvironment from "./CloudflareEnvironment.ts";
 import * as Credentials from "./Credentials.ts";
-import {
-  LocalWorkerProvider,
-  localRuntimeServices,
-} from "./Workers/LocalWorkerProvider.ts";
+import { localRuntimeServices } from "./LocalRuntime.ts";
+import { QueueProviderLocal } from "./Queue/Queue.ts";
+import { QueueConsumerProviderLocal } from "./Queue/QueueConsumer.ts";
+import { LocalWorkerProvider } from "./Workers/LocalWorkerProvider.ts";
 
 const cloudflareServices = Layer.provide(
   Layer.merge(
@@ -16,7 +16,11 @@ const cloudflareServices = Layer.provide(
   CloudflareAuth,
 );
 
-LocalWorkerProvider().pipe(
+Layer.mergeAll(
+  LocalWorkerProvider(),
+  QueueProviderLocal(),
+  QueueConsumerProviderLocal(),
+).pipe(
   Layer.provide(localRuntimeServices()),
   Layer.provide(cloudflareServices),
   RpcServer.launch,

package/src/Cloudflare/LocalRuntime.ts

@@ -0,0 +1,70 @@
+import { layerRuntime } from "@distilled.cloud/cloudflare-runtime";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as MutableHashMap from "effect/MutableHashMap";
+import * as Path from "effect/Path";
+import { AlchemyContext } from "../AlchemyContext.ts";
+import * as RpcProvider from "../Local/RpcProvider.ts";
+import { CloudflareEnvironment } from "./CloudflareEnvironment.ts";
+import type { Queue } from "./Queue/Queue.ts";
+import type { QueueConsumer } from "./Queue/QueueConsumer.ts";
+
+export const LOCAL_ENTRY_URL = import.meta.resolve(
+  // `import.meta.resolve(<string>)` is a runtime API — TypeScript's
+  // `rewriteRelativeImportExtensions` does NOT touch the string literal, so
+  // we have to pick the right extension ourselves. `import.meta.url` reflects
+  // the actual on-disk extension of *this* file (`.ts` when loaded from
+  // `src/` under Bun or vitest, `.js` when loaded from the compiled `lib/`
+  // under Node), which is exactly the signal we need.
+  import.meta.url.endsWith(".ts") ? "./Local.ts" : "./Local.js",
+  import.meta.url,
+);
+
+export class LocalRuntimeState extends Context.Service<
+  LocalRuntimeState,
+  {
+    readonly queues: MutableHashMap.MutableHashMap<
+      Queue["Attributes"]["queueId"],
+      Queue["Attributes"]
+    >;
+    readonly queueConsumers: MutableHashMap.MutableHashMap<
+      QueueConsumer["Attributes"]["consumerId"],
+      QueueConsumer["Attributes"]
+    >;
+  }
+>()("alchemy/cloudflare/LocalRuntimeState") {}
+
+const LocalRuntimeStateLive = Layer.succeed(
+  LocalRuntimeState,
+  LocalRuntimeState.of({
+    queues: MutableHashMap.empty(),
+    queueConsumers: MutableHashMap.empty(),
+  }),
+);
+
+export const localRuntimeServices = () =>
+  RpcProvider.providerServicesEffect(
+    Effect.gen(function* () {
+      const getEnv = yield* CloudflareEnvironment;
+      const { dotAlchemy } = yield* AlchemyContext;
+      const path = yield* Path.Path;
+      return Layer.merge(
+        LocalRuntimeStateLive,
+        layerRuntime({
+          api: {
+            accountId: getEnv.pipe(Effect.map((env) => env.accountId)),
+          },
+          storage: {
+            directory: path.join(dotAlchemy, "local"),
+          },
+        }),
+      );
+    }),
+  );
+
+export const isLocalId = (id: string | undefined): id is string =>
+  typeof id === "string" && id.startsWith("dev:");
+export const isLiveId = (id: string | undefined): id is string =>
+  typeof id === "string" && !id.startsWith("dev:");
+export const generateLocalId = (): string => `dev:${crypto.randomUUID()}`;

package/src/Cloudflare/Providers.ts

@@ -29,6 +29,7 @@ import * as Email from "./Email/index.ts";
 import * as Hyperdrive from "./Hyperdrive/index.ts";
 import * as Images from "./Images/index.ts";
 import * as KV from "./KV/index.ts";
+import { localRuntimeServices } from "./LocalRuntime.ts";
 import * as Queue from "./Queue/index.ts";
 import * as R2 from "./R2/index.ts";
 import * as RateLimit from "./RateLimit/index.ts";
@@ -173,6 +174,7 @@ export const providers = () =>
         RandomProvider(),
       ),
     ),
+    Layer.provideMerge(localRuntimeServices()),
     Layer.provideMerge(Credentials.fromAuthProvider()),
     Layer.provideMerge(CloudflareEnvironment.fromProfile()),
     Layer.provideMerge(CloudflareAuth),

package/src/Cloudflare/Queue/Queue.ts

@@ -1,12 +1,21 @@
 import * as queues from "@distilled.cloud/cloudflare/queues";
 import * as Effect from "effect/Effect";
+import * as MutableHashMap from "effect/MutableHashMap";
 import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
 import { isResolved } from "../../Diff.ts";
+import * as ProviderLayer from "../../Local/ProviderLayer.ts";
+import * as RpcProvider from "../../Local/RpcProvider.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import {
+  generateLocalId,
+  isLiveId,
+  LOCAL_ENTRY_URL,
+  LocalRuntimeState,
+} from "../LocalRuntime.ts";
 import type { Providers } from "../Providers.ts";
 import { QueueBinding } from "./QueueBinding.ts";
 
@@ -96,12 +105,18 @@ export const Queue = Resource<Queue>("Cloudflare.Queue")({
   bind: QueueBinding.bind,
 });
 
-export const QueueProvider = () =>
+export const QueueProviderLive = () =>
   Provider.succeed(Queue, {
-    stables: ["queueId", "accountId"],
+    // The `queueId` is not marked as stable because if you start in dev mode, the ID will change on first deploy.
+    stables: ["accountId"],
     diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
       const { accountId } = yield* yield* CloudflareEnvironment;
       if (!isResolved(news)) return undefined;
+      // If the queueId is a `dev:` ID, we need to update to a live one.
+      // The live resource doesn't exist yet, so there's no need to replace even if the name or accountId changed.
+      if (!isLiveId(output?.queueId)) {
+        return { action: "update" };
+      }
       if ((output?.accountId ?? accountId) !== accountId) {
         return { action: "replace" } as const;
       }
@@ -171,6 +186,8 @@ export const QueueProvider = () =>
       };
     }),
     delete: Effect.fn(function* ({ output }) {
+      // If the queueId is a `dev:` ID, the resource only exists locally, so we don't need to delete it from Cloudflare.
+      if (!isLiveId(output.queueId)) return;
       yield* queues
         .deleteQueue({
           accountId: output.accountId,
@@ -228,3 +245,57 @@ const findQueueByName = Effect.fnUntraced(function* (queueName: string) {
     Effect.map(Option.getOrUndefined),
   );
 });
+
+export const QueueProviderLocal = () =>
+  RpcProvider.effect(
+    Queue,
+    LOCAL_ENTRY_URL,
+    Effect.gen(function* () {
+      const localRuntimeState = yield* LocalRuntimeState;
+      return {
+        stables: ["accountId"],
+        diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
+          const { accountId } = yield* yield* CloudflareEnvironment;
+          if (!output?.queueId) return { action: "update" };
+          if (!isResolved(news)) return undefined;
+          const name = yield* createQueueName(id, news.name);
+          const oldName = output?.queueName
+            ? yield* createQueueName(id, olds.name)
+            : yield* createQueueName(id, olds.name);
+          if (name !== oldName || output.accountId !== accountId) {
+            return { action: "replace" };
+          }
+          // If the resource is a noop, add it to the local runtime state so it's available downstream.
+          // We do it here instead of in the reconcile function so it doesn't appear as an update.
+          MutableHashMap.set(localRuntimeState.queues, output.queueId, output);
+          return { action: "noop" };
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.queueId) return undefined;
+          return MutableHashMap.get(
+            localRuntimeState.queues,
+            output.queueId,
+          ).pipe(Option.getOrUndefined);
+        }),
+        reconcile: Effect.fn(function* ({ id, news = {}, output }) {
+          const { accountId } = yield* yield* CloudflareEnvironment;
+          const queue: Queue["Attributes"] = {
+            queueId: output?.queueId ?? generateLocalId(),
+            queueName: yield* createQueueName(id, news.name),
+            accountId: output?.accountId ?? accountId,
+          };
+          MutableHashMap.set(localRuntimeState.queues, queue.queueId, queue);
+          return queue;
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          MutableHashMap.remove(localRuntimeState.queues, output.queueId);
+        }),
+      };
+    }),
+  );
+
+export const QueueProvider = () =>
+  ProviderLayer.select({
+    local: () => QueueProviderLocal(),
+    live: () => QueueProviderLive(),
+  });

package/src/Cloudflare/Queue/QueueConsumer.ts

@@ -1,12 +1,20 @@
 import * as queues from "@distilled.cloud/cloudflare/queues";
 import * as Effect from "effect/Effect";
+import * as MutableHashMap from "effect/MutableHashMap";
 import * as Option from "effect/Option";
 import * as Schedule from "effect/Schedule";
 import * as Stream from "effect/Stream";
 import { isResolved } from "../../Diff.ts";
+import * as ProviderLayer from "../../Local/ProviderLayer.ts";
+import * as RpcProvider from "../../Local/RpcProvider.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import {
+  isLiveId,
+  LOCAL_ENTRY_URL,
+  LocalRuntimeState,
+} from "../LocalRuntime.ts";
 import type { Providers } from "../Providers.ts";
 
 export type QueueConsumerProps = {
@@ -25,33 +33,35 @@ export type QueueConsumerProps = {
   /**
    * Consumer settings.
    */
-  settings?: {
-    /**
-     * The maximum number of messages per batch.
-     * @default 10
-     */
-    batchSize?: number;
-    /**
-     * The maximum number of concurrent consumer invocations.
-     */
-    maxConcurrency?: number;
-    /**
-     * The maximum number of retries for a message.
-     * @default 3
-     */
-    maxRetries?: number;
-    /**
-     * The maximum time to wait for a batch to fill, in milliseconds.
-     * @default 5000
-     */
-    maxWaitTimeMs?: number;
-    /**
-     * The number of seconds to wait before retrying a message.
-     */
-    retryDelay?: number;
-  };
+  settings?: QueueConsumerSettings;
 };
 
+export interface QueueConsumerSettings {
+  /**
+   * The maximum number of messages per batch.
+   * @default 10
+   */
+  batchSize?: number;
+  /**
+   * The maximum number of concurrent consumer invocations.
+   */
+  maxConcurrency?: number;
+  /**
+   * The maximum number of retries for a message.
+   * @default 3
+   */
+  maxRetries?: number;
+  /**
+   * The maximum time to wait for a batch to fill, in milliseconds.
+   * @default 5000
+   */
+  maxWaitTimeMs?: number;
+  /**
+   * The number of seconds to wait before retrying a message.
+   */
+  retryDelay?: number;
+}
+
 export type QueueConsumer = Resource<
   "Cloudflare.QueueConsumer",
   QueueConsumerProps,
@@ -60,6 +70,8 @@ export type QueueConsumer = Resource<
     queueId: string;
     scriptName: string;
     accountId: string;
+    deadLetterQueue?: string;
+    settings?: QueueConsumerSettings;
   },
   never,
   Providers
@@ -116,12 +128,19 @@ const findWorkerConsumer = (acct: string, queueId: string) =>
     Stream.runHead,
     Effect.map(Option.getOrUndefined),
   );
-export const QueueConsumerProvider = () =>
+
+export const QueueConsumerProviderLive = () =>
   Provider.succeed(QueueConsumer, {
-    stables: ["consumerId", "accountId"],
+    // The `consumerId` is not marked as stable because if you start in dev mode, the ID will change on first deploy.
+    stables: ["accountId"],
     diff: Effect.fn(function* ({ olds, news, output }) {
       const { accountId } = yield* yield* CloudflareEnvironment;
       if (!isResolved(news)) return undefined;
+      // If either contain `dev:` IDs, we need to update to live ones.
+      // The live resource doesn't exist yet, so there's no need to replace even when we otherwise would.
+      if (!isLiveId(output?.queueId) || !isLiveId(output?.consumerId)) {
+        return { action: "update" };
+      }
       if ((output?.accountId ?? accountId) !== accountId) {
         return { action: "replace" } as const;
       }
@@ -167,7 +186,7 @@ export const QueueConsumerProvider = () =>
       // updating it could clobber another team's wiring.
       let observed: ObservedConsumer | undefined;
       let owned = false;
-      if (output?.consumerId) {
+      if (isLiveId(output?.consumerId)) {
         const fetched = yield* queues
           .getConsumer({
             accountId: acct,
@@ -365,9 +384,14 @@ export const QueueConsumerProvider = () =>
         queueId,
         scriptName: news.scriptName!,
         accountId: acct,
+        deadLetterQueue: news.deadLetterQueue,
+        settings: news.settings,
       };
     }),
     delete: Effect.fn(function* ({ output }) {
+      // If the consumerId is a `dev:` ID, the resource only exists locally, so we don't need to delete it from Cloudflare.
+      if (!isLiveId(output.consumerId)) return;
+
       yield* queues
         .deleteConsumer({
           accountId: output.accountId,
@@ -421,6 +445,8 @@ export const QueueConsumerProvider = () =>
                 ? fetched.scriptName
                 : output.scriptName) ?? output.scriptName,
             accountId: output.accountId,
+            deadLetterQueue: output.deadLetterQueue,
+            settings: output.settings,
           };
         }
       }
@@ -439,6 +465,8 @@ export const QueueConsumerProvider = () =>
             queueId: output.queueId,
             scriptName: match.script ?? output.scriptName,
             accountId: output.accountId,
+            deadLetterQueue: output.deadLetterQueue,
+            settings: output.settings,
           };
         }
       }
@@ -465,3 +493,77 @@ const toObserved = (c: {
 const queueHandlerReadinessSchedule = Schedule.spaced("2 seconds").pipe(
   Schedule.both(Schedule.recurs(30)),
 );
+
+export const QueueConsumerProviderLocal = () =>
+  RpcProvider.effect(
+    QueueConsumer,
+    LOCAL_ENTRY_URL,
+    Effect.gen(function* () {
+      const localRuntimeState = yield* LocalRuntimeState;
+      return {
+        diff: Effect.fn(function* ({ news, output }) {
+          const { accountId } = yield* yield* CloudflareEnvironment;
+          if (!output) return { action: "update" };
+          if (!isResolved(news)) return undefined;
+          if (
+            output.queueId !== news.queueId ||
+            output.accountId !== accountId
+          ) {
+            return { action: "replace" };
+          }
+          if (
+            JSON.stringify(output.settings ?? {}) !==
+              JSON.stringify(news.settings ?? {}) ||
+            output.scriptName !== news.scriptName ||
+            output.deadLetterQueue !== news.deadLetterQueue
+          ) {
+            return { action: "update" };
+          }
+          // If the resource is a noop, add it to the local runtime state so it's available downstream.
+          // We do it here instead of in the reconcile function so it doesn't appear as an update.
+          MutableHashMap.set(
+            localRuntimeState.queueConsumers,
+            output.consumerId,
+            output,
+          );
+          return { action: "noop" };
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (!output?.consumerId) return undefined;
+          return MutableHashMap.get(
+            localRuntimeState.queueConsumers,
+            output.consumerId,
+          ).pipe(Option.getOrUndefined);
+        }),
+        reconcile: Effect.fn(function* ({ news, output }) {
+          const { accountId } = yield* yield* CloudflareEnvironment;
+          const consumer: QueueConsumer["Attributes"] = {
+            consumerId: output?.consumerId ?? `dev:${crypto.randomUUID()}`,
+            queueId: news.queueId,
+            scriptName: news.scriptName,
+            deadLetterQueue: news.deadLetterQueue,
+            accountId,
+            settings: news.settings,
+          };
+          MutableHashMap.set(
+            localRuntimeState.queueConsumers,
+            consumer.consumerId,
+            consumer,
+          );
+          return consumer;
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          MutableHashMap.remove(
+            localRuntimeState.queueConsumers,
+            output.consumerId,
+          );
+        }),
+      };
+    }),
+  );
+
+export const QueueConsumerProvider = () =>
+  ProviderLayer.select({
+    local: () => QueueConsumerProviderLocal(),
+    live: () => QueueConsumerProviderLive(),
+  });

package/src/Cloudflare/Workers/Assets.ts

@@ -1,4 +1,4 @@
-import { Ignore } from "@alchemy.run/node-utils/ignore";
+import createIgnore from "@alchemy.run/node-utils/ignore";
 import * as workers from "@distilled.cloud/cloudflare/workers";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
@@ -98,7 +98,7 @@ const maybeReadString = Effect.fnUntraced(function* (file: string) {
 });
 
 const createIgnoreMatcher = (patterns: string[]) => {
-  const matcher = new Ignore().add(patterns);
+  const matcher = createIgnore().add(patterns);
   return (file: string) => matcher.ignores(file);
 };