# @financial-times/n-es-client

Latest version **7.0.0** (published 2025-03-18) · 0 weekly downloads

## Install

```sh
npm install @financial-times/n-es-client
pnpm add @financial-times/n-es-client
yarn add @financial-times/n-es-client
bun add @financial-times/n-es-client
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 7.0.0 |
| Published | 2025-03-18 |
| First published | 2017-04-03 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | 20.x \|\| 22.x |
| Dependencies | 3 |
| Unpacked size | 22 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| Maintainers | the-ft, rowanmanning, chee, alexwilson, aendra, emmalewis, notlee, seraph2000, hamza.samih, robertboulton, robgodfrey |

## Links

- npm: https://www.npmjs.com/package/@financial-times/n-es-client
- Repository: git@github.com:Financial-Times/n-es-client
- Homepage: https://github.com/Financial-Times/n-es-client
- npm.io page: https://npm.io/package/@financial-times/n-es-client

## Dependencies (3)

- [http-errors](https://npm.io/package/http-errors.md) ^1.8.0
- [signed-aws-es-fetch](https://npm.io/package/signed-aws-es-fetch.md) ^1.6.0
- [@dotcom-reliability-kit/logger](https://npm.io/package/@dotcom-reliability-kit/logger.md) ^2.2.6

## Recent versions

- 7.0.0 (latest) — 2025-03-18
- 3.0.3-beta.1 (pre-release) — 2022-04-21
- 6.0.1 — 2024-05-08
- 6.0.0 — 2024-05-07
- 5.1.0 — 2024-04-09
- 5.0.0 — 2023-08-07
- 4.2.1 — 2023-01-24
- 4.2.0 — 2023-01-24
- 4.1.0 — 2022-07-13
- 4.0.0 — 2022-04-21
- 3.0.2 — 2021-05-19
- 3.0.1 — 2021-03-24
- 3.0.0 — 2021-03-03
- 2.0.0 — 2021-02-19
- 1.8.0 — 2020-03-12
- … 22 more at https://npm.io/package/@financial-times/n-es-client/versions

## README

# n-es-client

[![CircleCI](https://img.shields.io/circleci/project/github/Financial-Times/n-es-client/main.svg)](https://circleci.com/gh/Financial-Times/n-es-client) ![Coveralls Coverage](https://img.shields.io/coveralls/github/Financial-Times/n-es-client/main.svg) [![NPM version](https://img.shields.io/npm/v/@financial-times/n-es-client.svg)](https://www.npmjs.com/package/@financial-times/n-es-client)

A very thin wrapper around [signed fetch][1] and [http-errors][2] to search and retrieve content from our Elasticsearch clusters in a simple, DRY manner.

```js
const client = require('@financial-times/n-es-client');

client.get('cce58e8e-158c-11e7-80f4-13e067d5072c').then((data) => { … });
```

## Installation

```sh
# install from NPM
$ npm i -S @financial-times/n-es-client

# add Elasticsearch read AWS access key
export ES_AWS_ACCESS_KEY=123

# add Elasticsearch read AWS secret access key
export ES_AWS_SECRET_ACCESS_KEY=456
```

### Doppler compatibility

Set your secret name as `ES_AWS_ACCESS_KEY_ID` for the AWS ACCESS KEY, and this library will write its value to `ES_AWS_ACCESS_KEY` so that `signed-aws-es-fetch` accepts it

## Usage

All methods return a promise. If a request errors then it will be rejected with an appropriate HTTP error. Each method accepts an options object that will be preserved verbatim and sent with the request, either stringified as part of the URL or as the `POST` body.

All methods have an optional `timeout` argument that defaults to 3 seconds.

Some methods allow a custom `dataHandler` argument that will receive and may manipulate the raw response from Elasticsearch instead of the default handler.

It is _highly recommended_ to always use [source filtering][3] to fetch only the fields you require.

### `.get(uuid[, options][, timeout])`

Get a content item by UUID. Returns the content source.

#### Example

```js
client.get('cce58e8e-158c-11e7-80f4-13e067d5072c', { _source: ['id', 'title'] })
```

### `.mget(options[, timeout][, dataHandler])`

Get multiple content items by UUID. By default returns an array of content sources for the items that were found but allows an optional custom data handler function.

#### Example

```js
client.mget({
	ids: ['cce58e8e-158c-11e7-80f4-13e067d5072c', '0615fc8c-1558-11e7-80f4-13e067d5072c']
})

client.mget({
	docs: [
		{ _id: 'cce58e8e-158c-11e7-80f4-13e067d5072c', _source: ['title'] },
		{ _id: '0615fc8c-1558-11e7-80f4-13e067d5072c', _source: ['title'] }
	]
})
```

### `.search(options[, timeout][, dataHandler])`

Get content items by search query (the full [query DSL][4] is available). The default sort order is by `publishedDate` descending and with a query `size` of 10. By default returns an array of content sources for the items that matched but allows an optional custom data handler function.

#### Example

```js
client.search({
	_source: ['id', 'title'],
	query: {
		term: { 'annotations.id': 'dbb0bdae-1f0c-11e4-b0cb-b2227cce2b54' }
	},
	size: 100
});
```

### `.count(query[, timeout])`

Get the number of items by search query (the full [query DSL][4] is available). Returns a number.

#### Example

```js
client.count({
	query: {
		term: { 'annotations.id': 'dbb0bdae-1f0c-11e4-b0cb-b2227cce2b54' }
	}
});
```

### `.msearch(queries[, timeout][, dataHandler])`

Perform multiple search queries with one request. By default returns an array of query responses including total matches and content sources for the items that were found but allows an optional custom data handler function. Returns an array of result sets in the format `[ { total: number, hits: [] } ]`.

#### Example

```js
client.msearch([
	{ query: { term: { 'annotations.id': 'cce58e8e-158c-11e7-80f4-13e067d5072c' } } },
	{ query: { term: { 'annotations.id': '0615fc8c-1558-11e7-80f4-13e067d5072c' } } }
])
```

### `.concept(uuid[, timeout])`

Get a single concept by UUID. Returns an object or `undefined` if no matches were found.

[1]: https://github.com/matthew-andrews/signed-aws-es-fetch
[2]: https://www.npmjs.com/package/http-errors
[3]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-source-filtering.html
[4]: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html

## Environments

You can configure the Elasticsearch environment to use by setting the `N_ES_CLIENT_ENV` environment variable to either `development` or `production`. If this environment variable is not set it defaults to `production`.

---
_Source: https://npm.io/package/@financial-times/n-es-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._