[7.x][DOCS] Fine-tunes the Node.Js client breaking changes section. (#1013)
This commit is contained in:
István Zoltán Szabó
committed by
GitHub
GitHub
parent
95847f030c
commit
c51fbfaafd
@ -1,27 +1,44 @@
|
||||
[[breaking-changes]]
|
||||
== Breaking changes coming from the old client
|
||||
|
||||
If you were already using the previous version of this client --i.e. the one you used to install with `npm install elasticsearch`-- you will encounter some breaking changes.
|
||||
If you were already using the previous version of this client – the one you used
|
||||
to install with `npm install elasticsearch` – you will encounter some breaking
|
||||
changes.
|
||||
|
||||
|
||||
=== Don’t panic!
|
||||
|
||||
Every breaking change was carefully weighed, and each is justified. Furthermore, the new codebase has been rewritten with modern JavaScript and has been carefully designed to be easy to maintain.
|
||||
Every breaking change was carefully weighed, and each is justified. Furthermore,
|
||||
the new codebase has been rewritten with modern JavaScript and has been
|
||||
carefully designed to be easy to maintain.
|
||||
|
||||
|
||||
=== Breaking changes
|
||||
|
||||
* Minimum supported version of Node.js is `v8`.
|
||||
|
||||
* Everything has been rewritten using ES6 classes to help users extend the defaults more easily.
|
||||
* Everything has been rewritten using ES6 classes to help users extend the
|
||||
defaults more easily.
|
||||
|
||||
* There is no longer an integrated logger. The client now is an event emitter that emits the following events: `request`, `response`, and `error`.
|
||||
* There is no longer 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 that of the package’s major version, This means that if you are using Elasticsearch `v6`, you will be required to install `@elastic/elasticsearch@6`, and so on.
|
||||
* The code is no longer shipped with all the versions of the API, but only that
|
||||
of the package’s major version. This means that if you are using {es} `v6`, you
|
||||
are required to install `@elastic/elasticsearch@6`, and so on.
|
||||
|
||||
* The internals are completely different, so if you used to tweak them a lot, you will need to refactor your code. The public API should be almost the same.
|
||||
* The internals are completely different, so if you used to tweak them a lot,
|
||||
you will need to refactor your code. The public API should be almost the same.
|
||||
|
||||
* No more browser support, for that will be distributed via another module, `@elastic/elasticsearch-browser`. This module is intended for Node.js only.
|
||||
* There is no longer browser support, for that will be distributed via 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 only the `body` for promises. The new returned
|
||||
value will be a unique object containing the `body`, `statusCode`, `headers`,
|
||||
`warnings`, and `meta`, for both callback and promises.
|
||||
|
||||
* 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`, `warnings`, and `meta`, for both callback and promises.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -53,14 +70,20 @@ client.search({
|
||||
----
|
||||
|
||||
|
||||
* Errors: there is no longer a custom error class for every HTTP status code (such as `BadRequest` or `NotFound`). There is instead a single `ResponseError`. Each error class has been renamed, and now each is suffixed with `Error` at the end.
|
||||
* Errors: there is no longer a custom error class for every HTTP status code
|
||||
(such as `BadRequest` or `NotFound`). There is instead a single `ResponseError`.
|
||||
Every error class has been renamed, and now each is suffixed with `Error` at the
|
||||
end.
|
||||
|
||||
* Errors that have been removed: `RequestTypeError`, `Generic`, and all the status code specific errors (such as `BadRequest` or `NotFound`).
|
||||
* Removed errors: `RequestTypeError`, `Generic`, and all the status code
|
||||
specific errors (such as `BadRequest` or `NotFound`).
|
||||
|
||||
* Errors that have been added: `ConfigurationError` (in case of bad configurations) and `ResponseError`, which contains all the data you may need to handle the specific error, such as `statusCode`, `headers`, `body`, and `message`.
|
||||
* Added errors: `ConfigurationError` (in case of bad configurations) and
|
||||
`ResponseError` that contains all the data you may need to handle the specific
|
||||
error, such as `statusCode`, `headers`, `body`, and `message`.
|
||||
|
||||
|
||||
* Errors that has been renamed:
|
||||
* Renamed errors:
|
||||
|
||||
** `RequestTimeout` (408 statusCode) => `TimeoutError`
|
||||
** `ConnectionFault` => `ConnectionError`
|
||||
@ -68,9 +91,12 @@ client.search({
|
||||
** `Serialization` => `SerializationError`
|
||||
** `Serialization` => `DeserializationError`
|
||||
|
||||
* You must specify the port number in the configuration. In the previous version you can specify the host and port in a variety of ways, with the new client there is only one via the `node` parameter.
|
||||
* You must specify the port number in the configuration. In the previous
|
||||
version, you can specify the host and port in a variety of ways. With the new
|
||||
client, there is only one way to do it, 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.
|
||||
* The `plugins` option has been removed. If you want to extend the client now,
|
||||
you should use the `client.extend` API.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -84,7 +110,10 @@ 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.
|
||||
* 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 need to specify them
|
||||
in a second option object.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -121,7 +150,11 @@ client.search({
|
||||
})
|
||||
----
|
||||
|
||||
* 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.
|
||||
* The `transport.request` method no longer accepts the `query` key. Use the
|
||||
`querystring` key instead (which can be a string or an object). You also
|
||||
need to send a bulk-like request instead of the `body` key, use the `bulkBody`
|
||||
key. In this method, the client specific parameters should be passed as a second
|
||||
object.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -168,7 +201,8 @@ client.transport.request({
|
||||
|
||||
=== Talk is cheap. Show me the code.
|
||||
|
||||
Following you will find a snippet of code with the old client, followed by the same code logic, but with the new client.
|
||||
You can find a code snippet with the old client below followed by the same code
|
||||
logic but with the new client.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
|
||||
Reference in New Issue
Block a user