@upstash/vector 1.2.0 → 1.2.2

package/README.md

@@ -258,6 +258,22 @@ await namespace.fetch(["id-1", "id-2"]);
 
 If you wanna learn more about filtering check: [Metadata Filtering](https://upstash.com/docs/vector/features/filtering)
 
+## Telemetry
+
+This sdk sends anonymous telemetry data to help us improve your experience.
+We collect the following:
+
+- SDK version
+- Platform (Cloudflare, AWS or Vercel)
+- Runtime version (node@18.x)
+
+You can opt out by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable
+to any truthy value.
+
+```sh
+UPSTASH_DISABLE_TELEMETRY=1
+```
+
 ## Troubleshooting
 
 We have a [Discord](upstash.com/discord) for common problems. If you can't find a solution, please [open an issue](https://github.com/upstash/vector-js/issues/new).

package/dist/{chunk-4AKSNQD7.mjs → chunk-MQ3XJEJ2.mjs}

@@ -31,13 +31,15 @@ var HttpClient = class {
     };
   }
   async request(req) {
+    const signal = this.options.signal;
+    const isSignalFunction = typeof signal === "function";
     const requestOptions = {
       cache: this.options.cache,
       method: "POST",
       headers: this.headers,
       body: JSON.stringify(req.body),
       keepalive: true,
-      signal: this.options.signal
+      signal: isSignalFunction ? signal() : signal
     };
     let res = null;
     let error = null;
@@ -46,13 +48,15 @@ var HttpClient = class {
         res = await fetch([this.baseUrl, ...req.path ?? []].join("/"), requestOptions);
         break;
       } catch (error_) {
-        if (this.options.signal?.aborted) {
+        if (requestOptions.signal?.aborted && isSignalFunction) {
+          throw error_;
+        } else if (requestOptions.signal?.aborted) {
           const myBlob = new Blob([
-            JSON.stringify({ result: this.options.signal.reason ?? "Aborted" })
+            JSON.stringify({ result: requestOptions.signal.reason ?? "Aborted" })
           ]);
           const myOptions = {
             status: 200,
-            statusText: this.options.signal.reason ?? "Aborted"
+            statusText: requestOptions.signal.reason ?? "Aborted"
           };
           res = new Response(myBlob, myOptions);
           break;
@@ -148,18 +152,28 @@ var QueryCommand = class extends Command {
 
 // src/commands/client/delete/index.ts
 var DeleteCommand = class extends Command {
-  constructor(id, options) {
+  constructor(payload, options) {
     let endpoint = "delete";
     if (options?.namespace) {
       endpoint = `${endpoint}/${options.namespace}`;
     }
-    const finalArr = [];
-    if (Array.isArray(id)) {
-      finalArr.push(...id);
-    } else {
-      finalArr.push(id);
+    if (typeof payload === "string" || typeof payload === "number") {
+      super(
+        {
+          ids: [payload]
+        },
+        endpoint
+      );
+    } else if (Array.isArray(payload)) {
+      super(
+        {
+          ids: payload
+        },
+        endpoint
+      );
+    } else if (typeof payload === "object") {
+      super(payload, endpoint);
     }
-    super(finalArr, endpoint);
   }
 };
 
@@ -185,13 +199,19 @@ var isVectorPayload = (payload) => {
 
 // src/commands/client/fetch/index.ts
 var FetchCommand = class extends Command {
-  constructor([ids, opts]) {
+  constructor([payload, opts]) {
     let endpoint = "fetch";
     if (opts?.namespace) {
       endpoint = `${endpoint}/${opts.namespace}`;
       delete opts.namespace;
     }
-    super({ ids, ...opts }, endpoint);
+    if (Array.isArray(payload)) {
+      super({ ids: payload, ...opts }, endpoint);
+    } else if (typeof payload === "object") {
+      super({ ...payload, ...opts }, endpoint);
+    } else {
+      throw new Error("Invalid payload");
+    }
   }
 };
 
@@ -227,6 +247,67 @@ var InfoCommand = class extends Command {
   }
 };
 
+// src/commands/client/resumable-query/resume.ts
+var ResumeQueryCommand = class extends Command {
+  constructor(payload) {
+    super(payload, "resumable-query-next");
+  }
+};
+
+// src/commands/client/resumable-query/start.ts
+var StartResumableQueryCommand = class extends Command {
+  constructor(payload, namespace) {
+    let endpoint = "resumable-query";
+    if ("data" in payload) {
+      endpoint = "resumable-query-data";
+    }
+    if (namespace) {
+      endpoint = `${endpoint}/${namespace}`;
+    }
+    super(payload, endpoint);
+  }
+};
+
+// src/commands/client/resumable-query/stop.ts
+var StopResumableQueryCommand = class extends Command {
+  constructor(payload) {
+    super(payload, "resumable-query-end");
+  }
+};
+
+// src/commands/client/resumable-query/index.ts
+var ResumableQuery = class {
+  uuid;
+  start;
+  fetchNext;
+  stop;
+  constructor(payload, client, namespace) {
+    this.start = async () => {
+      const result = await new StartResumableQueryCommand(payload, namespace).exec(
+        client
+      );
+      this.uuid = result.uuid;
+      return result;
+    };
+    this.fetchNext = (additionalK) => {
+      if (!this.uuid) {
+        throw new Error(
+          "The resumable query has already been stopped. Please start another resumable query."
+        );
+      }
+      return new ResumeQueryCommand({ uuid: this.uuid, additionalK }).exec(client);
+    };
+    this.stop = async () => {
+      if (!this.uuid) {
+        throw new Error("Resumable query has not been started. Call start() first.");
+      }
+      const result = await new StopResumableQueryCommand({ uuid: this.uuid }).exec(client);
+      this.uuid = "";
+      return result;
+    };
+  }
+};
+
 // src/commands/client/namespace/index.ts
 var Namespace = class {
   client;
@@ -294,19 +375,21 @@ var Namespace = class {
    */
   update = (args) => new UpdateCommand(args, { namespace: this.namespace }).exec(this.client);
   /**
-   * It's used for retrieving specific items from the index namespace, optionally including
-   * their metadata and feature vectors.
+   * Fetches specific items from the index by their IDs or by an id prefix.
+   *
+   * Note: While using id prefix, the paginated `range` command is recommended to prevent timeouts on large result sets.
    *
    * @example
    * ```js
-   * const fetchIds = ['123', '456'];
-   * const fetchOptions = { includeMetadata: true, includeVectors: false };
-   * const fetchResults = await index.namespace("ns").fetch(fetchIds, fetchOptions);
-   * console.log(fetchResults); // Outputs the fetched items
+   * // Using ids
+   * await index.namespace("ns").fetch(["test-1", "test-2"], { includeMetadata: true });
+   *
+   * // Using id prefix
+   * await index.namespace("ns").fetch({ prefix: "test-" });
    * ```
    *
    * @param {...CommandArgs<typeof FetchCommand>} args - The arguments for the fetch command.
-   * @param {(number[]|string[])} args[0] - An array of IDs of the items to be fetched.
+   * @param {FetchPayload} args[0] - An array of IDs or the id prefix of the items to be fetched.
    * @param {FetchCommandOptions} args[1] - Options for the fetch operation.
    * @param {boolean} [args[1].includeMetadata=false] - Optionally include metadata of the fetched items.
    * @param {boolean} [args[1].includeVectors=false] - Optionally include feature vectors of the fetched items.
@@ -347,34 +430,82 @@ var Namespace = class {
    */
   query = (args) => new QueryCommand(args, { namespace: this.namespace }).exec(this.client);
   /**
-   * Deletes a specific item or items from the index namespace by their ID(s).   *
+   * Initializes a resumable query operation on the vector database.
+   * This method allows for querying large result sets in multiple chunks or implementing pagination.
    *
+   * @template TMetadata
+   * @param {ResumableQueryPayload} args - The arguments for the resumable query.
+   * @param {number} args.maxIdle - The maximum idle time in seconds before the query session expires.
+   * @param {number} args.topK - The number of top results to return in each fetch operation.
+   * @param {number[]} args.vector - The query vector used for similarity search.
+   * @param {boolean} [args.includeMetadata] - Whether to include metadata in the query results.
+   * @param {boolean} [args.includeVectors] - Whether to include vectors in the query results.
+   * @param {Object} [options] - Additional options for the query.
+   * @returns {Promise<ResumableQuery<TMetadata>>} A promise that resolves to a ResumableQuery object.
    * @example
-   * ```js
-   * await index.namespace("ns").delete('test-id')
-   * // { deleted: 1 }
-   * ```
+   * const { result, fetchNext, stop } = await index.namespace("ns").resumableQuery({
+   *   maxIdle: 3600,
+   *   topK: 50,
+   *   vector: [0.1, 0.2, 0.3, ...],
+   *   includeMetadata: true,
+   *   includeVectors: true
+   * }, { namespace: 'my-namespace' });
    *
-   * @param id - List of ids or single id
-   * @returns Number of deleted vectors like `{ deleted: number }`. The number will be 0 if no vectors are deleted.
+   * const firstBatch = await fetchNext(10);
+   * const secondBatch = await fetchNext(10);
+   * await stop(); // End the query session
    */
+  resumableQuery = async (args) => {
+    const resumableQuery = new ResumableQuery(args, this.client, this.namespace);
+    const initialQuery = await resumableQuery.start();
+    const { fetchNext, stop } = resumableQuery;
+    return { fetchNext, stop, result: initialQuery.scores };
+  };
+  /**
+     * Deletes items from the index namespace by id, by id prefix, or by filter.
+     *
+     * @example
+     * ```js
+     * // Delete by id
+     * await index.namespace("ns").delete("test-id");
+  
+     * // Delete by ids
+     * await index.namespace("ns").delete(["test-id1", "test-id2"]);
+  
+     * // Delete by id prefix
+     * await index.namespace("ns").delete({ prefix: "test-" });
+  
+     * // Delete by filter
+     * await index.namespace("ns").delete({ filter: "age >= 23" });
+     * ```
+     *
+     * @param args - A single id, an array of ids, a prefix, or a filter to delete items from the index.
+     * @returns Number of deleted vectors in the format `{ deleted: number }`.If no vectors are deleted, returns `{ deleted: 0 }`.
+     */
   delete = (args) => new DeleteCommand(args, { namespace: this.namespace }).exec(this.client);
   /**
-   * Retrieves a range of items from the index.
+   * Retrieves a paginated range of items from the index. Optionally filter results by an id prefix.
+   * Returns items in batches with a cursor for pagination.
    *
    * @example
    * ```js
-   * const rangeArgs = {
-   *   cursor: 0,
+   * const args = {
    *   limit: 10,
    *   includeVectors: true,
    *   includeMetadata: false
    * };
-   * const rangeResults = await index.namespace("ns").range(rangeArgs);
-   * console.log(rangeResults); // Outputs the result of the range operation
+   * await index.namespace("ns").range(args);
+   *
+   * // Use the cursor to get the next page of results
+   * const nextPage = await index.namespace("ns").range({
+   *   // You have to pass the arguments from the first call
+   *   ...args,
+   *   cursor: rangeResult.nextCursor,
+   * });
    * ```
    *
    * @param {CommandArgs<typeof RangeCommand>} args - The arguments for the range command.
+   * @param {string} [args.prefix] - The prefix of the items to be fetched.
    * @param {number|string} args.cursor - The starting point (cursor) for the range query.
    * @param {number} args.limit - The maximum number of items to return in this range.
    * @param {boolean} [args.includeVectors=false] - Optionally include the feature vectors of the items in the response.
@@ -408,67 +539,6 @@ var UpdateCommand = class extends Command {
   }
 };
 
-// src/commands/client/resumable-query/resume.ts
-var ResumeQueryCommand = class extends Command {
-  constructor(payload) {
-    super(payload, "resumable-query-next");
-  }
-};
-
-// src/commands/client/resumable-query/start.ts
-var StartResumableQueryCommand = class extends Command {
-  constructor(payload, namespace) {
-    let endpoint = "resumable-query";
-    if ("data" in payload) {
-      endpoint = "resumable-query-data";
-    }
-    if (namespace) {
-      endpoint = `${endpoint}/${namespace}`;
-    }
-    super(payload, endpoint);
-  }
-};
-
-// src/commands/client/resumable-query/stop.ts
-var StopResumableQueryCommand = class extends Command {
-  constructor(payload) {
-    super(payload, "resumable-query-end");
-  }
-};
-
-// src/commands/client/resumable-query/index.ts
-var ResumableQuery = class {
-  uuid;
-  start;
-  fetchNext;
-  stop;
-  constructor(payload, client, namespace) {
-    this.start = async () => {
-      const result = await new StartResumableQueryCommand(payload, namespace).exec(
-        client
-      );
-      this.uuid = result.uuid;
-      return result;
-    };
-    this.fetchNext = (additionalK) => {
-      if (!this.uuid) {
-        throw new Error(
-          "The resumable query has already been stopped. Please start another resumable query."
-        );
-      }
-      return new ResumeQueryCommand({ uuid: this.uuid, additionalK }).exec(client);
-    };
-    this.stop = async () => {
-      if (!this.uuid) {
-        throw new Error("Resumable query has not been started. Call start() first.");
-      }
-      const result = await new StopResumableQueryCommand({ uuid: this.uuid }).exec(client);
-      this.uuid = "";
-      return result;
-    };
-  }
-};
-
 // src/commands/management/namespaces/list/index.ts
 var ListNamespacesCommand = class extends Command {
   constructor() {
@@ -504,17 +574,26 @@ var Index = class {
   }
   namespace = (namespace) => new Namespace(this.client, namespace);
   /**
-   * Deletes a specific item or items from the index by their ID(s).   *
-   *
-   * @example
-   * ```js
-   * const result = await index.delete('test-id');
-   * // { deleted: 1 }
-   * ```
-   *
-   * @param id - List of ids or single id
-   * @returns Number of deleted vectors like `{ deleted: number }`. The number will be 0 if no vectors are deleted.
-   */
+     * Deletes items from the index by id, by id prefix, or by filter.
+     *
+     * @example
+     * ```js
+     * // Delete by id
+     * await index.delete("test-id");
+  
+     * // Delete by ids
+     * await index.delete(["test-id1", "test-id2"]);
+  
+     * // Delete by id prefix
+     * await index.delete({ prefix: "test-" });
+  
+     * // Delete by filter
+     * await index.delete({ filter: "age >= 23" });
+     * ```
+     *
+     * @param args - A single id, an array of ids, a prefix, or a filter to delete items from the index.
+     * @returns Number of deleted vectors in the format `{ deleted: number }`.If no vectors are deleted, returns `{ deleted: 0 }`.
+     */
   delete = (args, options) => new DeleteCommand(args, options).exec(this.client);
   /**
    * Queries an index with specified parameters.
@@ -656,23 +735,25 @@ var Index = class {
    */
   update = (args, options) => new UpdateCommand(args, options).exec(this.client);
   /**
-   * It's used for retrieving specific items from the index, optionally including
-   * their metadata and feature vectors.
+   * Fetches specific items from the index by their IDs or by an id prefix.
+   *
+   * Note: While using id prefix, the paginated `range` command is recommended to prevent timeouts on large result sets.
    *
    * @example
    * ```js
-   * const fetchIds = ['123', '456'];
-   * const fetchOptions = { includeMetadata: true, includeVectors: false };
-   * const fetchResults = await index.fetch(fetchIds, fetchOptions);
-   * console.log(fetchResults); // Outputs the fetched items
+   * // Using ids
+   * await index.fetch(["test-1", "test-2"], { includeMetadata: true });
+   *
+   * // Using id prefix
+   * await index.fetch({ prefix: "test-" });
    * ```
    *
    * @param {...CommandArgs<typeof FetchCommand>} args - The arguments for the fetch command.
-   * @param {(number[]|string[])} args - An array of IDs of the items to be fetched.
-   * @param {FetchCommandOptions} args - Options for the fetch operation.
-   * @param {boolean} [args.includeMetadata=false] - Optionally include metadata of the fetched items.
-   * @param {boolean} [args.includeVectors=false] - Optionally include feature vectors of the fetched items.
-   * @param {boolean} [args.metadataUpdateMode="OVERWRITE"] - Specifies whether to overwrite or patch the metadata values.
+   * @param {FetchPayload} args[0] - An array of IDs or the id prefix of the items to be fetched.
+   * @param {FetchCommandOptions} args[1] - Options for the fetch operation.
+   * @param {boolean} [args[1].includeMetadata=false] - Optionally include metadata of the fetched items.
+   * @param {boolean} [args[1].includeVectors=false] - Optionally include feature vectors of the fetched items.
+   * @param {string} [args[1].namespace = ""] - The namespace of the index to fetch items from.
    *
    * @returns {Promise<FetchReturnResponse<TMetadata>[]>} A promise that resolves with an array of fetched items or null if not found, after the command is executed.
    */
@@ -708,27 +789,28 @@ var Index = class {
    */
   reset = (options) => new ResetCommand(options).exec(this.client);
   /**
-   * Retrieves a range of items from the index.
+   * Retrieves a paginated range of items from the index. Optionally filter results by an id prefix.
+   * Returns items in batches with a cursor for pagination.
    *
    * @example
    * ```js
-   * const rangeArgs = {
-   *   cursor: 0,
+   * const args = {
    *   limit: 10,
    *   includeVectors: true,
    *   includeMetadata: false
    * };
-   * const rangeResults = await index.range(rangeArgs);
-   * console.log(rangeResults); // Outputs the result of the range operation
-   * ```
-   *
-   * You can also pass a namespace like:
+   * await index.range(args);
    *
-   * ```js
-   * const rangeResults = await index.range(rangeArgs, { namespace: "ns" });
+   * // Use the cursor to get the next page of results
+   * const nextPage = await index.range({
+   *   // You have to pass the arguments from the first call
+   *   ...args,
+   *   cursor: rangeResult.nextCursor,
+   * });
    * ```
    *
    * @param {CommandArgs<typeof RangeCommand>} args - The arguments for the range command.
+   * @param {string} [args.prefix] - The prefix of the items to be fetched.
    * @param {number|string} args.cursor - The starting point (cursor) for the range query.
    * @param {number} args.limit - The maximum number of items to return in this range.
    * @param {boolean} [args.includeVectors=false] - Optionally include the feature vectors of the items in the response.
@@ -776,10 +858,14 @@ var Index = class {
   deleteNamespace = (namespace) => new DeleteNamespaceCommand(namespace).exec(this.client);
 };
 
+// version.ts
+var VERSION = "v1.2.2";
+
 export {
   HttpClient,
   WeightingStrategy,
   FusionAlgorithm,
   QueryMode,
-  Index
+  Index,
+  VERSION
 };

package/dist/cloudflare.d.mts

@@ -1,5 +1,5 @@
-import { R as RequesterConfig, D as Dict, I as Index$1 } from './vector-FeePts30.mjs';
-export { d as FetchResult, F as FusionAlgorithm, f as InfoResult, Q as QueryMode, e as QueryResult, c as RangeResult, a as Requester, S as SparseVector, U as UpstashRequest, b as UpstashResponse, V as Vector, W as WeightingStrategy } from './vector-FeePts30.mjs';
+import { H as HttpClientConfig, R as RequesterConfig, D as Dict, I as Index$1 } from './vector-7jBuY6ad.mjs';
+export { d as FetchResult, F as FusionAlgorithm, f as InfoResult, Q as QueryMode, e as QueryResult, c as RangeResult, a as Requester, S as SparseVector, U as UpstashRequest, b as UpstashResponse, V as Vector, W as WeightingStrategy } from './vector-7jBuY6ad.mjs';
 
 /**
  * Connection credentials for upstash vector.
@@ -18,7 +18,14 @@ type IndexConfig = {
      * The signal will allow aborting requests on the fly.
      * For more check: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
      */
-    signal?: AbortSignal;
+    signal?: HttpClientConfig["signal"];
+    /**
+     * Enable telemetry to help us improve the SDK.
+     * The sdk will send the sdk version, platform and node version as telemetry headers.
+     *
+     * @default true
+     */
+    enableTelemetry?: boolean;
 } & RequesterConfig;
 /**
  * Serverless vector client for upstash.

package/dist/cloudflare.d.ts

@@ -1,5 +1,5 @@
-import { R as RequesterConfig, D as Dict, I as Index$1 } from './vector-FeePts30.js';
-export { d as FetchResult, F as FusionAlgorithm, f as InfoResult, Q as QueryMode, e as QueryResult, c as RangeResult, a as Requester, S as SparseVector, U as UpstashRequest, b as UpstashResponse, V as Vector, W as WeightingStrategy } from './vector-FeePts30.js';
+import { H as HttpClientConfig, R as RequesterConfig, D as Dict, I as Index$1 } from './vector-7jBuY6ad.js';
+export { d as FetchResult, F as FusionAlgorithm, f as InfoResult, Q as QueryMode, e as QueryResult, c as RangeResult, a as Requester, S as SparseVector, U as UpstashRequest, b as UpstashResponse, V as Vector, W as WeightingStrategy } from './vector-7jBuY6ad.js';
 
 /**
  * Connection credentials for upstash vector.
@@ -18,7 +18,14 @@ type IndexConfig = {
      * The signal will allow aborting requests on the fly.
      * For more check: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
      */
-    signal?: AbortSignal;
+    signal?: HttpClientConfig["signal"];
+    /**
+     * Enable telemetry to help us improve the SDK.
+     * The sdk will send the sdk version, platform and node version as telemetry headers.
+     *
+     * @default true
+     */
+    enableTelemetry?: boolean;
 } & RequesterConfig;
 /**
  * Serverless vector client for upstash.