No native build steps, pod installs, or Android linking are required. This is a pure Node.js package.

Project setup

1. Copy the source/ directory into your project, e.g. vendor/opensearch-js/.
2. Install the runtime dependencies listed above.
3. Point your module resolution at the vendored copy, or use it directly via the installed npm package. If using the vendored source, add a path alias in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@opensearch-project/opensearch": ["./vendor/opensearch-js/index.js"]
    }
  }
}

4. Set the following environment variables before running your application:

OPENSEARCH_URL=https://localhost:9200
OPENSEARCH_USERNAME=admin
OPENSEARCH_PASSWORD=admin
# For AWS-managed OpenSearch:
AWS_REGION=us-east-1

5. For TypeScript projects, ensure "esModuleInterop": true and "resolveJsonModule": true are set in tsconfig.json.
6. For ESM projects, import from index.mjs or use the exports field in package.json (resolved automatically by Node.js 12+).

Public API

Client

import { Client } from '@opensearch-project/opensearch';

const client = new Client({
  node: string | string[] | NodeOptions | NodeOptions[];
  auth?: { username: string; password: string } | { apiKey: string };
  ssl?: { rejectUnauthorized?: boolean; ca?: string | Buffer };
  maxRetries?: number;
  requestTimeout?: number;
  sniffOnStart?: boolean;
});

The primary entry point. Instantiate once and reuse across the application. Exposes all API namespaces as properties (e.g., client.index(), client.search(), client.indices.create()). Emits lifecycle events via the events constants.

Transport

import { Transport } from '@opensearch-project/opensearch';

class Transport {
  request(
    params: { method: string; path: string; querystring?: object; body?: object },
    options?: TransportRequestOptions,
    callback?: Function
  ): Promise<ApiResponse>;
}

Handles the low-level HTTP request lifecycle: retries, sniffing, serialization, and connection selection. Pass a custom Transport subclass to Client constructor to intercept or modify all requests.

ConnectionPool

import { ConnectionPool } from '@opensearch-project/opensearch';

class ConnectionPool {
  addConnection(url: string | object): Connection;
  removeConnection(connection: Connection): ConnectionPool;
  getConnection(options?: { filter?: Function; selector?: Function }): Connection | null;
  update(nodes: object[]): ConnectionPool;
}

Manages the pool of live Connection instances. Use directly when building custom load-balancing logic or integrating with service discovery. CloudConnectionPool is a subclass tuned for Elastic Cloud endpoints; it is included but rarely needed for OpenSearch.

errors

import { errors } from '@opensearch-project/opensearch';

// Available error classes:
errors.ConfigurationError     // bad client config
errors.ConnectionError        // network-level failure
errors.TimeoutError           // request timed out
errors.ResponseError          // non-2xx HTTP response (contains .meta with statusCode, body)
errors.SerializationError     // JSON serialization failed
errors.DeserializationError   // JSON deserialization failed
errors.NoLivingConnectionsError
errors.NotCompatibleError

Import individual error classes to write targeted catch blocks and distinguish network failures from cluster-level errors.

Working examples

Scenario - Basic CRUD and search

Connect to a local OpenSearch node, create an index, index a document, and run a match query.

import { Client } from '@opensearch-project/opensearch';

const client = new Client({
  node: process.env.OPENSEARCH_URL ?? 'https://localhost:9200',
  auth: {
    username: process.env.OPENSEARCH_USERNAME ?? 'admin',
    password: process.env.OPENSEARCH_PASSWORD ?? 'admin',
  },
  ssl: { rejectUnauthorized: false },
});

async function main() {
  // Create index
  await client.indices.create({
    index: 'products',
    body: {
      mappings: {
        properties: {
          name: { type: 'text' },
          price: { type: 'float' },
        },
      },
    },
  });

  // Index a document
  await client.index({
    index: 'products',
    id: '1',
    body: { name: 'Widget', price: 9.99 },
    refresh: 'wait_for',
  });

  // Search
  const response = await client.search({
    index: 'products',
    body: { query: { match: { name: 'widget' } } },
  });

  console.log(response.body.hits.hits);

  // Delete index
  await client.indices.delete({ index: 'products' });
}

main().catch(console.error);

Scenario - AWS SigV4 authentication (Amazon OpenSearch Service)

Use AwsSigv4Signer from lib/aws to sign requests with AWS credentials before they are sent.

import { Client } from '@opensearch-project/opensearch';
import { AwsSigv4Signer } from '@opensearch-project/opensearch/lib/aws';
import { defaultProvider } from '@aws-sdk/credential-provider-node';

const client = new Client({
  ...AwsSigv4Signer({
    region: process.env.AWS_REGION ?? 'us-east-1',
    service: 'es', // use 'aoss' for Serverless
    getCredentials: defaultProvider(),
  }),
  node: `https://${process.env.OPENSEARCH_DOMAIN_ENDPOINT}`,
});

async function listIndices() {
  const { body } = await client.cat.indices({ format: 'json' });
  console.log(body);
}

listIndices().catch(console.error);

