@upstash/vector 0.1.0-alpha

package/README.md

@@ -0,0 +1,15 @@
+# vector-sdk
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.0.4. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/dist/index.d.mts

@@ -0,0 +1,358 @@
+type CacheSetting = "default" | "force-cache" | "no-cache" | "no-store" | "only-if-cached" | "reload";
+type UpstashRequest = {
+    path?: string[];
+    /**
+     * Request body will be serialized to json
+     */
+    body?: unknown;
+};
+type UpstashResponse<TResult> = {
+    result?: TResult;
+    error?: string;
+};
+interface Requester {
+    request: <TResult = unknown>(req: UpstashRequest) => Promise<UpstashResponse<TResult>>;
+}
+type RetryConfig = false | {
+    /**
+     * The number of retries to attempt before giving up.
+     *
+     * @default 5
+     */
+    retries?: number;
+    /**
+     * A backoff function receives the current retry cound and returns a number in milliseconds to wait before retrying.
+     *
+     * @default
+     * ```ts
+     * Math.exp(retryCount) * 50
+     * ```
+     */
+    backoff?: (retryCount: number) => number;
+};
+type RequesterConfig = {
+    /**
+     * Configure the retry behaviour in case of network errors
+     */
+    retry?: RetryConfig;
+    /**
+     * Configure the cache behaviour
+     * @default "no-store"
+     */
+    cache?: CacheSetting;
+};
+
+type Vector<TMetadata> = {
+    id: string;
+    vector: number[];
+    metadata?: TMetadata;
+};
+
+declare const ENDPOINTS: readonly ["upsert", "query", "delete", "fetch", "reset", "range"];
+type EndpointVariants = (typeof ENDPOINTS)[number];
+/**
+ * TResult is the raw data returned from upstash, which may need to be transformed or parsed.
+ */
+declare class Command<TResult> {
+    readonly payload: Record<string, unknown> | unknown[];
+    readonly endpoint: EndpointVariants;
+    constructor(command: Record<string, unknown> | unknown[], endpoint: EndpointVariants);
+    /**
+     * Execute the command using a client.
+     */
+    exec(client: Requester): Promise<TResult>;
+}
+
+/**
+ * Payload Type Definition for DeleteCommand
+ *
+ * This type defines the structure of the payload specifically used in the DeleteCommand.
+ *
+ * Properties:
+ *  - ids: An array of numbers or strings representing the unique identifiers of the records to be deleted. These could be database IDs, unique keys, or any identifier used to uniquely refer to records in a specific context.
+ *
+ * Usage:
+ * This type is typically used in scenarios where a batch deletion of records is required. The `ids` array allows specifying multiple records for deletion in a single command, thereby facilitating efficient bulk operations.
+ */
+type Payload$4 = {
+    ids: number[] | string[];
+};
+/**
+ * DeleteCommand Class
+ *
+ * This class extends the generic Command class to implement the deletion functionality.
+ *
+ * Example:
+ *  ```
+ *  const deletionIds = [123, 456, 789];
+ *  const deleteCommand = new DeleteCommand({ ids: deletionIds });
+ *  // Use deleteCommand to execute the deletion operation
+ *  ```
+ */
+declare class DeleteCommand extends Command<string> {
+    constructor(payload: Payload$4);
+}
+
+/**
+ * Payload Type Definition
+ *
+ * This type defines the structure of the payload used in a specific function or API call.
+ *
+ * Properties:
+ *  - vector: An array of numbers representing a specific vector. This could be coordinates, data points, or any numerical representation depending on the context of the function or API.
+ *
+ *  - topK: A number indicating the 'top K' elements to be considered or returned. In many contexts, this refers to the top 'K' results, items, or entities based on certain criteria like highest score, most relevance, etc.
+ *
+ *  - includeVectors: A boolean value indicating whether to include the vector data in the response or output. Setting this to 'true' includes the vector data.
+ *
+ * Usage:
+ * This type is typically used when sending or receiving data where a combination of a numerical vector, a limit on the number of elements to consider, and an option to include or exclude detailed vector data is required.
+ */
+type Payload$3 = {
+    vector: number[];
+    topK: number;
+    includeVectors: boolean;
+};
+type QueryReturnResponse<TMetadata> = {
+    id: number | string;
+    score: number;
+    vector: number[];
+    metadata?: TMetadata;
+};
+/**
+ * QueryCommand Class
+ * Example:
+ *  ```
+ *  const payload = { vector: [1, 2, 3], topK: 5, includeVectors: true };
+ *  const queryCommand = new QueryCommand(payload);
+ *  // Use queryCommand for further operations
+ *  ```
+ */
+declare class QueryCommand<TResult> extends Command<QueryReturnResponse<TResult>[]> {
+    constructor(payload: Payload$3);
+}
+
+/**
+ * Payload Type Definition for UpsertCommand
+ *
+ * This type defines the structure of the payload used in the UpsertCommand.
+ *
+ * Properties:
+ *  - id: A number or string representing the unique identifier of the record to be upserted (inserted or updated).
+ *  - vector: An array of numbers representing a specific vector. This could be coordinates, data points, or any numerical representation depending on the context.
+ *  - metadata (optional): An object with key-value pairs, where the keys are strings and the values are of unknown type. This allows for flexible and additional data to be associated with the record being upserted.
+ *
+ * Usage:
+ * This type is primarily used in scenarios where a record needs to be inserted into a database if it does not already exist, or updated if it does. The flexibility of the metadata field allows for various additional information to be passed along with the primary data.
+ */
+type Payload$2 = {
+    id: number | string;
+    vector: number[];
+    metadata?: Record<string, unknown>;
+};
+/**
+ * UpsertCommand Class
+ *
+ * Extends the generic Command class to implement an upsert (insert or update) operation.
+ *
+ * Example:
+ *  ```
+ *  const upsertPayload = { id: 123, vector: [1.1, 2.2, 3.3], metadata: { key: "value" } };
+ *  const upsertCommand = new UpsertCommand(upsertPayload);
+ *  // Use upsertCommand to execute the upsert operation
+ *  ```
+ *
+ * The UpsertCommand takes a payload containing the necessary data for the upsert operation. It supports handling both insertion and update of records based on the provided identifier.
+ */
+declare class UpsertCommand extends Command<string> {
+    constructor(payload: Payload$2);
+}
+
+/**
+ * Type definition for FetchCommand payload
+ *
+ * Properties:
+ *  - ids: An array of numbers or strings, representing the unique identifiers of the records to be fetched.
+ *  - includeMetadata (optional): A boolean flag indicating whether to include metadata in the response.
+ *  - includeVectors (optional): A boolean flag indicating whether to include vector data in the response.
+ *
+ * The Payload type is used in the FetchCommand to specify the data required to fetch specific records.
+ * The optional flags allow for more detailed responses depending on the requirements.
+ */
+type Payload$1 = {
+    ids: number[] | string[];
+    includeMetadata?: boolean;
+    includeVectors?: boolean;
+};
+/**
+ * Generic response type for FetchCommand
+ *
+ * This type represents the possible return type of a FetchCommand. It can be either a Vector
+ * containing metadata or null, depending on whether the fetch operation was successful or not.
+ */
+type FetchReturnResponse<TMetadata> = Vector<TMetadata> | null;
+/**
+ * FetchCommand Class
+ *
+ * Extends the generic Command class to implement a fetch operation.
+ *
+ * Example:
+ *  ```
+ *  const fetchPayload = { ids: [1, 2, 3], includeMetadata: true };
+ *  const fetchCommand = new FetchCommand(fetchPayload);
+ *  // Use fetchCommand to execute the fetch operation
+ *  ```
+ */
+declare class FetchCommand<TMetadata> extends Command<FetchReturnResponse<TMetadata>[]> {
+    constructor(payload: Payload$1);
+}
+
+/**
+ * Type definition for RangeCommand payload
+ *
+ * This type specifies the structure of the payload used in the RangeCommand.
+ *
+ * Properties:
+ *  - cursor: A number indicating the starting point for the range query.
+ *  - limit: A number specifying the maximum number of records to be returned.
+ *  - includeVectors (optional): A boolean flag indicating whether to include vector data in the response.
+ *  - includeMetadata (optional): A boolean flag indicating whether to include metadata in the response.
+ *
+ * This payload type is used for range queries, where a set of records is retrieved based on the specified cursor
+ * and limit. The optional inclusion of vectors and metadata allows for flexible and detailed data retrieval.
+ */
+type Payload = {
+    cursor: number;
+    limit: number;
+    includeVectors?: boolean;
+    includeMetadata?: boolean;
+};
+/**
+ * Type definition for the response returned by RangeCommand
+ *
+ * This type outlines the structure of the response from a RangeCommand.
+ *
+ * Properties:
+ *  - nextCursor: A string that indicates the cursor to be used for the next range query, facilitating pagination.
+ *  - vectors: An array of Vector objects, each containing TMetadata, representing the data retrieved in the range query.
+ *
+ * The RangeReturnResponse type is crucial for operations that involve retrieving a range of records,
+ * providing both the data (in the form of vectors) and the means to continue fetching subsequent ranges (via nextCursor).
+ */
+type RangeReturnResponse<TMetadata> = {
+    nextCursor: string;
+    vectors: Vector<TMetadata>[];
+};
+/**
+ * RangeCommand Class
+ * Example:
+ *  ```
+ *  const rangePayload = { cursor: 0, limit: 10, includeVectors: true };
+ *  const rangeCommand = new RangeCommand(rangePayload);
+ *  // Use rangeCommand to execute the range query and retrieve data
+ *  ```
+ */
+declare class RangeCommand<TResult> extends Command<RangeReturnResponse<TResult>> {
+    constructor(payload: Payload);
+}
+
+type CommandArgs<TCommand extends new (_args: any) => any> = ConstructorParameters<TCommand>[0];
+/**
+ * Serverless vector client for upstash vector db.
+ */
+declare class Index$1 {
+    protected client: Requester;
+    /**
+     * Create a new vector db client
+     *
+     * @example
+     * ```typescript
+     * const index = new Index({
+     *  url: "<UPSTASH_VECTOR_REST_URL>",
+     *  token: "<UPSTASH_VECTOR_REST_TOKEN>",
+     * });
+     * ```
+     */
+    constructor(client: Requester);
+    delete: (args: CommandArgs<typeof DeleteCommand>) => Promise<string>;
+    query: (args: CommandArgs<typeof QueryCommand>) => Promise<{
+        id: string | number;
+        score: number;
+        vector: number[];
+        metadata?: unknown;
+    }[]>;
+    upsert: (args: CommandArgs<typeof UpsertCommand>) => Promise<string>;
+    fetch: (args: CommandArgs<typeof FetchCommand>) => Promise<(Vector<unknown> | null)[]>;
+    reset: () => Promise<string>;
+    range: (args: CommandArgs<typeof RangeCommand>) => Promise<{
+        nextCursor: string;
+        vectors: Vector<unknown>[];
+    }>;
+}
+
+/**
+ * Connection credentials for upstash vector.
+ * Get them from https://console.upstash.com/vector/<uuid>
+ */
+type VectorConfig = {
+    /**
+     * UPSTASH_VECTOR_REST_URL
+     */
+    url: string;
+    /**
+     * UPSTASH_VECTOR_REST_TOKEN
+     */
+    token: string;
+    /**
+     * The signal will allow aborting requests on the fly.
+     * For more check: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+     */
+    signal?: AbortSignal;
+} & RequesterConfig;
+/**
+ * Serverless vector client for upstash.
+ */
+declare class Index extends Index$1 {
+    /**
+     * Create a new vector client by providing the url and token
+     *
+     * @example
+     * ```typescript
+     * const vector = new Vector({
+     *  url: "<UPSTASH_VECTOR_REST_URL>",
+     *  token: "<UPSTASH_VECTOR_REST_TOKEN>",
+     * });
+     * ```
+     */
+    constructor(config: VectorConfig);
+    /**
+     * Create a new vector client by providing a custom `Requester` implementation
+     *
+     * @example
+     * ```ts
+     *
+     * import { UpstashRequest, Requester, UpstashResponse, vector } from "@upstash/vector"
+     *
+     *  const requester: Requester = {
+     *    request: <TResult>(req: UpstashRequest): Promise<UpstashResponse<TResult>> => {
+     *      // ...
+     *    }
+     *  }
+     *
+     * const vector = new vector(requester)
+     * ```
+     */
+    constructor(requesters: Requester);
+    /**
+     * Create a new Upstash Vector instance from environment variables.
+     *
+     * Use this to automatically load connection secrets from your environment
+     * variables. For instance when using the Vercel integration.
+     *
+     * This tries to load `UPSTASH_VECTOR_REST_URL` and `UPSTASH_VECTOR_REST_TOKEN` from
+     * your environment using `process.env`.
+     */
+    static fromEnv(config?: Omit<VectorConfig, "url" | "token">): Index;
+}
+
+export { Index, type Requester, type UpstashRequest, type UpstashResponse, type VectorConfig };

