alchemy 0.8.0 → 0.9.0

package/src/alchemy.ts

@@ -1,14 +1,12 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { DestroyedSignal, destroy } from "./destroy";
+import { destroy, DestroyedSignal } from "./destroy";
+import type { PendingResource } from "./resource";
 import { Scope } from "./scope";
 import { secret } from "./secret";
 import type { StateStoreType } from "./state";
 
-// TODO: support browser
-const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
-
 /**
  * Type alias for semantic highlighting of `alchemy` as a type keyword
  */
@@ -37,7 +35,6 @@ export const alchemy: Alchemy = _alchemy as any;
  * await app.finalize();
  */
 export interface Alchemy {
-  scope: typeof scope;
   run: typeof run;
   destroy: typeof destroy;
 
@@ -63,7 +60,7 @@ export interface Alchemy {
    *   password: process.env.SECRET_PASSPHRASE
    * });
    */
-  (...parameters: Parameters<typeof scope>): Promise<Scope>;
+  (appName: string, options?: Omit<AlchemyOptions, "appName">): Promise<Scope>;
   /**
    * Template literal tag that supports file interpolation for documentation.
    * Automatically formats the content and appends file contents as code blocks.
@@ -95,11 +92,12 @@ async function _alchemy(
 ): Promise<Scope | string | never> {
   if (typeof args[0] === "string") {
     const [appName, options] = args as [string, AlchemyOptions?];
-    const root = scope(undefined, {
+    const root = new Scope({
       ...options,
       appName,
       stage: options?.stage,
     });
+    root.enter();
     if (options?.phase === "destroy") {
       await destroy(root);
       return process.exit(0);
@@ -215,7 +213,6 @@ async function _alchemy(
 }
 _alchemy.destroy = destroy;
 _alchemy.run = run;
-_alchemy.scope = scope;
 _alchemy.secret = secret;
 _alchemy.env = env;
 
@@ -256,7 +253,6 @@ export interface AlchemyOptions {
    * @default false
    */
   quiet?: boolean;
