alchemy 0.6.0 → 0.7.1

package/lib/cloudflare/queue.js

@@ -0,0 +1,192 @@
+import { Resource } from "../resource";
+import { CloudflareApi, createCloudflareApi, } from "./api";
+import { CloudflareApiError, handleApiError } from "./api-error";
+/**
+ * Creates and manages Cloudflare Queues.
+ *
+ * Queues provide a managed queue system for reliable message delivery
+ * between workers and other systems.
+ *
+ * @example
+ * // Create a basic queue with default settings
+ * const basicQueue = await Queue("my-app-queue", {
+ *   name: "my-app-queue"
+ * });
+ *
+ * @example
+ * // Create a queue with custom settings
+ * const customQueue = await Queue("delayed-queue", {
+ *   name: "delayed-queue",
+ *   settings: {
+ *     deliveryDelay: 30, // 30 second delay before message delivery
+ *     messageRetentionPeriod: 86400 // Store messages for 1 day
+ *   }
+ * });
+ *
+ * @example
+ * // Create a paused queue for later activation
+ * const pausedQueue = await Queue("paused-queue", {
+ *   name: "paused-queue",
+ *   settings: {
+ *     deliveryPaused: true
+ *   }
+ * });
+ *
+ * @see https://developers.cloudflare.com/queues/
+ */
+export const Queue = Resource("cloudflare::Queue", async function (id, props) {
+    const api = await createCloudflareApi(props);
+    const queueName = props.name || id;
+    if (this.phase === "delete") {
+        console.log("Deleting Cloudflare Queue:", queueName);
+        if (props.delete !== false) {
+            // Delete Queue
+            await deleteQueue(api, this.output?.id);
+        }
+        // Return void (a deleted queue has no content)
+        return this.destroy();
+    }
+    else {
+        let queueData;
+        if (this.phase === "create") {
+            console.log("Creating Cloudflare Queue:", queueName);
+            queueData = await createQueue(api, queueName, props);
+        }
+        else {
+            // Update operation
+            if (this.output?.id) {
+                console.log("Updating Cloudflare Queue:", queueName);
+                // Check if name is being changed, which is not allowed
+                if (props.name !== this.output.name) {
+                    throw new Error("Cannot update Queue name after creation. Queue name is immutable.");
+                }
+                // Update the queue with new settings
+                queueData = await updateQueue(api, this.output.id, props);
+            }
+            else {
+                // If no ID exists, fall back to creating a new queue
+                console.log("No existing Queue ID found, creating new Cloudflare Queue:", queueName);
+                queueData = await createQueue(api, queueName, props);
+            }
+        }
+        return this({
+            type: "queue",
+            id: queueData.result.queue_id || "",
+            name: queueName,
+            settings: queueData.result.settings
+                ? {
+                    deliveryDelay: queueData.result.settings.delivery_delay,
+                    deliveryPaused: queueData.result.settings.delivery_paused,
+                    messageRetentionPeriod: queueData.result.settings.message_retention_period,
+                }
+                : undefined,
+            createdOn: queueData.result.created_on || new Date().toISOString(),
+            modifiedOn: queueData.result.modified_on || new Date().toISOString(),
+            accountId: api.accountId,
+        });
+    }
+});
+/**
+ * Create a new Cloudflare Queue
+ */
+export async function createQueue(api, queueName, props) {
+    // Prepare the create payload
+    const createPayload = {
+        queue_name: queueName,
+    };
+    // Add settings if provided
+    if (props.settings) {
+        createPayload.settings = {};
+        if (props.settings.deliveryDelay !== undefined) {
+            createPayload.settings.delivery_delay = props.settings.deliveryDelay;
+        }
+        if (props.settings.deliveryPaused !== undefined) {
+            createPayload.settings.delivery_paused = props.settings.deliveryPaused;
+        }
+        if (props.settings.messageRetentionPeriod !== undefined) {
+            createPayload.settings.message_retention_period =
+                props.settings.messageRetentionPeriod;
+        }
+    }
+    const createResponse = await api.post(`/accounts/${api.accountId}/queues`, createPayload);
+    if (!createResponse.ok) {
+        return await handleApiError(createResponse, "creating", "Queue", queueName);
+    }
+    return (await createResponse.json());
+}
+/**
+ * Get a Cloudflare Queue
+ */
+export async function getQueue(api, queueId) {
+    const response = await api.get(`/accounts/${api.accountId}/queues/${queueId}`);
+    if (!response.ok) {
+        return await handleApiError(response, "getting", "Queue", queueId);
+    }
+    return (await response.json());
+}
+/**
+ * Delete a Cloudflare Queue
+ */
+export async function deleteQueue(api, queueId) {
+    if (!queueId) {
+        console.log("No Queue ID provided, skipping delete");
+        return;
+    }
+    // Delete Queue
+    const deleteResponse = await api.delete(`/accounts/${api.accountId}/queues/${queueId}`);
+    if (!deleteResponse.ok && deleteResponse.status !== 404) {
+        const errorData = await deleteResponse.json().catch(() => ({
+            errors: [{ message: deleteResponse.statusText }],
+        }));
+        throw new CloudflareApiError(`Error deleting Cloudflare Queue '${queueId}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`, deleteResponse);
+    }
+}
+/**
+ * Update a Cloudflare Queue
+ *
+ * Note: According to Cloudflare API, the queue name cannot be changed after creation.
+ * Only the settings can be updated.
+ */
+export async function updateQueue(api, queueId, props) {
+    // Prepare the update payload - only include settings
+    const updatePayload = {};
+    // Add settings if provided
+    if (props.settings) {
+        updatePayload.settings = {};
+        if (props.settings.deliveryDelay !== undefined) {
+            updatePayload.settings.delivery_delay = props.settings.deliveryDelay;
+        }
+        if (props.settings.deliveryPaused !== undefined) {
+            updatePayload.settings.delivery_paused = props.settings.deliveryPaused;
+        }
+        if (props.settings.messageRetentionPeriod !== undefined) {
+            updatePayload.settings.message_retention_period =
+                props.settings.messageRetentionPeriod;
+        }
+    }
+    // Use PATCH for partial updates (only settings can be updated)
+    const updateResponse = await api.patch(`/accounts/${api.accountId}/queues/${queueId}`, updatePayload);
+    if (!updateResponse.ok) {
+        return await handleApiError(updateResponse, "updating", "Queue", queueId);
+    }
+    return (await updateResponse.json());
+}
+/**
+ * List all Cloudflare Queues in an account
+ */
+export async function listQueues(api) {
+    const response = await api.get(`/accounts/${api.accountId}/queues`);
+    if (!response.ok) {
+        throw new CloudflareApiError(`Failed to list queues: ${response.statusText}`, response);
+    }
+    const data = (await response.json());
+    if (!data.success) {
+        const errorMessage = data.errors?.[0]?.message || "Unknown error";
+        throw new Error(`Failed to list queues: ${errorMessage}`);
+    }
+    // Transform API response
+    return (data.result || []).map((queue) => ({
+        name: queue.queue_name,
+        id: queue.queue_id,
+    }));
+}

