alchemy 0.8.0 → 0.9.0

package/src/cloudflare/vectorize-metadata-index.ts

@@ -0,0 +1,239 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import {
+  CloudflareApi,
+  createCloudflareApi,
+  type CloudflareApiOptions,
+} from "./api";
+import { CloudflareApiError, handleApiError } from "./api-error";
+import { VectorizeIndex } from "./vectorize-index";
+
+/**
+ * Properties for creating or deleting a Vectorize Metadata Index
+ */
+export interface VectorizeMetadataIndexProps extends CloudflareApiOptions {
+  /**
+   * Parent Vectorize Index
+   */
+  index: VectorizeIndex;
+
+  /**
+   * Name of the property in the metadata to create an index for
+   */
+  propertyName: string;
+
+  /**
+   * Type of the metadata index
+   */
+  indexType: "string" | "number" | "boolean";
+}
+
+/**
+ * Output returned after Vectorize Metadata Index creation/deletion
+ */
+export interface VectorizeMetadataIndex
+  extends Resource<"cloudflare::VectorizeMetadataIndex">,
+    VectorizeMetadataIndexProps {
+  /**
+   * ID of this metadata index (derived from propertyName)
+   */
+  id: string;
+
+  /**
+   * Mutation ID returned by the API after creation
+   */
+  mutationId?: string;
+}
+
+/**
+ * Creates and manages Cloudflare Vectorize Metadata Indexes.
+ *
+ * Vectorize Metadata Indexes enable filtering based on metadata properties when querying vectors.
+ * Each Vectorize Index can have up to 10 metadata indexes.
+ *
+ * @example
+ * // First create a Vectorize Index
+ * const vectorIndex = await VectorizeIndex("documents", {
+ *   name: "documents",
+ *   config: {
+ *     dimensions: 768,
+ *     metric: "cosine"
+ *   }
+ * });
+ *
+ * // Then create a metadata index for the "category" property
+ * const categoryIndex = await VectorizeMetadataIndex("category-index", {
+ *   index: vectorIndex,
+ *   propertyName: "category",
+ *   indexType: "string"
+ * });
+ *
+ * @example
+ * // Create a metadata index for a numeric property
+ * const yearIndex = await VectorizeMetadataIndex("year-index", {
+ *   index: vectorIndex,
+ *   propertyName: "year",
+ *   indexType: "number"
+ * });
+ *
+ * @see https://developers.cloudflare.com/vectorize/
+ */
+export const VectorizeMetadataIndex = Resource(
+  "cloudflare::VectorizeMetadataIndex",
+  async function (
+    this: Context<VectorizeMetadataIndex>,
+    id: string,
+    props: VectorizeMetadataIndexProps
+  ): Promise<VectorizeMetadataIndex> {
+    const api = await createCloudflareApi(props);
+    const indexName = props.index.name;
+    const propertyName = props.propertyName;
+
+    if (this.phase === "delete") {
+      // Delete metadata index
+      try {
+        await deleteMetadataIndex(api, indexName, propertyName);
+      } catch (error) {
+        if (
+          error instanceof CloudflareApiError &&
+          error.status === 400 &&
+          error.message.includes("does not exist")
+        ) {
+          // Index doesn't exist, which is what we want
+        } else {
+          throw error;
+        }
+      }
+      return this.destroy();
+    } else if (this.phase === "update") {
+      // Update operation is not supported
+      throw new Error(
+        "Updating Vectorize metadata indexes is not supported by the Cloudflare API. " +
+          "To change a metadata index, delete it and create a new one with the desired configuration."
+      );
+    } else {
+      const indexData = await createMetadataIndex(api, indexName, props);
+
+      return this({
+        id: propertyName, // Use propertyName as ID
+        index: props.index,
+        propertyName: props.propertyName,
+        indexType: props.indexType,
+        accountId: api.accountId,
+        mutationId: indexData.result.mutationId,
+      });
+    }
+  }
+);
+
+interface CloudflareMetadataIndexResponse {
+  result: {
+    mutationId: string;
+  };
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+}
+
+interface CloudflareMetadataIndexListResponse {
+  result: {
+    metadataIndexes: Array<{
+      propertyName: string;
+      indexType: "string" | "number" | "boolean";
+    }>;
+  };
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+}
+
+/**
+ * Create a new Vectorize metadata index
+ */
+export async function createMetadataIndex(
+  api: CloudflareApi,
+  indexName: string,
+  props: VectorizeMetadataIndexProps
+): Promise<CloudflareMetadataIndexResponse> {
+  // Create new metadata index
+  const createPayload = {
+    propertyName: props.propertyName,
+    indexType: props.indexType,
+  };
+
+  const createResponse = await api.post(
+    `/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}/metadata_index/create`,
+    createPayload
+  );
+
+  if (!createResponse.ok) {
+    return await handleApiError(
+      createResponse,
+      "creating",
+      "Vectorize metadata index",
+      props.propertyName
+    );
+  }
+
+  return (await createResponse.json()) as CloudflareMetadataIndexResponse;
+}
+
+/**
+ * Delete a Vectorize metadata index
+ */
+export async function deleteMetadataIndex(
+  api: CloudflareApi,
+  indexName: string,
+  propertyName: string
+): Promise<void> {
+  const deleteResponse = await api.post(
+    `/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}/metadata_index/delete`,
+    {
+      propertyName,
+    }
+  );
+
+  if (!deleteResponse.ok) {
+    await handleApiError(
+      deleteResponse,
+      "deleting",
+      "Vectorize metadata index",
+      propertyName
+    );
+  }
+}
+
+/**
+ * List all metadata indexes for a Vectorize index
+ */
+export async function listMetadataIndexes(
+  api: CloudflareApi,
+  indexName: string
+): Promise<
+  { propertyName: string; indexType: "string" | "number" | "boolean" }[]
+> {
+  const response = await api.get(
+    `/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}/metadata_index/list`
+  );
+
+  if (response.status === 410) {
+    // Gone
+    return [];
+  }
+
+  if (!response.ok) {
+    throw new CloudflareApiError(
+      `Failed to list metadata indexes: ${response.statusText}`,
+      response
+    );
+  }
+
+  const data = (await response.json()) as CloudflareMetadataIndexListResponse;
+
+  if (!data.success) {
+    const errorMessage = data.errors?.[0]?.message || "Unknown error";
+    throw new Error(`Failed to list metadata indexes: ${errorMessage}`);
+  }
+
+  return data.result.metadataIndexes;
+}

