Updated docs indentation and added more examples

docs/breaking-changes.asciidoc

@@ -14,13 +14,43 @@ Every breaking change was carefully weighted, and every breaking change has soli
 
 * There is no more an integrated logger. The client now is an event emitter that emits the following events: `request`, `response`, and `error`.
 
-* The code is no longer shipped with all the versions of the API, but only the same major version of the package.
+* The code is no longer shipped with all the versions of the API, but only the same major version of the package, this means that if you are using Elasticsearch `v6`, you will be required to install `@elasticelasticsearc@6`, and so on.
 
 * The internals are completely different, so if you used to tweak a lot with them, you will need to refactor your code, while the surface API should be almost the same.
 
 * No more browser support, for that will be built another module, `@elastic/elasticsearch-browser`. This module is intended for Node.js only.
 
-* The returned value of an API call will no longer be the `body`, `statusCode`, and `headers` for callbacks and just the `body` for promises. The new returned value will be a unique object containing the `body`, `statusCode`, `headers`, and `warnings`, for both callback and promises. With the `asStream` parameter you can get the original HTTP response stream if the case you need to pipe it to another response for a forwarding use case.
+* The returned value of an API call will no longer be the `body`, `statusCode`, and `headers` for callbacks and just the `body` for promises. The new returned value will be a unique object containing the `body`, `statusCode`, `headers`, and `warnings`, for both callback and promises. +
+With the `asStream` parameter you can get the original HTTP response stream if the case you need to pipe it to another response for a forwarding use case.
+[source,js]
+----
+// before
+const body = await client.search({
+  index: 'my-index',
+  body: { foo: 'bar' }
+})
+
+client.search({
+  index: 'my-index',
+  body: { foo: 'bar' }
+}, (err, body, statusCode, headers) => {
+  if (err) console.log(err)
+})
+
+// after
+const { body, statusCode, headers, warnings } = await client.search({
+  index: 'my-index',
+  body: { foo: 'bar' }
+})
+
+client.search({
+  index: 'my-index',
+  body: { foo: 'bar' }
+}, (err, { body, statusCode, headers, warnings }) => {
+  if (err) console.log(err)
+})
+----
+
 
 * Errors: there is no longer a custom error class for every HTTP status code (such as `BadRequest` or `NotFound`), but there is a single `ResponseError` instead.
 All the error classes have been renamed, and now all are suffixed with `Error` at the end. +
@@ -37,9 +67,97 @@ Errors that has been renamed:
 ** `Serialization` => `SerializationError`
 ** `Serialization` => `DeserializationError`
 
-* You must specify the port number in the configuration
+* You must specify the port number in the configuration. In the previous version you can specifiy the host and port in a variety of ways, with the new client there is only one via the `node` parameter.
 
 * The plugins option has been removed, if you want to extend the client now you should use the client.extend API.
-There is a clear distinction between the API related parameters and the client related configurations, the parameters `ignore`, `headers`, `requestTimeout` and `maxRetries` are no longer part of the API object, and you should specify them in a second option object.
+[source,js]
+----
+// before
+const { Client } = require('elasticsearch')
+const client = new Client({ plugins: [...] })
+
+// after
+const { Client } = require('@elastic/elasticsearch')
+const client = new Client({ ... })
+client.extend(...)
+----
+
+* There is a clear distinction between the API related parameters and the client related configurations, the parameters `ignore`, `headers`, `requestTimeout` and `maxRetries` are no longer part of the API object, and you should specify them in a second option object.
+[source,js]
+----
+// before
+const body = await client.search({
+  index: 'my-index',
+  body: { foo: 'bar' },
+  ignore: [404]
+})
+
+client.search({
+  index: 'my-index',
+  body: { foo: 'bar' },
+  ignore: [404]
+}, (err, body, statusCode, headers) => {
+  if (err) console.log(err)
+})
+
+// after
+const { body, statusCode, headers, warnings } = await client.search({
+  index: 'my-index',
+  body: { foo: 'bar' }
+}, {
+  ignore: [404]
+})
+
+client.search({
+  index: 'my-index',
+  body: { foo: 'bar' }
+}, {
+  ignore: [404]
+}, (err, { body, statusCode, headers, warnings }) => {
+  if (err) console.log(err)
+})
+----
 
 * The `transport.request` method will no longer accept the `query` key, but the `querystring` key instead (which can be a string or an object), furthermore, you need to send a bulk-like request, instead of the `body` key, you should use the `bulkBody` key. Also in this method, the client specific parameters should be passed as a second object.