package/lib/cloudflare/worker.js

@@ -2,13 +2,14 @@ import * as crypto from "crypto";
 import * as fs from "fs/promises";
 import { Bundle } from "../esbuild/bundle";
 import { Resource } from "../resource";
-import { isSecret } from "../secret";
 import { getContentType } from "../util/content-type";
 import { withExponentialBackoff } from "../util/retry";
 import { slugify } from "../util/slugify";
 import { createCloudflareApi, } from "./api";
-import { isAssets, isDurableObjectNamespace, } from "./bindings";
-import { isKVNamespace } from "./kv-namespace";
+import {} from "./assets";
+import {} from "./bindings";
+import {} from "./durable-object-namespace";
+import { upsertWorkflow } from "./workflow";
 /**
  * A Cloudflare Worker is a serverless function that can be deployed to the Cloudflare network.
  *
@@ -111,10 +112,16 @@ export const Worker = Resource("cloudflare::Worker", {
     const scriptContent = props.script ?? (await bundleWorkerScript(props));
     // Find any assets bindings
     const assetsBindings = [];
+    const workflowsBindings = [];
     if (props.bindings) {
         for (const [bindingName, binding] of Object.entries(props.bindings)) {
-            if (isAssets(binding)) {
-                assetsBindings.push({ name: bindingName, assets: binding });
+            if (typeof binding === "object") {
+                if (binding.type === "assets") {
+                    assetsBindings.push({ name: bindingName, assets: binding });
+                }
+                else if (binding.type === "workflow") {
+                    workflowsBindings.push(binding);
+                }
             }
         }
     }
@@ -129,8 +136,14 @@ export const Worker = Resource("cloudflare::Worker", {
     }
     // Prepare metadata with bindings
     const scriptMetadata = await prepareWorkerMetadata(this, oldBindings, props, assetUploadResult);
-    // Upload the worker script
     await putWorker(api, workerName, scriptContent, scriptMetadata);
+    for (const workflow of workflowsBindings) {
+        await upsertWorkflow(api, {
+            workflowName: workflow.workflowName,
+            className: workflow.className,
+            scriptName: workerName,
+        });
+    }
     // TODO: it is less than ideal that this can fail, resulting in state problem
     await this.set("bindings", props.bindings);
     // Handle worker URL if requested
@@ -139,8 +152,10 @@ export const Worker = Resource("cloudflare::Worker", {
     const now = Date.now();
     // Construct the output
     return this({
+        ...props,
         type: "service",
         id,
+        entrypoint: props.entrypoint,
         name: workerName,
         script: scriptContent,
         format: props.format || "esm", // Include format in the output
@@ -251,18 +266,25 @@ async function prepareWorkerMetadata(ctx, oldBindings, props, assetUploadResult)
     // Convert bindings to the format expected by the API
     for (const [bindingName, binding] of Object.entries(bindings)) {
         // Create a copy of the binding to avoid modifying the original
-        if (isKVNamespace(binding)) {
+        if (typeof binding === "string") {
             meta.bindings.push({
-                type: "kv_namespace",
+                type: "plain_text",
                 name: bindingName,
-                namespace_id: binding.namespaceId,
+                text: binding,
             });
         }
-        else if (typeof binding === "string") {
+        else if (binding.type === "d1") {
             meta.bindings.push({
-                type: "plain_text",
+                type: "d1",
                 name: bindingName,
-                text: binding,
+                id: binding.id,
+            });
+        }
+        else if (binding.type === "kv_namespace") {
+            meta.bindings.push({
+                type: "kv_namespace",
+                name: bindingName,
+                namespace_id: binding.namespaceId,
             });
         }
         else if (binding.type === "service") {
@@ -273,33 +295,15 @@ async function prepareWorkerMetadata(ctx, oldBindings, props, assetUploadResult)
             });
         }
         else if (binding.type === "durable_object_namespace") {
-            const stableId = binding.id;
-            const className = binding.className;
             meta.bindings.push({
                 type: "durable_object_namespace",
                 name: bindingName,
-                class_name: className,
+                class_name: binding.className,
                 script_name: binding.scriptName,
                 environment: binding.environment,
                 namespace_id: binding.namespaceId,
             });
-            const oldBinding = Object.values(oldBindings ?? {})
-                ?.filter(isDurableObjectNamespace)
-                ?.find((b) => b.id === stableId);
-            if (!oldBinding) {
-                if (binding.sqlite) {
-                    meta.migrations.new_sqlite_classes.push(className);
-                }
-                else {
-                    meta.migrations.new_classes.push(className);
-                }
-            }
-            else if (oldBinding.className !== className) {
-                meta.migrations.renamed_classes.push({
-                    from: oldBinding.className,
-                    to: className,
-                });
-            }
+            configureClassMigration(binding, binding.id, binding.className);
         }
         else if (binding.type === "r2_bucket") {
             meta.bindings.push({
@@ -308,25 +312,65 @@ async function prepareWorkerMetadata(ctx, oldBindings, props, assetUploadResult)
                 bucket_name: binding.name,
             });
         }
-        else if (isAssets(binding)) {
+        else if (binding.type === "assets") {
             meta.bindings.push({
                 type: "assets",
                 name: bindingName,
             });
         }
-        else if (isSecret(binding)) {
+        else if (binding.type === "secret") {
             meta.bindings.push({
                 type: "secret_text",
                 name: bindingName,
                 text: binding.unencrypted,
             });
         }
+        else if (binding.type === "workflow") {
+            meta.bindings.push({
+                type: "workflow",
+                name: bindingName,
+                workflow_name: binding.workflowName,
+                class_name: binding.className,
+                // this should be set if the Workflow is in another script ...
+                // script_name: ??,
+            });
+            // it's unclear whether this is needed, but it works both ways
+            configureClassMigration(binding, binding.id, binding.className);
+        }
+        else if (binding.type === "queue") {
+            meta.bindings.push({
+                type: "queue",
+                name: bindingName,
+                queue_name: binding.name,
+            });
+        }
         else {
             // @ts-expect-error - we should never reach here
             throw new Error(`Unsupported binding type: ${binding.type}`);
         }
     }
+    function configureClassMigration(binding, stableId, className) {
+        const oldBinding = Object.values(oldBindings ?? {})
+            ?.filter((b) => typeof b === "object" &&
+            (b.type === "durable_object_namespace" || b.type === "workflow"))
+            ?.find((b) => b.id === stableId);
+        if (!oldBinding) {
+            if (binding.type === "durable_object_namespace" && binding.sqlite) {
+                meta.migrations.new_sqlite_classes.push(className);
+            }
+            else {
+                meta.migrations.new_classes.push(className);
+            }
+        }
+        else if (oldBinding.className !== className) {
+            meta.migrations.renamed_classes.push({
+                from: oldBinding.className,
+                to: className,
+            });
+        }
+    }
     // Convert env variables to plain_text bindings
+    // TODO(sam): remove Worker.env in favor of always bindings
     if (props.env) {
         for (const [key, value] of Object.entries(props.env)) {
             meta.bindings.push({

package/lib/cloudflare/workflow.d.ts

@@ -0,0 +1,46 @@
+import type { CloudflareApi } from "./api";
+export interface WorkflowProps {
+    /**
+     * Name of the workflow
+     *
+     * @maxLength 64
+     * @minLength 1
+     * @default - className if provided, otherwise id
+     */
+    workflowName?: string;
+    /**
+     * Name of the class that implements the workflow
+     *
+     * @maxLength 255
+     * @minLength 1
+     * @default - workflowName if provided, otherwise id
+     */
+    className?: string;
+}
+export declare class Workflow<PARAMS = unknown> {
+    readonly id: string;
+    readonly type: "workflow";
+    /**
+     * Phantom property to preserve workflow params at the type level.
+     *
+     * No value exists.
+     */
+    readonly _PARAMS: PARAMS;
+    readonly workflowName: string;
+    readonly className: string;
+    constructor(id: string, props?: WorkflowProps);
+}
+export interface WorkflowMetadata {
+    id: string;
+    class_name: string;
+    created_on: string;
+    modified_on: string;
+    name: string;
+    script_name: string;
+    triggered_on: string;
+    version_id: string;
+}
+export declare function upsertWorkflow(api: CloudflareApi, props: WorkflowProps & {
+    workflowName: string;
+    scriptName: string;
+}): Promise<WorkflowMetadata>;

package/lib/cloudflare/workflow.js

@@ -0,0 +1,29 @@
+import { handleApiError } from "./api-error";
+export class Workflow {
+    id;
+    type = "workflow";
+    /**
+     * Phantom property to preserve workflow params at the type level.
+     *
+     * No value exists.
+     */
+    _PARAMS = undefined;
+    workflowName;
+    className;
+    constructor(id, props = {}) {
+        this.id = id;
+        this.workflowName = props.workflowName ?? props.className ?? id;
+        this.className = props.className ?? this.workflowName;
+    }
+}
+export async function upsertWorkflow(api, props) {
+    const response = await api.put(`/accounts/${api.accountId}/workflows/${props.workflowName}`, {
+        class_name: props.className,
+        script_name: props.scriptName,
+    });
+    if (!response.ok) {
+        await handleApiError(response, "create", "workflow", props.workflowName);
+    }
+    const body = (await response.json());
+    return body.result;
+}