# opensearch-typescript

> Typescript types for the Opensearch Query DSL

Latest version **1.1.0** (published 2025-10-18) · (ISC OR GPL-3.0) license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install opensearch-typescript
pnpm add opensearch-typescript
yarn add opensearch-typescript
bun add opensearch-typescript
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2025-10-18 |
| First published | 2024-04-18 |
| Weekly downloads | 0 |
| License | (ISC OR GPL-3.0) |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=14.15.0 |
| Dependencies | 3 |
| Unpacked size | 156 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | derrops@derrops.net |
| Maintainers | derrops |
| Keywords | opensearch, types, typescript, query |

## Links

- npm: https://www.npmjs.com/package/opensearch-typescript
- Repository: https://github.com/derrops-net/opensearch-typescript
- Homepage: https://github.com/derrops-net/opensearch-typescript#readme
- Issues: https://github.com/derrops-net/opensearch-typescript/issues
- npm.io page: https://npm.io/package/opensearch-typescript

## Dependencies (3)

- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [type-fest](https://npm.io/package/type-fest.md) ^4.15.0
- [@opensearch-project/opensearch](https://npm.io/package/@opensearch-project/opensearch.md) ^3.2.0

## Alternatives

- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2025-10-18
- 1.0.6 — 2025-05-16
- 1.0.5 — 2025-02-04
- 1.0.4 — 2025-02-04
- 1.0.3 — 2025-02-04
- 1.0.2 — 2025-02-02
- 0.5.41 — 2025-01-29
- 0.5.40 — 2025-01-28
- 0.5.39 — 2025-01-28
- 0.5.38 — 2025-01-27
- 0.5.37 — 2025-01-27
- 0.5.36 — 2025-01-25
- 0.5.34 — 2025-01-25
- 0.5.32 — 2025-01-25
- 0.5.31 — 2024-11-23
- … 42 more at https://npm.io/package/opensearch-typescript/versions

## README

# Opensearch-Typescript

Opensearch Typescript

[![Node.js Package](https://github.com/derrickfutschik/opensearch-typescript/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/derrickfutschik/opensearch-typescript/actions/workflows/npm-publish.yml)

This library can be used to proxy the opensearch client which then provides a more type-rich client. For the most part this is a seemless change, the same requests which worked with `@opensearch-project/opensearch` will work with `opensearch-typescript`, with the exception of **Multi-search** (see workaround below). I wrote this library after experiencing too much difficulty when trying to write opensearch querries in code, I would always have ot write them in the **Dev Tools** console, and then turn them into code, which wasn't too dificult. But what provided me enough motiviation to create this library was then parsing the respones in code was overly complex without a type-system for the respones.

## Usage
To use this library, create the `TypescriptOSProxyClient` client by wrapping the `opensearch Client`:
```typescript
new TypescriptOSProxyClient(client)
```

To have strongly typed query and responses, the requirement is to define a `Search<T,A extends AggsQuery>` whereby `T` represents the type of your document in the index, and `A` is a description of the aggregation query you are planning to perform, which contains the nested aggregation structure, as well as the type of aggregation looking to be performed. With `T` & `A` this provides typescript with enough information to calculate the type of the response from opensearch. For example lets look at the sample ecommerce data and do a query to find the average baes price in a category. I used [quicktype](https://quicktype.io/) to generate the type `Ecommerce` which can be found [here](docs/files/Ecommerce.ts).

```typescript
  type AvgBasePriceByCategoryQuery = Search<Ecommerce, {
    category : {
      agg : "terms",
      aggs : {
        "avg_base_price_in_category" : {
          agg : "avg",
        }
      }
    }
  }>
```

Now when we write this query we get autocomplete suggestions, and highlighting for incorrect type errors:
![screenshot](docs/images/screenshot1.png)

Then to do the search:

```typescript
const search : AvgBasePriceByCategoryQuery = 
{
    "size": 0,
    "aggs": {
    "category": {
        "terms": {
        "field": "category.keyword"
        },
        "aggs" : {
        "avg_base_price_in_category" : {
            "avg" : {
            "field" : "products.base_price"
            }
        }
        }
    }
    }
}

const result = await tsClient.searchTS({
    body : search,
    index : "opensearch_dashboards_sample_data_ecommerce"
})
```
Whilst you will have to specify the `type` of the `search` object, as it's not possible to infer types for this case, however the `result` object you'll notice is strongly typed, having a type of:
``` typescript
const result: SearchResponse<Ecommerce, {
    category: {
        agg: "terms";
        aggs: {
            "avg_base_price_in_category": {
                agg: "avg";
            };
        };
    };
}>
```
This provides proper auto-complete suggestions and compile checks:

**Autocomplete**
![screenshot](docs/images/screenshot2.png)

**Compiler Checks**
![screenshot](docs/images/screenshot3.png)

Drastically reducing programmer errors, and making it just as easy if not easier to write queries within a typescript project.


## Incomplete Client Coverage
Please note this client is not 100% complete, please reach out if parts of the opensearch client are missing and you want to make use of this library, I will do my best to keep this as up-to-date as possible. I also haven't tested all `agg` queries, with all permutations of `number|string` and `dates`.

## Incomplete Types
I have support thus for for:
 - `string`
 - `number`
 - `Date`
 - `boolean`
 - `GeoPoint`

I plan to have strong types for other fields in the future, for not strings can be used.

## Multi-search Limitation
I was not able to map individual values in a dictionary to different types. This meant I couldn't map a collection of requests to a strongly typed collection of responses. The work-around for this was to store the responses of each individual request back onto itself. Because the type information of the request remained in-tact after execution, this was the only way to all the type information in type-script. Obviously this has some paradigm drawbacks, mutating requests as opposed to immutability and functional paradigms It also requires different code if you were to refactor existing opensearh code to make use of this library.


## Elasticsearch
This same approach could be taken with Elasticsearch but unless adoption of this client takes off I don't plan to replicate this in Elasticsearch.

---
_Source: https://npm.io/package/opensearch-typescript · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._