package/dist/index.d.ts

@@ -0,0 +1,358 @@
+type CacheSetting = "default" | "force-cache" | "no-cache" | "no-store" | "only-if-cached" | "reload";
+type UpstashRequest = {
+    path?: string[];
+    /**
+     * Request body will be serialized to json
+     */
+    body?: unknown;
+};
+type UpstashResponse<TResult> = {
+    result?: TResult;
+    error?: string;
+};
+interface Requester {
+    request: <TResult = unknown>(req: UpstashRequest) => Promise<UpstashResponse<TResult>>;
+}
+type RetryConfig = false | {
+    /**
+     * The number of retries to attempt before giving up.
+     *
+     * @default 5
+     */
+    retries?: number;
+    /**
+     * A backoff function receives the current retry cound and returns a number in milliseconds to wait before retrying.
+     *
+     * @default
+     * ```ts
+     * Math.exp(retryCount) * 50
+     * ```
+     */
+    backoff?: (retryCount: number) => number;
+};
+type RequesterConfig = {
+    /**
+     * Configure the retry behaviour in case of network errors
+     */
+    retry?: RetryConfig;
+    /**
+     * Configure the cache behaviour
+     * @default "no-store"
+     */
+    cache?: CacheSetting;
+};
+
+type Vector<TMetadata> = {
+    id: string;
+    vector: number[];
+    metadata?: TMetadata;
+};
+
+declare const ENDPOINTS: readonly ["upsert", "query", "delete", "fetch", "reset", "range"];
+type EndpointVariants = (typeof ENDPOINTS)[number];
+/**
+ * TResult is the raw data returned from upstash, which may need to be transformed or parsed.
+ */
+declare class Command<TResult> {
+    readonly payload: Record<string, unknown> | unknown[];
+    readonly endpoint: EndpointVariants;
+    constructor(command: Record<string, unknown> | unknown[], endpoint: EndpointVariants);
+    /**
+     * Execute the command using a client.
+     */
+    exec(client: Requester): Promise<TResult>;
+}
+
+/**
+ * Payload Type Definition for DeleteCommand
+ *
+ * This type defines the structure of the payload specifically used in the DeleteCommand.
+ *
+ * Properties:
+ *  - ids: An array of numbers or strings representing the unique identifiers of the records to be deleted. These could be database IDs, unique keys, or any identifier used to uniquely refer to records in a specific context.
+ *
+ * Usage:
+ * This type is typically used in scenarios where a batch deletion of records is required. The `ids` array allows specifying multiple records for deletion in a single command, thereby facilitating efficient bulk operations.
+ */
+type Payload$4 = {
+    ids: number[] | string[];
+};
+/**
+ * DeleteCommand Class
+ *
+ * This class extends the generic Command class to implement the deletion functionality.
+ *
+ * Example:
+ *  ```
+ *  const deletionIds = [123, 456, 789];
+ *  const deleteCommand = new DeleteCommand({ ids: deletionIds });
+ *  // Use deleteCommand to execute the deletion operation
+ *  ```
+ */
+declare class DeleteCommand extends Command<string> {
+    constructor(payload: Payload$4);
+}
+
+/**
+ * Payload Type Definition
+ *
+ * This type defines the structure of the payload used in a specific function or API call.
+ *
+ * Properties:
+ *  - vector: An array of numbers representing a specific vector. This could be coordinates, data points, or any numerical representation depending on the context of the function or API.
+ *
+ *  - topK: A number indicating the 'top K' elements to be considered or returned. In many contexts, this refers to the top 'K' results, items, or entities based on certain criteria like highest score, most relevance, etc.
+ *
+ *  - includeVectors: A boolean value indicating whether to include the vector data in the response or output. Setting this to 'true' includes the vector data.
+ *
+ * Usage:
+ * This type is typically used when sending or receiving data where a combination of a numerical vector, a limit on the number of elements to consider, and an option to include or exclude detailed vector data is required.
+ */
+type Payload$3 = {
+    vector: number[];
+    topK: number;
+    includeVectors: boolean;
+};
+type QueryReturnResponse<TMetadata> = {
+    id: number | string;
+    score: number;
+    vector: number[];
+    metadata?: TMetadata;
+};
+/**
+ * QueryCommand Class
+ * Example:
+ *  ```
+ *  const payload = { vector: [1, 2, 3], topK: 5, includeVectors: true };
+ *  const queryCommand = new QueryCommand(payload);
+ *  // Use queryCommand for further operations
+ *  ```
+ */
+declare class QueryCommand<TResult> extends Command<QueryReturnResponse<TResult>[]> {
+    constructor(payload: Payload$3);
+}
+
+/**
+ * Payload Type Definition for UpsertCommand
+ *
+ * This type defines the structure of the payload used in the UpsertCommand.
+ *
+ * Properties:
+ *  - id: A number or string representing the unique identifier of the record to be upserted (inserted or updated).
+ *  - vector: An array of numbers representing a specific vector. This could be coordinates, data points, or any numerical representation depending on the context.
+ *  - metadata (optional): An object with key-value pairs, where the keys are strings and the values are of unknown type. This allows for flexible and additional data to be associated with the record being upserted.
+ *
+ * Usage:
+ * This type is primarily used in scenarios where a record needs to be inserted into a database if it does not already exist, or updated if it does. The flexibility of the metadata field allows for various additional information to be passed along with the primary data.
+ */
+type Payload$2 = {
+    id: number | string;
+    vector: number[];
+    metadata?: Record<string, unknown>;
+};
+/**
+ * UpsertCommand Class
+ *
+ * Extends the generic Command class to implement an upsert (insert or update) operation.
+ *
+ * Example:
+ *  ```
+ *  const upsertPayload = { id: 123, vector: [1.1, 2.2, 3.3], metadata: { key: "value" } };
+ *  const upsertCommand = new UpsertCommand(upsertPayload);
+ *  // Use upsertCommand to execute the upsert operation
+ *  ```
+ *
+ * The UpsertCommand takes a payload containing the necessary data for the upsert operation. It supports handling both insertion and update of records based on the provided identifier.
+ */
+declare class UpsertCommand extends Command<string> {
+    constructor(payload: Payload$2);
+}
+
+/**
+ * Type definition for FetchCommand payload
+ *
+ * Properties:
+ *  - ids: An array of numbers or strings, representing the unique identifiers of the records to be fetched.
+ *  - includeMetadata (optional): A boolean flag indicating whether to include metadata in the response.
+ *  - includeVectors (optional): A boolean flag indicating whether to include vector data in the response.
+ *
+ * The Payload type is used in the FetchCommand to specify the data required to fetch specific records.
+ * The optional flags allow for more detailed responses depending on the requirements.
+ */
+type Payload$1 = {
+    ids: number[] | string[];
+    includeMetadata?: boolean;
+    includeVectors?: boolean;
+};
+/**
+ * Generic response type for FetchCommand
+ *
+ * This type represents the possible return type of a FetchCommand. It can be either a Vector
+ * containing metadata or null, depending on whether the fetch operation was successful or not.
+ */
+type FetchReturnResponse<TMetadata> = Vector<TMetadata> | null;
+/**
+ * FetchCommand Class
+ *
+ * Extends the generic Command class to implement a fetch operation.
+ *
+ * Example:
+ *  ```
+ *  const fetchPayload = { ids: [1, 2, 3], includeMetadata: true };
+ *  const fetchCommand = new FetchCommand(fetchPayload);
+ *  // Use fetchCommand to execute the fetch operation
+ *  ```
+ */
+declare class FetchCommand<TMetadata> extends Command<FetchReturnResponse<TMetadata>[]> {
+    constructor(payload: Payload$1);
+}
+
+/**
+ * Type definition for RangeCommand payload
+ *
+ * This type specifies the structure of the payload used in the RangeCommand.
+ *
+ * Properties:
+ *  - cursor: A number indicating the starting point for the range query.
+ *  - limit: A number specifying the maximum number of records to be returned.
+ *  - includeVectors (optional): A boolean flag indicating whether to include vector data in the response.
+ *  - includeMetadata (optional): A boolean flag indicating whether to include metadata in the response.
+ *
+ * This payload type is used for range queries, where a set of records is retrieved based on the specified cursor
+ * and limit. The optional inclusion of vectors and metadata allows for flexible and detailed data retrieval.
+ */
+type Payload = {
+    cursor: number;
+    limit: number;
+    includeVectors?: boolean;
+    includeMetadata?: boolean;
+};
+/**
+ * Type definition for the response returned by RangeCommand
+ *
+ * This type outlines the structure of the response from a RangeCommand.
+ *
+ * Properties:
+ *  - nextCursor: A string that indicates the cursor to be used for the next range query, facilitating pagination.
+ *  - vectors: An array of Vector objects, each containing TMetadata, representing the data retrieved in the range query.
+ *
+ * The RangeReturnResponse type is crucial for operations that involve retrieving a range of records,
+ * providing both the data (in the form of vectors) and the means to continue fetching subsequent ranges (via nextCursor).
+ */
+type RangeReturnResponse<TMetadata> = {
+    nextCursor: string;
+    vectors: Vector<TMetadata>[];
+};
+/**
+ * RangeCommand Class
+ * Example:
+ *  ```
+ *  const rangePayload = { cursor: 0, limit: 10, includeVectors: true };
+ *  const rangeCommand = new RangeCommand(rangePayload);
+ *  // Use rangeCommand to execute the range query and retrieve data
+ *  ```
+ */
+declare class RangeCommand<TResult> extends Command<RangeReturnResponse<TResult>> {
+    constructor(payload: Payload);
+}
+
+type CommandArgs<TCommand extends new (_args: any) => any> = ConstructorParameters<TCommand>[0];
+/**
+ * Serverless vector client for upstash vector db.
+ */
+declare class Index$1 {
+    protected client: Requester;
+    /**
+     * Create a new vector db client
+     *
+     * @example
+     * ```typescript
+     * const index = new Index({
+     *  url: "<UPSTASH_VECTOR_REST_URL>",
+     *  token: "<UPSTASH_VECTOR_REST_TOKEN>",
+     * });
+     * ```
+     */
+    constructor(client: Requester);
+    delete: (args: CommandArgs<typeof DeleteCommand>) => Promise<string>;
+    query: (args: CommandArgs<typeof QueryCommand>) => Promise<{
+        id: string | number;
+        score: number;
+        vector: number[];
+        metadata?: unknown;
+    }[]>;
+    upsert: (args: CommandArgs<typeof UpsertCommand>) => Promise<string>;
+    fetch: (args: CommandArgs<typeof FetchCommand>) => Promise<(Vector<unknown> | null)[]>;
+    reset: () => Promise<string>;
+    range: (args: CommandArgs<typeof RangeCommand>) => Promise<{
+        nextCursor: string;
+        vectors: Vector<unknown>[];
+    }>;
+}
+
+/**
+ * Connection credentials for upstash vector.
+ * Get them from https://console.upstash.com/vector/<uuid>
+ */
+type VectorConfig = {
+    /**
+     * UPSTASH_VECTOR_REST_URL
+     */
+    url: string;
+    /**
+     * UPSTASH_VECTOR_REST_TOKEN
+     */
+    token: string;
+    /**
+     * The signal will allow aborting requests on the fly.
+     * For more check: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+     */
+    signal?: AbortSignal;
+} & RequesterConfig;
+/**
+ * Serverless vector client for upstash.
+ */
+declare class Index extends Index$1 {
+    /**
+     * Create a new vector client by providing the url and token
+     *
+     * @example
+     * ```typescript
+     * const vector = new Vector({
+     *  url: "<UPSTASH_VECTOR_REST_URL>",
+     *  token: "<UPSTASH_VECTOR_REST_TOKEN>",
+     * });
+     * ```
+     */
+    constructor(config: VectorConfig);
+    /**
+     * Create a new vector client by providing a custom `Requester` implementation
+     *
+     * @example
+     * ```ts
+     *
+     * import { UpstashRequest, Requester, UpstashResponse, vector } from "@upstash/vector"
+     *
+     *  const requester: Requester = {
+     *    request: <TResult>(req: UpstashRequest): Promise<UpstashResponse<TResult>> => {
+     *      // ...
+     *    }
+     *  }
+     *
+     * const vector = new vector(requester)
+     * ```
+     */
+    constructor(requesters: Requester);
+    /**
+     * Create a new Upstash Vector instance from environment variables.
+     *
+     * Use this to automatically load connection secrets from your environment
+     * variables. For instance when using the Vercel integration.
+     *
+     * This tries to load `UPSTASH_VECTOR_REST_URL` and `UPSTASH_VECTOR_REST_TOKEN` from
+     * your environment using `process.env`.
+     */
+    static fromEnv(config?: Omit<VectorConfig, "url" | "token">): Index;
+}
+
+export { Index, type Requester, type UpstashRequest, type UpstashResponse, type VectorConfig };