-
   /**
    * A passphrase to use to encrypt/decrypt secrets.
    * Required if using alchemy.secret() in this scope.
@@ -264,35 +260,16 @@ export interface AlchemyOptions {
   password?: string;
 }
 
-/**
- * Enter a new scope synchronously.
- *
- * @example
- * // Create a scope with a password for secret handling
- * await using scope = alchemy.scope("my-scope", {
- *   password: process.env.SECRET_PASSPHRASE
- * });
- *
- * // Use secrets within the scope
- * const resource = await Resource("my-resource", {
- *   apiKey: alchemy.secret(process.env.API_KEY)
- * });
- */
-function scope(
-  id: string | undefined,
-  options?: AlchemyOptions
-  // TODO: maybe we want to allow using _ = await alchemy.scope(import.meta)
-  // | [meta: ImportMeta]
-): Scope {
-  const scope = new Scope({
-    ...options,
-    appName: options?.appName,
-    stage: options?.stage ?? DEFAULT_STAGE,
-    scopeName: id,
-    parent: options?.parent ?? Scope.get(),
-  });
-  scope.enter();
-  return scope;
+export interface ScopeOptions extends AlchemyOptions {
+  enter: boolean;
+}
+
+export interface RunOptions extends AlchemyOptions {
+  /**
+   * @default false
+   */
+  // TODO(sam): this is an awful hack to differentiate between naked scopes and resources
+  isResource?: boolean;
 }
 
 /**
@@ -315,7 +292,7 @@ async function run<T>(
     | [id: string, fn: (this: Scope, scope: Scope) => Promise<T>]
     | [
         id: string,
-        options: AlchemyOptions,
+        options: RunOptions,
         fn: (this: Scope, scope: Scope) => Promise<T>,
       ]
 ): Promise<T> {
@@ -324,20 +301,49 @@ async function run<T>(
       ? [args[0], undefined, args[1]]
       : (args as [
           string,
-          AlchemyOptions | undefined,
+          RunOptions,
           (this: Scope, scope: Scope) => Promise<T>,
         ]);
-  const scope = alchemy.scope(id, options);
+  const _scope = new Scope({
+    ...options,
+    scopeName: id,
+  });
   try {
-    return await fn.bind(scope)(scope);
+    if (options?.isResource !== true && _scope.parent) {
+      // TODO(sam): this is an awful hack to differentiate between naked scopes and resources
+      const seq = _scope.parent.seq();
+      const output = {
+        ID: id,
+        FQN: "",
+        Kind: "alchemy::Scope",
+        Scope: _scope,
+        Seq: seq,
+      } as const;
+      const resource = {
+        kind: "scope",
+        id,
+        seq,
+        data: {},
+        fqn: "",
+        props: {},
+        status: "created",
+        output,
+      } as const;
+      await _scope.parent!.state.set(id, resource);
+      _scope.parent!.resources.set(
+        id,
+        Object.assign(Promise.resolve(resource), output) as PendingResource
+      );
+    }
+    return await _scope.run(async () => fn.bind(_scope)(_scope));
   } catch (error) {
     if (!(error instanceof DestroyedSignal)) {
-      scope.fail();
-    } else {
+      console.log(error);
+      _scope.fail();
     }
     throw error;
   } finally {
-    await scope.finalize();
+    await _scope.finalize();
   }
 }
 

package/src/apply.ts

@@ -107,8 +107,12 @@ export async function apply<Out extends Resource>(
       },
     });
 
-    const output = await alchemy.run(resource.ID, async () =>
-      provider.handler.bind(ctx)(resource.ID, props)
+    const output = await alchemy.run(
+      resource.ID,
+      {
+        isResource: true,
+      },
+      async () => provider.handler.bind(ctx)(resource.ID, props)
     );
     if (!quiet) {
       console.log(

package/src/cloudflare/api-error.ts

@@ -49,7 +49,7 @@ export async function handleApiError(
   resourceName: string
 ): Promise<never> {
   const json: any = await response.json();
-  const errors: { message: string }[] = json.errors || [
+  const errors: { message: string }[] = json?.errors || [
     { message: response.statusText },
   ];
   const errorMessage = `Error ${action} ${resourceType} '${resourceName}': ${errors[0]?.message || response.statusText}`;

package/src/cloudflare/bindings.ts

@@ -11,6 +11,7 @@ import type { DurableObjectNamespace } from "./durable-object-namespace";
 import type { KVNamespace } from "./kv-namespace";
 import type { Pipeline } from "./pipeline";
 import type { Queue } from "./queue";
+import type { VectorizeIndex } from "./vectorize-index";
 import type { Worker } from "./worker";
 import type { Workflow } from "./workflow";
 
@@ -31,6 +32,7 @@ export type Binding =
   | R2Bucket
   | Secret
   | string
+  | VectorizeIndex
   | Worker
   | Workflow;
 

package/src/cloudflare/bound.ts

@@ -8,6 +8,7 @@ import type { DurableObjectNamespace as _DurableObjectNamespace } from "./durabl
 import type { KVNamespace as _KVNamespace } from "./kv-namespace";
 import type { Pipeline as _Pipeline } from "./pipeline";
 import type { Queue as _Queue } from "./queue";
+import type { VectorizeIndex as _VectorizeIndex } from "./vectorize-index";
 import type { Worker as _Worker } from "./worker";
 import type { Workflow as _Workflow } from "./workflow";
 
@@ -27,8 +28,10 @@ export type Bound<T extends Binding> = T extends _DurableObjectNamespace
               ? Workflow<P>
               : T extends _D1Database
                 ? D1Database
-                : T extends _Queue
-                  ? Queue
-                  : T extends _Pipeline<infer R>
-                    ? Pipeline<R>
-                    : Service;
+                : T extends _VectorizeIndex
+                  ? VectorizeIndex
+                  : T extends _Queue
+                    ? Queue
+                    : T extends _Pipeline<infer R>
+                      ? Pipeline<R>
+                      : Service;

package/src/cloudflare/index.ts

@@ -13,6 +13,9 @@ export * from "./permission-groups";
 export * from "./pipeline";
 export * from "./queue";
 export * from "./r2-rest-state-store";
+export * from "./vectorize-index";
+export * from "./vectorize-metadata-index";
+export * from "./vite-site";
 export * from "./worker";
 export { Workflow } from "./workflow";
 export * from "./wrangler.json";

package/src/cloudflare/pipeline.ts

@@ -318,7 +318,6 @@ export const Pipeline = Resource("cloudflare::Pipeline", async function <
   const pipelineName = props.name || id;
 
   if (this.phase === "delete") {
-    console.log("Deleting Cloudflare Pipeline:", pipelineName);
     if (props.delete !== false) {
       // Delete Pipeline
       await deletePipeline(api, pipelineName);
@@ -330,13 +329,10 @@ export const Pipeline = Resource("cloudflare::Pipeline", async function <
     let pipelineData: CloudflarePipelineResponse;
 
     if (this.phase === "create") {
-      console.log("Creating Cloudflare Pipeline:", pipelineName);
       pipelineData = await createPipeline(api, pipelineName, props);
     } else {
       // Update operation
       if (this.output?.id) {
-        console.log("Updating Cloudflare Pipeline:", pipelineName);
-
         // Check if name is being changed, which is not allowed
         if (props.name !== this.output.name) {
           throw new Error(

package/src/cloudflare/vectorize-index.ts

@@ -0,0 +1,331 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import {
+  CloudflareApi,
+  createCloudflareApi,
+  type CloudflareApiOptions,
+} from "./api";
+import { CloudflareApiError, handleApiError } from "./api-error";
+
+/**
+ * Properties for creating or updating a Vectorize Index
+ */
+export interface VectorizeIndexProps extends CloudflareApiOptions {
+  /**
+   * Name of the index
+   */
+  name: string;
+
+  /**
+   * Optional description of the index
+   */
+  description?: string;
+
+  /**
+   * Dimensions of the vectors
+   */
+  dimensions: number;
+
+  /**
+   * Distance metric used for vector similarity
+   */
+  metric: "cosine" | "euclidean" | "dot_product";
+
+  /**
+   * Whether to delete the index if removed
+   * If set to false, the index will remain but the resource will be removed from state
+   *
+   * @default true
+   */
+  delete?: boolean;
+
+  /**
+   * Whether to adopt an existing index with the same name if it exists
+   * If true and an index with the same name exists, it will be adopted rather than creating a new one
+   *
+   * @default false
+   */
+  adopt?: boolean;
+}
+
+/**
+ * Output returned after Vectorize Index creation/update
+ */
+export interface VectorizeIndex
+  extends Resource<"cloudflare::VectorizeIndex">,
+    VectorizeIndexProps {
+  type: "vectorize";
+
+  /**
+   * The unique identifier for the index (same as name)
+   */
+  id: string;
+
+  /**
+   * Time at which the index was created
+   */
+  createdAt?: number;
+}
+
+/**
+ * Creates and manages Cloudflare Vectorize Indexes.
+ *
+ * Vectorize is Cloudflare's vector database that enables vector search within Cloudflare Workers.
+ *
+ * @example
+ * // Create a basic vector index for text embeddings
+ * const basicIndex = await VectorizeIndex("text-embeddings", {
+ *   name: "text-embeddings",
+ *   config: {
+ *     dimensions: 768,
+ *     metric: "cosine"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a vector index with a description
+ * const descIndex = await VectorizeIndex("image-embeddings", {
+ *   name: "image-embeddings",
+ *   description: "Vector index for image embeddings using CLIP model",
+ *   config: {
+ *     dimensions: 512,
+ *     metric: "cosine"
+ *   }
+ * });
+ *
+ * @example
+ * // Adopt an existing index if it already exists instead of failing
+ * const existingIndex = await VectorizeIndex("existing-index", {
+ *   name: "existing-index",
+ *   adopt: true,
+ *   config: {
+ *     dimensions: 1024,
+ *     metric: "euclidean"
+ *   }
+ * });
+ *
+ * @see https://developers.cloudflare.com/vectorize/
+ */
+export const VectorizeIndex = Resource(
+  "cloudflare::VectorizeIndex",
+  async function (
+    this: Context<VectorizeIndex>,
+    id: string,
+    props: VectorizeIndexProps
+  ): Promise<VectorizeIndex> {
+    const api = await createCloudflareApi(props);
+    const indexName = props.name || id;
+
+    if (this.phase === "delete") {
+      console.log("Deleting Vectorize index:", indexName);
+      if (props.delete !== false) {
+        // Delete Vectorize index
+        await deleteIndex(api, indexName);
+      }
+
+      // Return void (a deleted index has no content)
+      return this.destroy();
+    } else {
+      let indexData: CloudflareVectorizeResponse;
+
+      if (this.phase === "create") {
+        console.log("Creating Vectorize index:", indexName);
+        try {
+          indexData = await createIndex(api, indexName, {
+            ...props,
+            name: indexName,
+          });
+        } catch (error) {
+          // Check if this is a "index already exists" error and adopt is enabled
+          if (
+            props.adopt &&
+            error instanceof CloudflareApiError &&
+            error.message.includes("already exists")
+          ) {
+            console.log(`Index ${indexName} already exists, adopting it`);
+            // Find the existing index
+            indexData = await getIndex(api, indexName);
+          } else {
+            // Re-throw the error if adopt is false or it's not a "index already exists" error
+            throw error;
+          }
+        }
+      } else {
+        // Update operation is not supported by Vectorize API
+        throw new Error(
+          "Updating Vectorize indexes is not supported by the Cloudflare API. " +
+            "To change an index, delete it and create a new one with the desired configuration."
+        );
+      }
+
+      return this({
+        type: "vectorize",
+        id: indexName,
+        name: indexName,
+        description: props.description,
+        dimensions: indexData.result.config.dimensions,
+        metric: indexData.result.config.metric as
+          | "cosine"
+          | "euclidean"
+          | "dot_product",
+        accountId: api.accountId,
+        createdAt: indexData.result.created_on
+          ? new Date(indexData.result.created_on).getTime()
+          : undefined,
+      });
+    }
+  }
+);
+
+interface CloudflareVectorizeResponse {
+  result: {
+    name: string;
+    description?: string;
+    created_on?: string;
+    config: {
+      dimensions: number;
+      metric: string;
+    };
+  };
+  success: boolean;
+  errors: Array<{ code: number; message: string }>;
+  messages: string[];
+}
+
+/**
+ * Create a new Vectorize index
+ */
+export async function createIndex(
+  api: CloudflareApi,
+  indexName: string,
+  props: VectorizeIndexProps
+): Promise<CloudflareVectorizeResponse> {
+  // Create new Vectorize index
+  const createPayload: any = {
+    name: indexName,
+    config: {
+      dimensions: props.dimensions,
+      metric: props.metric,
+    },
+  };
+
+  if (props.description) {
+    createPayload.description = props.description;
+  }
+
+  const createResponse = await api.post(
+    `/accounts/${api.accountId}/vectorize/v2/indexes`,
+    createPayload
+  );
+
+  if (!createResponse.ok) {
+    return await handleApiError(
+      createResponse,
+      "creating",
+      "Vectorize index",
+      indexName
+    );
+  }
+
+  return (await createResponse.json()) as CloudflareVectorizeResponse;
+}
+
+/**
+ * Get a Vectorize index
+ */
+export async function getIndex(
+  api: CloudflareApi,
+  indexName: string
+): Promise<CloudflareVectorizeResponse> {
+  const response = await api.get(
+    `/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}`
+  );
+
+  if (!response.ok) {
+    return await handleApiError(
+      response,
+      "getting",
+      "Vectorize index",
+      indexName
+    );
+  }
+
+  return (await response.json()) as CloudflareVectorizeResponse;
+}
+
+/**
+ * Delete a Vectorize index
+ */
+export async function deleteIndex(
+  api: CloudflareApi,
+  indexName: string
+): Promise<void> {
+  // Delete Vectorize index
+  const deleteResponse = await api.delete(
+    `/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}`
+  );
+
+  if (!deleteResponse.ok && deleteResponse.status !== 404) {
+    const errorData: any = await deleteResponse.json().catch(() => ({
+      errors: [{ message: deleteResponse.statusText }],
+    }));
+    throw new CloudflareApiError(
+      `Error deleting Vectorize index '${indexName}': ${errorData.errors?.[0]?.message || deleteResponse.statusText}`,
+      deleteResponse
+    );
+  }
+}
+
+/**
+ * List all Vectorize indexes in an account
+ */
+export async function listIndexes(
+  api: CloudflareApi
+): Promise<{ name: string; description?: string }[]> {
+  const response = await api.get(
+    `/accounts/${api.accountId}/vectorize/v2/indexes`
+  );
+
+  if (!response.ok) {
+    throw new CloudflareApiError(
+      `Failed to list indexes: ${response.statusText}`,
+      response
+    );
+  }
+
+  const data = (await response.json()) as {
+    success: boolean;
+    errors?: Array<{ code: number; message: string }>;
+    result?: Array<{
+      name: string;
+      description?: string;
+    }>;
+  };
+
+  if (!data.success) {
+    const errorMessage = data.errors?.[0]?.message || "Unknown error";
+    throw new Error(`Failed to list indexes: ${errorMessage}`);
+  }
+
+  // Transform API response
+  return (data.result || []).map((index) => ({
+    name: index.name,
+    description: index.description,
+  }));
+}
+
+/**
+ * Update a Vectorize index
+ *
+ * Note: The Cloudflare Vectorize API does not support updating indexes.
+ * This function will always throw an error.
+ */
+export async function updateIndex(
+  api: CloudflareApi,
+  indexName: string,
+  props: VectorizeIndexProps
+): Promise<CloudflareVectorizeResponse> {
+  throw new Error(
+    "Updating Vectorize indexes is not supported by the Cloudflare API. To change an index, delete it and create a new one."
+  );
+}