@ibm-cloud/cloudant
Version:
IBM Cloudant Node.js SDK
938 lines • 646 kB
JavaScript
"use strict";
/**
* (C) Copyright IBM Corp. 2025.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
const extend_1 = __importDefault(require("extend"));
const ibm_cloud_sdk_core_1 = require("ibm-cloud-sdk-core");
const common_1 = require("../lib/common");
const cloudantBaseService_1 = require("../lib/cloudantBaseService");
const getAuthenticatorFromEnvCloudantExtension_1 = require("../lib/getAuthenticatorFromEnvCloudantExtension");
/* eslint @typescript-eslint/no-use-before-define: 0 */
/* eslint max-classes-per-file: 0 */
/**
* NoSQL database based on Apache CouchDB
*
* See: https://cloud.ibm.com/docs/services/Cloudant/
*/
class CloudantV1 extends cloudantBaseService_1.CloudantBaseService {
static _logger = (0, ibm_cloud_sdk_core_1.getNewLogger)('CloudantV1');
static DEFAULT_SERVICE_URL = 'https://~replace-with-cloudant-host~.cloudantnosqldb.appdomain.cloud';
static DEFAULT_SERVICE_NAME = 'cloudant';
/*************************
* Factory method
************************/
/**
* Constructs an instance of CloudantV1 with passed in options and external configuration.
*
* @param {UserOptions} [options] - The parameters to send to the service.
* @param {string} [options.serviceName] - The name of the service to configure
* @param {Authenticator} [options.authenticator] - The Authenticator object used to authenticate requests to the service
* @param {string} [options.serviceUrl] - The base URL for the service
* @returns {CloudantV1}
*/
static newInstance(options) {
options = options || {};
if (!options.serviceName) {
options.serviceName = this.DEFAULT_SERVICE_NAME;
}
if (!options.authenticator) {
options.authenticator = (0, getAuthenticatorFromEnvCloudantExtension_1.getAuthenticatorFromEnvCloudantExtension)(options.serviceName);
}
const service = new CloudantV1(options);
service.configureService(options.serviceName);
if (options.serviceUrl) {
service.setServiceUrl(options.serviceUrl);
}
return service;
}
/**
* Construct a CloudantV1 object.
*
* @param {Object} options - Options for the service.
* @param {string} [options.serviceUrl] - The base URL for the service
* @param {OutgoingHttpHeaders} [options.headers] - Default headers that shall be included with every request to the service.
* @param {Authenticator} options.authenticator - The Authenticator object used to authenticate requests to the service
* @constructor
* @returns {CloudantV1}
*/
constructor(options) {
options = options || {};
// enable gzip compression of request bodies
options.enableGzipCompression = true;
super(options);
if (options.serviceUrl) {
this.setServiceUrl(options.serviceUrl);
}
else {
this.setServiceUrl(CloudantV1.DEFAULT_SERVICE_URL);
}
}
/*************************
* server
************************/
/**
* Retrieve server instance information.
*
* When you access the root of an instance, IBM Cloudant returns meta-information about the instance. The response
* includes a JSON structure that contains information about the server, including a welcome message and the server's
* version.
*
* **Tip:** The authentication for this endpoint is only enforced when using IAM.
*
* @param {Object} [params] - The parameters to send to the service.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.ServerInformation>>}
*/
getServerInformation(params) {
const _params = { ...params };
const _requiredParams = [];
const _validParams = ['signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'getServerInformation');
const parameters = {
options: {
url: '/',
method: 'GET',
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequestAndDeserializeResponse(parameters, CloudantV1.ServerInformation.deserialize);
}
/**
* Retrieve provisioned throughput capacity information.
*
* View the amount of provisioned throughput capacity that is allocated to an IBM Cloudant instance and what is the
* target provisioned throughput capacity.
*
* @param {Object} [params] - The parameters to send to the service.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.CapacityThroughputInformation>>}
*/
getCapacityThroughputInformation(params) {
const _params = { ...params };
const _requiredParams = [];
const _validParams = ['signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'getCapacityThroughputInformation');
const parameters = {
options: {
url: '/_api/v2/user/capacity/throughput',
method: 'GET',
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequestAndDeserializeResponse(parameters, CloudantV1.CapacityThroughputInformation.deserialize);
}
/**
* Update the target provisioned throughput capacity.
*
* Sets the target provisioned throughput capacity for an IBM Cloudant instance. When target capacity is changed, the
* current capacity asynchronously changes to meet the target capacity.
*
* @param {Object} params - The parameters to send to the service.
* @param {number} params.blocks - A number of blocks of throughput units. A block consists of 100 reads/sec, 50
* writes/sec, and 5 global queries/sec of provisioned throughput capacity. Not available for some plans.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.CapacityThroughputInformation>>}
*/
putCapacityThroughputConfiguration(params) {
const _params = { ...params };
const _requiredParams = ['blocks'];
const _validParams = ['blocks', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const body = {
'blocks': _params.blocks,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'putCapacityThroughputConfiguration');
const parameters = {
options: {
url: '/_api/v2/user/capacity/throughput',
method: 'PUT',
body,
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
'Content-Type': 'application/json',
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequestAndDeserializeResponse(parameters, CloudantV1.CapacityThroughputInformation.deserialize);
}
/**
* Retrieve one or more UUIDs.
*
* Requests one or more Universally Unique Identifiers (UUIDs) from the instance. The response is a JSON object that
* provides a list of UUIDs.
*
* **Tip:** The authentication for this endpoint is only enforced when using IAM.
*
* @param {Object} [params] - The parameters to send to the service.
* @param {number} [params.count] - Query parameter to specify the number of UUIDs to return.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.UuidsResult>>}
*/
getUuids(params) {
const _params = { ...params };
const _requiredParams = [];
const _validParams = ['count', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const query = {
'count': _params.count,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'getUuids');
const parameters = {
options: {
url: '/_uuids',
method: 'GET',
qs: query,
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequestAndDeserializeResponse(parameters, CloudantV1.UuidsResult.deserialize);
}
/*************************
* changes
************************/
/**
* Retrieve change events for all databases.
*
* **This endpoint is not available in IBM Cloudant.**
*
* Lists changes to databases, like a global changes feed. Types of changes include updating the database and creating
* or deleting a database. Like the changes feed, the feed is not guaranteed to return changes in the correct order
* and might repeat changes. Polling modes for this method work like polling modes for the changes feed.
*
* @param {Object} [params] - The parameters to send to the service.
* @param {boolean} [params.descending] - Query parameter to specify whether to return the documents in descending by
* key order.
* @param {string} [params.feed] - Query parameter to specify the changes feed type.
* @param {number} [params.heartbeat] - Query parameter to specify the period in milliseconds after which an empty
* line is sent in the results. Off by default and only applicable for
* `continuous` and `eventsource` feeds. Overrides any timeout to keep the feed alive indefinitely. May also be `true`
* to use a value of `60000`.
*
* **Note:** Delivery of heartbeats cannot be relied on at specific intervals. If your application runs in an
* environment where idle network connections may break, `heartbeat` is not suitable as a keepalive mechanism.
* Instead, consider one of the following options:
* * Use the `timeout` parameter with a value that is compatible with your network environment.
* * Switch to scheduled usage of one of the non-continuous changes feed types
* (`normal` or `longpoll`).
* * Use TCP keepalive.
* @param {number} [params.limit] - Query parameter to specify the number of returned documents to limit the result
* to.
* @param {number} [params.timeout] - Query parameter to specify the maximum period in milliseconds to wait for a
* change before the response is sent, even if there are no results. Only applicable for `longpoll` or `continuous`
* feeds. Default value is specified by `httpd/changes_timeout` configuration option. Note that `60000` value is also
* the default maximum timeout to prevent undetected dead connections.
* @param {string} [params.since] - Query parameter to specify to start the results from the change immediately after
* the given update sequence. Can be a valid update sequence or `now` value. Default is `0` i.e. all changes.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.DbUpdates>>}
* @deprecated this method is deprecated and may be removed in a future release
*/
getDbUpdates(params) {
CloudantV1._logger.warn('A deprecated operation has been invoked: getDbUpdates');
const _params = { ...params };
const _requiredParams = [];
const _validParams = ['descending', 'feed', 'heartbeat', 'limit', 'timeout', 'since', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const query = {
'descending': _params.descending,
'feed': _params.feed,
'heartbeat': _params.heartbeat,
'limit': _params.limit,
'timeout': _params.timeout,
'since': _params.since,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'getDbUpdates');
const parameters = {
options: {
url: '/_db_updates',
method: 'GET',
qs: query,
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequestAndDeserializeResponse(parameters, CloudantV1.DbUpdates.deserialize);
}
/**
* Query the database document changes feed.
*
* Requests the database changes feed in the same way as `GET /{db}/_changes` does. It is widely used with the
* `filter` query parameter because it allows one to pass more information to the filter.
*
* ### Note
*
* Before using the changes feed read the
* [FAQs](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-faq-using-changes-feed) to understand the limitations and
* appropriate use cases.
*
* If you need to pass parameters to dynamically change the filtered content use the `_selector` filter type for
* better performance and compatibility. The SDKs have full support for change requests using selector filters, but
* don't support passing parameters to design document filters.
*
* @param {Object} params - The parameters to send to the service.
* @param {string} params.db - Path parameter to specify the database name.
* @param {string[]} [params.docIds] - Schema for a list of document IDs.
* @param {string[]} [params.fields] - JSON array that uses the field syntax. Use this parameter to specify which
* fields of a document must be returned. If it is omitted or empty, the entire document is returned.
* @param {JsonObject} [params.selector] - JSON object describing criteria used to select documents. The selector
* specifies fields in the document, and provides an expression to evaluate with the field content or other data.
*
* The selector object must:
* * Be structured as valid JSON.
* * Contain a valid query expression.
*
* Using a selector is significantly more efficient than using a JavaScript filter function, and is the recommended
* option if filtering on document attributes only.
*
* Elementary selector syntax requires you to specify one or more fields, and the corresponding values required for
* those fields. You can create more complex selector expressions by combining operators.
*
* Operators are identified by the use of a dollar sign `$` prefix in the name field.
*
* There are two core types of operators in the selector syntax:
* * Combination operators: applied at the topmost level of selection. They are used to combine selectors. A
* combination operator takes a single argument. The argument is either another selector, or an array of selectors.
* * Condition operators: are specific to a field, and are used to evaluate the value stored in that field. For
* instance, the basic `$eq` operator matches when the specified field contains a value that is equal to the supplied
* argument.
*
* It is important for query performance to use appropriate selectors:
* * Only equality operators such as `$eq`, `$gt`, `$gte`, `$lt`, and `$lte` (but not `$ne`) can be used as the basis
* of a query. You should include at least one of these in a selector.
* * Some operators such as `$not`, `$or`, `$in`, and `$regex` cannot be answered from an index. For query selectors
* use these operators in conjunction with equality operators or create and use a partial index to reduce the number
* of documents that will need to be scanned.
*
* See [the Cloudant Docs](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-operators)for a list of all available
* combination and conditional operators.
*
* For further reference see [selector syntax](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-selector-syntax).
* @param {string} [params.lastEventId] - Header parameter to specify the ID of the last events received by the server
* on a previous connection. Overrides `since` query parameter.
* @param {boolean} [params.attEncodingInfo] - Query parameter to specify whether to include the encoding information
* in attachment stubs if the particular attachment is compressed.
* @param {boolean} [params.attachments] - Query parameter to specify whether to include attachments bodies in a
* response.
* @param {boolean} [params.conflicts] - Query parameter to specify whether to include a list of conflicted revisions
* in each returned document. Active only when `include_docs` is `true`.
* @param {boolean} [params.descending] - Query parameter to specify whether to return the documents in descending by
* key order.
* @param {string} [params.feed] - Query parameter to specify the changes feed type.
* @param {string} [params.filter] - Query parameter to specify a filter to emit only specific events from the changes
* stream.
*
* The built-in filter types are:
* * `_design` - Returns only changes to design documents.
* * `_doc_ids` - Returns changes for documents with an ID matching one specified in
* `doc_ids` request body parameter. (`POST` only)
* * `_selector` - Returns changes for documents that match the `selector`
* request body parameter. The selector syntax is the same as used for
* `_find`. (`POST` only)
* * `_view` - Returns changes for documents that match an existing map
* function in the view specified by the query parameter `view`.
*
* Additionally, the value can be the name of a JS filter function from a design document. For example:
* `design_doc/filtername`.
*
* **Note:** For better performance use the built-in `_selector`, `_design` or `_doc_ids` filters rather than JS based
* `_view` or design document filters. If you need to pass values to change the filtered content use the `_selector`
* filter type.
* @param {number} [params.heartbeat] - Query parameter to specify the period in milliseconds after which an empty
* line is sent in the results. Off by default and only applicable for
* `continuous` and `eventsource` feeds. Overrides any timeout to keep the feed alive indefinitely. May also be `true`
* to use a value of `60000`.
*
* **Note:** Delivery of heartbeats cannot be relied on at specific intervals. If your application runs in an
* environment where idle network connections may break, `heartbeat` is not suitable as a keepalive mechanism.
* Instead, consider one of the following options:
* * Use the `timeout` parameter with a value that is compatible with your network environment.
* * Switch to scheduled usage of one of the non-continuous changes feed types
* (`normal` or `longpoll`).
* * Use TCP keepalive.
* @param {boolean} [params.includeDocs] - Query parameter to specify whether to include the full content of the
* documents in the response.
* @param {number} [params.limit] - Query parameter to specify the number of returned documents to limit the result
* to.
* @param {number} [params.seqInterval] - Query parameter to specify that the update seq should only be calculated
* with every Nth result returned. When fetching changes in a batch, setting <code>seq_interval=<batch
* size></code>, where <batch size> is the number of results requested per batch, load can be reduced on the
* source database as computing the seq value across many shards (especially in highly-sharded databases) is
* expensive.
* @param {string} [params.since] - Query parameter to specify to start the results from the change immediately after
* the given update sequence. Can be a valid update sequence or `now` value. Default is `0` i.e. all changes.
* @param {string} [params.style] - Query parameter to specify how many revisions are returned in the changes array.
* The default, `main_only`, will only return the current "winning" revision; all_docs will return all leaf revisions
* (including conflicts and deleted former conflicts).
* @param {number} [params.timeout] - Query parameter to specify the maximum period in milliseconds to wait for a
* change before the response is sent, even if there are no results. Only applicable for `longpoll` or `continuous`
* feeds. Default value is specified by `httpd/changes_timeout` configuration option. Note that `60000` value is also
* the default maximum timeout to prevent undetected dead connections.
* @param {string} [params.view] - Query parameter to specify a view function as a filter. Documents pass the filter
* if the view's map function emits at least one record for them.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.ChangesResult>>}
*/
postChanges(params) {
const _params = { ...params };
const _requiredParams = ['db'];
const _validParams = ['db', 'docIds', 'fields', 'selector', 'lastEventId', 'attEncodingInfo', 'attachments', 'conflicts', 'descending', 'feed', 'filter', 'heartbeat', 'includeDocs', 'limit', 'seqInterval', 'since', 'style', 'timeout', 'view', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const body = {
'doc_ids': _params.docIds,
'fields': _params.fields,
'selector': _params.selector,
};
const query = {
'att_encoding_info': _params.attEncodingInfo,
'attachments': _params.attachments,
'conflicts': _params.conflicts,
'descending': _params.descending,
'feed': _params.feed,
'filter': _params.filter,
'heartbeat': _params.heartbeat,
'include_docs': _params.includeDocs,
'limit': _params.limit,
'seq_interval': _params.seqInterval,
'since': _params.since,
'style': _params.style,
'timeout': _params.timeout,
'view': _params.view,
};
const path = {
'db': _params.db,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'postChanges');
const parameters = {
options: {
url: '/{db}/_changes',
method: 'POST',
body,
qs: query,
path,
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Last-Event-ID': _params.lastEventId,
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequestAndDeserializeResponse(parameters, CloudantV1.ChangesResult.deserialize);
}
/**
* Query the database document changes feed as stream.
*
* Requests the database changes feed in the same way as `GET /{db}/_changes` does. It is widely used with the
* `filter` query parameter because it allows one to pass more information to the filter.
*
* ### Note
*
* Before using the changes feed read the
* [FAQs](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-faq-using-changes-feed) to understand the limitations and
* appropriate use cases.
*
* If you need to pass parameters to dynamically change the filtered content use the `_selector` filter type for
* better performance and compatibility. The SDKs have full support for change requests using selector filters, but
* don't support passing parameters to design document filters.
*
* @param {Object} params - The parameters to send to the service.
* @param {string} params.db - Path parameter to specify the database name.
* @param {string[]} [params.docIds] - Schema for a list of document IDs.
* @param {string[]} [params.fields] - JSON array that uses the field syntax. Use this parameter to specify which
* fields of a document must be returned. If it is omitted or empty, the entire document is returned.
* @param {JsonObject} [params.selector] - JSON object describing criteria used to select documents. The selector
* specifies fields in the document, and provides an expression to evaluate with the field content or other data.
*
* The selector object must:
* * Be structured as valid JSON.
* * Contain a valid query expression.
*
* Using a selector is significantly more efficient than using a JavaScript filter function, and is the recommended
* option if filtering on document attributes only.
*
* Elementary selector syntax requires you to specify one or more fields, and the corresponding values required for
* those fields. You can create more complex selector expressions by combining operators.
*
* Operators are identified by the use of a dollar sign `$` prefix in the name field.
*
* There are two core types of operators in the selector syntax:
* * Combination operators: applied at the topmost level of selection. They are used to combine selectors. A
* combination operator takes a single argument. The argument is either another selector, or an array of selectors.
* * Condition operators: are specific to a field, and are used to evaluate the value stored in that field. For
* instance, the basic `$eq` operator matches when the specified field contains a value that is equal to the supplied
* argument.
*
* It is important for query performance to use appropriate selectors:
* * Only equality operators such as `$eq`, `$gt`, `$gte`, `$lt`, and `$lte` (but not `$ne`) can be used as the basis
* of a query. You should include at least one of these in a selector.
* * Some operators such as `$not`, `$or`, `$in`, and `$regex` cannot be answered from an index. For query selectors
* use these operators in conjunction with equality operators or create and use a partial index to reduce the number
* of documents that will need to be scanned.
*
* See [the Cloudant Docs](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-operators)for a list of all available
* combination and conditional operators.
*
* For further reference see [selector syntax](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-selector-syntax).
* @param {string} [params.lastEventId] - Header parameter to specify the ID of the last events received by the server
* on a previous connection. Overrides `since` query parameter.
* @param {boolean} [params.attEncodingInfo] - Query parameter to specify whether to include the encoding information
* in attachment stubs if the particular attachment is compressed.
* @param {boolean} [params.attachments] - Query parameter to specify whether to include attachments bodies in a
* response.
* @param {boolean} [params.conflicts] - Query parameter to specify whether to include a list of conflicted revisions
* in each returned document. Active only when `include_docs` is `true`.
* @param {boolean} [params.descending] - Query parameter to specify whether to return the documents in descending by
* key order.
* @param {string} [params.feed] - Query parameter to specify the changes feed type.
* @param {string} [params.filter] - Query parameter to specify a filter to emit only specific events from the changes
* stream.
*
* The built-in filter types are:
* * `_design` - Returns only changes to design documents.
* * `_doc_ids` - Returns changes for documents with an ID matching one specified in
* `doc_ids` request body parameter. (`POST` only)
* * `_selector` - Returns changes for documents that match the `selector`
* request body parameter. The selector syntax is the same as used for
* `_find`. (`POST` only)
* * `_view` - Returns changes for documents that match an existing map
* function in the view specified by the query parameter `view`.
*
* Additionally, the value can be the name of a JS filter function from a design document. For example:
* `design_doc/filtername`.
*
* **Note:** For better performance use the built-in `_selector`, `_design` or `_doc_ids` filters rather than JS based
* `_view` or design document filters. If you need to pass values to change the filtered content use the `_selector`
* filter type.
* @param {number} [params.heartbeat] - Query parameter to specify the period in milliseconds after which an empty
* line is sent in the results. Off by default and only applicable for
* `continuous` and `eventsource` feeds. Overrides any timeout to keep the feed alive indefinitely. May also be `true`
* to use a value of `60000`.
*
* **Note:** Delivery of heartbeats cannot be relied on at specific intervals. If your application runs in an
* environment where idle network connections may break, `heartbeat` is not suitable as a keepalive mechanism.
* Instead, consider one of the following options:
* * Use the `timeout` parameter with a value that is compatible with your network environment.
* * Switch to scheduled usage of one of the non-continuous changes feed types
* (`normal` or `longpoll`).
* * Use TCP keepalive.
* @param {boolean} [params.includeDocs] - Query parameter to specify whether to include the full content of the
* documents in the response.
* @param {number} [params.limit] - Query parameter to specify the number of returned documents to limit the result
* to.
* @param {number} [params.seqInterval] - Query parameter to specify that the update seq should only be calculated
* with every Nth result returned. When fetching changes in a batch, setting <code>seq_interval=<batch
* size></code>, where <batch size> is the number of results requested per batch, load can be reduced on the
* source database as computing the seq value across many shards (especially in highly-sharded databases) is
* expensive.
* @param {string} [params.since] - Query parameter to specify to start the results from the change immediately after
* the given update sequence. Can be a valid update sequence or `now` value. Default is `0` i.e. all changes.
* @param {string} [params.style] - Query parameter to specify how many revisions are returned in the changes array.
* The default, `main_only`, will only return the current "winning" revision; all_docs will return all leaf revisions
* (including conflicts and deleted former conflicts).
* @param {number} [params.timeout] - Query parameter to specify the maximum period in milliseconds to wait for a
* change before the response is sent, even if there are no results. Only applicable for `longpoll` or `continuous`
* feeds. Default value is specified by `httpd/changes_timeout` configuration option. Note that `60000` value is also
* the default maximum timeout to prevent undetected dead connections.
* @param {string} [params.view] - Query parameter to specify a view function as a filter. Documents pass the filter
* if the view's map function emits at least one record for them.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<NodeJS.ReadableStream>>}
*/
postChangesAsStream(params) {
const _params = { ...params };
const _requiredParams = ['db'];
const _validParams = ['db', 'docIds', 'fields', 'selector', 'lastEventId', 'attEncodingInfo', 'attachments', 'conflicts', 'descending', 'feed', 'filter', 'heartbeat', 'includeDocs', 'limit', 'seqInterval', 'since', 'style', 'timeout', 'view', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const body = {
'doc_ids': _params.docIds,
'fields': _params.fields,
'selector': _params.selector,
};
const query = {
'att_encoding_info': _params.attEncodingInfo,
'attachments': _params.attachments,
'conflicts': _params.conflicts,
'descending': _params.descending,
'feed': _params.feed,
'filter': _params.filter,
'heartbeat': _params.heartbeat,
'include_docs': _params.includeDocs,
'limit': _params.limit,
'seq_interval': _params.seqInterval,
'since': _params.since,
'style': _params.style,
'timeout': _params.timeout,
'view': _params.view,
};
const path = {
'db': _params.db,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'postChangesAsStream');
const parameters = {
options: {
url: '/{db}/_changes',
method: 'POST',
body,
qs: query,
path,
responseType: 'stream',
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Last-Event-ID': _params.lastEventId,
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequest(parameters);
}
/*************************
* databases
************************/
/**
* Retrieve the HTTP headers for a database.
*
* Returns the HTTP headers that contain a minimal amount of information about the specified database. Since the
* response body is empty, using the HEAD method is a lightweight way to check if the database exists or not.
*
* @param {Object} params - The parameters to send to the service.
* @param {string} params.db - Path parameter to specify the database name.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.EmptyObject>>}
*/
headDatabase(params) {
const _params = { ...params };
const _requiredParams = ['db'];
const _validParams = ['db', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const path = {
'db': _params.db,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'headDatabase');
const parameters = {
options: {
url: '/{db}',
method: 'HEAD',
path,
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequest(parameters);
}
/**
* Query a list of all database names in the instance.
*
* Query to retrieve a list of database names from the instance.
*
* @param {Object} [params] - The parameters to send to the service.
* @param {boolean} [params.descending] - Query parameter to specify whether to return the documents in descending by
* key order.
* @param {string} [params.endKey] - Query parameter to specify to stop returning records when the specified key is
* reached. String representation of any JSON type that matches the key type emitted by the view function.
* @param {number} [params.limit] - Query parameter to specify the number of returned documents to limit the result
* to.
* @param {number} [params.skip] - Query parameter to specify the number of records before starting to return the
* results.
* @param {string} [params.startKey] - Query parameter to specify to start returning records from the specified key.
* String representation of any JSON type that matches the key type emitted by the view function.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<string[]>>}
*/
getAllDbs(params) {
const _params = { ...params };
const _requiredParams = [];
const _validParams = ['descending', 'endKey', 'limit', 'skip', 'startKey', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const query = {
'descending': _params.descending,
'end_key': _params.endKey,
'limit': _params.limit,
'skip': _params.skip,
'start_key': _params.startKey,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'getAllDbs');
const parameters = {
options: {
url: '/_all_dbs',
method: 'GET',
qs: query,
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequest(parameters);
}
/**
* Query information about multiple databases.
*
* This operation enables you to request information about multiple databases in a single request, instead of issuing
* multiple `GET /{db}` requests. It returns a list that contains an information object for each database specified in
* the request.
*
* @param {Object} params - The parameters to send to the service.
* @param {string[]} params.keys - A list of database names.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.DbsInfoResult[]>>}
*/
postDbsInfo(params) {
const _params = { ...params };
const _requiredParams = ['keys'];
const _validParams = ['keys', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const body = {
'keys': _params.keys,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'postDbsInfo');
const parameters = {
options: {
url: '/_dbs_info',
method: 'POST',
body,
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
'Content-Type': 'application/json',
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequestAndDeserializeResponse(parameters, CloudantV1.DbsInfoResult.deserialize);
}
/**
* Delete a database.
*
* Deletes the specified database and all documents and attachments contained within it. To avoid deleting a database,
* the server responds with a 400 HTTP status code when the request URL includes a `?rev=` parameter. This response
* suggests that a user wanted to delete a document but forgot to add the document ID to the URL.
*
* @param {Object} params - The parameters to send to the service.
* @param {string} params.db - Path parameter to specify the database name.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.Ok>>}
*/
deleteDatabase(params) {
const _params = { ...params };
const _requiredParams = ['db'];
const _validParams = ['db', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const path = {
'db': _params.db,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'deleteDatabase');
const parameters = {
options: {
url: '/{db}',
method: 'DELETE',
path,
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequestAndDeserializeResponse(parameters, CloudantV1.Ok.deserialize);
}
/**
* Retrieve information about a database.
*
* Retrieve detailed information about the database.
*
* @param {Object} params - The parameters to send to the service.
* @param {string} params.db - Path parameter to specify the database name.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.DatabaseInformation>>}
*/
getDatabaseInformation(params) {
const _params = { ...params };
const _requiredParams = ['db'];
const _validParams = ['db', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const path = {
'db': _params.db,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'getDatabaseInformation');
const parameters = {
options: {
url: '/{db}',
method: 'GET',
path,
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequestAndDeserializeResponse(parameters, CloudantV1.DatabaseInformation.deserialize);
}
/**
* Create a database.
*
* Create a new database with the requested properties.
*
* @param {Object} params - The parameters to send to the service.
* @param {string} params.db - Path parameter to specify the database name.
* @param {boolean} [params.partitioned] - Query parameter to specify whether to enable database partitions when
* creating a database.
*
* Before using read the
* [FAQs](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-database-partitioning#partitioned-databases-database-partitioning)
* to understand the limitations and appropriate use cases.
* @param {number} [params.q] - The number of shards in the database. Each shard is a partition of the hash value
* range. Cloudant recommends using the default value for most databases. However, if your database is expected to be
* larger than 250 GB or have a lot of indexes, you may need to adjust the settings. In these cases, it's best to
* reach out to IBM Cloudant customer support for guidance on how to meet your specific needs and requirements.
* @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
* @returns {Promise<CloudantV1.Response<CloudantV1.Ok>>}
*/
putDatabase(params) {
const _params = { ...params };
const _requiredParams = ['db'];
const _validParams = ['db', 'partitioned', 'q', 'signal', 'headers'];
const _validationErrors = (0, ibm_cloud_sdk_core_1.validateParams)(_params, _requiredParams, _validParams);
if (_validationErrors) {
return Promise.reject(_validationErrors);
}
const query = {
'partitioned': _params.partitioned,
'q': _params.q,
};
const path = {
'db': _params.db,
};
const sdkHeaders = (0, common_1.getSdkHeaders)(CloudantV1.DEFAULT_SERVICE_NAME, 'v1', 'putDatabase');
const parameters = {
options: {
url: '/{db}',
method: 'PUT',
qs: query,
path,
},
defaultOptions: (0, extend_1.default)(true, {}, this.baseOptions, {
headers: (0, extend_1.default)(true, sdkHeaders, this.baseOptions.headers, {
'Accept': 'application/json',
}, _params.headers),
axiosOptions: {
signal: _params.signal,
},
}),
};
return this.createRequestAndDeserializeResponse(parameters, CloudantV1.Ok.deserialize);
}
/*************************
* documents
**********