pinecone-ts-client

The Pinecone TypeScript SDK is the official client for Pinecone, a managed vector database used to store, search, and manage high-dimensional embeddings for semantic search, recommendation systems, and retrieval-augmented generation. It gives TypeScript and Node.js developers a fully-typed surface for creating and configuring serverless or pod-based indexes, then upserting, querying, fetching, updating, and deleting vectors against them.

Beyond core vector operations, the client bundles Pinecone’s integrated inference API (embedding generation and reranking without a separate SDK) and the Pinecone Assistant API for building RAG-powered chat assistants that can ingest files and hold conversations. The package is built and tested for both standard Node.js and edge runtimes, with a typed error hierarchy that maps HTTP failures to specific exception classes.

What You Get

• Full CRUD operations for indexes and vectors through strongly-typed methods with a generic metadata type parameter
• Support for both serverless (auto-scaling) and pod-based (dedicated) index architectures
• Integrated inference client for embedding generation and reranking without a separate embeddings SDK
• Pinecone Assistant API for creating RAG-powered chat assistants that ingest files and hold conversations
• Bulk import operations for loading large vector datasets from object storage
• A typed error hierarchy (PineconeBadRequestError, PineconeAuthorizationError, PineconeNotFoundError, etc.) for precise failure handling

Common Use Cases

• Building semantic search over product catalogs, documentation, or support tickets
• Powering retrieval-augmented generation (RAG) pipelines for LLM applications
• Recommendation systems based on embedding similarity
• Multi-tenant vector storage using namespaces to isolate customer data within a shared index
• Bulk-loading historical embeddings from object storage into a fresh index

Under The Hood

Architecture The Pinecone class in src/pinecone.ts is the facade that composes four functional areas: control (index/collection/backup lifecycle management in src/control), data (vector CRUD and bulk import in src/data, exposed via the Index class), inference (embedding/reranking in src/inference), and assistant (RAG chat and file management in src/assistant). Each hand-written wrapper (e.g. createIndex.ts, upsert.ts) is a thin typed layer over auto-generated low-level REST clients under src/pinecone-generated-ts-fetch and -alpha, regenerated from Pinecone’s OpenAPI specs via codegen/build-oas.sh. IndexHostSingleton and AssistantHostSingleton cache resolved per-index/per-assistant hostnames so repeated calls don’t re-resolve on every request. Error handling is centralized in src/errors, with handling.ts mapping HTTP status codes to a typed exception hierarchy. This layered generated-plus-handwritten design means a change to the underlying OpenAPI spec ripples through the generated clients first, then the hand-written wrappers that depend on them.

Tech Stack Written in TypeScript (~99% of the codebase) targeting TypeScript >=5.2 and Node.js >=20, built with plain tsc (no bundler). Testing runs on Jest 30 with ts-jest, plus @edge-runtime/jest-environment for edge-runtime-specific test suites, jest-progress-bar-reporter, and separate Jest configs for unit, integration (node/edge), and smoke (mocked) test runs. Linting uses ESLint 10 with typescript-eslint and eslint-plugin-import-x; formatting is enforced with Prettier 3.9. Docs are generated with TypeDoc and published via a dedicated GitHub Actions workflow. No runtime dependencies are declared — the client relies on the platform’s native fetch, which is part of how it supports edge runtimes alongside Node.js.

Code Quality The repo carries roughly 97 test files spread across per-module __tests__ directories (control, data, errors, assistant, inference), a dedicated src/integration/ suite that exercises both Node and edge runtimes against real Pinecone resources, a mocked smoke-test suite (jest.config.smoke.js), and standalone ts-compilation-test/ts-external-app-test directories that verify the published package still compiles and works correctly when consumed as an external dependency. Errors are modeled as a typed class hierarchy (PineconeBadRequestError, PineconeAuthorizationError, PineconeNotFoundError, and others) rather than generic throws, each carrying request context and actionable messaging. Five GitHub Actions workflows (pr.yml, testing.yml, testing-cleanup.yml, release.yml, build-and-publish-docs.yml) run linting, the full test matrix, and doc publishing on every change.

API Design The public API is built around a small number of composable entrypoints: new Pinecone({ apiKey }), then pc.index() for vector operations or pc.assistant() for RAG chat. A generic RecordMetadata type parameter gives compile-time safety over arbitrary metadata shapes on vectors. The integrated-inference path (createIndexForModel plus upsertRecords/searchRecords) lets callers hand Pinecone raw text and skip standing up a separate embeddings client entirely — a meaningful reduction in boilerplate versus vector-database clients that leave embedding generation to the caller. An extensive guides/ directory (index management, data operations, inference, assistant, TypeScript features, upgrading, FAQ) backs the generated API reference with task-oriented documentation.