alchemy 0.39.1 → 0.40.0

package/src/cloudflare/worker.ts

@@ -1,3 +1,11 @@
+import { spawn } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import path from "node:path";
 import { BUILD_DATE } from "../build-date.ts";
 import type { Context } from "../context.ts";
@@ -11,6 +19,7 @@ import { Secret, secret } from "../secret.ts";
 import { serializeScope } from "../serde.ts";
 import type { type } from "../type.ts";
 import { getContentType } from "../util/content-type.ts";
+import { DeferredPromise } from "../util/deferred-promise.ts";
 import { logger } from "../util/logger.ts";
 import { withExponentialBackoff } from "../util/retry.ts";
 import { CloudflareApiError, handleApiError } from "./api-error.ts";
@@ -28,6 +37,7 @@ import {
 } from "./bindings.ts";
 import type { Bound } from "./bound.ts";
 import { isBucket } from "./bucket.ts";
+import { createWorkerDevContext } from "./bundle/bundle-worker-dev.ts";
 import {
   type NoBundleResult,
   bundleWorkerScript,
@@ -61,6 +71,9 @@ import {
   prepareWorkerMetadata,
 } from "./worker-metadata.ts";
 import { WorkerStub, isWorkerStub } from "./worker-stub.ts";
+import type { MiniflareWorkerOptions } from "./worker/miniflare-worker-options.ts";
+import { miniflareServer } from "./worker/miniflare.ts";
+import { getAccountSubdomain } from "./worker/subdomain.ts";
 import { Workflow, isWorkflow, upsertWorkflow } from "./workflow.ts";
 
 /**
@@ -300,6 +313,32 @@ export interface BaseWorkerProps<
    * @example "pr-123"
    */
   version?: string;
+
+  /**
+   * Configuration for local development. By default, when Alchemy is running in development mode,
+   * the worker will be emulated locally and available at a randomly selected port.
+   */
+  dev?:
+    | boolean
+    | {
+        /**
+         * Port to use for local development
+         */
+        port?: number;
+        /**
+         * EXPERIMENTAL: Whether to run the worker remotely instead of locally.
+         *
+         * When this is enabled, hot reloading will not work.
+         *
+         * @default false
+         */
+        remote?: boolean;
+      }
+    | {
+        command: string;
+        url: string;
+        cwd?: string;
+      };
 }
 
 export interface InlineWorkerProps<
@@ -922,9 +961,6 @@ export const _Worker = Resource(
       throw new Error("entrypoint must be provided when noBundle is true");
     }
 
-    // Create Cloudflare API client with automatic account discovery
-    const api = await createCloudflareApi(props);
-
     // Use the provided name
     const workerName = props.name ?? id;
 
