feat: Assets resource & Worker Binding (#40)

Author: sam-goodwin

alchemy-web/.vitepress/config.mts

@@ -44,10 +44,7 @@ export default defineConfig({
     ],
     socialLinks: [
       { icon: "github", link: "https://github.com/sam-goodwin/alchemy" },
-      {
-        icon: "discord",
-        link: "https://discord.gg/jwKw8dBJdN",
-      },
+      { icon: "discord", link: "https://discord.gg/jwKw8dBJdN" },
       { icon: "x", link: "https://twitter.com/samgoodwin89" },
     ],
     sidebar: [
@@ -153,6 +150,7 @@ export default defineConfig({
                 text: "AccountId",
                 link: "/docs/providers/cloudflare/account-id",
               },
+              { text: "Assets", link: "/docs/providers/cloudflare/assets" },
               {
                 text: "CustomDomain",
                 link: "/docs/providers/cloudflare/custom-domain",

alchemy-web/docs/providers/cloudflare/assets.md

@@ -0,0 +1,35 @@
+# Assets
+
+The Assets resource lets you add [static assets](https://developers.cloudflare.com/workers/platform/sites/) to your Cloudflare Workers.
+
+# Minimal Example
+
+Create a basic assets bundle from a local directory:
+
+```ts
+import { Assets } from "alchemy/cloudflare";
+
+const staticAssets = await Assets("static", {
+  path: "./src/assets"
+});
+```
+
+# Bind to a Worker
+
+Use the assets with a Cloudflare Worker:
+
+```ts
+import { Worker, Assets } from "alchemy/cloudflare";
+
+const staticAssets = await Assets("static", {
+  path: "./src/assets" 
+});
+
+const worker = await Worker("frontend", {
+  name: "frontend-worker",
+  entrypoint: "./src/worker.ts",
+  bindings: {
+    ASSETS: staticAssets
+  }
+});
+```

alchemy/src/cloudflare/assets.ts

@@ -0,0 +1,155 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { getContentType } from "../util/content-type";
+
+/**
+ * Properties for creating or updating Assets
+ */
+export interface AssetsProps {
+  /**
+   * Path to a directory containing static assets to be uploaded
+   * These files will be served by Cloudflare's Workers runtime
+   */
+  path: string;
+}
+
+/**
+ * Output returned after Assets creation/update
+ */
+export interface Assets extends Resource<"cloudflare::Asset">, AssetsProps {
+  /**
+   * The type of binding
+   */
+  type: "assets";
+
+  /**
+   * The ID of the assets bundle
+   */
+  id: string;
+
+  /**
+   * Asset files that were found
+   */
+  files: AssetFile[];
+
+  /**
+   * Time at which the assets were created
+   */
+  createdAt: number;
+
+  /**
+   * Time at which the assets were last updated
+   */
+  updatedAt: number;
+}
+
+/**
+ * Represents a single asset file
+ */
+export interface AssetFile {
+  /**
+   * Path relative to the assets directory
+   */
+  path: string;
+
+  /**
+   * Full filesystem path to the file
+   */
+  filePath: string;
+
+  /**
+   * Content type of the file
+   */
+  contentType: string;
+}
+
+/**
+ * Cloudflare Assets represent a collection of static files that can be uploaded and served
+ * by Cloudflare Workers.
+ *
+ * @example
+ * // Create a basic assets bundle from a local directory
+ * const staticAssets = await Assets("static", {
+ *   path: "./src/assets"
+ * });
+ *
+ * // Use these assets with a worker
+ * const worker = await Worker("frontend", {
+ *   name: "frontend-worker",
+ *   entrypoint: "./src/worker.ts",
+ *   bindings: {
+ *     ASSETS: staticAssets
+ *   }
+ * });
+ */
+export const Assets = Resource(
+  "cloudflare::Asset",
+  async function (
+    this: Context<Assets>,
+    id: string,
+    props: AssetsProps
+  ): Promise<Assets> {
+    if (this.phase === "delete") {
+      return this.destroy();
+    }
+
+    try {
+      // Check if the assets directory exists
+      const stats = await fs.stat(props.path);
+      if (!stats.isDirectory()) {
+        throw new Error(`Assets path ${props.path} is not a directory`);
+      }
+    } catch (error) {
+      throw new Error(
+        `Assets directory ${props.path} does not exist or is not accessible`
+      );
+    }
+
+    // Recursively get all files in the assets directory
+    const filesList = await getFilesRecursively(props.path);
+
+    // Create asset file objects
+    const files: AssetFile[] = filesList.map((filePath) => {
+      const relativePath = path.relative(props.path, filePath);
+      const normalizedPath = relativePath.split(path.sep).join("/"); // Ensure forward slashes for URLs
+
+      return {
+        path: normalizedPath,
+        filePath,
+        contentType: getContentType(filePath),
+      };
+    });
+
+    // Get current timestamp
+    const now = Date.now();
+
+    // Construct the output
+    return this({
+      id,
+      type: "assets",
+      path: props.path,
+      files,
+      createdAt: this.output?.createdAt || now,
+      updatedAt: now,
+    });
+  }
+);
+
+// Helper functions for file operations
+async function getFilesRecursively(dir: string): Promise<string[]> {
+  const files = await fs.readdir(dir, { withFileTypes: true });
+
+  const allFiles = await Promise.all(
+    files.map(async (file) => {
+      const path = `${dir}/${file.name}`;
+      if (file.isDirectory()) {
+        return getFilesRecursively(path);
+      }
+      return path;
+    })
+  );
+
+  return allFiles.flat();
+}

alchemy/src/cloudflare/bindings.ts

@@ -4,6 +4,7 @@
  * https://developers.cloudflare.com/api/resources/workers/subresources/scripts/methods/update/
  */
 import type { Secret } from "../secret";
+import type { Assets } from "./assets";
 import type { R2Bucket } from "./bucket";
 import type { DurableObjectNamespace } from "./durable-object-namespace";
 import type { KVNamespace } from "./kv-namespace";
@@ -22,16 +23,24 @@ export type Binding =
   | Worker
   | R2Bucket
   | Secret
-  | string;
+  | string
+  | Assets;
 
 export function isDurableObjectNamespace(
-  binding: Binding,
+  binding: Binding
 ): binding is DurableObjectNamespace {
   return (
     typeof binding === "object" && binding.type === "durable_object_namespace"
   );
 }
 
+/**
+ * Check if a binding is an Assets resource
+ */
+export function isAssets(binding: Binding): binding is Assets {
+  return typeof binding === "object" && binding.type === "assets";
+}
+
 /**
  * Union type for all Worker binding types (API spec)
  */

alchemy/src/cloudflare/index.ts

@@ -1,5 +1,6 @@
 export * from "./account-api-token";
 export * from "./api";
+export * from "./assets";
 export * from "./bindings";
 export * from "./bucket";
 export * from "./custom-domain";