alchemy 0.8.0 → 0.8.1

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,8 @@ 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 "./worker";
 export { Workflow } from "./workflow";
 export * from "./wrangler.json";

package/lib/cloudflare/index.js

@@ -13,6 +13,8 @@ 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 "./worker";
 export { Workflow } from "./workflow";
 export * from "./wrangler.json";

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 {};

package/lib/cloudflare/vectorize-metadata-index.js

@@ -0,0 +1,120 @@
+import { Resource } from "../resource";
+import { CloudflareApi, createCloudflareApi, } from "./api";
+import { CloudflareApiError, handleApiError } from "./api-error";
+import { VectorizeIndex } from "./vectorize-index";
+/**
+ * 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 (id, props) {
+    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,
+        });
+    }
+});
+/**
+ * Create a new Vectorize metadata index
+ */
+export async function createMetadataIndex(api, indexName, props) {
+    // 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());
+}
+/**
+ * Delete a Vectorize metadata index
+ */
+export async function deleteMetadataIndex(api, indexName, propertyName) {
+    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, indexName) {
+    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());
+    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/lib/cloudflare/worker.js

@@ -353,6 +353,13 @@ async function prepareWorkerMetadata(ctx, oldBindings, props, assetUploadResult)
                 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/lib/cloudflare/wrangler.json.d.ts

@@ -114,6 +114,13 @@ export interface WranglerJsonSpec {
         binding: string;
         class_name: string;
     }[];
+    /**
+     * Vectorize index bindings
+     */
+    vectorize_indexes?: {
+        binding: string;
+        index_name: string;
+    }[];
     /**
      * Plain text bindings (vars)
      */

package/lib/cloudflare/wrangler.json.js

@@ -50,6 +50,7 @@ function processBindings(spec, bindings) {
     const workflows = [];
     const d1Databases = [];
     const queues = [];
+    const vectorizeIndexes = [];
     // Process each binding
     for (const [bindingName, binding] of Object.entries(bindings)) {
         if (typeof binding === "string") {
@@ -120,6 +121,12 @@ function processBindings(spec, bindings) {
                 queue: binding.name,
             });
         }
+        else if (binding.type === "vectorize") {
+            vectorizeIndexes.push({
+                binding: bindingName,
+                index_name: binding.name,
+            });
+        }
     }
     // Add collected bindings to the spec
     if (kvNamespaces.length > 0) {
@@ -139,4 +146,7 @@ function processBindings(spec, bindings) {
     if (queues.length > 0) {
         spec.queues = queues;
     }
+    if (vectorizeIndexes.length > 0) {
+        spec.vectorize_indexes = vectorizeIndexes;
+    }
 }

package/lib/test/bun.js

@@ -79,6 +79,9 @@ export function test(meta, defaultOptions) {
     function test(...args) {
         const testName = args[0];
         const _options = typeof args[1] === "object" ? args[1] : undefined;
+        const timeout = typeof args[args.length - 1] === "number"
+            ? args[args.length - 1]
+            : 120000;
         const spread = (obj) => obj && typeof obj === "object"
             ? Object.fromEntries(Object.entries(obj).flatMap(([k, v]) => v !== undefined ? [[k, v]] : []))
             : {};
@@ -110,7 +113,7 @@ export function test(meta, defaultOptions) {
                         await destroy(scope);
                     }
                 }
-            });
+            }, timeout);
         });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "type": "module",
   "module": "./lib/index.js",
   "scripts": {

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}`;