+[source,js]
+----
+// before
+const body = await client.transport.request({
+  method: 'GET',
+  path: '/my-index/_search',
+  body: { foo: 'bar' },
+  query: { bar: 'baz' }
+  ignore: [404]
+})
+
+client.transport.request({
+  method: 'GET',
+  path: '/my-index/_search',
+  body: { foo: 'bar' },
+  query: { bar: 'baz' }
+  ignore: [404]
+}, (err, body, statusCode, headers) => {
+  if (err) console.log(err)
+})
+
+// after
+const { body, statusCode, headers, warnings } = await client.transport.request({
+  method: 'GET',
+  path: '/my-index/_search',
+  body: { foo: 'bar' },
+  querystring: { bar: 'baz' }
+}, {
+  ignore: [404]
+})
+
+client.transport.request({
+  method: 'GET',
+  path: '/my-index/_search',
+  body: { foo: 'bar' },
+  querystring: { bar: 'baz' }
+}, {
+  ignore: [404]
+}, (err, { body, statusCode, headers, warnings }) => {
+  if (err) console.log(err)
+})
+----

docs/configuration.asciidoc

@@ -7,10 +7,10 @@ The client is designed to be easily configured as you see fit for your needs, fo
 const { Client } = require('@elastic/elasticsearch')
 
 const client = new Client({
-    node: 'http://localhost:9200'
+  node: 'http://localhost:9200'
-    maxRetries: 5,
+  maxRetries: 5,
-    requestTimeout: 60000,
+  requestTimeout: 60000,
-    sniffOnStart: true
+  sniffOnStart: true
 })
 ----
 
@@ -28,17 +28,17 @@ Or it can be an object (or an array of objects) that represents the node
 [source,js]
 ----
 node: {
-    url: new URL('http://localhost:9200'),
+  url: new URL('http://localhost:9200'),
-    ssl: 'ssl options',
+  ssl: 'ssl options',
-    agent: 'http agent options',
+  agent: 'http agent options',
-    id: 'custom node id',
+  id: 'custom node id',
-    headers: { 'custom': 'headers' }
+  headers: { 'custom': 'headers' }
-    roles: {
+  roles: {
-        master: true,
+    master: true,
-        data: true,
+    data: true,
-        ingest: true,
+    ingest: true,
-        ml: false
+    ml: false
-    }
+  }
 }
 ----
 