package/dist/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+var n=class extends Error{constructor(e){super(e),this.name="UpstashError";}};var i=class{baseUrl;headers;options;retry;constructor(e){this.options={cache:e.cache,signal:e.signal},this.baseUrl=e.baseUrl.replace(/\/$/,""),this.headers={"Content-Type":"application/json",...e.headers},typeof e?.retry=="boolean"&&e?.retry===!1?this.retry={attempts:1,backoff:()=>0}:this.retry={attempts:e?.retry?.retries??5,backoff:e?.retry?.backoff??(s=>Math.exp(s)*50)};}async request(e){let s={cache:this.options.cache,method:"POST",headers:this.headers,body:JSON.stringify(e.body),keepalive:!0,signal:this.options.signal},o=null,f=null;for(let y=0;y<=this.retry.attempts;y++)try{o=await fetch([this.baseUrl,...e.path??[]].join("/"),s);break}catch(g){if(this.options.signal?.aborted){let R=new Blob([JSON.stringify({result:this.options.signal.reason??"Aborted"})]),T={status:200,statusText:this.options.signal.reason??"Aborted"};o=new Response(R,T);break}f=g,await new Promise(R=>setTimeout(R,this.retry.backoff(y)));}if(!o)throw f??new Error("Exhausted all retries");let a=await o.json();if(x(a)){if(!o.ok)throw new n(`${a.error}, command was: ${JSON.stringify(e.body)}`);return a}return {result:a}}};function x(t){return t&&typeof t=="object"&&("result"in t||"error"in t)}var r=class{payload;endpoint;constructor(e,s){this.payload=e,this.endpoint=s;}async exec(e){let{result:s,error:o}=await e.request({body:this.payload,path:[this.endpoint]});if(o)throw new n(o);if(typeof s>"u")throw new Error("Request did not return a result");return s}};var p=class extends r{constructor(e){super(e.ids,"delete");}};var l=class extends r{constructor(e){super({...e},"query");}};var u=class extends r{constructor(e){super({...e},"upsert");}};var c=class extends r{constructor(e){super({...e},"fetch");}};var m=class extends r{constructor(e){super(e,"range");}};var d=class extends r{constructor(){super([],"reset");}};var h=class{client;constructor(e){this.client=e;}delete=e=>new p(e).exec(this.client);query=e=>new l(e).exec(this.client);upsert=e=>new u(e).exec(this.client);fetch=e=>new c(e).exec(this.client);reset=()=>new d().exec(this.client);range=e=>new m(e).exec(this.client)};var b=class t extends h{constructor(e){if("request"in e){super(e);return}(e.url.startsWith(" ")||e.url.endsWith(" ")||/\r|\n/.test(e.url))&&console.warn("The vector url contains whitespace or newline, which can cause errors!"),(e.token.startsWith(" ")||e.token.endsWith(" ")||/\r|\n/.test(e.token))&&console.warn("The vector token contains whitespace or newline, which can cause errors!");let s=new i({baseUrl:e.url,retry:e.retry,headers:{authorization:`Bearer ${e.token}`},cache:e.cache||"no-store",signal:e.signal});super(s);}static fromEnv(e){let s=process?.env.UPSTASH_VECTOR_REST_URL;if(!s)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_URL`");let o=process?.env.UPSTASH_VECTOR_REST_TOKEN;if(!o)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_TOKEN`");return new t({...e,url:s,token:o})}};
+
+exports.Index = b;

package/dist/index.mjs

@@ -0,0 +1,3 @@
+var n=class extends Error{constructor(e){super(e),this.name="UpstashError";}};var i=class{baseUrl;headers;options;retry;constructor(e){this.options={cache:e.cache,signal:e.signal},this.baseUrl=e.baseUrl.replace(/\/$/,""),this.headers={"Content-Type":"application/json",...e.headers},typeof e?.retry=="boolean"&&e?.retry===!1?this.retry={attempts:1,backoff:()=>0}:this.retry={attempts:e?.retry?.retries??5,backoff:e?.retry?.backoff??(s=>Math.exp(s)*50)};}async request(e){let s={cache:this.options.cache,method:"POST",headers:this.headers,body:JSON.stringify(e.body),keepalive:!0,signal:this.options.signal},o=null,f=null;for(let y=0;y<=this.retry.attempts;y++)try{o=await fetch([this.baseUrl,...e.path??[]].join("/"),s);break}catch(g){if(this.options.signal?.aborted){let R=new Blob([JSON.stringify({result:this.options.signal.reason??"Aborted"})]),T={status:200,statusText:this.options.signal.reason??"Aborted"};o=new Response(R,T);break}f=g,await new Promise(R=>setTimeout(R,this.retry.backoff(y)));}if(!o)throw f??new Error("Exhausted all retries");let a=await o.json();if(x(a)){if(!o.ok)throw new n(`${a.error}, command was: ${JSON.stringify(e.body)}`);return a}return {result:a}}};function x(t){return t&&typeof t=="object"&&("result"in t||"error"in t)}var r=class{payload;endpoint;constructor(e,s){this.payload=e,this.endpoint=s;}async exec(e){let{result:s,error:o}=await e.request({body:this.payload,path:[this.endpoint]});if(o)throw new n(o);if(typeof s>"u")throw new Error("Request did not return a result");return s}};var p=class extends r{constructor(e){super(e.ids,"delete");}};var l=class extends r{constructor(e){super({...e},"query");}};var u=class extends r{constructor(e){super({...e},"upsert");}};var c=class extends r{constructor(e){super({...e},"fetch");}};var m=class extends r{constructor(e){super(e,"range");}};var d=class extends r{constructor(){super([],"reset");}};var h=class{client;constructor(e){this.client=e;}delete=e=>new p(e).exec(this.client);query=e=>new l(e).exec(this.client);upsert=e=>new u(e).exec(this.client);fetch=e=>new c(e).exec(this.client);reset=()=>new d().exec(this.client);range=e=>new m(e).exec(this.client)};var b=class t extends h{constructor(e){if("request"in e){super(e);return}(e.url.startsWith(" ")||e.url.endsWith(" ")||/\r|\n/.test(e.url))&&console.warn("The vector url contains whitespace or newline, which can cause errors!"),(e.token.startsWith(" ")||e.token.endsWith(" ")||/\r|\n/.test(e.token))&&console.warn("The vector token contains whitespace or newline, which can cause errors!");let s=new i({baseUrl:e.url,retry:e.retry,headers:{authorization:`Bearer ${e.token}`},cache:e.cache||"no-store",signal:e.signal});super(s);}static fromEnv(e){let s=process?.env.UPSTASH_VECTOR_REST_URL;if(!s)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_URL`");let o=process?.env.UPSTASH_VECTOR_REST_TOKEN;if(!o)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_TOKEN`");return new t({...e,url:s,token:o})}};
+
+export { b as Index };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@upstash/vector",
+  "description": "An HTTP/REST based Vector DB client built on top of Upstash REST API.",
+  "module": "./dist/index.mjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "version": "v0.1.0-alpha",
+  "keywords": [
+    "vector",
+    "upstash",
+    "db"
+  ],
+  "author": "Oguzhan Olguncu <oguzhan@upstash.com>",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "bugs": {
+    "url": "https://github.com/upstash/vector/issues"
+  },
+  "scripts": {
+    "test": "bun test src --coverage --bail --coverageSkipTestFiles=[test-utils.ts]",
+    "fmt": "bunx biome check --apply ./src",
+    "build": "tsup",
+    "prepare": "husky install"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@biomejs/biome": "^1.4.1",
+    "bun-types": "latest",
+    "husky": "^8.0.3",
+    "tsup": "latest"
+  }
+}