vector-js

@upstash/vector is the official TypeScript client for Upstash Vector, an HTTP/REST-based vector database purpose-built for serverless functions, Cloudflare Workers, and other environments where holding open a persistent TCP connection isn’t practical. Every operation — upsert, query, fetch, range, reset — is a single stateless HTTP call over Upstash’s REST API, making it a natural fit for AWS Lambda, Next.js edge routes, and WebAssembly runtimes where traditional database drivers don’t work.

The client supports dense, sparse, and hybrid vector indexes behind the same API, server-side embedding (upsert plain text via a data field and let Upstash embed it for you), namespace partitioning for multi-tenant isolation, resumable and cursor-paginated queries for large result sets, and metadata filtering with a small query language. Two build targets — Node.js and Cloudflare Workers — share a common core Index class and differ only in how each runtime reads connection credentials from the environment.

What You Get

• Dense, sparse, and hybrid vector upsert/query in one unified API
• Server-side embedding: upsert and query with plain text via the data field instead of pre-computed vectors
• Namespace partitioning to isolate reads/writes within a single index
• Resumable, cursor-based queries (resumableQuery, range) for iterating large result sets
• Built-in retry/backoff and AbortSignal support on every request
• Separate Node.js and Cloudflare Workers entry points sharing one core implementation

Common Use Cases

• Retrieval-augmented generation (RAG) pipelines that need a serverless-friendly vector store
• Semantic search over product catalogs, documentation, or support tickets from edge functions
• Multi-tenant applications that partition embeddings per customer using namespaces
• Hybrid dense+sparse search combining semantic similarity with keyword-style signals

Under The Hood

Architecture The SDK is organized around a command pattern: each API operation (UpsertCommand, QueryCommand, DeleteCommand, FetchCommand, RangeCommand, ResetCommand, UpdateCommand, plus a ResumableQuery and Namespace wrapper, all under src/commands/) extends a shared base and executes against a Requester interface implemented by HttpClient in src/http/index.ts, which POSTs JSON to the configured Upstash REST endpoint with retry/backoff and AbortSignal support. Two platform entry points, src/platforms/nodejs.ts and src/platforms/cloudflare.ts, both extend a shared core Index class defined in src/vector.ts and differ only in how they read connection credentials and attach telemetry headers for their respective runtimes. Path aliases (@commands, @http, @error, @utils) keep the codebase organized by concern, and the core Index class would ripple changes through every command file if the Requester contract changed, since each command’s exec() takes it directly.

Tech Stack Written in strict-mode TypeScript with zero runtime dependencies, relying on the native fetch API rather than axios or node-fetch. Built with tsup into dual ESM/CJS bundles per platform (dist/nodejs.mjs/.js, dist/cloudflare.mjs/.js), wired up via package.json exports for both platform-specific and generic import paths. Tests run on Bun’s built-in test runner (with a Vitest config also present for the Cloudflare Workers example), linting via ESLint 9’s flat config with typescript-eslint and eslint-plugin-unicorn, formatting via Prettier, and commit-message linting via commitlint plus Husky pre-commit hooks. CI runs through several GitHub Actions workflows, including a dedicated npm-retention workflow backed by a Python script.

Code Quality The test suite has one file per command (upsert, delete, fetch, query, range, reset, update, resumable-query, namespace, management namespaces) using shared helpers in test-utils.ts (newHttpClient, randomID, populateSparseIndex, populateHybridIndex) — these are integration-style tests that exercise a live Upstash Vector index rather than a mocked HTTP layer. Errors surface through a small typed UpstashError class instead of generic throws, and the whole codebase is strict TypeScript with consistent naming conventions enforced by ESLint. There is no separate unit-test layer with request mocking, so test reliability depends on a reachable test index.

API Design The public surface stays small and consistent: every command mirrors the REST endpoint it wraps, optional { namespace } options are threaded uniformly through nearly every method, and generics (TIndexMetadata) let callers type their metadata shape once on new Index<Metadata>() and get it back on every query result. Getting started requires only a URL and token (or Index.fromEnv() to skip even that), and extensive inline JSDoc with runnable examples sits directly on every public method, which keeps the API discoverable from an editor’s hover tooltips alone. What distinguishes it from most vector database clients is that it commits fully to being connectionless and HTTP-first — dense, sparse, and hybrid vectors, plus server-side text embedding, all travel through the same stateless request shape, so there’s no separate driver or persistent session object to manage in serverless or edge contexts the way there is with gRPC-based vector database clients.