@@ -138,9 +138,9 @@ This class is responsible to perform the request to Elasticsearch and handling e
 const { Client, Transport } = require('@elastic/elasticsearch')
 
 class MyTransport extends Transport {
-    request (params, options, callback) {
+  request (params, options, callback) {
-        // your code
+    // your code
-    }
+  }
 }
 
 const client = new Client({
@@ -152,10 +152,10 @@ Sometimes you just need to inject a little snippet of your code and then continu
 [source,js]
 ----
 class MyTransport extends Transport {
-    request (params, options, callback) {
+  request (params, options, callback) {
-        // your code
+    // your code
-        super.request(params, options, callback)
+    super.request(params, options, callback)
-    }
+  }
 }
 ----
 
@@ -167,10 +167,10 @@ Moreover, the connection pool will handle the resurrection strategies and the up
 const { Client, ConnectionPool } = require('@elastic/elasticsearch')
 
 class MyConnectionPool extends ConnectionPool {
-    markAlive (connection) {
+  markAlive (connection) {
-        // your code
+    // your code
-        super.markAlive(connection)
+    super.markAlive(connection)
-    }
+  }
 }
 
 const client = new Client({
@@ -185,13 +185,13 @@ This class represents a single Node, it holds every information we have on the n
 const { Client, Connection } = require('@elastic/elasticsearch')
 
 class MyConnection extends Connection {
-    request (params, callback) {
+  request (params, callback) {
-        // your code
+    // your code
-    }
+  }
 }
 
 const client = new Client({
-    Connection: MyConnection
+  Connection: MyConnection
 })
 ----
 
@@ -208,12 +208,12 @@ This class is responsible of the serialization of every request, it offers the f
 const { Client, Serializer } = require('@elastic/elasticsearch')
 
 class MySerializer extends Serializer {
-    serialize (object) {
+  serialize (object) {
-        // your code
+    // your code
-    }
+  }
 }
 
 const client = new Client({
-    Serializer: MySerializer
+  Serializer: MySerializer
 })
 ----

docs/extend.asciidoc

@@ -11,50 +11,50 @@ const { Client } = require('@elastic/elasticsearch')
 const client = new Client({ node: 'http://localhost:9200' })
 
 client.extend('supersearch', ({ makeRequest, ConfigurationError }) => {
-    return function supersearch (params, options) {
+  return function supersearch (params, options) {
-        const {
+    const {
-            body,
+      body,
-            index,
+      index,
-            method,
+      method,
-            ...querystring
+      ...querystring
-        } = params
+    } = params
 
-        // params validation
+    // params validation
-        if (body == null) {
+    if (body == null) {
-            throw new ConfigurationError('Missing required parameter: body')
+      throw new ConfigurationError('Missing required parameter: body')
-        }
-
-        // build request object
-        const request = {
-            method: method || 'POST',
-            path: `/${encodeURIComponent(index)}/_search_`,
-            body,
-            querystring
-        }
-
-        // build request options object
-        const requestOptions = {
-            ignore: options.ignore || null,
-            requestTimeout: options.requestTimeout || null,
-            maxRetries: options.maxRetries || null,
-            asStream: options.asStream || false,
-            headers: options.headers || null
-        }
-
-        return makeRequest(request, requestOptions)
     }
+
+    // build request object
+    const request = {
+      method: method || 'POST',
+      path: `/${encodeURIComponent(index)}/_search_`,
+      body,
+      querystring
+    }
+
+    // build request options object
+    const requestOptions = {
+      ignore: options.ignore || null,
+      requestTimeout: options.requestTimeout || null,
+      maxRetries: options.maxRetries || null,
+      asStream: options.asStream || false,
+      headers: options.headers || null
+    }
+
+    return makeRequest(request, requestOptions)
+  }
 })
 
 client.extend('utility.index', ({ makeRequest }) => {
-    return function _index (params, options) {
+  return function _index (params, options) {
-        // your code
+    // your code
-    }
+  }
 })
 
 client.extend('utility.delete', ({ makeRequest }) => {
-    return function _delete (params, options) {
+  return function _delete (params, options) {
-        // your code
+    // your code
-    }
+  }
 })
 
 client.supersearch(...)

docs/usage.asciidoc

@@ -162,7 +162,7 @@ a|Emitted before to send the actual request to Elasticsearch.
 [source,js]
 ----
 client.on('request', (err, meta) => {
-    console.log(err, meta)
+  console.log(err, meta)
 })
 ----
 `meta` is an object that contains the following informations:
@@ -178,7 +178,7 @@ a|Emitted before to send the actual request to Elasticsearch.
 [source,js]
 ----
 client.on('response', (err, meta) => {
-    console.log(err, meta)
+  console.log(err, meta)
 })
 ----
 `meta` is an object that contains the following informations:
@@ -194,7 +194,7 @@ a|Emitted before to send the actual request to Elasticsearch.
 [source,js]
 ----
 client.on('sniff', (err, meta) => {
-    console.log(err, meta)
+  console.log(err, meta)
 })
 ----
 `meta` is an object that contains the following informations:
@@ -207,7 +207,7 @@ a|Emitted before to send the actual request to Elasticsearch.
 [source,js]
 ----
 client.on('resurrect', (err, meta) => {
-    console.log(err, meta)
+  console.log(err, meta)
 })
 ----
 `meta` is an object that contains the following informations:
@@ -227,10 +227,10 @@ const { Client } = require('@elastic/elasticsearch')
 const client = new Client({ node: 'http://localhost:9200' })
 
 client.on('response', (err, meta) => {
-    if (err) {
+  if (err) {
-        logger.error(err)
+    logger.error(err)
-    } else {
+  } else {
-        logger.info(meta)
+    logger.info(meta)
-    }
+  }
 })
 ----