@upstash/vector 1.0.3 → 1.0.4

package/README.md

@@ -1,5 +1,10 @@
 # Upstash Vector Node.js Client · ![license](https://img.shields.io/npm/l/%40upstash%2Fvector) [![Tests](https://github.com/upstash/vector-js/actions/workflows/tests.yaml/badge.svg)](https://github.com/upstash/vector-js/actions/workflows/tests.yaml) ![npm (scoped)](https://img.shields.io/npm/v/@upstash/vector) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@upstash/vector) ![npm weekly download](https://img.shields.io/npm/dw/%40upstash%2Fvector)
 
+> [!NOTE]  
+> **This project is in GA Stage.**
+>
+> The Upstash Professional Support fully covers this project. It receives regular updates, and bug fixes. The Upstash team is committed to maintaining and improving its functionality.
+
 `@upstash/vector` is an HTTP/REST based client for Typescript, built on top of [Upstash REST API](https://upstash.com/docs/vector/api/endpoints/).
 
 It is the only connectionless (HTTP based) Vector client and designed for:

package/dist/index.d.mts

@@ -74,6 +74,7 @@ type FetchResult<TMetadata = Record<string, unknown>> = Vector<TMetadata> | null
 type QueryCommandPayload = {
     vector: number[];
     topK: number;
+    filter?: string;
     includeVectors?: boolean;
     includeMetadata?: boolean;
 };
@@ -147,13 +148,18 @@ declare class Index$1<TIndexMetadata extends Record<string, unknown> = Record<st
      *
      * @example
      * ```js
-     * await index.query({ topK: 3, vector: [ 0.22, 0.66 ]})
+     * await index.query({
+     *  topK: 3,
+     *  vector: [ 0.22, 0.66 ],
+     *  filter: "age >= 23 and (type = \'turtle\' OR type = \'cat\')"
+     * });
      * ```
      *
      * @param {Object} args - The arguments for the query command.
      * @param {number[]} args.vector - An array of numbers representing the feature vector for the query.
      *                                This vector is utilized to find the most relevant items in the index.
      * @param {number} args.topK - The desired number of top results to be returned, based on relevance or similarity to the query vector.
+     * @param {string} [args.filter] - An optional filter string to be used in the query. The filter string is used to narrow down the query results.
      * @param {boolean} [args.includeVectors=false] - When set to true, includes the feature vectors of the returned items in the response.
      * @param {boolean} [args.includeMetadata=false] - When set to true, includes additional metadata of the returned items in the response.
      *

package/dist/index.d.ts

@@ -74,6 +74,7 @@ type FetchResult<TMetadata = Record<string, unknown>> = Vector<TMetadata> | null
 type QueryCommandPayload = {
     vector: number[];
     topK: number;
+    filter?: string;
     includeVectors?: boolean;
     includeMetadata?: boolean;
 };
@@ -147,13 +148,18 @@ declare class Index$1<TIndexMetadata extends Record<string, unknown> = Record<st
      *
      * @example
      * ```js
-     * await index.query({ topK: 3, vector: [ 0.22, 0.66 ]})
+     * await index.query({
+     *  topK: 3,
+     *  vector: [ 0.22, 0.66 ],
+     *  filter: "age >= 23 and (type = \'turtle\' OR type = \'cat\')"
+     * });
      * ```
      *
      * @param {Object} args - The arguments for the query command.
      * @param {number[]} args.vector - An array of numbers representing the feature vector for the query.
      *                                This vector is utilized to find the most relevant items in the index.
      * @param {number} args.topK - The desired number of top results to be returned, based on relevance or similarity to the query vector.
+     * @param {string} [args.filter] - An optional filter string to be used in the query. The filter string is used to narrow down the query results.
      * @param {boolean} [args.includeVectors=false] - When set to true, includes the feature vectors of the returned items in the response.
      * @param {boolean} [args.includeMetadata=false] - When set to true, includes additional metadata of the returned items in the response.
      *

package/dist/index.js

@@ -1 +1 @@
-"use strict";var x=Object.defineProperty;var w=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var U=Object.prototype.hasOwnProperty;var S=(r,e)=>{for(var t in e)x(r,t,{get:e[t],enumerable:!0})},M=(r,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let s of E(e))!U.call(r,s)&&s!==t&&x(r,s,{get:()=>e[s],enumerable:!(n=w(e,s))||n.enumerable});return r};var _=r=>M(x({},"__esModule",{value:!0}),r);var P={};S(P,{Index:()=>b});module.exports=_(P);var a=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??(t=>Math.exp(t)*50)}}async request(e){let t={cache:this.options.cache,method:"POST",headers:this.headers,body:JSON.stringify(e.body),keepalive:!0,signal:this.options.signal},n=null,s=null;for(let y=0;y<=this.retry.attempts;y++)try{n=await fetch([this.baseUrl,...e.path??[]].join("/"),t);break}catch(g){if(this.options.signal?.aborted){let R=new Blob([JSON.stringify({result:this.options.signal.reason??"Aborted"})]),C={status:200,statusText:this.options.signal.reason??"Aborted"};n=new Response(R,C);break}s=g,await new Promise(R=>setTimeout(R,this.retry.backoff(y)))}if(!n)throw s??new Error("Exhausted all retries");let f=await n.json();if(!n.ok)throw new a(`${f.error}`);return{result:f.result,error:f.error}}};var o=class{payload;endpoint;constructor(e,t){this.payload=e,this.endpoint=t}async exec(e){let{result:t,error:n}=await e.request({body:this.payload,path:[this.endpoint]});if(n)throw new a(n);if(typeof t>"u")throw new Error("Request did not return a result");return t}};var p=class extends o{constructor(e){let t=[];Array.isArray(e)?t.push(...e):t.push(e),super(t,"delete")}};var c=class extends o{constructor(e){super(e,"query")}};var d=class extends o{constructor(e){super(e,"upsert")}};var u=class extends o{constructor([e,t]){super({ids:e,...t},"fetch")}};var m=class extends o{constructor(e){super(e,"range")}};var l=class extends o{constructor(){super([],"reset")}};var h=class extends o{constructor(){super([],"info")}};var T=class{client;constructor(e){this.client=e}delete=e=>new p(e).exec(this.client);query=e=>new c(e).exec(this.client);upsert=e=>new d(e).exec(this.client);fetch=(...e)=>new u(e).exec(this.client);reset=()=>new l().exec(this.client);range=e=>new m(e).exec(this.client);info=()=>new h().exec(this.client)};var b=class r extends T{constructor(e){if(typeof e<"u"&&"request"in e){super(e);return}let t=e?.token??process.env.NEXT_PUBLIC_UPSTASH_VECTOR_REST_TOKEN??process.env.UPSTASH_VECTOR_REST_TOKEN,n=e?.url??process.env.NEXT_PUBLIC_UPSTASH_VECTOR_REST_URL??process.env.UPSTASH_VECTOR_REST_URL;if(!t)throw new Error("UPSTASH_VECTOR_REST_TOKEN is missing!");if(!n)throw new Error("UPSTASH_VECTOR_REST_URL is missing!");(n.startsWith(" ")||n.endsWith(" ")||/\r|\n/.test(n))&&console.warn("The vector url contains whitespace or newline, which can cause errors!"),(t.startsWith(" ")||t.endsWith(" ")||/\r|\n/.test(t))&&console.warn("The vector token contains whitespace or newline, which can cause errors!");let s=new i({baseUrl:n,retry:e?.retry,headers:{authorization:`Bearer ${t}`},cache:e?.cache||"no-store",signal:e?.signal});super(s)}static fromEnv(e){let t=process?.env.UPSTASH_VECTOR_REST_URL;if(!t)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_URL`");let n=process?.env.UPSTASH_VECTOR_REST_TOKEN;if(!n)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_TOKEN`");return new r({...e,url:t,token:n})}};0&&(module.exports={Index});
+"use strict";var x=Object.defineProperty;var w=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var U=Object.prototype.hasOwnProperty;var S=(r,e)=>{for(var t in e)x(r,t,{get:e[t],enumerable:!0})},M=(r,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let s of E(e))!U.call(r,s)&&s!==t&&x(r,s,{get:()=>e[s],enumerable:!(n=w(e,s))||n.enumerable});return r};var _=r=>M(x({},"__esModule",{value:!0}),r);var P={};S(P,{Index:()=>g});module.exports=_(P);var a=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??(t=>Math.exp(t)*50)}}async request(e){let t={cache:this.options.cache,method:"POST",headers:this.headers,body:JSON.stringify(e.body),keepalive:!0,signal:this.options.signal},n=null,s=null;for(let y=0;y<=this.retry.attempts;y++)try{n=await fetch([this.baseUrl,...e.path??[]].join("/"),t);break}catch(b){if(this.options.signal?.aborted){let R=new Blob([JSON.stringify({result:this.options.signal.reason??"Aborted"})]),C={status:200,statusText:this.options.signal.reason??"Aborted"};n=new Response(R,C);break}s=b,await new Promise(R=>setTimeout(R,this.retry.backoff(y)))}if(!n)throw s??new Error("Exhausted all retries");let T=await n.json();if(!n.ok)throw new a(`${T.error}`);return{result:T.result,error:T.error}}};var o=class{payload;endpoint;constructor(e,t){this.payload=e,this.endpoint=t}async exec(e){let{result:t,error:n}=await e.request({body:this.payload,path:[this.endpoint]});if(n)throw new a(n);if(typeof t>"u")throw new Error("Request did not return a result");return t}};var p=class extends o{constructor(e){let t=[];Array.isArray(e)?t.push(...e):t.push(e),super(t,"delete")}};var c=class extends o{constructor(e){super(e,"query")}};var d=class extends o{constructor(e){super(e,"upsert")}};var u=class extends o{constructor([e,t]){super({ids:e,...t},"fetch")}};var m=class extends o{constructor(e){super(e,"range")}};var l=class extends o{constructor(){super([],"reset")}};var h=class extends o{constructor(){super([],"info")}};var f=class{client;constructor(e){this.client=e}delete=e=>new p(e).exec(this.client);query=e=>new c(e).exec(this.client);upsert=e=>new d(e).exec(this.client);fetch=(...e)=>new u(e).exec(this.client);reset=()=>new l().exec(this.client);range=e=>new m(e).exec(this.client);info=()=>new h().exec(this.client)};var g=class r extends f{constructor(e){if(typeof e<"u"&&"request"in e){super(e);return}let t=e?.token??process.env.NEXT_PUBLIC_UPSTASH_VECTOR_REST_TOKEN??process.env.UPSTASH_VECTOR_REST_TOKEN,n=e?.url??process.env.NEXT_PUBLIC_UPSTASH_VECTOR_REST_URL??process.env.UPSTASH_VECTOR_REST_URL;if(!t)throw new Error("UPSTASH_VECTOR_REST_TOKEN is missing!");if(!n)throw new Error("UPSTASH_VECTOR_REST_URL is missing!");(n.startsWith(" ")||n.endsWith(" ")||/\r|\n/.test(n))&&console.warn("The vector url contains whitespace or newline, which can cause errors!"),(t.startsWith(" ")||t.endsWith(" ")||/\r|\n/.test(t))&&console.warn("The vector token contains whitespace or newline, which can cause errors!");let s=new i({baseUrl:n,retry:e?.retry,headers:{authorization:`Bearer ${t}`},cache:e?.cache||"no-store",signal:e?.signal});super(s)}static fromEnv(e){let t=process?.env.UPSTASH_VECTOR_REST_URL;if(!t)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_URL`");let n=process?.env.UPSTASH_VECTOR_REST_TOKEN;if(!n)throw new Error("Unable to find environment variable: `UPSTASH_VECTOR_REST_TOKEN`");return new r({...e,url:t,token:n})}};0&&(module.exports={Index});

package/dist/index.mjs

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

package/package.json

@@ -1 +1 @@
-{ "name": "@upstash/vector", "version": "v1.0.3", "author": "Oguzhan Olguncu <oguzhan@upstash.com>", "repository": { "type": "git", "url": "https://github.com/upstash/vector-js" }, "main": "./dist/index.js", "module": "./dist/index.mjs", "devDependencies": { "@biomejs/biome": "^1.4.1", "@commitlint/cli": "^18.6.0", "@commitlint/config-conventional": "^18.6.0", "bun-types": "latest", "husky": "^8.0.3", "tsup": "latest", "typescript": "^5.0.0", "vitest": "^1.2.2" }, "bugs": { "url": "https://github.com/upstash/vector/issues" }, "description": "An HTTP/REST based Vector DB client built on top of Upstash REST API.", "files": [ "dist" ], "homepage": "https://upstash.com/vector", "keywords": [ "vector", "upstash", "db" ], "license": "MIT", "scripts": { "test": "bun test src --coverage --bail --coverageSkipTestFiles=[test-utils.ts] && vitest run --typecheck", "fmt": "bunx biome check --apply ./src", "build": "tsup", "prepare": "husky install" }, "types": "./dist/index.d.ts" }
+{ "name": "@upstash/vector", "version": "v1.0.4", "author": "Oguzhan Olguncu <oguzhan@upstash.com>", "repository": { "type": "git", "url": "https://github.com/upstash/vector-js" }, "main": "./dist/index.js", "module": "./dist/index.mjs", "devDependencies": { "@biomejs/biome": "^1.4.1", "@commitlint/cli": "^18.6.0", "@commitlint/config-conventional": "^18.6.0", "bun-types": "latest", "husky": "^8.0.3", "tsup": "latest", "typescript": "^5.0.0", "vitest": "^1.2.2" }, "bugs": { "url": "https://github.com/upstash/vector/issues" }, "description": "An HTTP/REST based Vector DB client built on top of Upstash REST API.", "files": [ "dist" ], "homepage": "https://upstash.com/vector", "keywords": [ "vector", "upstash", "db" ], "license": "MIT", "scripts": { "test": "bun test src --coverage --bail --coverageSkipTestFiles=[test-utils.ts] && vitest run --typecheck", "fmt": "bunx biome check --apply ./src", "build": "tsup", "prepare": "husky install" }, "types": "./dist/index.d.ts" }