From ef1c52ba83ecb4b80507ffca7c946d346e1fdd80 Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Mon, 7 Apr 2025 13:39:34 -0500 Subject: [PATCH 1/4] Changelog for 9.0.0 --- docs/release-notes/breaking-changes.md | 40 ++++++++++++++++++++------ docs/release-notes/index.md | 18 ++++++++++-- 2 files changed, 47 insertions(+), 11 deletions(-) diff --git a/docs/release-notes/breaking-changes.md b/docs/release-notes/breaking-changes.md index a05c07b7c..89b769514 100644 --- a/docs/release-notes/breaking-changes.md +++ b/docs/release-notes/breaking-changes.md @@ -3,22 +3,46 @@ navigation_title: "Breaking changes" --- # Elasticsearch JavaScript Client breaking changes [elasticsearch-javascript-client-breaking-changes] + Breaking changes can impact your Elastic applications, potentially disrupting normal operations. Before you upgrade, carefully review the Elasticsearch JavaScript Client breaking changes and take the necessary steps to mitigate any issues. To learn how to upgrade, check [Upgrade](docs-content://deploy-manage/upgrade.md). % ## Next version [elasticsearch-javascript-client-versionnext-breaking-changes] -% ::::{dropdown} Title of breaking change +% ::::{dropdown} Title of breaking change % Description of the breaking change. % For more information, check [PR #](PR link). % **Impact**
Impact of the breaking change. % **Action**
Steps for mitigating deprecation impact. % :::: -% ## 9.0.0 [elasticsearch-javascript-client-900-breaking-changes] +## 9.0.0 [elasticsearch-javascript-client-900-breaking-changes] -% ::::{dropdown} Title of breaking change -% Description of the breaking change. -% For more information, check [PR #](PR link). -% **Impact**
Impact of the breaking change. -% **Action**
Steps for mitigating deprecation impact. -% :::: \ No newline at end of file +::::{dropdown} Improvements to the optional `body` property + +In 8.x, every API function had a `body` property that would provide a place to put arbitrary values that should go in the HTTP request body, even if they were not noted in the specification or documentation. In 9.0, each API function still includes an optional `body` property, but TypeScript's type checker will disallow properties that should go in the root of the object. A `querystring` parameter has also been added that behaves the same as `body`, but inserts its values into the request querystring. + +Also, the logic for where each parameter should be added to an API HTTP request has been updated: + +1. If recognized as a `body` parameter according to the Elasticsearch specification, put it in the JSON body +2. If recognized as a `path` parameter, put it in the URL path +3. If recognized as a `query` parameter or a "common" query parameter (e.g. `pretty`, `error_trace`), put it in the querystring +4. If not recognized, and this API accepts a JSON body, put it in the JSON body +5. If not recognized and this API does not accept a JSON body, put it in the querystring + +The first two steps are identical in 8.x. The final three steps replace the logic from 8.x that put all unrecognized parameters in the querystring. + +**Impact**
Some adjustments to API calls may be necessary for code that used a `body` property 8.x, especially to appease the TypeScript type checker, but it should not have any impact on any code that was not using a `body` property. + +**Action**
Check existing code for use of the `body` property, and move any properties that should be in the root object according to the API function's request type definition. If using TypeScript, the TypeScript type checker will surface most of these issues for you. +:::: + +::::{dropdown} Removal of the default 30-second timeout on all API calls + +The default 30-second timeout on all HTTP requests sent to Elasticsearch has been dropped in favor of having no timeout set at all. The previous behavior still works as it did when setting the `requestTimeout` value. + +See pull request [#2573](https://github.com/elastic/elasticsearch-js/pull/2573) for more information. + +**Impact**
Requests to Elasticsearch that used to time out after 30 seconds will now wait for as long as it takes for Elasticsearch to respond. + +**Action**
In environments where it is not ideal to wait for an API response indefinitely, manually setting the `requestTimeout` option when instantiating the client still works as it did in 8.x. +:::: diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md index 098bb38fb..1db6d2e77 100644 --- a/docs/release-notes/index.md +++ b/docs/release-notes/index.md @@ -15,13 +15,25 @@ To check for security updates, go to [Security announcements for the Elastic sta % ## version.next [elasticsearch-javascript-client-next-release-notes] % ### Features and enhancements [elasticsearch-javascript-client-next-features-enhancements] -% * +% \* % ### Fixes [elasticsearch-javascript-client-next-fixes] -% * +% \* ## 9.0.0 [elasticsearch-javascript-client-900-release-notes] ### Features and enhancements [elasticsearch-javascript-client-900-features-enhancements] -### Fixes [elasticsearch-javascript-client-900-fixes] \ No newline at end of file +- **Compatibility with Elasticsearch 9.0:** All changes and additions to Elasticsearch APIs for its 9.0 release are reflected in this release. +- **Serverless client merged in:** the `@elastic/elasticsearch-serverless` client is being deprecated, and its functionality has been merged back into this client. This should have zero impact on the way the client works, except that a new `serverMode` option has been added. When it's explicitly set to `"serverless"` by a user, a few default settings and behaviors are changed: + + - turns off sniffing and ignores any sniffing-related options + - ignores all nodes passed in config except the first one, and ignores any node filtering and selecting options + - enables compression and `TLSv1_2_method` (same as when configured for Elastic Cloud) + - adds an `elastic-api-version` HTTP header to all requests + - uses `CloudConnectionPool` by default instead of `WeightedConnectionPool` + - turns off vendored `content-type` and `accept` headers in favor or standard MIME types + + Docstrings for types that differ between stack and serverless have also been updated to indicate when that is the case. + +### Fixes [elasticsearch-javascript-client-900-fixes] From 558e3a08506c173de634c3ef230794864a10fb64 Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Mon, 7 Apr 2025 13:42:45 -0500 Subject: [PATCH 2/4] Update title for release notes page --- docs/release-notes/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md index 1db6d2e77..bde71aee6 100644 --- a/docs/release-notes/index.md +++ b/docs/release-notes/index.md @@ -1,5 +1,5 @@ --- -navigation_title: "Elasticsearch JavaScript Client" +navigation_title: "JavaScript client release notes" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/changelog-client.html --- From ce28b823948170591463696471cd0d43c76f4f37 Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Mon, 7 Apr 2025 13:44:06 -0500 Subject: [PATCH 3/4] Grammar tweak --- docs/release-notes/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md index bde71aee6..1aa261e09 100644 --- a/docs/release-notes/index.md +++ b/docs/release-notes/index.md @@ -25,7 +25,7 @@ To check for security updates, go to [Security announcements for the Elastic sta ### Features and enhancements [elasticsearch-javascript-client-900-features-enhancements] - **Compatibility with Elasticsearch 9.0:** All changes and additions to Elasticsearch APIs for its 9.0 release are reflected in this release. -- **Serverless client merged in:** the `@elastic/elasticsearch-serverless` client is being deprecated, and its functionality has been merged back into this client. This should have zero impact on the way the client works, except that a new `serverMode` option has been added. When it's explicitly set to `"serverless"` by a user, a few default settings and behaviors are changed: +- **Serverless client merged in:** the `@elastic/elasticsearch-serverless` client is being deprecated, and its functionality has been merged back into this client. This should have zero impact on the way the client works by default, except that a new `serverMode` option has been added. When it's explicitly set to `"serverless"` by a user, a few default settings and behaviors are changed: - turns off sniffing and ignores any sniffing-related options - ignores all nodes passed in config except the first one, and ignores any node filtering and selecting options From 56f628800fd6140e7c74339e206e1179b453d447 Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Mon, 7 Apr 2025 13:51:04 -0500 Subject: [PATCH 4/4] Adjustment to formatting --- docs/release-notes/breaking-changes.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/release-notes/breaking-changes.md b/docs/release-notes/breaking-changes.md index 89b769514..326fafdaf 100644 --- a/docs/release-notes/breaking-changes.md +++ b/docs/release-notes/breaking-changes.md @@ -17,11 +17,18 @@ Breaking changes can impact your Elastic applications, potentially disrupting no ## 9.0.0 [elasticsearch-javascript-client-900-breaking-changes] -::::{dropdown} Improvements to the optional `body` property +::::{dropdown} Changes to the optional body property In 8.x, every API function had a `body` property that would provide a place to put arbitrary values that should go in the HTTP request body, even if they were not noted in the specification or documentation. In 9.0, each API function still includes an optional `body` property, but TypeScript's type checker will disallow properties that should go in the root of the object. A `querystring` parameter has also been added that behaves the same as `body`, but inserts its values into the request querystring. -Also, the logic for where each parameter should be added to an API HTTP request has been updated: +**Impact**
Some adjustments to API calls may be necessary for code that used a `body` property 8.x, especially to appease the TypeScript type checker, but it should not have any impact on any code that was not using a `body` property. + +**Action**
Check existing code for use of the `body` property, and move any properties that should be in the root object according to the API function's request type definition. If using TypeScript, the TypeScript type checker will surface most of these issues for you. +:::: + +::::{dropdown} Changes to API parameter collation into an HTTP request + +The logic for where each parameter in an API function call should be added to its HTTP request has been updated: 1. If recognized as a `body` parameter according to the Elasticsearch specification, put it in the JSON body 2. If recognized as a `path` parameter, put it in the URL path @@ -31,9 +38,9 @@ Also, the logic for where each parameter should be added to an API HTTP request The first two steps are identical in 8.x. The final three steps replace the logic from 8.x that put all unrecognized parameters in the querystring. -**Impact**
Some adjustments to API calls may be necessary for code that used a `body` property 8.x, especially to appease the TypeScript type checker, but it should not have any impact on any code that was not using a `body` property. +**Impact**
Some parameters that were sent via querystring to Elasticsearch may be sent in the JSON request body, and vice versa. -**Action**
Check existing code for use of the `body` property, and move any properties that should be in the root object according to the API function's request type definition. If using TypeScript, the TypeScript type checker will surface most of these issues for you. +**Action**
If Elasticsearch sends back an error response due to a request not being valid, verify with the client's TypeScript type definitions, or via the docs, that the parameters your code passes are correct. :::: ::::{dropdown} Removal of the default 30-second timeout on all API calls