alchemy 0.37.2 → 0.38.0

package/src/cloudflare/worker-stub.ts

@@ -7,6 +7,7 @@ import {
   type CloudflareApi,
   type CloudflareApiOptions,
 } from "./api.ts";
+import { configureURL } from "./worker.ts";
 
 /**
  * Properties for creating a Worker stub
@@ -19,6 +20,14 @@ export interface WorkerStubProps<
    */
   name: string;
 
+  /**
+   * Whether to enable a workers.dev URL for this worker
+   *
+   * If true, the worker will be available at {name}.{subdomain}.workers.dev
+   * @default true
+   */
+  url?: boolean;
+
   /**
    * The RPC class to use for the worker.
    *
@@ -39,6 +48,12 @@ export interface WorkerStub<
    */
   name: string;
 
+  /**
+   * The worker's URL if enabled
+   * Format: {name}.{subdomain}.workers.dev
+   */
+  url?: string;
+
   /**
    * Optional type branding for the worker's RPC entrypoint.
    *
@@ -59,12 +74,21 @@ export function isWorkerStub(resource: Resource): resource is WorkerStub {
  * exists and creates an empty one if needed.
  *
  * @example
- * // Reserve a worker name without deploying code
+ * // Reserve a worker name without deploying code, with URL enabled (default)
  * const workerStub = await WorkerStub("my-worker", {
  *   name: "my-reserved-worker"
  * });
  *
- * console.log(`Worker ${workerStub.name} exists: ${!workerStub.created}`);
+ * console.log(`Worker ${workerStub.name} is available at: ${workerStub.url}`);
+ *
+ * @example
+ * // Reserve a worker name without enabling URL
+ * const workerStub = await WorkerStub("my-worker", {
+ *   name: "my-reserved-worker",
+ *   url: false
+ * });
+ *
+ * console.log(`Worker ${workerStub.name} created without URL`);
  */
 export const WorkerStub = Resource("cloudflare::WorkerStub", async function <
   RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
@@ -84,11 +108,16 @@ export const WorkerStub = Resource("cloudflare::WorkerStub", async function <
     await createEmptyWorker(api, props.name);
   }
 
+  // Configure URL if requested (defaults to true)
+  const enableUrl = props.url ?? true;
+  const workerUrl = await configureURL(this, api, props.name, enableUrl);
+
   // Return the worker stub info
   return this({
     type: "service",
     __rpc__: props.rpc as unknown as RPC,
     ...props,
+    url: workerUrl,
   }) as WorkerStub<RPC>;
 });
 

package/src/cloudflare/worker.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { BUILD_DATE } from "../build-date.ts";
 import type { Context } from "../context.ts";
 import type { BundleProps } from "../esbuild/bundle.ts";
 import { InnerResourceScope, Resource, ResourceKind } from "../resource.ts";
@@ -178,7 +179,7 @@ export interface BaseWorkerProps<
 
   /**
    * The compatibility date for the worker
-   * @default "2025-04-26"
+   * @default BUILD_DATE - automatically pinned to the package build date
    */
   compatibilityDate?: string;
 
@@ -861,7 +862,7 @@ export function Worker<const B extends Bindings>(
   });
 }
 
