alchemy 0.1.11 → 0.1.12

package/src/cloudflare/kv-namespace.ts

@@ -0,0 +1,195 @@
+import { type Context, Resource } from "../resource";
+import { createCloudflareApi } from "./api";
+
+/**
+ * Properties for creating or updating a KV Namespace
+ */
+export interface KVNamespaceProps {
+  /**
+   * Title of the namespace
+   */
+  title: string;
+
+  /**
+   * KV pairs to store in the namespace
+   * Only used for initial setup or updates
+   */
+  values?: KVPair[];
+}
+
+/**
+ * Key-value pair to store in a KV Namespace
+ */
+export interface KVPair {
+  /**
+   * Key name
+   */
+  key: string;
+
+  /**
+   * Value to store (string or JSON object)
+   */
+  value: string | object;
+
+  /**
+   * Optional expiration in seconds from now
+   */
+  expiration?: number;
+
+  /**
+   * Optional expiration timestamp in seconds since epoch
+   */
+  expirationTtl?: number;
+
+  /**
+   * Optional metadata for the key
+   */
+  metadata?: any;
+}
+
+/**
+ * Output returned after KV Namespace creation/update
+ */
+export interface KVNamespaceOutput extends KVNamespaceProps {
+  /**
+   * The ID of the namespace
+   */
+  id: string;
+
+  /**
+   * Time at which the namespace was created
+   */
+  createdAt: number;
+
+  /**
+   * Time at which the namespace was last modified
+   */
+  modifiedAt: number;
+}
+
+export class KVNamespace extends Resource(
+  "cloudflare::KVNamespace",
+  async (ctx: Context<KVNamespaceOutput>, props: KVNamespaceProps) => {
+    // Create Cloudflare API client with automatic account discovery
+    const api = await createCloudflareApi();
+
+    if (ctx.event === "delete") {
+      // For delete operations, we need to check if the namespace ID exists in the output
+      const namespaceId = ctx.output?.id;
+
+      if (namespaceId) {
+        // Delete KV namespace
+        const deleteResponse = await api.delete(
+          `/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}`,
+        );
+
+        if (!deleteResponse.ok && deleteResponse.status !== 404) {
+          const errorData: any = await deleteResponse.json().catch(() => ({
+            errors: [{ message: deleteResponse.statusText }],
+          }));
+          console.error(
+            "Error deleting KV namespace:",
+            errorData.errors?.[0]?.message || deleteResponse.statusText,
+          );
+        }
+      }
+
+      // Return minimal output for deleted state
+      return;
+    } else {
+      // For create or update operations
+      // If ctx.event is "update", we expect ctx.output to exist
+      let namespaceId = ctx.event === "update" ? ctx.output?.id || "" : "";
+      let createdAt =
+        ctx.event === "update"
+          ? ctx.output?.createdAt || Date.now()
+          : Date.now();
+
+      if (ctx.event === "update" && namespaceId) {
+        // Can't update a KV namespace title directly, just work with existing ID
+      } else {
+        // Create new KV namespace
+        const createResponse = await api.post(
+          `/accounts/${api.accountId}/storage/kv/namespaces`,
+          {
+            title: props.title,
+          },
+        );
+
+        if (!createResponse.ok) {
+          const errorData: any = await createResponse.json().catch(() => ({
+            errors: [{ message: createResponse.statusText }],
+          }));
+          throw new Error(
+            `Error creating KV namespace: ${errorData.errors?.[0]?.message || createResponse.statusText}`,
+          );
+        }
+
+        const createResult: any = await createResponse.json();
+        namespaceId = createResult.result.id;
+        createdAt = Date.now();
+      }
+
+      // Handle KV pairs if provided
+      if (props.values && props.values.length > 0 && namespaceId) {
+        // Process KV pairs in batches of 10000 (API limit)
+        const BATCH_SIZE = 10000;
+
+        for (let i = 0; i < props.values.length; i += BATCH_SIZE) {
+          const batch = props.values.slice(i, i + BATCH_SIZE);
+
+          const bulkPayload = batch.map((entry) => {
+            const item: any = {
+              key: entry.key,
+              value:
+                typeof entry.value === "string"
+                  ? entry.value
+                  : JSON.stringify(entry.value),
+            };
+
+            if (entry.expiration) {
+              item.expiration = entry.expiration;
+            }
+
+            if (entry.expirationTtl) {
+              item.expiration_ttl = entry.expirationTtl;
+            }
+
+            if (entry.metadata) {
+              item.metadata = entry.metadata;
+            }
+
+            return item;
+          });
+
+          const bulkResponse = await api.put(
+            `/accounts/${api.accountId}/storage/kv/namespaces/${namespaceId}/bulk`,
+            bulkPayload,
+          );
+
+          if (!bulkResponse.ok) {
+            const errorData: any = await bulkResponse.json().catch(() => ({
+              errors: [{ message: bulkResponse.statusText }],
+            }));
+            console.warn(
+              `Error writing KV batch: ${errorData.errors?.[0]?.message || bulkResponse.statusText}`,
+            );
+          }
+        }
+      }
+
+      const now = Date.now();
+
+      // Construct the output
+      const output: KVNamespaceOutput = {
+        id: namespaceId,
+        title: props.title,
+        values: props.values,
+        createdAt: createdAt,
+        modifiedAt: now,
+      };
+
+      return output;
+    }
+  },
+) {}

