qdrant-js

@qdrant/js-client-rest is the official REST client for Qdrant, an open-source vector similarity search engine used to power semantic search, recommendation systems, and retrieval-augmented generation (RAG) pipelines. Built on the native Fetch API, it runs across Node.js (18+), Deno, and browsers, and exposes a fully typed surface generated directly from Qdrant’s OpenAPI schema.

The client wraps low-level REST calls with ergonomic facade methods for common operations like scroll, count, search, and upsert, while still exposing the raw generated API for anything not covered by the facade. It ships with automatic client-server version compatibility checks on connect, discriminated-union typed error handling per status code, configurable connection pooling via undici, and built-in handling for rate-limited (429) responses.

What You Get

• Fully typed API generated from Qdrant’s OpenAPI schema, covering every REST endpoint
• Ergonomic facade methods (scroll, search, count, upsert, and more) alongside direct access to the raw generated client via .api()
• Automatic client-server version compatibility checking on connect, with console warnings on mismatch
• Discriminated-union typed error handling that lets you branch on HTTP status per operation
• Built-in handling for 429 rate-limit responses via QdrantClientResourceExhaustedError with a parsed retry_after value
• Configurable connection pooling through a custom undici dispatcher on Node.js

Common Use Cases

• Powering semantic search over embeddings stored in a Qdrant collection from a Node.js backend
• Building retrieval-augmented generation (RAG) pipelines that fetch nearest-neighbor context for an LLM prompt
• Managing Qdrant collections (create, index, upsert, delete) from CI/CD or admin scripts
• Running vector similarity search directly from browser or Deno-based edge applications

Under The Hood

Architecture The package follows a thin layered structure: qdrant-client.ts exposes the public QdrantClient class with ergonomic facade methods (scroll, count, search, upsert, and more), each delegating to a generated OpenAPI client built in api-client.ts via createApis()/createClientApi() (openapi/generated_api_client.ts, generated_client_type.ts, generated_schema.ts) — files produced from Qdrant server’s OpenAPI schema via the codegen:openapi-typescript script, keeping the type surface in lockstep with the server. api-client.ts composes a stack of Fetcher middleware (context-headers.ts for per-request headers, a timeout middleware built on AbortController, and a response-normalization middleware that turns 429s into QdrantClientResourceExhaustedError and non-2xx responses into QdrantClientUnexpectedResponseError) around @qdrant/openapi-typescript-fetch’s Fetcher, with dispatcher.ts supplying a custom undici Dispatcher for connection pooling on Node. client-version.ts implements standalone version comparison invoked fire-and-forget from the constructor against the server’s root() response. The core abstraction is the generated OpenAPI client; if Qdrant’s schema changes shape, the generated files and the facade methods (which type against Schemas[…] from types.ts) need regenerating and updating together.

Tech Stack TypeScript 5.9 targeting dual ESM+CJS+browser builds (tsconfig.esm.json/tsconfig.cjs.json, rollup.config.js for bundling), built on @qdrant/openapi-typescript-fetch and undici — Node’s own HTTP/1.1 implementation, used both as the runtime fetch on Node and as a custom Dispatcher for connection pooling. Type generation runs via openapi-typescript against Qdrant’s live OpenAPI schema. The package is published from a pnpm workspace monorepo (qdrant-js) alongside a sibling gRPC client. Build and quality tooling includes pnpm, tsc, rollup, knip for dead-code and type-export checking, ESLint 10 with typescript-eslint, Prettier, and Husky plus lint-staged for pre-commit checks.

Code Quality Tests live under tests/unit (api-client, qdrant-client, and client-version specs) run via Vitest, plus a separate tests/integration suite that exercises a live Qdrant Docker container — giving both isolated unit coverage and real integration coverage. Error handling is explicit and typed: a CustomError base class with QdrantClientConfigError, QdrantClientTimeoutError, QdrantClientResourceExhaustedError, and QdrantClientUnexpectedResponseError subclasses, carrying structured data (like a parsed retry_after) rather than generic strings. Naming is consistent and descriptive; strict TypeScript throughout with generated types keeping the API surface accurate; ESLint plus typescript-eslint enforce lint rules. Chained pre-commit/pre-check scripts run type-checking, dead-code detection, linting, and tests together.

API Design The public API favors ergonomics over minimalism: QdrantClient exposes facade methods with sensible defaults (with_payload=true, with_vector=false) so common calls need only a collection name and a few options, while .api() still exposes the full generated OpenAPI client for anything the facade doesn’t cover. Every public method carries extensive JSDoc describing parameters like consistency and order_by in plain language, meaningfully lowering the barrier to using the API without external docs. Error handling doubles as documentation: discriminated-union errors let TypeScript narrow the response shape per HTTP status, and domain-specific error classes name failure modes instead of forcing callers to inspect generic fetch errors. The main rough edge is the constructor surface (url vs host/port mutual exclusivity, prefix handling), which requires reading validation error messages to get right on first use.