diff --git a/.ci/license/check-license-headers.sh b/.ci/license/check-license-headers.sh index e94203302..8470661f7 100755 --- a/.ci/license/check-license-headers.sh +++ b/.ci/license/check-license-headers.sh @@ -37,13 +37,13 @@ function check_license_header { cd "$TOP" nErrors=0 -for f in $(git ls-files --directory ../ | grep '\.ts$'); do +for f in $(git ls-files --directory ../ | grep '\.ts$' | grep -v '^docs/'); do if ! check_license_header $f; then nErrors=$((nErrors+1)) fi done -for f in $(git ls-files --directory ../ | grep '\.js$'); do +for f in $(git ls-files --directory ../ | grep '\.js$' | grep -v '^docs/'); do if ! check_license_header $f; then nErrors=$((nErrors+1)) fi @@ -53,4 +53,4 @@ if [[ $nErrors -eq 0 ]]; then exit 0 else exit 1 -fi \ No newline at end of file +fi diff --git a/.github/workflows/gh_pages.yml b/.github/workflows/gh_pages.yml new file mode 100644 index 000000000..9d40effde --- /dev/null +++ b/.github/workflows/gh_pages.yml @@ -0,0 +1,37 @@ +name: Publish Docs to Github Pages +on: + workflow_dispatch: + push: + branches: [main, jsdoc] +jobs: + update-docs: + runs-on: ubuntu-latest + name: Update gh-pages with docs + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v1 + with: + ruby-version: 16.x + - name: Install Tools + run: | + sudo apt install -y jq + npm install -g jsdoc + - name: Generate Docs + run: | + export PACKAGE_VERSION=$(jq .version package.json -r | awk -F. '{print $1"."$2}') + export DOC_FOLDER=docs/$PACKAGE_VERSION + jsdoc api lib -d $DOC_FOLDER -r --readme README.md + cp *.md $DOC_FOLDER + cp *.txt $DOC_FOLDER + - name: Commit Docs Change + uses: EndBug/add-and-commit@v9 + with: + default_author: github_actions + add: 'docs/* -f' + - name: Deploy Docs to gh-pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs + keep_files: true + enable_jekyll: true diff --git a/.gitignore b/.gitignore index 09aaa949d..d8abd2df1 100644 --- a/.gitignore +++ b/.gitignore @@ -53,6 +53,9 @@ opensearch* !opensearch_dashboards* !opensearchDashboards* +# documentation +docs/ + test/benchmarks/macro/fixtures/* *-junit.xml diff --git a/CHANGELOG.md b/CHANGELOG.md index 5afad1585..fa99ecc95 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,9 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ## [Unreleased] ### Added - Add release details to releasing.md ([319](https://github.com/opensearch-project/opensearch-js/pull/319)) +- jsdoc for documentation generation ([#335](https://github.com/opensearch-project/opensearch-js/issues/335)) +- Documentation for Transport#request ([#335](https://github.com/opensearch-project/opensearch-js/issues/335)) +- Documentation for api/bulk ([#335](https://github.com/opensearch-project/opensearch-js/issues/335)) ### Dependencies ### Changed ### Deprecated diff --git a/api/api/bulk.js b/api/api/bulk.js index d9dd652f1..c7016f858 100644 --- a/api/api/bulk.js +++ b/api/api/bulk.js @@ -32,6 +32,8 @@ /* eslint camelcase: 0 */ /* eslint no-unused-vars: 0 */ +/** @namespace API-bulk */ + const { handleError, snakeCaseKeys, normalizeArguments, kConfigurationError } = require('../utils'); const acceptedQuerystring = [ 'wait_for_active_shards', @@ -63,6 +65,24 @@ const snakeCase = { filterPath: 'filter_path', }; +/** + * The bulk operation lets you add, update, or delete many documents in a single request. + * Compared to individual OpenSearch indexing requests, the bulk operation has significant performance benefits. + * Whenever practical, we recommend batching indexing operations into bulk requests. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/document-apis/bulk/|OpenSearch - Bulk} + * + * @memberOf API-bulk + * + * @param {Object} params + * @param {Object[]} params.body - {@link https://opensearch.org/docs/latest/api-reference/document-apis/bulk/#request-body|Request Body} + * @param {string} [params.index] - Specifying the index means you don’t need to include it in the request body. + * @param {} [params....] {@link https://opensearch.org/docs/latest/api-reference/document-apis/bulk/#url-parameters|URL parameters} + * + * @param {Object} options - Options for {@link Transport#request} + * @param {function} callback - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/document-apis/bulk/#response|Bulk Response} + */ function bulkApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); diff --git a/api/api/cat.js b/api/api/cat.js index 394d6db1e..f06fc49dd 100644 --- a/api/api/cat.js +++ b/api/api/cat.js @@ -32,6 +32,8 @@ /* eslint camelcase: 0 */ /* eslint no-unused-vars: 0 */ +/** @namespace API-cat */ + const { handleError, snakeCaseKeys, normalizeArguments, kConfigurationError } = require('../utils'); const acceptedQuerystring = [ 'format', @@ -69,6 +71,7 @@ const acceptedQuerystring = [ 'nodes', 'actions', 'parent_task_id', + 'pri', ]; const snakeCase = { expandWildcards: 'expand_wildcards', @@ -92,16 +95,34 @@ function CatApi(transport, ConfigurationError) { this[kConfigurationError] = ConfigurationError; } +/** + * The CAT aliases operation lists the mapping of aliases to indices, plus routing and filtering information. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-aliases/ OpenSearch - CAT aliases} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.alias] - To limit the information to specific aliases, provide the alias names seperated by commas. + * @param {boolean} [params.local=false] - Whether to return information from the local node only instead of from the cluster manager node. + * @param {string} [params.expand_wildcards=open] - Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are 'all', 'open', 'closed', 'hidden', and 'none'. Default is 'open'. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-aliases/#response CAT aliases Response} + */ + CatApi.prototype.aliases = function catAliasesApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); - let { method, body, name, ...querystring } = params; + let { method, body, name, alias, ...querystring } = params; + alias = alias || name; querystring = snakeCaseKeys(acceptedQuerystring, snakeCase, querystring); let path = ''; - if (name != null) { + if (alias != null) { if (method == null) method = 'GET'; - path = '/' + '_cat' + '/' + 'aliases' + '/' + encodeURIComponent(name); + path = '/' + '_cat' + '/' + 'aliases' + '/' + encodeURIComponent(alias); } else { if (method == null) method = 'GET'; path = '/' + '_cat' + '/' + 'aliases'; @@ -118,16 +139,35 @@ CatApi.prototype.aliases = function catAliasesApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT allocation operation lists the allocation of disk space for indices and the number of shards on each node. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-allocation/ OpenSearch - CAT allocation} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.node_name] - To limit the information to specific nodes, provide the node names seperated by commas. + * @param {boolean} [params.local=false] - Whether to return information from the local node only instead of from the cluster manager node. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * @param {string} [params.bytes] - Specify the units for byte size. For example, '7kb' or '6gb'. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-allocation/#response CAT allocation Response} + */ + CatApi.prototype.allocation = function catAllocationApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); - let { method, body, nodeId, node_id, ...querystring } = params; + let { method, body, nodeId, node_id, node_name, nodeName, ...querystring } = params; + node_name = node_name || nodeName || nodeId || node_id; querystring = snakeCaseKeys(acceptedQuerystring, snakeCase, querystring); let path = ''; - if ((node_id || nodeId) != null) { + if (node_name != null) { if (method == null) method = 'GET'; - path = '/' + '_cat' + '/' + 'allocation' + '/' + encodeURIComponent(node_id || nodeId); + path = '/' + '_cat' + '/' + 'allocation' + '/' + encodeURIComponent(node_name); } else { if (method == null) method = 'GET'; path = '/' + '_cat' + '/' + 'allocation'; @@ -144,6 +184,21 @@ CatApi.prototype.allocation = function catAllocationApi(params, options, callbac return this.transport.request(request, options, callback); }; +/** + * The CAT count operation lists the number of documents in your cluster. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-count/ OpenSearch - CAT count} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.index] - To see the number of documents in specific indices or aliases, provide the index/alias names seperated by commas. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-count/#response CAT count Response} + */ + CatApi.prototype.count = function catCountApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -170,16 +225,32 @@ CatApi.prototype.count = function catCountApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT fielddata operation lists the memory size used by each field per node. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-field-data/ OpenSearch - CAT fielddata} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.field_name] - To limit the information to specific fields, provide the field names seperated by commas. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-field-data/#response CAT fielddata Response} + */ + CatApi.prototype.fielddata = function catFielddataApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); - let { method, body, fields, ...querystring } = params; + let { method, body, fields, field_name, ...querystring } = params; + field_name = field_name || fields; querystring = snakeCaseKeys(acceptedQuerystring, snakeCase, querystring); let path = ''; - if (fields != null) { + if (field_name != null) { if (method == null) method = 'GET'; - path = '/' + '_cat' + '/' + 'fielddata' + '/' + encodeURIComponent(fields); + path = '/' + '_cat' + '/' + 'fielddata' + '/' + encodeURIComponent(field_name); } else { if (method == null) method = 'GET'; path = '/' + '_cat' + '/' + 'fielddata'; @@ -196,6 +267,22 @@ CatApi.prototype.fielddata = function catFielddataApi(params, options, callback) return this.transport.request(request, options, callback); }; +/** + * The CAT health operation lists the status of the cluster, how long the cluster has been up, the number of nodes, + * and other useful information that helps you analyze the health of your cluster. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-health/ OpenSearch - CAT health} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.time] - Specify the units for time. For example, '5d' or '7h'. + * @param {boolean} [params.ts=true] - If true, returns HH:MM:SS and Unix epoch timestamps. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-health/#response CAT health Response} + */ CatApi.prototype.health = function catHealthApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -217,6 +304,18 @@ CatApi.prototype.health = function catHealthApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * See the available operations in the CAT API + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/index OpenSearch - CAT} + * + * @memberOf API-cat + * + * @param {Object} params - (ignored) + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} + */ CatApi.prototype.help = function catHelpApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -238,6 +337,27 @@ CatApi.prototype.help = function catHelpApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT indices operation lists information related to indices—how much disk space they are using, how many shards they have, their health status, and so on. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-indices/ OpenSearch - CAT indices} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.index] - To limit the information to specific indices, provide the index names seperated by commas. + * @param {string} [params.bytes] - Specify the units for byte size. For example, '7kb' or '6gb'. + * @param {string} [params.health] - Limit indices based on their health status. Supported values are 'green', 'yellow', and 'red'. + * @param {boolean} [params.include_unloaded_segments=false] - Whether to include information from segments not loaded into memory. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * @param {boolean} [params.pri=false] - Whether to return information only from the primary shards. + * @param {string} [params.time] - Specify the units for time. For example, '5d' or '7h'. + * @param {string} [params.expand_wildcards=open] - Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are 'all', 'open', 'closed', 'hidden', and 'none'. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-indices/#response CAT indices Response} + */ CatApi.prototype.indices = function catIndicesApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -264,6 +384,18 @@ CatApi.prototype.indices = function catIndicesApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT cluster manager operation lists information that helps identify the elected cluster manager node. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-cluster_manager/ OpenSearch - CAT cluster manager} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-cluster_manager/#response CAT cluster manager Response} + */ CatApi.prototype.cluster_manager = function catClusterManagerApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -310,6 +442,21 @@ CatApi.prototype.master = function catMasterApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT nodeattrs operation lists the attributes of custom nodes. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-nodeattrs/ OpenSearch - CAT aliases} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {boolean} [params.local=false] - Whether to return information from the local node only instead of from the cluster manager node. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-nodeattrs/#response CAT nodeattrs Response} + */ CatApi.prototype.nodeattrs = function catNodeattrsApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -331,6 +478,25 @@ CatApi.prototype.nodeattrs = function catNodeattrsApi(params, options, callback) return this.transport.request(request, options, callback); }; +/** + * The CAT nodes operation lists node-level information, including node roles and load metrics. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-nodes/ OpenSearch - CAT nodes} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.bytes] - Specify the units for byte size. For example, '7kb' or '6gb'. + * @param {boolean} [params.full_id=false] - If true, return the full node ID. If false, return the shortened node ID. + * @param {boolean} [params.local=false] - Whether to return information from the local node only instead of from the cluster_manager node. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * @param {string} [params.time] - Specify the units for time. For example, '5d' or '7h'. + * @param {boolean} [params.include_unloaded_segments=false] - Whether to include information from segments not loaded into memory. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-nodes/#response CAT nodes Response} + */ CatApi.prototype.nodes = function catNodesApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -352,6 +518,22 @@ CatApi.prototype.nodes = function catNodesApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT pending tasks operation lists the progress of all pending tasks, including task priority and time in queue. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-pending-tasks/ OpenSearch - CAT pending tasks} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {boolean} [params.local=false] - Whether to return information from the local node only instead of from the cluster_manager node. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * @param {string} [params.time] - Specify the units for time. For example, '5d' or '7h'. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-pending-tasks/#response CAT pending tasks Response} + */ CatApi.prototype.pendingTasks = function catPendingTasksApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -373,6 +555,21 @@ CatApi.prototype.pendingTasks = function catPendingTasksApi(params, options, cal return this.transport.request(request, options, callback); }; +/** + * The CAT plugins operation lists the names, components, and versions of the installed plugins. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-plugins/ OpenSearch - CAT plugins} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {boolean} [params.local=false] - Whether to return information from the local node only instead of from the cluster_manager node. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-plugins/#response CAT plugins Response} + */ CatApi.prototype.plugins = function catPluginsApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -394,6 +591,23 @@ CatApi.prototype.plugins = function catPluginsApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT recovery operation lists all completed and ongoing index and shard recoveries. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-recovery/ OpenSearch - CAT recovery} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.bytes] - Specify the units for byte size. For example, '7kb' or '6gb'. + * @param {string} [params.time] - Specify the units for time. For example, '5d' or '7h'. + * @param {boolean} [params.active_only=false] - Whether to only include ongoing shard recoveries. + * @param {boolean} [params.detailed=false] - Whether to only include ongoing shard recoveries. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-recovery/#response CAT recovery Response} + */ CatApi.prototype.recovery = function catRecoveryApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -420,6 +634,21 @@ CatApi.prototype.recovery = function catRecoveryApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT repositories operation lists all completed and ongoing index and shard recoveries. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-repositories/ OpenSearch - CAT repositories} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {boolean} [params.local=false] - Whether to return information from the local node only instead of from the cluster_manager node. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-repositories/#response CAT repositories Response} + */ CatApi.prototype.repositories = function catRepositoriesApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -441,6 +670,22 @@ CatApi.prototype.repositories = function catRepositoriesApi(params, options, cal return this.transport.request(request, options, callback); }; +/** + * The cat segments operation lists Lucene segment-level information for each index. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-segments/ OpenSearch - CAT segments} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.index] - To see only the information about segments of specific indices, provide the index names seperated by commas. + * @param {string} [params.bytes] - Specify the units for byte size. For example, '7kb' or '6gb'. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-segments/#response CAT segments Response} + */ CatApi.prototype.segments = function catSegmentsApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -467,6 +712,24 @@ CatApi.prototype.segments = function catSegmentsApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT shards operation lists the state of all primary and replica shards and how they are distributed. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-shards/ OpenSearch - CAT shards} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.index] - To see only the information about shards of specific indices, provide the index names seperated by commas. + * @param {string} [params.bytes] - Specify the units for byte size. For example, '7kb' or '6gb'. + * @param {boolean} [params.local=false] - Whether to return information from the local node only instead of from the cluster_manager node. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * @param {string} [params.time] - Specify the units for time. For example, '5d' or '7h'. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-shards/#response CAT shards Response} + */ CatApi.prototype.shards = function catShardsApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -493,6 +756,21 @@ CatApi.prototype.shards = function catShardsApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT snapshots operation lists all snapshots for a repository. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-snapshots/ OpenSearch - CAT snapshots} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * @param {string} [params.time] - Specify the units for time. For example, '5d' or '7h'. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-snapshots/#response CAT snapshots Response} + */ CatApi.prototype.snapshots = function catSnapshotsApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -519,6 +797,23 @@ CatApi.prototype.snapshots = function catSnapshotsApi(params, options, callback) return this.transport.request(request, options, callback); }; +/** + * The CAT tasks operation lists the progress of all tasks currently running on your cluster. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-tasks/ OpenSearch - CAT tasks} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {string} [params.nodes] - A comma-separated list of node IDs or names to limit the returned information. Use '_local' to return information from the node you’re connecting to, specify the node name to get information from specific nodes, or keep the parameter empty to get information from all nodes. + * @param {string} [params.time] - Specify the units for time. For example, '5d' or '7h'. + * @param {boolean} [params.detailed=false] - Returns detailed task information. + * @param {string} [params.parent_task_id] - Returns tasks with a specified parent task ID (node_id:task_number). Keep empty or set to -1 to return all. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-tasks/#response CAT tasks Response} + */ CatApi.prototype.tasks = function catTasksApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -540,6 +835,22 @@ CatApi.prototype.tasks = function catTasksApi(params, options, callback) { return this.transport.request(request, options, callback); }; +/** + * The CAT templates operation lists the names, patterns, order numbers, and version numbers of index templates. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-templates/ OpenSearch - CAT templates} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {boolean} [params.name] - If you want to limit it to a specific template or pattern, provide the template name or pattern. + * @param {boolean} [params.local=false] - Whether to return information from the local node only instead of from the cluster manager node. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-templates/#response CAT templates Response} + */ CatApi.prototype.templates = function catTemplatesApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); @@ -566,6 +877,21 @@ CatApi.prototype.templates = function catTemplatesApi(params, options, callback) return this.transport.request(request, options, callback); }; +/** + * The CAT thread pool operation lists the active, queued, and rejected threads of different thread pools on each node. + *
See Also: {@link https://opensearch.org/docs/latest/api-reference/cat/cat-thread-pool/ OpenSearch - CAT thread pool} + * + * @memberOf API-cat + * + * @param {Object} params - Accepts {@link https://opensearch.org/docs/latest/api-reference/cat/index#optional-query-parameters - common CAT parameters} along with the following unique parameters: + * @param {boolean} [params.local=false] - Whether to return information from the local node only instead of from the cluster manager node. + * @param {string} [params.cluster_manager_timeout=30s] - The amount of time to wait for a connection to the cluster manager node. + * + * @param {Object} [options] - Options for {@link Transport#request} + * @param {function} [callback] - Callback that handles errors and response + * + * @returns {{abort: function(), then: function(), catch: function()}|Promise|*} {@link https://opensearch.org/docs/latest/api-reference/cat/cat-thread-pool/#response CAT thread pool Response} + */ CatApi.prototype.threadPool = function catThreadPoolApi(params, options, callback) { [params, options, callback] = normalizeArguments(params, options, callback); diff --git a/lib/Serializer.js b/lib/Serializer.js index 224a5bd4b..aaf162256 100644 --- a/lib/Serializer.js +++ b/lib/Serializer.js @@ -90,7 +90,7 @@ class Serializer { const keys = Object.keys(object); for (let i = 0, len = keys.length; i < len; i++) { const key = keys[i]; - // OpenSearch will complain for keys without a value + // OpenSearch will complain about keys without a value if (object[key] === undefined) { delete object[key]; } else if (Array.isArray(object[key]) === true) { diff --git a/lib/Transport.js b/lib/Transport.js index 9e1c4f3cb..399d2641f 100644 --- a/lib/Transport.js +++ b/lib/Transport.js @@ -56,6 +56,7 @@ const HEAP_SIZE_LIMIT = require('v8').getHeapStatistics().heap_size_limit; const kCompatibleCheck = Symbol('compatible check'); const kApiVersioning = Symbol('api versioning'); +/** Default Transport Layer */ class Transport { constructor(opts) { if (typeof opts.compression === 'string' && opts.compression !== 'gzip') { @@ -110,6 +111,27 @@ class Transport { } } + /** + * @param {Object} params + * @param {string} params.method - HTTP Method (e.g. HEAD, GET, POST...) + * @param {string} params.path - Relative URL path + * @param {Object | string} [params.body] - Body of a standard request. + * @param {Object[] | string} [params.bulkBody] - Body of a bulk request. + * @param {Object[] | string} [params.querystring] - Querystring params. + * + * @param {Object} options + * @param {number} [options.id] - Request ID + * @param {Object} [options.context] - Object used for observability + * @param {number} [options.maxRetries] - Max number of retries + * @param {false | 'gzip'} [options.compression] - Request body compression, if any + * @param {boolean} [options.asStream] - Whether to emit the response as stream + * @param {number[]} [options.ignore] - Response's Error Status Codes to ignore + * @param {Object} [options.headers] - Request headers + * @param {Object | string} [options.querystring] - Request's query string + * @param {number} [options.requestTimeout] - Max request timeout in milliseconds + * + * @param {function} callback - Callback that handles errors and response + */ request(params, options, callback) { options = options || {}; if (typeof options === 'function') { @@ -386,7 +408,7 @@ class Transport { // if the statusCode is 502/3/4 we should run our retry strategy // and mark the connection as dead this.connectionPool.markDead(meta.connection); - // retry logic (we shoukd not retry on "429 - Too Many Requests") + // retry logic (we should not retry on "429 - Too Many Requests") if (meta.attempts < maxRetries && result.statusCode !== 429) { meta.attempts++; debug(`Retrying request, there are still ${maxRetries - meta.attempts} attempts`, params); diff --git a/package.json b/package.json index 6e70572f4..2fce33c5a 100644 --- a/package.json +++ b/package.json @@ -71,6 +71,7 @@ "fast-deep-equal": "^3.1.3", "into-stream": "^6.0.0", "js-yaml": "^4.1.0", + "jsdoc": "^4.0.0", "license-checker": "^25.0.1", "minimist": "^1.2.5", "node-fetch": "^3.2.10",