package/src/cloudflare/vite-site.ts

@@ -0,0 +1,111 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { alchemy } from "../alchemy";
+import { Exec } from "../os";
+import { Assets } from "./assets";
+import type { Bindings } from "./bindings";
+import { Worker } from "./worker";
+import { WranglerJson } from "./wrangler.json";
+
+export interface ViteSiteProps<B extends Bindings> {
+  /**
+   * The command to run to build the site
+   */
+  command: string;
+  /**
+   * The name of the worker
+   *
+   * @default id
+   */
+  name?: string;
+  /**
+   * The entrypoint to your server
+   *
+   * @default - a simple server that serves static assets is generated
+   */
+  main?: string;
+  /**
+   * The directory containing your static assets
+   */
+  assets: string;
+  /**
+   * The bindings to pass to the worker
+   */
+  bindings?: B;
+  /**
+   * @default process.cwd()
+   */
+  cwd?: string;
+}
+
+export type ViteSite<B extends Bindings> = Promise<
+  // don't allow the ASSETS to be overriden
+  B extends { ASSETS: any } ? never : Worker<B & { ASSETS: Assets }>
+>;
+
+export async function ViteSite<B extends Bindings>(
+  id: string,
+  props: ViteSiteProps<B>
+): ViteSite<B> {
+  if (props.bindings?.ASSETS) {
+    throw new Error("ASSETS binding is reserved for internal use");
+  }
+
+  // @ts-ignore - we know the types are correct
+  return await alchemy.run(id, async () => {
+    // Create minimal wrangler.jsonc if it doesn't exist
+
+    // `building the site requires a wrangler.jsonc file to start - so initialize an empty one if it doesn't exist`
+    const cwd = props.cwd || process.cwd();
+    const wranglerPath = path.join(cwd, "wrangler.jsonc");
+    try {
+      await fs.access(wranglerPath);
+    } catch {
+      await fs.writeFile(
+        wranglerPath,
+        JSON.stringify(
+          {
+            name: id,
+            main: props.main,
+            compatibility_date: new Date().toISOString().split("T")[0],
+          },
+          null,
+          2
+        )
+      );
+    }
+
+    await Exec("build", {
+      command: props.command,
+    });
+
+    const staticAssets = await Assets("assets", {
+      path: "./dist",
+    });
+
+    const worker = await Worker("worker", {
+      name: props.name ?? id,
+      entrypoint: props.main,
+      script: props.main
+        ? undefined
+        : `
+export default {
+  async fetch(request, env) {
+    return env.ASSETS.fetch(request);
+  },
+};`,
+      url: true,
+      adopt: true,
+      bindings: {
+        ...props.bindings,
+        ASSETS: staticAssets,
+      },
+    });
+
+    await WranglerJson("wrangler.jsonc", {
+      worker,
+    });
+
+    return worker;
+  });
+}