@@ -932,6 +968,200 @@ export const _Worker = Resource(
       props.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE;
     const compatibilityFlags = props.compatibilityFlags ?? [];
 
+    if (this.scope.dev && this.phase !== "delete" && props.dev !== false) {
+      // Get current timestamp
+      const now = Date.now();
+
+      if (typeof props.dev === "object" && "command" in props.dev) {
+        upsertDevCommand({
+          id,
+          command: props.dev.command,
+          cwd: props.dev.cwd ?? process.cwd(),
+          env: props.env ?? {},
+        });
+        return this({
+          type: "service",
+          id,
+          entrypoint: props.entrypoint,
+          name: workerName,
+          compatibilityDate,
+          compatibilityFlags,
+          format: props.format || "esm", // Include format in the output
+          bindings: props.bindings ?? ({} as B),
+          env: props.env,
+          observability: props.observability,
+          createdAt: now,
+          updatedAt: now,
+          eventSources: props.eventSources,
+          url: props.dev.url,
+          dev: props.dev,
+          // Include assets configuration in the output
+          assets: props.assets,
+          // Include cron triggers in the output
+          crons: props.crons,
+          // phantom property
+          Env: undefined!,
+        } as unknown as Worker<B>);
+      }
+
+      const sharedOptions: Omit<MiniflareWorkerOptions, "script"> = {
+        name: workerName,
+        compatibilityDate,
+        compatibilityFlags,
+        bindings: props.bindings ?? ({} as B),
+        port: typeof props.dev === "object" ? props.dev.port : undefined,
+      };
+
+      let url: string;
+
+      // If entrypoint is provided, set up hot reloading with esbuild context
+      if (props.entrypoint) {
+        const startPromise = new DeferredPromise<string>();
+
+        await createWorkerDevContext(
+          workerName,
+          {
+            ...props,
+            entrypoint: props.entrypoint,
+            compatibilityDate,
+            compatibilityFlags,
+          },
+          {
+            onBuildStart: () => {
+              logger.task("miniflare-server", {
+                message: `${startPromise.status === "pending" ? "Building" : "Rebuilding"}`,
+                status: "pending",
+                resource: id,
+                prefix: "build",
+                prefixColor: "cyanBright",
+              });
+            },
+            onBuildEnd: async (newScript) => {
+              try {
+                // Hot reload callback - update the miniflare worker
+                const server = await miniflareServer.push({
+                  ...sharedOptions,
+                  script: newScript,
+                });
+                if (startPromise.status === "pending") {
+                  logger.task("miniflare-server", {
+                    message: `Started Miniflare server at ${server.url}`,
+                    status: "success",
+                    resource: id,
+                    prefix: "ready",
+                    prefixColor: "cyanBright",
+                  });
+                  startPromise.resolve(server.url);
+                } else {
+                  logger.task("miniflare-server", {
+                    message: `Updated Miniflare server at ${server.url}`,
+                    status: "success",
+                    resource: id,
+                    prefix: "reload",
+                    prefixColor: "cyanBright",
+                  });
+                }
+              } catch (error) {
+                if (startPromise.status === "pending") {
+                  logger.error(error);
+                  logger.task("miniflare-server", {
+                    message: "Failed to start Miniflare server",
+                    status: "failure",
+                    resource: id,
+                    prefix: "error",
+                    prefixColor: "redBright",
+                  });
+                  startPromise.reject(
+                    new Error(
+                      `Failed to start Miniflare server for worker "${workerName}"`,
+                      { cause: error },
+                    ),
+                  );
+                } else {
+                  logger.task("miniflare-server", {
+                    message: "Failed to update Miniflare server",
+                    status: "failure",
+                    resource: id,
+                    prefix: "error",
+                    prefixColor: "redBright",
+                  });
+                  logger.error(error);
+                }
+              }
+            },
+            onBuildError: (errors) => {
+              if (startPromise.status === "pending") {
+                logger.task("miniflare-server", {
+                  message: "Failed to build worker",
+                  status: "failure",
+                  resource: id,
+                  prefix: "error",
+                  prefixColor: "redBright",
+                });
+                startPromise.reject(errors);
+              } else {
+                logger.task("miniflare-server", {
+                  message: "Failed to rebuild worker",
+                  status: "failure",
+                  resource: id,
+                  prefix: "error",
+                  prefixColor: "redBright",
+                });
+                logger.error(errors);
+              }
+            },
+          },
+        );
+
+        url = await startPromise.value;
+      } else {
+        // Fallback to one-time bundling for inline scripts
+        const scriptContent =
+          props.script ??
+          (await bundleWorkerScript({
+            name: workerName,
+            ...props,
+            compatibilityDate,
+            compatibilityFlags,
+          }));
+        const server = await miniflareServer.push({
+          ...sharedOptions,
+          script:
+            typeof scriptContent === "string"
+              ? scriptContent
+              : scriptContent[props.entrypoint!].toString(),
+        });
+        url = server.url;
+      }
+
+      return this({
+        type: "service",
+        id,
+        entrypoint: props.entrypoint,
+        name: workerName,
+        compatibilityDate,
+        compatibilityFlags,
+        format: props.format || "esm", // Include format in the output
+        bindings: props.bindings ?? ({} as B),
+        env: props.env,
+        observability: props.observability,
+        createdAt: now,
+        updatedAt: now,
+        eventSources: props.eventSources,
+        url,
+        dev: props.dev,
+        // Include assets configuration in the output
+        assets: props.assets,
+        // Include cron triggers in the output
+        crons: props.crons,
+        // phantom property
+        Env: undefined!,
+      } as unknown as Worker<B>);
+    }
+
+    // Create Cloudflare API client with automatic account discovery
+    const api = await createCloudflareApi(props);
+
     const uploadWorkerScript = async (props: WorkerProps<B>) => {
       // Get the script content - either from props.script, or by bundling
       const scriptBundle =
@@ -1229,6 +1459,7 @@ export const _Worker = Resource(
       updatedAt: now,
       eventSources: props.eventSources,
       url: workerUrl,
+      dev: props.dev,
       // Include assets configuration in the output
       assets: props.assets,
       // Include cron triggers in the output
@@ -1288,6 +1519,55 @@ export async function deleteWorker(
   return;
 }
 
+function upsertDevCommand(props: {
+  id: string;
+  command: string;
+  cwd: string;
+  env: Record<string, string>;
+}) {
+  const persistFile = path.join(process.cwd(), ".alchemy", `${props.id}.pid`);
+  if (existsSync(persistFile)) {
+    const pid = Number.parseInt(readFileSync(persistFile, "utf8"));
+    try {
+      // Actually kill the process if it's alive
+      process.kill(pid, "SIGTERM");
+    } catch {
+      // ignore
+    }
+    try {
+      unlinkSync(persistFile);
+    } catch {
+      // ignore
+    }
+  }
+  const command = props.command.split(" ");
+  const proc = spawn(command[0], command.slice(1), {
+    env: {
+      ...process.env,
+      ...props.env,
+      ALCHEMY_CLOUDFLARE_PERSIST_PATH: path.join(
+        process.cwd(),
+        ".alchemy",
+        "miniflare",
+      ),
+    },
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+  process.on("SIGINT", () => {
+    try {
+      unlinkSync(persistFile);
+    } catch {
+      // ignore
+    }
+    proc.kill("SIGINT");
+    process.exit(0);
+  });
+  if (proc.pid) {
+    mkdirSync(path.dirname(persistFile), { recursive: true });
+    writeFileSync(persistFile, proc.pid.toString());
+  }
+}
+
 type PutWorkerOptions = WorkerProps & {
   dispatchNamespace?: string;
   migrationTag?: string;
@@ -1564,21 +1844,7 @@ export async function configureURL<B extends Bindings>(
     );
 
     // Get the account's workers.dev subdomain
-    const subdomainResponse = await api.get(
-      `/accounts/${api.accountId}/workers/subdomain`,
-    );
-
-    if (!subdomainResponse.ok) {
-      throw new Error(
-        `Could not fetch workers.dev subdomain: ${subdomainResponse.status} ${subdomainResponse.statusText}`,
-      );
-    }
-    const subdomainData: {
-      result: {
-        subdomain: string;
-      };
-    } = await subdomainResponse.json();
-    const subdomain = subdomainData.result?.subdomain;
+    const subdomain = await getAccountSubdomain(api);
 
     if (subdomain) {
       workerUrl = `https://${workerName}.${subdomain}.workers.dev`;

package/src/cloudflare/workflow.ts

@@ -25,6 +25,13 @@ export interface WorkflowProps {
    * @default - bound worker script
    */
   scriptName?: string;
+  dev?: {
+    /**
+     * Whether to run the workflow remotely instead of locally
+     * @default false
+     */
+    remote?: boolean;
+  };
 }
 
 export function isWorkflow(binding: Binding): binding is Workflow {

package/src/scope.ts

@@ -36,6 +36,7 @@ export interface ScopeOptions {
   stateStore?: StateStoreType;
   quiet?: boolean;
   phase?: Phase;
+  dev?: boolean;
   telemetryClient?: ITelemetryClient;
   logger?: LoggerApi;
 }
@@ -100,6 +101,7 @@ export class Scope {
   public readonly stateStore: StateStoreType;
   public readonly quiet: boolean;
   public readonly phase: Phase;
+  public readonly dev?: boolean;
   public readonly logger: LoggerApi;
   public readonly telemetryClient: ITelemetryClient;
   public readonly dataMutex: AsyncMutex;
@@ -111,7 +113,7 @@ export class Scope {
   private deferred: (() => Promise<any>)[] = [];
 
   constructor(options: ScopeOptions) {
-    this.appName = options.appName;
+    this.appName = options.appName ?? options.parent?.appName;
     this.scopeName = options.scopeName ?? null;
     if (this.scopeName?.includes(":")) {
       throw new Error(
@@ -143,6 +145,14 @@ export class Scope {
           options.logger,
         );
 
+    this.dev = options.dev ?? this.parent?.dev ?? false;
+
+    if (this.dev) {
+      this.logger.warnOnce(
+        "Local development mode is in beta. Please report any issues to https://github.com/sam-goodwin/alchemy/issues.",
+      );
+    }
+
     this.stateStore =
       options.stateStore ??
       this.parent?.stateStore ??

package/src/util/assert-never.ts

@@ -1,3 +1,3 @@
-export function assertNever(value: never): never {
-  throw new Error(`Unexpected value: ${value}`);
+export function assertNever(value: never, message?: string): never {
+  throw new Error(message ?? `Unexpected value: ${value}`);
 }

package/src/util/cli.ts

@@ -2,6 +2,10 @@ import packageJson from "../../package.json" with { type: "json" };
 import type { Phase } from "../alchemy.ts";
 import { dedent } from "./dedent.ts";
 
+declare global {
+  var _ALCHEMY_WARNINGS: Set<string> | undefined;
+}
+
 // ANSI color codes
 const colors = {
   reset: "\x1b[0m",
@@ -28,27 +32,28 @@ const colorize = (text: string, color: ColorName): string => {
   return `${colors[color]}${text}${colors.reset}`;
 };
 
-export type Task = {
+export interface Task {
   prefix?: string;
-  prefixColor?: string;
+  prefixColor?: ColorName;
   resource?: string;
   message: string;
   status?: "pending" | "success" | "failure";
-};
+}
 
-export type LoggerApi = {
+export interface LoggerApi {
   log: (...args: unknown[]) => void;
   warn: (...args: unknown[]) => void;
+  warnOnce: (message: string) => void;
   error: (...args: unknown[]) => void;
   task: (id: string, data: Task) => void;
   exit: () => void;
-};
+}
 
-type AlchemyInfo = {
+interface AlchemyInfo {
   phase: Phase;
   stage: string;
   appName: string;
-};
+}
 
 let loggerApi: LoggerApi | null = null;
 export const createLoggerInstance = (
@@ -67,6 +72,7 @@ export const createDummyLogger = (): LoggerApi => {
     log: () => {},
     error: () => {},
     warn: () => {},
+    warnOnce: () => {},
     task: () => {},
     exit: () => {},
   };
@@ -87,6 +93,12 @@ export const createFallbackLogger = (alchemyInfo: AlchemyInfo): LoggerApi => {
       console.error(colorize("ERROR", "redBright"), ...args),
     warn: (...args: unknown[]) =>
       console.warn(colorize("WARN", "yellowBright"), ...args),
+    warnOnce: (message: string) => {
+      globalThis._ALCHEMY_WARNINGS ??= new Set();
+      if (globalThis._ALCHEMY_WARNINGS.has(message)) return;
+      globalThis._ALCHEMY_WARNINGS.add(message);
+      console.warn(colorize("WARN", "yellowBright"), message);
+    },
     task: (_id: string, data: Task) => {
       const prefix = data.prefix ? `[${data.prefix}]` : "";
 

package/src/util/deferred-promise.ts

@@ -0,0 +1,19 @@
+export class DeferredPromise<T> {
+  private promise = Promise.withResolvers<T>();
+
+  status: "pending" | "fulfilled" | "rejected" = "pending";
+
+  get value() {
+    return this.promise.promise;
+  }
+
+  resolve(value: T) {
+    this.status = "fulfilled";
+    this.promise.resolve(value);
+  }
+
+  reject(reason?: any) {
+    this.status = "rejected";
+    this.promise.reject(reason);
+  }
+}

package/src/util/detect-package-manager.ts

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+
+export type PackageManager = "bun" | "pnpm" | "yarn" | "npm";
+
+export function detectPackageManager(): PackageManager {
+  if (fs.existsSync("bun.lockb")) return "bun";
+  if (fs.existsSync("pnpm-lock.yaml")) return "pnpm";
+  if (fs.existsSync("yarn.lock")) return "yarn";
+
+  if (process.env.npm_execpath?.includes("bun")) {
+    return "bun";
+  }
+
+  const userAgent = process.env.npm_config_user_agent;
+  if (userAgent) {
+    if (userAgent.startsWith("bun")) return "bun";
+    if (userAgent.startsWith("pnpm")) return "pnpm";
+    if (userAgent.startsWith("yarn")) return "yarn";
+    if (userAgent.startsWith("npm")) return "npm";
+  }
+
+  return "npm";
+}

package/src/util/logger.ts

@@ -9,6 +9,7 @@ export const logger = new Proxy({} as LoggerApi, {
         log: console.log,
         error: console.error,
         warn: console.warn,
+        warnOnce: console.warn,
         task: () => {},
         exit: () => {},
       } as LoggerApi);

package/src/util/memoize.ts

@@ -0,0 +1,23 @@
+type AsyncReturnType<T> = T extends (...args: any[]) => Promise<infer R>
+  ? R
+  : T;
+
+export function memoize<F extends (...args: any[]) => Promise<any>>(
+  fn: F,
+  keyFn: (...args: Parameters<F>) => string,
+) {
+  const cache = new Map<string, Promise<AsyncReturnType<F>>>();
+  return async (...args: Parameters<F>): Promise<AsyncReturnType<F>> => {
+    const key = keyFn(...args);
+    const cached = cache.get(key);
+    if (cached) {
+      return await cached;
+    }
+    const promise = fn(...args).catch((error) => {
+      cache.delete(key);
+      throw error;
+    });
+    cache.set(key, promise);
+    return await promise;
+  };
+}