-export const DEFAULT_COMPATIBILITY_DATE = "2025-04-20";
+export const DEFAULT_COMPATIBILITY_DATE = BUILD_DATE;
 
 export const _Worker = Resource(
   "cloudflare::Worker",
@@ -1467,7 +1468,7 @@ export async function assertWorkerDoesNotExist<B extends Bindings>(
 }
 
 export async function configureURL<B extends Bindings>(
-  ctx: Context<Worker<B>>,
+  ctx: Context<Worker<B>> | Context<WorkerStub>,
   api: CloudflareApi,
   workerName: string,
   url: boolean,

package/src/context.ts

@@ -53,7 +53,7 @@ export interface BaseContext<Out extends Resource> {
    * Indicate that this resource is being replaced.
    * This will cause the resource to be deleted at the end of the stack's CREATE phase.
    */
-  replace(): void;
+  replace(): never;
   /**
    * Terminate the resource lifecycle handler and destroy the resource.
    *
@@ -97,7 +97,7 @@ export function context<
   seq: number;
   props: Props;
   state: State<Kind, Props, Out>;
-  replace: () => void;
+  replace: () => never;
 }): Context<Out> {
   type InternalSymbols =
     | typeof ResourceID

package/src/destroy.ts

@@ -6,10 +6,11 @@ import {
   ResourceFQN,
   ResourceID,
   ResourceKind,
+  type ResourceProps,
   ResourceScope,
   ResourceSeq,
 } from "./resource.ts";
-import { isScope, Scope } from "./scope.ts";
+import { isScope, type PendingDeletions, Scope } from "./scope.ts";
 import { formatFQN } from "./util/cli.ts";
 import { logger } from "./util/logger.ts";
 
@@ -18,6 +19,10 @@ export class DestroyedSignal extends Error {}
 export interface DestroyOptions {
   quiet?: boolean;
   strategy?: "sequential" | "parallel";
+  replace?: {
+    props?: ResourceProps | undefined;
+    output?: Resource<string>;
+  };
 }
 
 function isScopeArgs(a: any): a is [scope: Scope, options?: DestroyOptions] {
@@ -40,7 +45,8 @@ export async function destroy<Type extends string>(
     } satisfies DestroyOptions;
 
     await scope.run(async () => {
-      // destroy all active resources
+      // destroy all active and pending resources
+      await scope.destroyPendingDeletions();
       await destroyAll(Array.from(scope.resources.values()), options);
 
       // then detect orphans and destroy them
@@ -109,7 +115,7 @@ export async function destroy<Type extends string>(
       id: instance[ResourceID],
       fqn: instance[ResourceFQN],
       seq: instance[ResourceSeq],
-      props: state.props,
+      props: options?.replace?.props ?? state.props,
       state,
       replace: () => {
         throw new Error("Cannot replace a resource that is being deleted");
@@ -127,10 +133,10 @@ export async function destroy<Type extends string>(
           parent: scope,
         },
         async (scope) => {
-          nestedScope = scope;
+          nestedScope = options?.replace?.props == null ? scope : undefined;
           return await Provider.handler.bind(ctx)(
             instance[ResourceID],
-            state.props!,
+            options?.replace?.props ?? state.props!,
           );
         },
       );
@@ -146,7 +152,21 @@ export async function destroy<Type extends string>(
       await destroy(nestedScope, options);
     }
 
-    await scope.delete(instance[ResourceID]);
+    if (options?.replace == null) {
+      if (nestedScope) {
+        await destroy(nestedScope, options);
+      }
+      await scope.deleteResource(instance[ResourceID]);
+    } else {
+      let pendingDeletions =
+        await state.output[ResourceScope].get<PendingDeletions>(
+          "pendingDeletions",
+        );
+      pendingDeletions = pendingDeletions?.filter(
+        (deletion) => deletion.resource[ResourceID] !== instance[ResourceID],
+      );
+      await scope.set("pendingDeletions", pendingDeletions);
+    }
 
     if (!quiet) {
       logger.task(instance[ResourceFQN], {
@@ -165,11 +185,14 @@ export async function destroy<Type extends string>(
 
 export async function destroyAll(
   resources: Resource[],
-  options?: DestroyOptions,
+  options?: DestroyOptions & { force?: boolean },
 ) {
   if (options?.strategy !== "parallel") {
     const sorted = resources.sort((a, b) => b[ResourceSeq] - a[ResourceSeq]);
     for (const resource of sorted) {
+      if (isScope(resource)) {
+        await resource.destroyPendingDeletions();
+      }
       await destroy(resource, options);
     }
   } else {

package/src/scope.ts

@@ -1,16 +1,32 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { Phase } from "./alchemy.ts";
-import { destroyAll } from "./destroy.ts";
+import { destroy, destroyAll } from "./destroy.ts";
 import { FileSystemStateStore } from "./fs/file-system-state-store.ts";
-import { ResourceID, type PendingResource } from "./resource.ts";
-import type { StateStore, StateStoreType } from "./state.ts";
+import {
+  ResourceFQN,
+  ResourceID,
+  ResourceKind,
+  ResourceScope,
+  ResourceSeq,
+  type PendingResource,
+  type Resource,
+  type ResourceProps,
+} from "./resource.ts";
+import type { State, StateStore, StateStoreType } from "./state.ts";
 import {
   createDummyLogger,
   createLoggerInstance,
   type LoggerApi,
 } from "./util/cli.ts";
+import { AsyncMutex } from "./util/mutex.ts";
 import type { ITelemetryClient } from "./util/telemetry/client.ts";
 
+export class RootScopeStateAttemptError extends Error {
+  constructor() {
+    super("Root scope cannot contain state");
+  }
+}
+
 export interface ScopeOptions {
   appName?: string;
   stage?: string;
@@ -24,6 +40,11 @@ export interface ScopeOptions {
   logger?: LoggerApi;
 }
 
+export type PendingDeletions = Array<{
+  resource: Resource<string>;
+  oldProps?: ResourceProps;
+}>;
+
 // TODO: support browser
 const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 
@@ -47,7 +68,7 @@ export class Scope {
     new AsyncLocalStorage<Scope>());
   public static globals: Scope[] = (globalThis.__ALCHEMY_GLOBALS__ ??= []);
 
-  public static get(): Scope | undefined {
+  public static getScope(): Scope | undefined {
     const scope = Scope.storage.getStore();
     if (!scope) {
       if (Scope.globals.length > 0) {
@@ -63,7 +84,7 @@ export class Scope {
   }
 
   public static get current(): Scope {
-    const scope = Scope.get();
+    const scope = Scope.getScope();
     if (!scope) throw new Error("Not running within an Alchemy Scope");
     return scope;
   }
@@ -81,6 +102,7 @@ export class Scope {
   public readonly phase: Phase;
   public readonly logger: LoggerApi;
   public readonly telemetryClient: ITelemetryClient;
+  public readonly dataMutex: AsyncMutex;
 
   private isErrored = false;
   private finalized = false;
@@ -96,7 +118,7 @@ export class Scope {
         `Scope name ${this.scopeName} cannot contain double colons`,
       );
     }
-    this.parent = options.parent ?? Scope.get();
+    this.parent = options.parent ?? Scope.getScope();
     this.stage = options?.stage ?? this.parent?.stage ?? DEFAULT_STAGE;
     this.parent?.children.set(this.scopeName!, this);
     this.quiet = options.quiet ?? this.parent?.quiet ?? false;
@@ -131,6 +153,7 @@ export class Scope {
     }
     this.telemetryClient =
       options.telemetryClient ?? this.parent?.telemetryClient!;
+    this.dataMutex = new AsyncMutex();
   }
 
   public get root(): Scope {
@@ -141,7 +164,7 @@ export class Scope {
     return root;
   }
 
-  public async delete(resourceID: ResourceID) {
+  public async deleteResource(resourceID: ResourceID) {
     await this.state.delete(resourceID);
     this.resources.delete(resourceID);
   }
@@ -158,7 +181,7 @@ export class Scope {
     if (this.parent) {
       return [...this.parent.chain, ...thisScope];
     }
-    return [...app, this.stage, ...thisScope];
+    return [...app, ...thisScope];
   }
 
   public fail() {
@@ -179,6 +202,78 @@ export class Scope {
     return [...this.chain, resourceID].join("/");
   }
 
+  /**
+   * Centralizes the "lock → locate the right scope → hand the caller a live
+   * ScopeState instance and a persist() helper".
+   *
+   * @param fn   Your operation on the scope state.
+   *             • `state` is already resolved and, if we're at the root, created.
+   *             • `persist` will write the (possibly-mutated) state back.
+   */
+  private async withScopeState<R>(
+    fn: (
+      state: State<string, ResourceProps | undefined, Resource<string>>, // current state for this.scopeName
+      persist: (
+        next: State<string, ResourceProps | undefined, Resource<string>>,
+      ) => Promise<void>, // helper to save changes
+    ) => Promise<R>,
+  ): Promise<R> {
+    return this.dataMutex.lock(async () => {
+      // 1. We must know where to look.
+      if (!this.parent || !this.scopeName) {
+        throw new RootScopeStateAttemptError();
+      }
+
+      // 2. Pull (or lazily create) the state bucket we care about.
+      const isRoot = this.parent.scopeName === this.root.scopeName;
+      const state =
+        (await this.parent.state.get(this.scopeName)) ??
+        (isRoot
+          ? {
+              //todo(michael): should this have a different type cause its root?
+              kind: "alchemy::Scope",
+              id: this.scopeName!,
+              fqn: this.root.fqn(this.scopeName!),
+              seq: this.seq(),
+              status: "created",
+              data: {},
+              output: {
+                [ResourceID]: this.scopeName!,
+                [ResourceFQN]: this.root.fqn(this.scopeName!),
+                [ResourceKind]: "alchemy::Scope",
+                [ResourceScope]: this,
+                [ResourceSeq]: this.seq(),
+              },
+              props: {},
+            }
+          : undefined);
+
+      if (!state) throw new RootScopeStateAttemptError();
+
+      return fn(state, (updated) =>
+        this.parent!.state.set(this.scopeName!, updated),
+      );
+    });
+  }
+
+  public async set<T>(key: string, value: T): Promise<void> {
+    return this.withScopeState<void>(async (state, persist) => {
+      state.data[key] = value;
+      await persist(state); // only one line to save!
+    });
+  }
+
+  public async get<T>(key: string): Promise<T> {
+    return this.withScopeState<T>(async (state) => state.data[key]);
+  }
+
+  public async delete(key: string): Promise<void> {
+    return this.withScopeState<void>(async (state, persist) => {
+      delete state.data[key];
+      await persist(state);
+    });
+  }
+
   public async run<T>(fn: (scope: Scope) => Promise<T>): Promise<T> {
     return Scope.storage.run(this, () => fn(this));
   }
@@ -198,7 +293,11 @@ export class Scope {
     return null;
   }
 
-  public async finalize() {
+  public async finalize(force?: boolean) {
+    const shouldForce =
+      force ||
+      this.parent === undefined ||
+      this?.parent?.scopeName === this.root.scopeName;
     if (this.phase === "read") {
       this.rootTelemetryClient?.record({
         event: "app.success",
@@ -206,7 +305,7 @@ export class Scope {
       });
       return;
     }
-    if (this.finalized) {
+    if (this.finalized && !shouldForce) {
       return;
     }
     if (this.parent === undefined && Scope.globals.length > 0) {
@@ -227,12 +326,23 @@ export class Scope {
       const orphanIds = Array.from(
         resourceIds.filter((id) => !aliveIds.has(id)),
       );
+
+      if (shouldForce) {
+        await this.destroyPendingDeletions();
+        await Promise.all(
+          Array.from(this.children.values()).map((child) =>
+            child.finalize(shouldForce),
+          ),
+        );
+      }
+
       const orphans = await Promise.all(
         orphanIds.map(async (id) => (await this.state.get(id))!.output),
       );
       await destroyAll(orphans, {
         quiet: this.quiet,
         strategy: "sequential",
+        force: shouldForce,
       });
       this.rootTelemetryClient?.record({
         event: "app.success",
@@ -250,6 +360,31 @@ export class Scope {
     await this.rootTelemetryClient?.finalize();
   }
 
+  public async destroyPendingDeletions() {
+    const pendingDeletions =
+      (await this.get<PendingDeletions>("pendingDeletions").catch((e) => {
+        if (e instanceof RootScopeStateAttemptError) {
+          return [];
+        }
+        throw e;
+      })) ?? [];
+    if (pendingDeletions) {
+      for (const { resource, oldProps } of pendingDeletions) {
+        //todo(michael): ugly hack due to the way scope is serialized
+        const realResource = this.resources.get(resource[ResourceID])!;
+        resource[ResourceScope] = realResource?.[ResourceScope] ?? this;
+        await destroy(resource, {
+          quiet: this.quiet,
+          strategy: "sequential",
+          replace: {
+            props: oldProps,
+            output: resource,
+          },
+        });
+      }
+    }
+  }
+
   /**
    * Defers execution of a function until the Alchemy application finalizes.
    */

package/src/sentry/project.ts

@@ -347,7 +347,7 @@ export const Project = Resource(
         }
 
         if (!response.ok) {
-          throw new Error(`API error: ${response.statusText}`);
+          throw new Error(`API error: ${await response.text()}`);
         }
 
         const data = (await response.json()) as Omit<

package/src/util/logger.ts

@@ -4,7 +4,7 @@ import type { LoggerApi } from "./cli.ts";
 export const logger = new Proxy({} as LoggerApi, {
   get: (_, prop: keyof LoggerApi) => {
     const logger =
-      Scope.get()?.logger ??
+      Scope.getScope()?.logger ??
       ({
         log: console.log,
         error: console.error,

package/src/util/mutex.ts

@@ -0,0 +1,33 @@
+/**
+ * Simple async mutex that ensures only one async operation executes at a time
+ */
+export class AsyncMutex {
+  private locked = false;
+  private queue: Array<() => void> = [];
+
+  async lock<T>(operation: () => Promise<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const execute = async () => {
+        this.locked = true;
+        try {
+          const result = await operation();
+          resolve(result);
+        } catch (error) {
+          reject(error);
+        } finally {
+          this.locked = false;
+          const next = this.queue.shift();
+          if (next) {
+            next();
+          }
+        }
+      };
+
+      if (this.locked) {
+        this.queue.push(execute);
+      } else {
+        execute();
+      }
+    });
+  }
+}

package/templates/astro/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

package/templates/astro/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

package/templates/astro/README.md

@@ -0,0 +1,48 @@
+# Astro Starter Kit: Basics
+
+```sh
+bun create astro@latest -- --template basics
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/astro/tree/latest/examples/basics)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/astro/tree/latest/examples/basics)
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/withastro/astro?devcontainer_path=.devcontainer/basics/devcontainer.json)
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+![just-the-basics](https://github.com/withastro/astro/assets/2244813/a0a5533c-a856-4198-8470-2d67b1d7c554)
+
+## 🚀 Project Structure
+
+Inside of your Astro project, you'll see the following folders and files:
+
+```text
+/
+├── public/
+│   └── favicon.svg
+├── src/
+│   ├── layouts/
+│   │   └── Layout.astro
+│   └── pages/
+│       └── index.astro
+└── package.json
+```
+
+To learn more about the folder structure of an Astro project, refer to [our guide on project structure](https://docs.astro.build/en/basics/project-structure/).
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `bun install`             | Installs dependencies                            |
+| `bun dev`             | Starts local dev server at `localhost:4321`      |
+| `bun build`           | Build your production site to `./dist/`          |
+| `bun preview`         | Preview your build locally, before deploying     |
+| `bun astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `bun astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).

package/templates/astro/_env.example

@@ -0,0 +1 @@
+ALCHEMY_PASSWORD=change-me

package/templates/astro/_gitignore

@@ -0,0 +1,27 @@
+# build output
+dist/
+
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/
+
+.alchemy/
+.env

package/templates/astro/alchemy.run.ts

@@ -0,0 +1,16 @@
+/// <reference types="@types/node" />
+
+import alchemy from "alchemy";
+import { Astro } from "alchemy/cloudflare";
+
+const app = await alchemy("my-alchemy-app");
+
+export const worker = await Astro("website", {
+  command: "bun run build",
+});
+
+console.log({
+  url: worker.url,
+});
+
+await app.finalize();

package/templates/astro/astro.config.mjs

@@ -0,0 +1,8 @@
+import { defineConfig } from 'astro/config';
+import cloudflare from '@astrojs/cloudflare';
+
+// https://astro.build/config
+export default defineConfig({
+  output: 'server',
+  adapter: cloudflare(),
+});

package/templates/astro/package.json

@@ -0,0 +1,23 @@
+{
+  "type": "module",
+  "name": "astro",
+  "version": "0.0.1",
+  "scripts": {
+    "astro": "astro",
+    "build": "astro check && astro build",
+    "deploy": "bun --env-file=./.env ./alchemy.run.ts",
+    "destroy": "bun --env-file=./.env ./alchemy.run.ts --destroy",
+    "dev": "astro dev",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "astro": "^5.10.0"
+  },
+  "devDependencies": {
+    "alchemy": "workspace:*",
+    "@astrojs/cloudflare": "^12.6.0",
+    "miniflare": "^4.20250617.3",
+    "@cloudflare/workers-types": "^4.20250620.0",
+    "typescript": "^5.8.3"
+  }
+}