package/src/cloudflare/worker.ts

@@ -611,6 +611,12 @@ async function prepareWorkerMetadata<B extends Bindings>(
         name: bindingName,
         pipeline: binding.name,
       });
+    } else if (binding.type === "vectorize") {
+      meta.bindings.push({
+        type: "vectorize",
+        name: bindingName,
+        index_name: binding.name,
+      });
     } else {
       // @ts-expect-error - we should never reach here
       throw new Error(`Unsupported binding type: ${binding.type}`);

package/src/cloudflare/wrangler.json.ts

@@ -55,7 +55,7 @@ export const WranglerJson = Resource(
     props: WranglerJsonProps
   ): Promise<WranglerJson> {
     // Default path is wrangler.json in current directory
-    const filePath = props.path || "wrangler.json";
+    const filePath = props.path || "wrangler.jsonc";
 
     if (this.phase === "delete") {
       return this.destroy();
@@ -187,6 +187,14 @@ export interface WranglerJsonSpec {
     class_name: string;
   }[];
 
+  /**
+   * Vectorize index bindings
+   */
+  vectorize_indexes?: {
+    binding: string;
+    index_name: string;
+  }[];
+
   /**
    * Plain text bindings (vars)
    */
@@ -239,6 +247,7 @@ function processBindings(spec: WranglerJsonSpec, bindings: Bindings): void {
     database_name: string;
   }[] = [];
   const queues: { binding: string; queue: string }[] = [];
+  const vectorizeIndexes: { binding: string; index_name: string }[] = [];
 
   // Process each binding
   for (const [bindingName, binding] of Object.entries(bindings)) {
@@ -302,6 +311,11 @@ function processBindings(spec: WranglerJsonSpec, bindings: Bindings): void {
         binding: bindingName,
         queue: binding.name,
       });
+    } else if (binding.type === "vectorize") {
+      vectorizeIndexes.push({
+        binding: bindingName,
+        index_name: binding.name,
+      });
     }
   }
 
@@ -327,4 +341,8 @@ function processBindings(spec: WranglerJsonSpec, bindings: Bindings): void {
   if (queues.length > 0) {
     spec.queues = queues;
   }
+
+  if (vectorizeIndexes.length > 0) {
+    spec.vectorize_indexes = vectorizeIndexes;
+  }
 }

package/src/destroy.ts

@@ -39,7 +39,7 @@ export async function destroy<Type extends string>(
         ...orphan.output,
         Scope: scope,
       })),
-      options,
+      options
     );
     // finally, destroy the scope container
     await scope.deinit();