Scenario - Error handling with typed error classes

Distinguish between a missing document (404 ResponseError) and a network-level failure (ConnectionError).

import { Client, errors } from '@opensearch-project/opensearch';

const client = new Client({
  node: process.env.OPENSEARCH_URL ?? 'https://localhost:9200',
  auth: { username: 'admin', password: 'admin' },
  ssl: { rejectUnauthorized: false },
});

async function getDocument(index: string, id: string) {
  try {
    const { body } = await client.get({ index, id });
    return body._source;
  } catch (err) {
    if (err instanceof errors.ResponseError && err.meta.statusCode === 404) {
      console.warn(`Document ${id} not found in ${index}`);
      return null;
    }
    if (err instanceof errors.ConnectionError) {
      console.error('Cannot reach OpenSearch cluster:', err.message);
      throw err;
    }
    throw err;
  }
}

getDocument('products', 'missing-id').then(console.log);

File walkthrough

• index.js - CommonJS barrel; re-exports Client, Transport, ConnectionPool, Connection, Serializer, errors, events.
• index.mjs - ESM barrel; re-exports the same symbols for "type": "module" projects.
• index.d.ts - Aggregated TypeScript declarations; the primary type source for IDE autocompletion.
• lib/Client.js - Client class definition; mounts all API namespaces and manages Transport lifecycle.
• lib/Transport.js - HTTP request dispatch, retry logic, sniffing scheduler.
• lib/Connection.js - Single node HTTP/HTTPS connection wrapper built on Node.js http/https.
• lib/Serializer.js - JSON serialization/deserialization with secure-json-parse and json11.
• lib/errors.js - All error class definitions exported under errors.
• lib/pool/ - BaseConnectionPool, ConnectionPool, CloudConnectionPool for node lifecycle management.
• lib/aws/ - AwsSigv4Signer and AwsSigv4SignerError for AWS IAM authentication.
• api/ - Auto-generated per-namespace API files (_core, indices, cluster, ml, knn, ism, etc.).
• api_generator/ - Mustache templates and Node.js scripts to regenerate api/ from the OpenSearch spec.
• guides/ - Focused markdown guides for SSL, authentication, index templates, bulk operations, etc.
• samples/ - Self-contained Node.js scripts that demonstrate end-to-end workflows.
• scripts/ - CI and developer tooling (license header injection, API spec download).
• package.json - Package metadata, entry points, and runtime dependency declarations.

Common pitfalls and fixes

• Self-signed certificate rejection: Local or dev OpenSearch nodes use self-signed certs; set ssl: { rejectUnauthorized: false } in the Client constructor or supply ssl.ca with the CA bundle.
• AWS SigV4 service mismatch: Amazon OpenSearch Service uses 'es'; Amazon OpenSearch Serverless uses 'aoss'. Using the wrong value returns 403 Forbidden.
• ESM/CJS interop: index.mjs re-exports from index.js via a default import; if bundlers complain about dual-package hazard, pin to one entry point and set "esModuleInterop": true in tsconfig.json.
• ResponseError body access: The HTTP response body is at err.meta.body, not err.body. Check err.meta.statusCode for the HTTP status code.
• Stale connection pool after cluster restart: Enable sniffOnStart: true and sniffInterval: 30000 so the pool re-discovers nodes automatically.
• Bulk API missing newline delimiter: The bulk API requires each action/source pair to be newline-delimited JSON; use client.helpers.bulk() (available on Client) to avoid manually constructing the body.

Vibe-coding prompt template

I have vendored the OpenSearch JavaScript client source from @opensearch-project/opensearch@3.6.0
into the directory `source/` of my project. I also have USAGE.md in the same location.

Please help me integrate the OpenSearch client into my existing Node.js/TypeScript project by:

1. Reading USAGE.md and source/index.js to understand available exports.
2. Creating a singleton client module (e.g., `src/lib/opensearchClient.ts`) that instantiates
   `Client` from `source/index.js` using environment variables for the node URL and credentials.
3. Adding typed helper functions for: indexing a document, fetching a document by ID,
   running a search query, and deleting an index.
4. Wrapping all calls in try/catch blocks that distinguish `errors.ResponseError` (cluster errors)
   from `errors.ConnectionError` (network failures) using the `errors` export from `source/index.js`.
5. If my cluster is on AWS, applying `AwsSigv4Signer` from `source/lib/aws/index.js` using
   `@aws-sdk/credential-provider-node`.
6. Writing a brief Jest test file that mocks `Transport#request` and verifies my helper functions.

Do not invent any API methods. Only use exports visible in source/index.js and source/lib/aws/index.js.
Show all import paths explicitly. Ask me for my cluster URL and auth method before writing code.

License and credit

This source is licensed under the Apache License, Version 2.0. See source/LICENSE.txt for the full text. Portions are derived from the original elasticsearch-js client, also Apache 2.0 licensed; see source/NOTICE.txt for attribution details.

Upstream package: @opensearch-project/opensearch - GitHub: opensearch-project/opensearch-js.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Automation, Utilities & Developer Tools

Free