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",