@cloudflare/workers-types 4.20230904.0 → 4.20230914.0

package/experimental/index.d.ts

@@ -884,7 +884,7 @@ declare class TextDecoder {
 }
 declare class TextEncoder {
   constructor();
-  encode(input?: string): ArrayBuffer | ArrayBufferView;
+  encode(input?: string): Uint8Array;
   encodeInto(
     input: string,
     buffer: ArrayBuffer | ArrayBufferView
@@ -2951,9 +2951,6 @@ declare type ContinentCode = "AF" | "AN" | "AS" | "EU" | "NA" | "OC" | "SA";
 declare type CfProperties<HostMetadata = unknown> =
   | IncomingRequestCfProperties<HostMetadata>
   | RequestInitCfProperties;
-// Copyright (c) 2022-2023 Cloudflare, Inc.
-// Licensed under the Apache 2.0 license found in the LICENSE file or at:
-//     https://opensource.org/licenses/Apache-2.0
 declare interface D1Result<T = unknown> {
   results: T[];
   success: true;
@@ -2978,9 +2975,6 @@ declare abstract class D1PreparedStatement {
   all<T = Record<string, unknown>>(): Promise<D1Result<T>>;
   raw<T = unknown[]>(): Promise<T[]>;
 }
-// Copyright (c) 2023 Cloudflare, Inc.
-// Licensed under the Apache 2.0 license found in the LICENSE file or at:
-//     https://opensource.org/licenses/Apache-2.0
 /**
  * An email message that can be sent from a Worker.
  */
@@ -3045,9 +3039,53 @@ declare module "cloudflare:email" {
   };
   export { _EmailMessage as EmailMessage };
 }
-// Copyright (c) 2022-2023 Cloudflare, Inc.
-// Licensed under the Apache 2.0 license found in the LICENSE file or at:
-//     https://opensource.org/licenses/Apache-2.0
+declare interface Hyperdrive {
+  /**
+   * Connect directly to Hyperdrive as if it's your database, returning a TCP socket.
+   *
+   * Calling this method returns an idential socket to if you call
+   * `connect("host:port")` using the `host` and `port` fields from this object.
+   * Pick whichever approach works better with your preferred DB client library.
+   *
+   * Note that this socket is not yet authenticated -- it's expected that your
+   * code (or preferably, the client library of your choice) will authenticate
+   * using the information in this class's readonly fields.
+   */
+  connect(): Socket;
+  /**
+   * A valid DB connection string that can be passed straight into the typical
+   * client library/driver/ORM. This will typically be the easiest way to use
+   * Hyperdrive.
+   */
+  readonly connectionString: string;
+  /*
+   * A randomly generated hostname that is only valid within the context of the
+   * currently running Worker which, when passed into `connect()` function from
+   * the "cloudflare:sockets" module, will connect to the Hyperdrive instance
+   * for your database.
+   */
+  readonly host: string;
+  /*
+   * The port that must be paired the the host field when connecting.
+   */
+  readonly port: string;
+  /*
+   * The username to use when authenticating to your database via Hyperdrive.
+   * Unlike the host and password, this will be the same every time
+   */
+  readonly user: string;
+  /*
+   * The randomly generated password to use when authenticating to your
+   * database via Hyperdrive. Like the host field, this password is only valid
+   * within the context of the currently running Worker instance from which
+   * it's read.
+   */
+  readonly password: string;
+  /*
+   * The name of the database to connect to.
+   */
+  readonly database: string;
+}
 declare type Params<P extends string = any> = Record<P, string | string[]>;
 declare type EventContext<Env, P extends string, Data> = {
   request: Request;
@@ -3094,13 +3132,10 @@ declare type PagesPluginFunction<
 declare module "assets:*" {
   export const onRequest: PagesFunction;
 }
-// Copyright (c) 2023 Cloudflare, Inc.
-// Licensed under the Apache 2.0 license found in the LICENSE file or at:
-//     https://opensource.org/licenses/Apache-2.0
-// https://developers.cloudflare.com/pub-sub/
 // PubSubMessage represents an incoming PubSub message.
 // The message includes metadata about the broker, the client, and the payload
 // itself.
+// https://developers.cloudflare.com/pub-sub/
 declare interface PubSubMessage {
   // Message ID
   readonly mid: number;
@@ -3131,9 +3166,6 @@ declare interface JsonWebKeyWithKid extends JsonWebKey {
   // Key Identifier of the JWK
   readonly kid: string;
 }
-// Copyright (c) 2023 Cloudflare, Inc.
-// Licensed under the Apache 2.0 license found in the LICENSE file or at:
-//     https://opensource.org/licenses/Apache-2.0
 declare module "cloudflare:sockets" {
   function _connect(
     address: string | SocketAddress,
@@ -3141,10 +3173,149 @@ declare module "cloudflare:sockets" {
   ): Socket;
   export { _connect as connect };
 }
-// Copyright (c) 2023 Cloudflare, Inc.
+// Copyright (c) 2022-2023 Cloudflare, Inc.
 // Licensed under the Apache 2.0 license found in the LICENSE file or at:
 //     https://opensource.org/licenses/Apache-2.0
-// https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/
+/**
+ * Additional information to associate with a vector.
+ */
+declare type VectorizeVectorMetadata =
+  | string
+  | number
+  | boolean
+  | string[]
+  | Record<string, string | number | boolean | string[]>;
+declare type VectorFloatArray = Float32Array | Float64Array;
+declare interface VectorizeError {
+  code?: number;
+  error: string;
+}
+/**
+ * A pre-configured list of known models.
+ * These can be supplied in place of configuring explicit dimensions.
+ */
+declare type VectorizePreset =
+  | "openapi-text-embedding-ada-002"
+  | "workers-ai/bge-small-en"
+  | "cohere/embed-multilingual-v2.0";
+/**
+ * Supported distance metrics for an index.
+ * Distance metrics determine how other "similar" vectors are determined.
+ */
+declare type VectorizeDistanceMetric = "euclidean" | "cosine" | "dot-product";
+declare interface VectorizeQueryOptions {
+  topK?: number;
+  namespace?: string;
+  returnVectors?: boolean;
+}
+/**
+ * Information about the configuration of an index.
+ */
+declare type VectorizeIndexConfig =
+  | {
+      dimensions: number;
+      metric: VectorizeDistanceMetric;
+    }
+  | {
+      preset: VectorizePreset;
+    };
+/**
+ * Metadata about an existing index.
+ */
+declare interface VectorizeIndexDetails {
+  /** The unique ID of the index */
+  readonly id: string;
+  /** The name of the index. */
+  name: string;
+  /** (optional) A human readable description for the index. */
+  description?: string;
+  /** The index configuration, including the dimension size and distance metric. */
+  config: VectorizeIndexConfig;
+  /** The number of records containing vectors within the index. */
+  vectorsCount: number;
+}
+/**
+ * Represents a single vector value set along with its associated metadata.
+ */
+declare interface VectorizeVector {
+  /** The ID for the vector. This can be user-defined, and must be unique. It should uniquely identify the object, and is best set based on the ID of what the vector represents. */
+  id: string;
+  /** The vector values */
+  values: VectorFloatArray | number[];
+  /** The namespace this vector belongs to. */
+  namespace?: string;
+  /** Metadata associated with the binding. Includes the values of the other fields and potentially additional details. */
+  metadata?: Record<string, VectorizeVectorMetadata>;
+}
+/**
+ * Represents a matched vector for a query along with its score and (if specified) the matching vector information.
+ */
+declare interface VectorizeMatch {
+  /** The ID for the vector. This can be user-defined, and must be unique. It should uniquely identify the object, and is best set based on the ID of what the vector represents. */
+  vectorId: string;
+  /** The score or rank for similarity, when returned as a result */
+  score: number;
+  /** Vector data for the match. Included only if the user specified they want it returned (via {@link VectorizeQueryOptions}). */
+  vector?: VectorizeVector;
+}
+/**
+ * A set of vector {@link VectorizeMatch} for a particular query.
+ */
+declare interface VectorizeMatches {
+  matches: VectorizeMatch[];
+  count: number;
+}
+/**
+ * Results of an operation that performed a mutation on a set of vectors.
+ * Here, `ids` is a list of vectors that were successfully processed.
+ */
+declare interface VectorizeVectorMutation {
+  /* List of ids of vectors that were successfully processed. */
+  ids: string[];
+  /* Total count of the number of processed vectors. */
+  count: number;
+}
+declare abstract class VectorizeIndex {
+  /**
+   * Get information about the currently bound index.
+   * @returns A promise that resolves with information about the current index.
+   */
+  public describe(): Promise<VectorizeIndexDetails>;
+  /**
+   * Use the provided vector to perform a similarity search across the index.
+   * @param vector Input vector that will be used to drive the similarity search.
+   * @param options Configuration options to massage the returned data.
+   * @returns A promise that resolves with matched and scored vectors.
+   */
+  public query(
+    vector: VectorFloatArray | number[],
+    options: VectorizeQueryOptions
+  ): Promise<VectorizeMatches>;
+  /**
+   * Insert a list of vectors into the index dataset. If a provided id exists, an error will be thrown.
+   * @param vectors List of vectors that will be inserted.
+   * @returns A promise that resolves with the ids & count of records that were successfully processed.
+   */
+  public insert(vectors: VectorizeVector[]): Promise<VectorizeVectorMutation>;
+  /**
+   * Upsert a list of vectors into the index dataset. If a provided id exists, it will be replaced with the new values.
+   * @param vectors List of vectors that will be upserted.
+   * @returns A promise that resolves with the ids & count of records that were successfully processed.
+   */
+  public upsert(vectors: VectorizeVector[]): Promise<VectorizeVectorMutation>;
+  /**
+   * Delete a list of vectors with a matching id.
+   * @param ids List of vector ids that should be deleted.
+   * @returns A promise that resolves with the ids & count of records that were successfully processed (and thus deleted).
+   */
+  public deleteByIds(ids: string[]): Promise<VectorizeVectorMutation>;
+  /**
+   * Get a list of vectors with a matching id.
+   * @param ids List of vector ids that should be returned.
+   * @returns A promise that resolves with the raw unscored vectors matching the id set.
+   */
+  public getByIds(ids: string[]): Promise<VectorizeVector[]>;
+}
 declare interface DynamicDispatchLimits {
   /**
    * Limit CPU time in milliseconds.

package/experimental/index.ts

@@ -886,7 +886,7 @@ export declare class TextDecoder {
 }
 export declare class TextEncoder {
   constructor();
-  encode(input?: string): ArrayBuffer | ArrayBufferView;
+  encode(input?: string): Uint8Array;
   encodeInto(
     input: string,
     buffer: ArrayBuffer | ArrayBufferView
@@ -2956,9 +2956,6 @@ export type ContinentCode = "AF" | "AN" | "AS" | "EU" | "NA" | "OC" | "SA";
 export type CfProperties<HostMetadata = unknown> =
   | IncomingRequestCfProperties<HostMetadata>
   | RequestInitCfProperties;
-// Copyright (c) 2022-2023 Cloudflare, Inc.
-// Licensed under the Apache 2.0 license found in the LICENSE file or at:
-//     https://opensource.org/licenses/Apache-2.0
 export interface D1Result<T = unknown> {
   results: T[];
   success: true;
@@ -2983,9 +2980,6 @@ export declare abstract class D1PreparedStatement {
   all<T = Record<string, unknown>>(): Promise<D1Result<T>>;
   raw<T = unknown[]>(): Promise<T[]>;
 }
-// Copyright (c) 2023 Cloudflare, Inc.
-// Licensed under the Apache 2.0 license found in the LICENSE file or at:
-//     https://opensource.org/licenses/Apache-2.0
 /**
  * An email message that can be sent from a Worker.
  */
@@ -3043,9 +3037,53 @@ export type EmailExportedHandler<Env = unknown> = (
   env: Env,
   ctx: ExecutionContext
 ) => void | Promise<void>;
-// Copyright (c) 2022-2023 Cloudflare, Inc.
-// Licensed under the Apache 2.0 license found in the LICENSE file or at:
-//     https://opensource.org/licenses/Apache-2.0
+export interface Hyperdrive {
+  /**
+   * Connect directly to Hyperdrive as if it's your database, returning a TCP socket.
+   *
+   * Calling this method returns an idential socket to if you call
+   * `connect("host:port")` using the `host` and `port` fields from this object.
+   * Pick whichever approach works better with your preferred DB client library.
+   *
+   * Note that this socket is not yet authenticated -- it's expected that your
+   * code (or preferably, the client library of your choice) will authenticate
+   * using the information in this class's readonly fields.
+   */
+  connect(): Socket;
+  /**
+   * A valid DB connection string that can be passed straight into the typical
+   * client library/driver/ORM. This will typically be the easiest way to use
+   * Hyperdrive.
+   */
+  readonly connectionString: string;
+  /*
+   * A randomly generated hostname that is only valid within the context of the
+   * currently running Worker which, when passed into `connect()` function from
+   * the "cloudflare:sockets" module, will connect to the Hyperdrive instance
+   * for your database.
+   */
+  readonly host: string;
+  /*
+   * The port that must be paired the the host field when connecting.
+   */
+  readonly port: string;
+  /*
+   * The username to use when authenticating to your database via Hyperdrive.
+   * Unlike the host and password, this will be the same every time
+   */
+  readonly user: string;
+  /*
+   * The randomly generated password to use when authenticating to your
+   * database via Hyperdrive. Like the host field, this password is only valid
+   * within the context of the currently running Worker instance from which
+   * it's read.
+   */
+  readonly password: string;
+  /*
+   * The name of the database to connect to.
+   */
+  readonly database: string;
+}
 export type Params<P extends string = any> = Record<P, string | string[]>;
 export type EventContext<Env, P extends string, Data> = {
   request: Request;
@@ -3089,13 +3127,10 @@ export type PagesPluginFunction<
 > = (
   context: EventPluginContext<Env, Params, Data, PluginArgs>
 ) => Response | Promise<Response>;
-// Copyright (c) 2023 Cloudflare, Inc.
-// Licensed under the Apache 2.0 license found in the LICENSE file or at:
-//     https://opensource.org/licenses/Apache-2.0
-// https://developers.cloudflare.com/pub-sub/
 // PubSubMessage represents an incoming PubSub message.
 // The message includes metadata about the broker, the client, and the payload
 // itself.
+// https://developers.cloudflare.com/pub-sub/
 export interface PubSubMessage {
   // Message ID
   readonly mid: number;
@@ -3126,10 +3161,149 @@ export interface JsonWebKeyWithKid extends JsonWebKey {
   // Key Identifier of the JWK
   readonly kid: string;
 }
-// Copyright (c) 2023 Cloudflare, Inc.
+// Copyright (c) 2022-2023 Cloudflare, Inc.
 // Licensed under the Apache 2.0 license found in the LICENSE file or at:
 //     https://opensource.org/licenses/Apache-2.0
-// https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/
+/**
+ * Additional information to associate with a vector.
+ */
+export type VectorizeVectorMetadata =
+  | string
+  | number
+  | boolean
+  | string[]
+  | Record<string, string | number | boolean | string[]>;
+export type VectorFloatArray = Float32Array | Float64Array;
+export interface VectorizeError {
+  code?: number;
+  error: string;
+}
+/**
+ * A pre-configured list of known models.
+ * These can be supplied in place of configuring explicit dimensions.
+ */
+export type VectorizePreset =
+  | "openapi-text-embedding-ada-002"
+  | "workers-ai/bge-small-en"
+  | "cohere/embed-multilingual-v2.0";
+/**
+ * Supported distance metrics for an index.
+ * Distance metrics determine how other "similar" vectors are determined.
+ */
+export type VectorizeDistanceMetric = "euclidean" | "cosine" | "dot-product";
+export interface VectorizeQueryOptions {
+  topK?: number;
+  namespace?: string;
+  returnVectors?: boolean;
+}
+/**
+ * Information about the configuration of an index.
+ */
+export type VectorizeIndexConfig =
+  | {
+      dimensions: number;
+      metric: VectorizeDistanceMetric;
+    }
+  | {
+      preset: VectorizePreset;
+    };
+/**
+ * Metadata about an existing index.
+ */
+export interface VectorizeIndexDetails {
+  /** The unique ID of the index */
+  readonly id: string;
+  /** The name of the index. */
+  name: string;
+  /** (optional) A human readable description for the index. */
+  description?: string;
+  /** The index configuration, including the dimension size and distance metric. */
+  config: VectorizeIndexConfig;
+  /** The number of records containing vectors within the index. */
+  vectorsCount: number;
+}
+/**
+ * Represents a single vector value set along with its associated metadata.
+ */
+export interface VectorizeVector {
+  /** The ID for the vector. This can be user-defined, and must be unique. It should uniquely identify the object, and is best set based on the ID of what the vector represents. */
+  id: string;
+  /** The vector values */
+  values: VectorFloatArray | number[];
+  /** The namespace this vector belongs to. */
+  namespace?: string;
+  /** Metadata associated with the binding. Includes the values of the other fields and potentially additional details. */
+  metadata?: Record<string, VectorizeVectorMetadata>;
+}
+/**
+ * Represents a matched vector for a query along with its score and (if specified) the matching vector information.
+ */
+export interface VectorizeMatch {
+  /** The ID for the vector. This can be user-defined, and must be unique. It should uniquely identify the object, and is best set based on the ID of what the vector represents. */
+  vectorId: string;
+  /** The score or rank for similarity, when returned as a result */
+  score: number;
+  /** Vector data for the match. Included only if the user specified they want it returned (via {@link VectorizeQueryOptions}). */
+  vector?: VectorizeVector;
+}
+/**
+ * A set of vector {@link VectorizeMatch} for a particular query.
+ */
+export interface VectorizeMatches {
+  matches: VectorizeMatch[];
+  count: number;
+}
+/**
+ * Results of an operation that performed a mutation on a set of vectors.
+ * Here, `ids` is a list of vectors that were successfully processed.
+ */
+export interface VectorizeVectorMutation {
+  /* List of ids of vectors that were successfully processed. */
+  ids: string[];
+  /* Total count of the number of processed vectors. */
+  count: number;
+}
+export declare abstract class VectorizeIndex {
+  /**
+   * Get information about the currently bound index.
+   * @returns A promise that resolves with information about the current index.
+   */
+  public describe(): Promise<VectorizeIndexDetails>;
+  /**
+   * Use the provided vector to perform a similarity search across the index.
+   * @param vector Input vector that will be used to drive the similarity search.
+   * @param options Configuration options to massage the returned data.
+   * @returns A promise that resolves with matched and scored vectors.
+   */
+  public query(
+    vector: VectorFloatArray | number[],
+    options: VectorizeQueryOptions
+  ): Promise<VectorizeMatches>;
+  /**
+   * Insert a list of vectors into the index dataset. If a provided id exists, an error will be thrown.
+   * @param vectors List of vectors that will be inserted.
+   * @returns A promise that resolves with the ids & count of records that were successfully processed.
+   */
+  public insert(vectors: VectorizeVector[]): Promise<VectorizeVectorMutation>;
+  /**
+   * Upsert a list of vectors into the index dataset. If a provided id exists, it will be replaced with the new values.
+   * @param vectors List of vectors that will be upserted.
+   * @returns A promise that resolves with the ids & count of records that were successfully processed.
+   */
+  public upsert(vectors: VectorizeVector[]): Promise<VectorizeVectorMutation>;
+  /**
+   * Delete a list of vectors with a matching id.
+   * @param ids List of vector ids that should be deleted.
+   * @returns A promise that resolves with the ids & count of records that were successfully processed (and thus deleted).
+   */
+  public deleteByIds(ids: string[]): Promise<VectorizeVectorMutation>;
+  /**
+   * Get a list of vectors with a matching id.
+   * @param ids List of vector ids that should be returned.
+   * @returns A promise that resolves with the raw unscored vectors matching the id set.
+   */
+  public getByIds(ids: string[]): Promise<VectorizeVector[]>;
+}
 export interface DynamicDispatchLimits {
   /**
    * Limit CPU time in milliseconds.