package/src/cloudflare/state.ts

@@ -0,0 +1,138 @@
+import type { KVNamespace } from "@cloudflare/workers-types";
+import type { State, StateStore } from "../state";
+
+/**
+ * Options for CloudflareStateStore
+ */
+export interface CloudflareStateStoreOptions {
+  /**
+   * The prefix to use for keys in the KV namespace
+   * This allows multiple state stores to use the same KV namespace
+   */
+  prefix?: string;
+}
+
+/**
+ * State store implementation using Cloudflare KV Namespace
+ */
+export class CloudflareStateStore implements StateStore {
+  private namespace: KVNamespace;
+  private prefix: string;
+
+  /**
+   * Create a new CloudflareStateStore
+   *
+   * @param namespace The KV namespace to use for storing state
+   * @param options Options for the state store
+   */
+  constructor(
+    namespace: KVNamespace,
+    options: CloudflareStateStoreOptions = {},
+  ) {
+    this.namespace = namespace;
+    this.prefix = options.prefix || "alchemy-state:";
+  }
+
+  /**
+   * No initialization needed for KV namespaces as they are pre-provisioned
+   */
+  async init(): Promise<void> {
+    // KV namespaces are pre-provisioned in Cloudflare, so no initialization is needed
+  }
+
+  /**
+   * KV namespaces cannot be deleted programmatically
+   */
+  async deinit(): Promise<void> {
+    // KV namespaces can only be deleted through the Cloudflare dashboard or API
+    // We cannot delete the namespace itself here
+  }
+
+  /**
+   * List all resources in the state store
+   */
+  async list(): Promise<string[]> {
+    const list = await this.namespace.list({ prefix: this.prefix });
+    return list.keys.map((key) => key.name.slice(this.prefix.length));
+  }
+
+  /**
+   * Count the number of items in the state store
+   */
+  async count(): Promise<number> {
+    const list = await this.namespace.list({ prefix: this.prefix });
+    return list.keys.length;
+  }
+
+  /**
+   * Get a state by key
+   *
+   * @param key The key to look up
+   * @returns The state or undefined if not found
+   */
+  async get(key: string): Promise<State | undefined> {
+    const data = await this.namespace.get(this.getNamespacedKey(key), "json");
+    return data as State | undefined;
+  }
+
+  /**
+   * Get multiple states by their keys
+   *
+   * @param ids Array of keys to fetch
+   * @returns Record mapping keys to their states
+   */
+  async getBatch(ids: string[]): Promise<Record<string, State>> {
+    const result: Record<string, State> = {};
+
+    // KV doesn't have a native batch get operation, so we need to make multiple requests
+    // We could optimize this with Promise.all for parallel fetching
+    const promises = ids.map(async (id) => {
+      const state = await this.get(id);
+      if (state) {
+        result[id] = state;
+      }
+    });
+
+    await Promise.all(promises);
+    return result;
+  }
+
+  /**
+   * Get all states in the store
+   *
+   * @returns Record mapping all keys to their states
+   */
+  async all(): Promise<Record<string, State>> {
+    const keys = await this.list();
+    return this.getBatch(keys);
+  }
+
+  /**
+   * Set a state for a key
+   *
+   * @param key The key to set
+   * @param value The state to store
+   */
+  async set(key: string, value: State): Promise<void> {
+    await this.namespace.put(this.getNamespacedKey(key), JSON.stringify(value));
+  }
+
+  /**
+   * Delete a state by key
+   *
+   * @param key The key to delete
+   */
+  async delete(key: string): Promise<void> {
+    await this.namespace.delete(this.getNamespacedKey(key));
+  }
+
+  /**
+   * Get the namespaced key for storage
+   *
+   * @param key The original key
+   * @returns The key with prefix for use in the KV namespace
+   */
+  private getNamespacedKey(key: string): string {
+    return `${this.prefix}${key}`;
+  }
+}

