Version Bump for 3.1.0 Release

CHANGELOG.md

@@ -2,22 +2,43 @@
 
 Inspired by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
-
 ## [Unreleased]
 ### Added
-- Added export of component types ([#955])
 ### Dependencies
 ### Changed
 ### Deprecated
 ### Removed
 ### Fixed
 ### Security
 
+## [3.1.0]
+### Added
+- Added export of component types ([#955](https://github.com/opensearch-project/opensearch-js/issues/955))
+### Dependencies
+### Changed
+- Updated API to match the OpenSearch spec from Jan 09, 2025
+### Deprecated
+### Removed
+### Fixed
+### Security
+
 ## [3.0.0]
 ### Added
 - Added API Generator ([#789](https://github.com/opensearch-project/opensearch-js/issues/789))
 - Added missing API functions and modules.
 - Added missing request and response types.
+### Changed
+- All API functions are now generated from the OpenSearch API specification.
+- API request and response types are now generated from the OpenSearch API specification.
+- Overhauled API codebase and break it into smaller, more manageable files for better readability and maintainability.
+### Deprecated
+- Support for snake_cased API function aliases have been deprecated to conform to JavaScript naming conventions.
+### Removed
+- Removed support for API param aliases. That is, the API functions now only accept params with the exact names specified in the OpenSearch API specification.
+- Removed support for overriding HTTP methods in API functions.
+- Removed support for Node.js 10 and 12. The minimum supported Node.js version is now 14.
+
+## [2.13.0]
 ### Dependencies
 - Bumps `@babel/traverse` from 7.22.8 to 7.24.7
 - Bumps `@types/node` from 22.5.0 to 22.5.4
@@ -29,20 +50,9 @@ Inspired by [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Bumps `simple-git` from 3.24.0 to 3.26.0
 - Bumps `simple-git` from 3.25.0 to 3.26.0
 - Bumps `simple-statistics` from 7.8.4 to 7.8.5
-### Changed
-- All API functions are now generated from the OpenSearch API specification.
-- API request and response types are now generated from the OpenSearch API specification.
-- Overhauled API codebase and break it into smaller, more manageable files for better readability and maintainability.
-### Deprecated
-- Support for snake_cased API function aliases have been deprecated to conform to JavaScript naming conventions.
-### Removed
-- Removed support for API param aliases. That is, the API functions now only accept params with the exact names specified in the OpenSearch API specification.
-- Removed support for overriding HTTP methods in API functions.
-- Removed support for Node.js 10 and 12. The minimum supported Node.js version is now 14.
 ### Fixed
 - Upgrade JSON11 from 1.1.2 to 2.0.0 to ensure UTF-8 safety when stringifying JSON data
 - Fixed typo cause JSON11 parse will always be executed when json string has number inside
-### Security
 
 ## [2.12.0]
 ### Dependencies

UPGRADING.md

@@ -43,7 +43,7 @@ import { Client, type opensearchtypes, type RequestParams } from '@opensearch-pr
 const client = new Client({ node: 'http://localhost:9200' });
 
 const searchRequest: RequestParams.Search = { body: { query: { match: { director: 'miller' } } } };
-const searchResponse = (await client.search(searchBody)).body as opensearchtypes.SearchResponse;
+const searchResponseBody = (await client.search(searchRequest)).body as opensearchtypes.SearchResponse;
 ```
 
 In 3.x:
@@ -53,10 +53,25 @@ import { Client, type API } from '@opensearch-project/opensearch';
 const client = new Client({ node: 'http://localhost:9200' });
 
 const searchRequest: API.Search_Request = { body: { query: { match: { director: 'miller' } } } };
-const searchResponse = (await client.search(searchBody)).body; 
+const searchResponseBody = (await client.search(searchRequest)).body; 
 // Note that the response type is now inferred, and you don't need to cast with `as API.Search_ResponseBody`
 ```
 
+### Typescript - Accessing component types:
+There are 2 ways to access components of the request and response types. For example, if you want to access the type for an index settings object:
+1. Through the Types module (Note that this could result in a breaking change when the name of the component type is changed with the spec)
+```typescript
+
+import { type Types } from '@opensearch-project/opensearch';
+const settings: Types.Indices_Common.IndexSettings = { number_of_shards: 1, number_of_replicas: 0 };
+```
+
+2. Through the API module (This is helpful when you don't know the exact path to the type)
+```typescript
+import { type API } from '@opensearch-project/opensearch';
+const settings: API.Indices_Create_RequestBody['settings'] = { number_of_shards: 1, number_of_replicas: 0 };
+```
+
 ### Typescript - Stricter type definitions:
 In the same vein as the previous point, the typescript definitions are now stricter and more accurate. This means that you may need to update your code to match the new types. For example, the `client.search` function now only accepts a `API.Search_Request` object, and passing an object with a different shape will result in a type error. And since the response object is now inferred to match the proper response type, accessing undefined properties will also result in a type error. 
 

USER_GUIDE.md

@@ -136,17 +136,20 @@ import { Client, type API } from '@opensearch-project/opensearch';
 const client = new Client({ node: 'http://localhost:9200' });
 
 const searchRequest: API.Search_Request = { body: { query: { match: { director: 'miller' } } } }; // is type checked against API.Search_Request
-const searchResponse = (await client.search(searchRequest)).body; // is inferred as API.Search_ResponseBody
+const searchResponseBody = (await client.search(searchRequest)).body; // is inferred as API.Search_ResponseBody
 ```
 
-Note that even though there are types generated for the components of the request and response, only the top-level request and response types are exported. This is intentional! You should NOT access those component types directly, as it can result in breaking changes when the API spec changes. Instead, access the component types through the top-level request and response types:
-
+### Typescript: Accessing component types
+There are 2 ways to access components of the request and response types. For example, if you want to access the type for an index settings object:
+1. Through the Types module (Note that this could result in a breaking change when the name of the component type is changed with the spec)
 ```typescript
-// Do NOT do this!
-import { type IndexSettings } from '@opensearch-project/opensearch/api/_types/indices._common';
-const settings: IndexSettings = { number_of_shards: 1, number_of_replicas: 0 };
 
-// Do this instead!
+import { type Types } from '@opensearch-project/opensearch';
+const settings: Types.Indices_Common.IndexSettings = { number_of_shards: 1, number_of_replicas: 0 };
+```
+
+2. Through the API module (This is helpful when you don't know the exact path to the type)
+```typescript
 import { type API } from '@opensearch-project/opensearch';
 const settings: API.Indices_Create_RequestBody['settings'] = { number_of_shards: 1, number_of_replicas: 0 };
 ```

package.json

@@ -36,7 +36,7 @@
     "LICENSE.txt"
   ],
   "homepage": "https://www.opensearch.org/",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "versionCanary": "7.10.0-canary.6",
   "keywords": [
     "opensearch",