alchemy 0.20.0 → 0.21.0

package/src/cloudflare/worker.ts

@@ -8,6 +8,7 @@ import { bootstrapPlugin } from "../runtime/plugin.js";
 import { Scope } from "../scope.js";
 import { Secret, secret } from "../secret.js";
 import { serializeScope } from "../serde.js";
+import type { type } from "../type.js";
 import { withExponentialBackoff } from "../util/retry.js";
 import { slugify } from "../util/slugify.js";
 import { CloudflareApiError, handleApiError } from "./api-error.js";
@@ -17,11 +18,20 @@ import {
   createCloudflareApi,
 } from "./api.js";
 import type { Assets } from "./assets.js";
-import { type Binding, type Bindings, Json } from "./bindings.js";
+import {
+  type Binding,
+  type Bindings,
+  Json,
+  type WorkerBindingSpec,
+} from "./bindings.js";
 import type { Bound } from "./bound.js";
 import { isBucket } from "./bucket.js";
 import { bundleWorkerScript } from "./bundle/bundle-worker.js";
 import { isD1Database } from "./d1-database.js";
+import {
+  DurableObjectNamespace,
+  isDurableObjectNamespace,
+} from "./durable-object-namespace.js";
 import {
   type EventSource,
   type QueueEventSource,
@@ -90,8 +100,10 @@ export interface AssetsConfig {
   serve_directly?: boolean;
 }
 
-export interface BaseWorkerProps<B extends Bindings = Bindings>
-  extends CloudflareApiOptions {
+export interface BaseWorkerProps<
+  B extends Bindings | undefined = undefined,
+  RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
+> extends CloudflareApiOptions {
   /**
    * Bundle options when using entryPoint
    *
@@ -198,16 +210,27 @@ export interface BaseWorkerProps<B extends Bindings = Bindings>
    * Can include queues, streams, or other event sources.
    */
   eventSources?: EventSource[];
+
+  /**
+   * The RPC class to use for the worker.
+   *
+   * This is only used when using the rpc property.
+   */
+  rpc?: (new (...args: any[]) => RPC) | type<RPC>;
 }
 
-export interface InlineWorkerProps<B extends Bindings = Bindings>
-  extends BaseWorkerProps<B> {
+export interface InlineWorkerProps<
+  B extends Bindings | undefined = Bindings,
+  RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
+> extends BaseWorkerProps<B, RPC> {
   script: string;
   entrypoint?: undefined;
 }
 
-export interface EntrypointWorkerProps<B extends Bindings = Bindings>
-  extends BaseWorkerProps<B> {
+export interface EntrypointWorkerProps<
+  B extends Bindings | undefined = Bindings,
+  RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
+> extends BaseWorkerProps<B, RPC> {
   entrypoint: string;
   script?: undefined;
 }
@@ -215,9 +238,10 @@ export interface EntrypointWorkerProps<B extends Bindings = Bindings>
 /**
  * Properties for creating or updating a Worker
  */
-export type WorkerProps<B extends Bindings = Bindings> =
-  | InlineWorkerProps<B>
-  | EntrypointWorkerProps<B>;
+export type WorkerProps<
+  B extends Bindings | undefined = Bindings,
+  RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
+> = InlineWorkerProps<B, RPC> | EntrypointWorkerProps<B, RPC>;
 
 export type FetchWorkerProps<
   B extends Bindings = Bindings,
@@ -265,63 +289,70 @@ export function isWorker(resource: Resource): resource is Worker<any> {
 /**
  * Output returned after Worker creation/update
  */
-export type Worker<B extends Bindings = Bindings> =
-  Resource<"cloudflare::Worker"> &
-    Omit<WorkerProps<B>, "url" | "script"> &
-    globalThis.Service & {
-      type: "service";
-
-      /**
-       * The ID of the worker
-       */
-      id: string;
-
-      /**
-       * The name of the worker
-       */
-      name: string;
-
-      /**
-       * Time at which the worker was created
-       */
-      createdAt: number;
-
-      /**
-       * Time at which the worker was last updated
-       */
-      updatedAt: number;
-
-      /**
-       * The worker's URL if enabled
-       * Format: {name}.{subdomain}.workers.dev
-       */
-      url?: string;
-
-      /**
-       * The bindings that were created
-       */
-      bindings: B | undefined;
-
-      /**
-       * Configuration for static assets
-       */
-      assets?: AssetsConfig;
-
-      // phantom property (for typeof myWorker.Env)
-      Env: {
-        [bindingName in keyof B]: Bound<B[bindingName]>;
-      };
+export type Worker<
+  B extends Bindings | undefined = Bindings | undefined,
+  RPC extends Rpc.WorkerEntrypointBranded = Rpc.WorkerEntrypointBranded,
+> = Resource<"cloudflare::Worker"> &
+  Omit<WorkerProps<B>, "url" | "script"> &
+  globalThis.Service & {
+    /** @internal phantom property */
+    __rpc__?: RPC;
 
-      /**
-       * The compatibility date for the worker
-       */
-      compatibilityDate: string;
+    type: "service";
 
-      /**
-       * The compatibility flags for the worker
-       */
-      compatibilityFlags: string[];
-    };
+    /**
+     * The ID of the worker
+     */
+    id: string;
+
+    /**
+     * The name of the worker
+     */
+    name: string;
+
+    /**
+     * Time at which the worker was created
+     */
+    createdAt: number;
+
+    /**
+     * Time at which the worker was last updated
+     */
+    updatedAt: number;
+
+    /**
+     * The worker's URL if enabled
+     * Format: {name}.{subdomain}.workers.dev
+     */
+    url?: string;
+
+    /**
+     * The bindings that were created
+     */
+    bindings: B;
+
+    /**
+     * Configuration for static assets
+     */
+    assets?: AssetsConfig;
+
+    // phantom property (for typeof myWorker.Env)
+    Env: B extends Bindings
+      ? {
+          [bindingName in keyof B]: Bound<B[bindingName]>;
+        }
+      : undefined;
+
+    /**
+     * The compatibility date for the worker
+     */
+    compatibilityDate: string;
+
+    /**
+     * The compatibility flags for the worker
+     */
+    compatibilityFlags: string[];
+  };
 
 /**
  * A Cloudflare Worker is a serverless function that can be deployed to the Cloudflare network.
@@ -412,13 +443,36 @@ export type Worker<B extends Bindings = Bindings> =
  *   crons: ['* 15 * * *', '0 0 * * *', '0 12 * * MON']
  * })
  *
+ * @example
+ * // Create cross-script durable object binding where one worker
+ * // defines the durable object and another worker accesses it:
+ * const dataWorker = await Worker("data-worker", {
+ *   name: "data-worker",
+ *   entrypoint: "./src/data.ts",
+ *   bindings: {
+ *     // Bind to its own durable object
+ *     STORAGE: new DurableObjectNamespace("storage", {
+ *       className: "DataStorage"
+ *     })
+ *   }
+ * });
+ *
+ * const apiWorker = await Worker("api-worker", {
+ *   name: "api-worker",
+ *   entrypoint: "./src/api.ts",
+ *   bindings: {
+ *     // Cross-script binding to the data worker's durable object
+ *     SHARED_STORAGE: dataWorker.bindings.STORAGE
+ *   }
+ * });
+ *
  * @see
  * https://developers.cloudflare.com/workers/
  */
-export function Worker<const B extends Bindings>(
-  id: string,
-  props: WorkerProps<B>,
-): Promise<Worker<B>>;
+export function Worker<
+  const B extends Bindings,
+  RPC extends Rpc.WorkerEntrypointBranded,
+>(id: string, props: WorkerProps<B, RPC>): Promise<Worker<B, RPC>>;
 export function Worker<const B extends Bindings, const E extends EventSource[]>(
   id: string,
   meta: ImportMeta,
@@ -431,6 +485,7 @@ export function Worker<const B extends Bindings>(
 ): Promise<Worker<B>> {
   const [id, meta, props] =
     args.length === 2 ? [args[0], undefined, args[1]] : args;
+
   if (("fetch" in props && props.fetch) || ("queue" in props && props.queue)) {
     const scope = Scope.current;
 
@@ -648,7 +703,11 @@ export const _Worker = Resource(
     const compatibilityFlags = props.compatibilityFlags ?? [];
 
     const uploadWorkerScript = async (props: WorkerProps<B>) => {
-      const oldBindings = await this.get<Bindings>("bindings");
+      const [oldBindings, oldMetadata] = await Promise.all([
+        getWorkerBindings(api, workerName),
+        getWorkerScriptMetadata(api, workerName),
+      ]);
+      const oldTags = oldMetadata?.default_environment?.script?.tags;
 
       // Get the script content - either from props.script, or by bundling
       const scriptContent =
@@ -695,6 +754,7 @@ export const _Worker = Resource(
       const scriptMetadata = await prepareWorkerMetadata(
         this,
         oldBindings,
+        oldTags,
         {
           ...props,
           compatibilityDate,
@@ -706,9 +766,6 @@ export const _Worker = Resource(
 
       await putWorker(api, workerName, scriptContent, scriptMetadata);
 
-      // TODO: it is less than ideal that this can fail, resulting in state problem
-      await this.set("bindings", props.bindings);
-
       for (const workflow of workflowsBindings) {
         await upsertWorkflow(api, {
           workflowName: workflow.workflowName,
@@ -816,6 +873,24 @@ export const _Worker = Resource(
 
     const { scriptMetadata, workerUrl, now } = await uploadWorkerScript(props);
 
+    function exportBindings() {
+      return Object.fromEntries(
+        Object.entries(props.bindings ?? ({} as B)).map(
+          ([bindingName, binding]) => [
+            bindingName,
+            isDurableObjectNamespace(binding) &&
+            binding.scriptName === undefined
+              ? new DurableObjectNamespace(binding.id, {
+                  ...binding,
+                  // re-export this binding mapping to the host worker (this worker)
+                  scriptName: workerName,
+                })
+              : binding,
+          ],
+        ),
+      );
+    }
+
     // Construct the output
     return this({
       ...props,
@@ -826,7 +901,7 @@ export const _Worker = Resource(
       compatibilityDate,
       compatibilityFlags,
       format: props.format || "esm", // Include format in the output
-      bindings: props.bindings ?? ({} as B),
+      bindings: exportBindings(),
       env: props.env,
       observability: scriptMetadata.observability,
       createdAt: now,
@@ -1058,34 +1133,49 @@ export async function getWorkerScriptMetadata(
   return ((await response.json()) as any).result as WorkerScriptMetadata;
 }
 
-export async function _getWorkerBindings(
-  api: CloudflareApi,
-  workerName: string,
-  environment = "production",
-) {
+async function getWorkerBindings(api: CloudflareApi, workerName: string) {
+  // Fetch the bindings for a worker by calling the Cloudflare API endpoint:
+  // GET /accounts/:account_id/workers/scripts/:script_name/bindings
+  // See: https://developers.cloudflare.com/api/resources/workers/subresources/scripts/subresources/script_and_version_settings/methods/get/
   const response = await api.get(
-    `/accounts/${api.accountId}/workers/services/${workerName}/environments/${environment}/bindings`,
-    {
-      headers: {
-        Authorization: `Bearer ${process.env.CLOUDFLARE_API_TOKEN}`,
-        "Content-Type": "application/json",
-      },
-    },
+    `/accounts/${api.accountId}/workers/scripts/${workerName}/settings`,
   );
-
   if (response.status === 404) {
     return undefined;
   }
-
   if (!response.ok) {
     throw new Error(
-      `Failed to fetch bindings: ${response.status} ${response.statusText}`,
+      `Error getting worker bindings: ${response.status} ${response.statusText}`,
     );
   }
-
-  const data: any = await response.json();
-
-  return data.result;
+  // The result is an object with a "result" property containing the bindings array
+  const { result, success, errors } = (await response.json()) as {
+    result: {
+      bindings: WorkerBindingSpec[];
+      compatibility_date: string;
+      compatibility_flags: string[];
+      [key: string]: any;
+    };
+    success: boolean;
+    errors: Array<{
+      code: number;
+      message: string;
+      documentation_url: string;
+      [key: string]: any;
+    }>;
+    messages: Array<{
+      code: number;
+      message: string;
+      documentation_url: string;
+      [key: string]: any;
+    }>;
+  };
+  if (!success) {
+    throw new Error(
+      `Error getting worker bindings: ${response.status} ${response.statusText}\nErrors:\n${errors.map((e) => `- [${e.code}] ${e.message} (${e.documentation_url})`).join("\n")}`,
+    );
+  }
+  return result.bindings;
 }
 
 /**

package/src/cloudflare/workflow.ts

@@ -1,5 +1,6 @@
 import { handleApiError } from "./api-error.js";
 import type { CloudflareApi } from "./api.js";
+import type { Binding } from "./bindings.js";
 
 export interface WorkflowProps {
   /**
@@ -20,6 +21,10 @@ export interface WorkflowProps {
   className?: string;
 }
 
+export function isWorkflow(binding: Binding): binding is Workflow {
+  return typeof binding === "object" && binding.type === "workflow";
+}
+
 export class Workflow<PARAMS = unknown> {
   public readonly type = "workflow";
   /**

package/src/cloudflare/wrangler.json.ts

@@ -17,7 +17,7 @@ export interface WranglerJsonProps {
   /**
    * The worker to generate the wrangler.json file for
    */
-  worker: Worker;
+  worker: Worker<any>;
   /**
    * Path to write the wrangler.json file to
    *
@@ -393,6 +393,10 @@ function processBindings(
   }
   // Process each binding
   for (const [bindingName, binding] of Object.entries(bindings)) {
+    if (typeof binding === "function") {
+      // this is only reachable in the
+      throw new Error(`Invalid binding ${bindingName} is a function`);
+    }
     if (typeof binding === "string") {
       // Plain text binding - add to vars
       if (!spec.vars) {

package/src/index.ts

@@ -5,6 +5,7 @@ export type * from "./scope.js";
 export * from "./secret.js";
 export * from "./serde.js";
 export * from "./state.js";
+export * from "./type.js";
 export * from "./util/ignore.js";
 
 import { alchemy } from "./alchemy.js";

package/src/type.ts

@@ -0,0 +1,9 @@
+export type type<T> = typeof type<T>;
+/**
+ * Used to construct type-level alias information.
+ */
+export const type = ((): any => {
+  throw new Error("Should never be called, purely for type-level aliasing");
+}) as (<T>() => T) &
+  // we also want to make this a "class type" so that syntax highlighting is always as a type
+  (new <T>() => T);