alchemy 0.8.0 → 0.9.0

package/lib/alchemy.d.ts

@@ -28,7 +28,6 @@ export declare const alchemy: Alchemy;
  * await app.finalize();
  */
 export interface Alchemy {
-    scope: typeof scope;
     run: typeof run;
     destroy: typeof destroy;
     /**
@@ -52,7 +51,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.
@@ -115,21 +114,15 @@ 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)
- * });
- */
-declare function scope(id: string | undefined, options?: AlchemyOptions): Scope;
+export interface ScopeOptions extends AlchemyOptions {
+    enter: boolean;
+}
+export interface RunOptions extends AlchemyOptions {
+    /**
+     * @default false
+     */
+    isResource?: boolean;
+}
 /**
  * Run a function in a new scope asynchronously.
  * Useful for isolating secret handling with a specific password.
@@ -147,7 +140,7 @@ declare function scope(id: string | undefined, options?: AlchemyOptions): Scope;
  */
 declare function run<T>(...args: [id: string, fn: (this: Scope, scope: Scope) => Promise<T>] | [
     id: string,
-    options: AlchemyOptions,
+    options: RunOptions,
     fn: (this: Scope, scope: Scope) => Promise<T>
 ]): Promise<T>;
 export declare function env<T = string>(name: string, value?: T | undefined, error?: string): Promise<T>;

package/lib/alchemy.js

@@ -1,10 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { DestroyedSignal, destroy } from "./destroy";
+import { destroy, DestroyedSignal } from "./destroy";
 import { Scope } from "./scope";
 import { secret } from "./secret";
-// TODO: support browser
-const DEFAULT_STAGE = process.env.ALCHEMY_STAGE ?? process.env.USER ?? "dev";
 export const alchemy = _alchemy;
 /**
  * Implementation of the alchemy function that handles both application scoping
@@ -13,11 +11,12 @@ export const alchemy = _alchemy;
 async function _alchemy(...args) {
     if (typeof args[0] === "string") {
         const [appName, options] = args;
-        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);
@@ -119,37 +118,8 @@ async function _alchemy(...args) {
 }
 _alchemy.destroy = destroy;
 _alchemy.run = run;
-_alchemy.scope = scope;
 _alchemy.secret = secret;
 _alchemy.env = env;
-/**
- * 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, options
-// TODO: maybe we want to allow using _ = await alchemy.scope(import.meta)
-// | [meta: ImportMeta]
-) {
-    const scope = new Scope({
-        ...options,
-        appName: options?.appName,
-        stage: options?.stage ?? DEFAULT_STAGE,
-        scopeName: id,
-        parent: options?.parent ?? Scope.get(),
-    });
-    scope.enter();
-    return scope;
-}
 /**
  * Run a function in a new scope asynchronously.
  * Useful for isolating secret handling with a specific password.
@@ -169,20 +139,45 @@ async function run(...args) {
     const [id, options, fn] = typeof args[1] === "function"
         ? [args[0], undefined, args[1]]
         : args;
-    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,
+            };
+            const resource = {
+                kind: "scope",
+                id,
+                seq,
+                data: {},
+                fqn: "",
+                props: {},
+                status: "created",
+                output,
+            };
+            await _scope.parent.state.set(id, resource);
+            _scope.parent.resources.set(id, Object.assign(Promise.resolve(resource), output));
+        }
+        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();
     }
 }
 export async function env(name, value, error) {

package/lib/apply.js

@@ -75,7 +75,9 @@ export async function apply(resource, props, options) {
                 isReplaced = true;
             },
         });
-        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(`${phase === "create" ? "Created" : "Updated"}: "${resource.FQN}"`);
         }

package/lib/cloudflare/api-error.js

@@ -39,7 +39,7 @@ export class CloudflareApiError extends Error {
  */
 export async function handleApiError(response, action, resourceType, resourceName) {
     const json = await response.json();
-    const errors = json.errors || [
+    const errors = json?.errors || [
         { message: response.statusText },
     ];
     const errorMessage = `Error ${action} ${resourceType} '${resourceName}': ${errors[0]?.message || response.statusText}`;

package/lib/cloudflare/bindings.d.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";
 export type Bindings = {
@@ -19,7 +20,7 @@ export type Bindings = {
 /**
  * L2 Binding Resources.
  */
-export type Binding = Assets | D1Database | DurableObjectNamespace | KVNamespace | Pipeline | Queue | R2Bucket | Secret | string | Worker | Workflow;
+export type Binding = Assets | D1Database | DurableObjectNamespace | KVNamespace | Pipeline | Queue | R2Bucket | Secret | string | VectorizeIndex | Worker | Workflow;
 /**
  * Union type for all Worker binding types (API spec)
  */

package/lib/cloudflare/bound.d.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";
-export type Bound<T extends Binding> = T extends _DurableObjectNamespace ? DurableObjectNamespace : T extends _KVNamespace ? KVNamespace : T extends _Worker ? Worker : T extends _R2Bucket ? R2Bucket : T extends Secret ? string : T extends Assets ? Service : T extends _Workflow<infer P> ? Workflow<P> : T extends _D1Database ? D1Database : T extends _Queue ? Queue : T extends _Pipeline<infer R> ? Pipeline<R> : Service;
+export type Bound<T extends Binding> = T extends _DurableObjectNamespace ? DurableObjectNamespace : T extends _KVNamespace ? KVNamespace : T extends _Worker ? Worker : T extends _R2Bucket ? R2Bucket : T extends Secret ? string : T extends Assets ? Service : T extends _Workflow<infer P> ? Workflow<P> : T extends _D1Database ? D1Database : T extends _VectorizeIndex ? VectorizeIndex : T extends _Queue ? Queue : T extends _Pipeline<infer R> ? Pipeline<R> : Service;

package/lib/cloudflare/index.d.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/lib/cloudflare/index.js

@@ -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/lib/cloudflare/pipeline.js

@@ -71,7 +71,6 @@ export const Pipeline = Resource("cloudflare::Pipeline", async function (id, pro
     const api = await createCloudflareApi(props);
     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);
@@ -82,13 +81,11 @@ export const Pipeline = Resource("cloudflare::Pipeline", async function (id, pro
     else {
         let pipelineData;
         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("Cannot update Pipeline name after creation. Pipeline name is immutable.");

package/lib/cloudflare/vectorize-index.d.ts

@@ -0,0 +1,136 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { CloudflareApi, type CloudflareApiOptions } from "./api";
+/**
+ * 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 declare const VectorizeIndex: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<VectorizeIndex>, id: string, props: VectorizeIndexProps) => Promise<VectorizeIndex>);
+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 declare function createIndex(api: CloudflareApi, indexName: string, props: VectorizeIndexProps): Promise<CloudflareVectorizeResponse>;
+/**
+ * Get a Vectorize index
+ */
+export declare function getIndex(api: CloudflareApi, indexName: string): Promise<CloudflareVectorizeResponse>;
+/**
+ * Delete a Vectorize index
+ */
+export declare function deleteIndex(api: CloudflareApi, indexName: string): Promise<void>;
+/**
+ * List all Vectorize indexes in an account
+ */
+export declare function listIndexes(api: CloudflareApi): Promise<{
+    name: string;
+    description?: string;
+}[]>;
+/**
+ * Update a Vectorize index
+ *
+ * Note: The Cloudflare Vectorize API does not support updating indexes.
+ * This function will always throw an error.
+ */
+export declare function updateIndex(api: CloudflareApi, indexName: string, props: VectorizeIndexProps): Promise<CloudflareVectorizeResponse>;
+export {};

package/lib/cloudflare/vectorize-index.js

@@ -0,0 +1,170 @@
+import { Resource } from "../resource";
+import { CloudflareApi, createCloudflareApi, } from "./api";
+import { CloudflareApiError, handleApiError } from "./api-error";
+/**
+ * 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 (id, props) {
+    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;
+        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,
+            accountId: api.accountId,
+            createdAt: indexData.result.created_on
+                ? new Date(indexData.result.created_on).getTime()
+                : undefined,
+        });
+    }
+});
+/**
+ * Create a new Vectorize index
+ */
+export async function createIndex(api, indexName, props) {
+    // Create new Vectorize index
+    const createPayload = {
+        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());
+}
+/**
+ * Get a Vectorize index
+ */
+export async function getIndex(api, indexName) {
+    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());
+}
+/**
+ * Delete a Vectorize index
+ */
+export async function deleteIndex(api, indexName) {
+    // Delete Vectorize index
+    const deleteResponse = await api.delete(`/accounts/${api.accountId}/vectorize/v2/indexes/${indexName}`);
+    if (!deleteResponse.ok && deleteResponse.status !== 404) {
+        const errorData = 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) {
+    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());
+    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, indexName, props) {
+    throw new Error("Updating Vectorize indexes is not supported by the Cloudflare API. To change an index, delete it and create a new one.");
+}

package/lib/cloudflare/vectorize-metadata-index.d.ts

@@ -0,0 +1,95 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import { CloudflareApi, type CloudflareApiOptions } from "./api";
+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 declare const VectorizeMetadataIndex: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<VectorizeMetadataIndex>, id: string, props: VectorizeMetadataIndexProps) => Promise<VectorizeMetadataIndex>);
+interface CloudflareMetadataIndexResponse {
+    result: {
+        mutationId: string;
+    };
+    success: boolean;
+    errors: Array<{
+        code: number;
+        message: string;
+    }>;
+    messages: string[];
+}
+/**
+ * Create a new Vectorize metadata index
+ */
+export declare function createMetadataIndex(api: CloudflareApi, indexName: string, props: VectorizeMetadataIndexProps): Promise<CloudflareMetadataIndexResponse>;
+/**
+ * Delete a Vectorize metadata index
+ */
+export declare function deleteMetadataIndex(api: CloudflareApi, indexName: string, propertyName: string): Promise<void>;
+/**
+ * List all metadata indexes for a Vectorize index
+ */
+export declare function listMetadataIndexes(api: CloudflareApi, indexName: string): Promise<{
+    propertyName: string;
+    indexType: "string" | "number" | "boolean";
+}[]>;
+export {};