OpenSearch JavaScript Client

@opensearch-project/opensearch is the official Node.js client for OpenSearch, the community-driven fork of Elasticsearch. It wraps the full OpenSearch REST API in a single fluent Client object, handling connection pooling, request retries, node discovery (sniffing), gzip compression, and response deserialization so application code can focus on queries instead of HTTP plumbing.

The client ships first-class support for AWS-hosted OpenSearch through dedicated aws and aws-v3 entry points that sign requests with SigV4, plus TypeScript typings, a Helpers module for bulk and scroll operations, and a generated API surface that tracks OpenSearch’s REST endpoints release over release.

What You Get

• A generated API client covering the full OpenSearch REST surface (indices, documents, search, cluster, security, and more)
• Built-in connection pooling with round-robin and cloud-aware strategies, plus automatic node sniffing and resurrection
• First-class AWS SigV4 signing via dedicated aws and aws-v3 subpath exports for Amazon OpenSearch Service
• TypeScript type definitions and a typed Helpers module for bulk indexing and scroll-based search
• Configurable transport with gzip compression, request/response event hooks, and typed error classes for every failure mode

Common Use Cases

• Server-side full-text search - querying and aggregating documents from a Node.js backend
• Bulk data ingestion - indexing large document sets via the Helpers bulk API with automatic batching
• AWS-hosted OpenSearch - connecting to Amazon OpenSearch Service with SigV4-signed requests
• Cluster administration - managing indices, mappings, and cluster health from application or ops tooling

Under The Hood

Architecture The Client class (lib/Client.js) extends a generated OpenSearchAPI base (api/OpenSearchApi.js) that mounts every REST namespace as promise-returning methods, and composes a Transport (lib/Transport.js), a ConnectionPool/CloudConnectionPool (lib/pool/), a Serializer, and a Helpers module. The transport layer owns the request lifecycle - retries, gzip compression, node sniffing, resurrection of failed nodes, and typed event emission (request/response/sniff/resurrect/serialization/deserialization) - while the pool tracks per-node health and selection strategy. Crucially, the large api/ directory (35+ namespace folders) is not hand-written: it is produced by api_generator/, a separate build-time tool that regenerates the client’s method surface from OpenSearch’s API specification, keeping the library in lockstep with server capability changes release over release.

Tech Stack A dependency-light Node.js (>=14) library shipping dual CommonJS/ESM entry points (index.js/index.mjs) with matching .d.ts typings. It uses Node’s built-in http/https via a custom Connection class, hpagent for proxy-aware keep-alive agents, aws4 for SigV4 request signing, secure-json-parse/json11 for hardened JSON parsing, and ms/debug for time formatting and logging. Tooling is ESLint + Prettier for style, tap for the test runner, and tsd for validating the shipped TypeScript definitions against real usage.

Code Quality The test suite spans unit, acceptance, integration, bundler-compatibility, and type-testing directories, with roughly twenty unit test files covering the client, transport, pool, serializer, and error classes individually. package.json wires a test:coverage-90 script enforcing 90% branch/function/line/statement coverage, and CI workflows (Node.js, integration, bundler) run on every change. Errors are modeled as a typed hierarchy rooted in OpenSearchClientError (TimeoutError, ConnectionError, SerializationError, ResponseError, ConfigurationError, etc.) rather than generic thrown exceptions, giving callers named failure modes to branch on.

API Design The generated API mirrors OpenSearch’s own REST endpoint names and parameters closely, so anyone familiar with the HTTP API can predict the client’s method shapes. The constructor accepts a single options object handling node/nodes/cloud/auth/ssl configuration uniformly, and the AWS-signing variant is opt-in through separate aws/aws-v3 subpath imports rather than bloating the default import. Every generated method carries TypeScript types, and extensive supporting docs - a USER_GUIDE, UPGRADING and COMPATIBILITY notes, eight topic guides under guides/, and runnable samples - lower the ramp-up cost. The main rough edge is the size of the generated surface and the lack of a higher-level query builder, leaving callers to construct raw OpenSearch query DSL objects by hand.