From 8cd8dd3410f5132ac3d2fe3434a4d5c8986423d4 Mon Sep 17 00:00:00 2001 From: delvedor Date: Wed, 13 Feb 2019 07:51:39 +0100 Subject: [PATCH] Updated docs indentation and added more examples --- docs/breaking-changes.asciidoc | 126 +++++++++++++++++++++++++++++++-- docs/configuration.asciidoc | 68 +++++++++--------- docs/extend.asciidoc | 72 +++++++++---------- docs/usage.asciidoc | 18 ++--- 4 files changed, 201 insertions(+), 83 deletions(-) diff --git a/docs/breaking-changes.asciidoc b/docs/breaking-changes.asciidoc index b9c79bb61..e70228331 100644 --- a/docs/breaking-changes.asciidoc +++ b/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) +}) +---- diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc index 3e8bad483..5392cec24 100644 --- a/docs/configuration.asciidoc +++ b/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' - maxRetries: 5, - requestTimeout: 60000, - sniffOnStart: true + node: 'http://localhost:9200' + maxRetries: 5, + requestTimeout: 60000, + 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'), - ssl: 'ssl options', - agent: 'http agent options', - id: 'custom node id', - headers: { 'custom': 'headers' } - roles: { - master: true, - data: true, - ingest: true, - ml: false - } + url: new URL('http://localhost:9200'), + ssl: 'ssl options', + agent: 'http agent options', + id: 'custom node id', + headers: { 'custom': 'headers' } + roles: { + master: true, + data: true, + ingest: true, + 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) { - // your code - } + request (params, options, callback) { + // 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) { - // your code - super.request(params, options, callback) - } + request (params, options, callback) { + // your code + 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) { - // your code - super.markAlive(connection) - } + markAlive (connection) { + // your code + 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) { - // your code - } + request (params, callback) { + // 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) { - // your code - } + serialize (object) { + // your code + } } const client = new Client({ - Serializer: MySerializer + Serializer: MySerializer }) ---- \ No newline at end of file diff --git a/docs/extend.asciidoc b/docs/extend.asciidoc index 98c4390ca..643dbb2b5 100644 --- a/docs/extend.asciidoc +++ b/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) { - const { - body, - index, - method, - ...querystring - } = params + return function supersearch (params, options) { + const { + body, + index, + method, + ...querystring + } = params - // params validation - if (body == null) { - 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) + // params validation + if (body == null) { + 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) + } }) client.extend('utility.index', ({ makeRequest }) => { - return function _index (params, options) { - // your code - } + return function _index (params, options) { + // your code + } }) client.extend('utility.delete', ({ makeRequest }) => { - return function _delete (params, options) { - // your code - } + return function _delete (params, options) { + // your code + } }) client.supersearch(...) diff --git a/docs/usage.asciidoc b/docs/usage.asciidoc index 733bc6e5c..15fbf5dc4 100644 --- a/docs/usage.asciidoc +++ b/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) { - logger.error(err) - } else { - logger.info(meta) - } + if (err) { + logger.error(err) + } else { + logger.info(meta) + } }) ---- \ No newline at end of file