= Usage

Use the  client is pretty straightforward, it supports all the public APIs of Elasticsearch, and every method exposes the same signature.

[source,js]
----
const { Client } = require('@elastic/elasticsearch')
const client = new Client({ node: 'http://localhost:9200' })

// promise API
const result = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
})

// callback API
client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, (err, result) => {
  if (err) console.log(err)
})
----

The returned value of every API call is formed as follows:

[source,ts]
----
{
  body: object | boolean
  statusCode: number
  headers: object
  warnings: [string]
}
----

NOTE: The body will be a boolean value when using `HEAD` APIs.

The above valiue will be returned even if there is an error during the execution of the request, this means that you can safely use the https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment[destructuring assignment].

[source,js]
----
// promise API
const { body } = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
})

// callback API
client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, (err, { body }) => {
  if (err) console.log(err)
})
----

=== Request specific options
If needed you can pass request specific options in a second object:
[source,js]
----
// promise API
const result = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
})

// calback API
client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
}, (err, { body }) => {
  if (err) console.log(err)
})
----
The supported request specific options are:
[cols=2*]
|===
|`ignore`
|`[number]` -  HTTP status codes which should not be considered errors for this request. +
_Default:_ `null`

|`requestTimeout`
|`number` - Max request timeout for the request, it overrides the client default. +
_Default:_ `30000`

|`maxRetries`
|`number` - Max number of retries for the request, it overrides the client default. +
_Default:_ `3`

|`compression`
|`string, boolean` - Enables body compression for the request. +
_Options:_ `false`, `'gzip'` +
_Default:_ `false`

|`asStream`
|`boolean` - Instead of getting the parsed body back, you will get the raw Node.js stream of data. +
_Default:_ `false`

|`headers`
|`object` - Custom headers for the request. +
_Default:_ `null`
|===

=== Error handling
The client exposes a variety of error objects, that you can use to enhance your error handling. +
You can find all the error objects inside the `errors` key in the client.

[source,js]
----
const { errors } = require('@elastic/elasticsearch')
console.log(errors)
----

Following you can find the errors exported by the client.
[cols=2*]
|===
|`ElasticsearchClientErrors`
|Every error inherits from this class, it is the basic error generated by the client.

|`TimeoutError`
|Generated when a request exceeds the `requestTimeout` option.

|`ConnectionError`
|Generated when an error occurs during the reequest, it can be a connection error or a malformed stream of data.

|`NoLivingConnectionsError`
|Generated in case of all connections present in the connection pool are dead.

|`SerializationError`
|Generated if the serialization fails.

|`DeserializationError`
|Generated if the deserialization fails.

|`ConfigurationError`
|Generated if there is a malformed configuration or parameter.

|`ResponseError`
|Generated when in case of a `4xx` or `5xx` response.
|===

=== Events
The client is an event emitter, this means that you can listen for its event and add additional logic to your code, without need to change the client internals or your normal usage. +
You can find the events names by access the `events` key of the client.

[source,js]
----
const { events } = require('@elastic/elasticsearch')
console.log(events)
----

The client emits the following events:
[cols=2*]
|===
|`request`
a|Emitted before to send the actual request to Elasticsearch.
[source,js]
----
client.on('request', (err, meta) => {
  console.log(err, meta)
})
----
`meta` is an object that contains the following informations:

* `connection`: the connection instance
* `request`: every parameter that will be sent to Elasticsearch
* `response`: inside this event it will be always `null`.
* `attempts`: how many times the clients has tried to execute this request
* `aborted`: boolean check that is true if the request has been aborted.

|`response`
a|Emitted before to send the actual request to Elasticsearch.
[source,js]
----
client.on('response', (err, meta) => {
  console.log(err, meta)
})
----
`meta` is an object that contains the following informations:

* `connection`: the connection instance
* `request`: every parameter that will be sent to Elasticsearch
* `response`: the Elasticsearch response.
* `attempts`: how many times the clients has tried to execute this request
* `aborted`: boolean check that is true if the request has been aborted.

|`sniff`
a|Emitted before to send the actual request to Elasticsearch.
[source,js]
----
client.on('sniff', (err, meta) => {
  console.log(err, meta)
})
----
`meta` is an object that contains the following informations:

* `hosts`: the list of nodes obtained from Elasticsearch
* `reason`: the reason why the sniff was triggered.

|`resurrect`
a|Emitted before to send the actual request to Elasticsearch.
[source,js]
----
client.on('resurrect', (err, meta) => {
  console.log(err, meta)
})
----
`meta` is an object that contains the following informations:

* `connection`: the connection the client is trying to revive
* `strategy`: the strategy the client is using for reviving the connection
* `isAlive`: boolean value

|===

The event emitter functionality can be useful if you want to log every request, response and error that is happening during the use of the client.

[source,js]
----
const logger = require('my-logger')()
const { Client } = require('@elastic/elasticsearch')
const client = new Client({ node: 'http://localhost:9200' })

client.on('response', (err, meta) => {
  if (err) {
    logger.error(err)
  } else {
    logger.info(meta)
  }
})
----