@@ -52,10 +52,19 @@ export async function destroy<Type extends string>(
     return;
   }
 
+  if (instance.Kind === "alchemy::Scope") {
+    const scope = new Scope({
+      parent: instance.Scope,
+      scopeName: instance.ID,
+    });
+    console.log("Destroying scope", scope.chain.join("/"));
+    return await destroy(scope, options);
+  }
+
   const Provider: Provider<Type> | undefined = PROVIDERS.get(instance.Kind);
   if (!Provider) {
     throw new Error(
-      `Cannot destroy resource "${instance.FQN}" type ${instance.Kind} - no provider found. You may need to import the provider in your alchemy.config.ts.`,
+      `Cannot destroy resource "${instance.FQN}" type ${instance.Kind} - no provider found. You may need to import the provider in your alchemy.config.ts.`
     );
   }
 
@@ -93,10 +102,18 @@ export async function destroy<Type extends string>(
     let nestedScope: Scope | undefined;
     try {
       // BUG: this does not restore persisted scope
-      await alchemy.run(instance.ID, async (scope) => {
-        nestedScope = scope;
-        return await Provider.handler.bind(ctx)(instance.ID, state.props);
-      });
+      await alchemy.run(
+        instance.ID,
+        {
+          // TODO(sam): this is an awful hack to differentiate between naked scopes and resources
+          isResource: instance.Kind !== "alchemy::Scope",
+          parent: scope,
+        },
+        async (scope) => {
+          nestedScope = scope;
+          return await Provider.handler.bind(ctx)(instance.ID, state.props);
+        }
+      );
     } catch (err) {
       if (err instanceof DestroyedSignal) {
         // TODO: should we fail if the DestroyedSignal is not thrown?
@@ -125,11 +142,11 @@ export namespace destroy {
     if (options?.strategy !== "parallel") {
       const sorted = resources.sort((a, b) => b.Seq - a.Seq);
       for (const resource of sorted) {
-        await destroy(resource);
+        await destroy(resource, options);
       }
     } else {
       await Promise.all(
-        resources.map((resource) => destroy(resource, options)),
+        resources.map((resource) => destroy(resource, options))
       );
     }
   }

package/src/fs/file-system-state-store.ts

@@ -1,4 +1,4 @@
-import fs from "node:fs/promises";
+import fs from "node:fs";
 import path from "node:path";
 import type { Scope } from "../scope";
 import { deserialize, serialize } from "../serde";
@@ -9,17 +9,21 @@ const stateRootDir = path.join(process.cwd(), ".alchemy");
 
 export class FileSystemStateStore implements StateStore {
   public readonly dir: string;
+  private initialized = false;
   constructor(public readonly scope: Scope) {
     this.dir = path.join(stateRootDir, ...scope.chain);
   }
 
   async init(): Promise<void> {
-    await fs.mkdir(stateRootDir, { recursive: true });
-    await fs.mkdir(this.dir, { recursive: true });
+    if (this.initialized) {
+      return;
+    }
+    this.initialized = true;
+    await fs.promises.mkdir(this.dir, { recursive: true });
   }
 
   async deinit(): Promise<void> {
-    await ignore("ENOENT", () => fs.rmdir(this.dir));
+    await ignore("ENOENT", () => fs.promises.rmdir(this.dir));
   }
 
   async count(): Promise<number> {
@@ -28,7 +32,7 @@ export class FileSystemStateStore implements StateStore {
 
   async list(): Promise<string[]> {
     try {
-      const files = await fs.readdir(this.dir, {
+      const files = await fs.promises.readdir(this.dir, {
         withFileTypes: true,
       });
       return files
@@ -45,7 +49,7 @@ export class FileSystemStateStore implements StateStore {
 
   async get(key: string): Promise<State | undefined> {
     try {
-      const content = await fs.readFile(await this.getPath(key), "utf8");
+      const content = await fs.promises.readFile(this.getPath(key), "utf8");
       const state = (await deserialize(
         this.scope,
         JSON.parse(content)
@@ -64,14 +68,22 @@ export class FileSystemStateStore implements StateStore {
   }
 
   async set(key: string, value: State): Promise<void> {
-    return fs.writeFile(
-      await this.getPath(key),
+    await this.init();
+    await fs.promises.writeFile(
+      this.getPath(key),
       JSON.stringify(await serialize(this.scope, value), null, 2)
     );
   }
 
   async delete(key: string): Promise<void> {
-    return fs.unlink(await this.getPath(key));
+    try {
+      return await fs.promises.unlink(this.getPath(key));
+    } catch (error: any) {
+      if (error.code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
   }
 
   async all(): Promise<Record<string, State>> {
@@ -94,16 +106,13 @@ export class FileSystemStateStore implements StateStore {
     );
   }
 
-  private async getPath(key: string): Promise<string> {
+  private getPath(key: string): string {
     if (key.includes(":")) {
       throw new Error(`ID cannot include colons: ${key}`);
     }
     if (key.includes("/")) {
       key = key.replaceAll("/", ":");
     }
-    const file = path.join(this.dir, `${key}.json`);
-    const dir = path.dirname(file);
-    await fs.mkdir(dir, { recursive: true });
-    return file;
+    return path.join(this.dir, `${key}.json`);
   }
 }

package/src/scope.ts

@@ -8,7 +8,7 @@ const scopeStorage = new AsyncLocalStorage<Scope>();
 
 export type ScopeOptions = {
   appName?: string;
-  stage: string;
+  stage?: string;
   parent?: Scope;
   scopeName?: string;
   password?: string;
@@ -16,6 +16,9 @@ export type ScopeOptions = {
   quiet?: boolean;
 };
 
+// TODO: support browser
+const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
+
 export class Scope {
   public static get(): Scope | undefined {
     return scopeStorage.getStore();
@@ -42,14 +45,14 @@ export class Scope {
 
   constructor(options: ScopeOptions) {
     this.appName = options.appName;
-    this.stage = options.stage;
+    this.stage = options?.stage ?? DEFAULT_STAGE;
     this.scopeName = options.scopeName ?? null;
     this.parent = options.parent ?? Scope.get();
     this.quiet = options.quiet ?? this.parent?.quiet ?? false;
     if (this.parent && !this.scopeName) {
       throw new Error("Scope name is required when creating a child scope");
     }
-    this.password = options.password;
+    this.password = options.password ?? this.parent?.password;
     this.state = options.stateStore
       ? options.stateStore(this)
       : new FileSystemStateStore(this);
@@ -90,6 +93,7 @@ export class Scope {
   }
 
   public async deinit() {
+    await this.parent?.state.delete(this.scopeName!);
     await this.state.deinit?.();
   }
 
@@ -111,10 +115,10 @@ export class Scope {
       const resourceIds = await this.state.list();
       const aliveIds = new Set(this.resources.keys());
       const orphanIds = Array.from(
-        resourceIds.filter((id) => !aliveIds.has(id)),
+        resourceIds.filter((id) => !aliveIds.has(id))
       );
       const orphans = await Promise.all(
-        orphanIds.map(async (id) => (await this.state.get(id))!.output),
+        orphanIds.map(async (id) => (await this.state.get(id))!.output)
       );
       await destroy.all(orphans, {
         quiet: this.quiet,

package/src/state.ts

@@ -1,11 +1,11 @@
 import type { Resource, ResourceProps } from "./resource";
 import type { Scope } from "./scope";
 
-export interface State<
+export type State<
   Kind extends string = string,
   Props extends ResourceProps | undefined = ResourceProps | undefined,
   Out extends Resource = Resource,
-> {
+> = {
   status:
     | `creating`
     | `created`
@@ -22,7 +22,7 @@ export interface State<
   props: Props;
   oldProps?: Props;
   output: Out;
-}
+};
 
 export type StateStoreType = (scope: Scope) => StateStore;