package/src/cloudflare/static-site-router.ts

@@ -0,0 +1,108 @@
+// see: https://developers.cloudflare.com/workers/runtime-apis/cache/
+declare var caches: any;
+
+// injected by src/cloudflare/static-site.ts
+declare var __ASSET_MANIFEST__: Record<string, string>;
+
+export interface Env {
+  ASSETS: KVNamespace;
+  INDEX_PAGE: string;
+  ERROR_PAGE?: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    console.log("url", request.url);
+    const pathname = url.pathname.replace(/^\//, "");
+    const filePath = pathname === "" ? env.INDEX_PAGE : pathname;
+
+    // Return from cache if available
+    const cachedResponse = await lookupCache();
+    if (cachedResponse) return cachedResponse;
+
+    // Fetch from KV
+    {
+      const object = await env.ASSETS.getWithMetadata(filePath);
+      if (object.value) return await respond(200, filePath, object);
+    }
+    {
+      const guess =
+        filePath + (filePath.endsWith("/") ? "" : "/") + "index.html";
+      const object = await env.ASSETS.getWithMetadata(guess);
+      if (object.value) return await respond(200, guess, object);
+    }
+    {
+      const guess = filePath + ".html";
+      const object = await env.ASSETS.getWithMetadata(guess);
+      if (object.value) return await respond(200, guess, object);
+    }
+
+    // Handle error page
+    if (env.ERROR_PAGE) {
+      const object = await env.ASSETS.getWithMetadata(env.ERROR_PAGE);
+      if (object.value) return await respond(404, env.ERROR_PAGE, object);
+    } else {
+      const object = await env.ASSETS.getWithMetadata(env.INDEX_PAGE);
+      if (object.value) return await respond(200, env.INDEX_PAGE, object);
+    }
+
+    // Handle failed to render error page
+    return new Response("Page Not Found", { status: 404 });
+
+    async function lookupCache() {
+      const cache = caches.default;
+      const r = await cache.match(request);
+
+      // cache does not exist
+      if (!r) return;
+
+      // cache exists but etag does not match
+      if (r.headers.get("etag") !== __ASSET_MANIFEST__[filePath]) return;
+
+      // cache exists
+      return r;
+    }
+
+    async function saveCache(response: Response) {
+      const cache = caches.default;
+      await cache.put(request, response.clone());
+    }
+
+    async function respond(
+      status: number,
+      filePath: string,
+      object: KVNamespaceGetWithMetadataResult<any, any>,
+    ) {
+      // build response
+      const headers = new Headers();
+      if (__ASSET_MANIFEST__[filePath]) {
+        headers.set("etag", __ASSET_MANIFEST__[filePath]);
+        headers.set("content-type", object.metadata.contentType);
+        headers.set("cache-control", object.metadata.cacheControl);
+      }
+      // TODO: do we need base64 encoded here?
+      // const response = new Response(base64ToArrayBuffer(object.value), {
+      const response = new Response(object.value, {
+        status,
+        headers,
+      });
+
+      if (request.method === "GET") {
+        await saveCache(response);
+      }
+
+      return response;
+    }
+  },
+};
+
+function base64ToArrayBuffer(base64: any) {
+  const binaryString = atob(base64);
+  const len = binaryString.length;
+  const bytes = new Uint8Array(len);
+  for (let i = 0; i < len; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes.buffer;
+}