You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by gl...@apache.org on 2021/01/12 13:54:04 UTC
[couchdb-nano] branch 9.0.2prep created (now 0c42c22)
This is an automated email from the ASF dual-hosted git repository.
glynnbird pushed a change to branch 9.0.2prep
in repository https://gitbox.apache.org/repos/asf/couchdb-nano.git.
at 0c42c22 convert examples to async/await style
This branch includes the following new commits:
new a71752e more verbose TypeScript descriptions and links
new 4c8bf11 ensure creds are scrubbed from logged messages
new e6d3a17 improved README
new 0c42c22 convert examples to async/await style
The 4 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[couchdb-nano] 02/04: ensure creds are scrubbed from logged messages
Posted by gl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
glynnbird pushed a commit to branch 9.0.2prep
in repository https://gitbox.apache.org/repos/asf/couchdb-nano.git
commit 4c8bf11db8928ccc9fccc55fb7ef1306f3d5b549
Author: Glynn Bird <gl...@apache.org>
AuthorDate: Mon Jan 11 17:03:24 2021 +0000
ensure creds are scrubbed from logged messages
---
lib/nano.js | 25 +++++++++++++++++--------
1 file changed, 17 insertions(+), 8 deletions(-)
diff --git a/lib/nano.js b/lib/nano.js
index 0d1c666..4abeacf 100644
--- a/lib/nano.js
+++ b/lib/nano.js
@@ -23,6 +23,7 @@ const http = require('http')
const https = require('https')
const pkg = require('../package.json')
const AGENT_DEFAULTS = { keepAlive: true, maxSockets: 50, keepAliveMsecs: 30000 }
+const SCRUBBED_STR = 'XXXXXX'
const defaultHttpAgent = new http.Agent(AGENT_DEFAULTS)
const defaultHttpsAgent = new https.Agent(AGENT_DEFAULTS)
const ChangesReader = require('./changesreader.js')
@@ -94,9 +95,9 @@ module.exports = exports = function dbScope (cfg) {
}
}
- function scrub (str) {
+ function scrubURL (str) {
if (str) {
- str = str.replace(/\/\/(.*)@/, '//XXXXXX:XXXXXX@')
+ str = str.replace(/\/\/(.*)@/, `//${SCRUBBED_STR}:${SCRUBBED_STR}@`)
}
return str
}
@@ -149,8 +150,6 @@ module.exports = exports = function dbScope (cfg) {
return
}
- log({ err: 'couch', body: body, headers: responseHeaders })
-
// cloudant stacktrace
if (typeof body === 'string') {
body = { message: body }
@@ -164,12 +163,14 @@ module.exports = exports = function dbScope (cfg) {
delete body.stack
// scrub credentials
- req.url = scrub(req.url)
- responseHeaders.url = scrub(responseHeaders.url)
+ req.url = scrubURL(req.url)
+ responseHeaders.uri = scrubURL(responseHeaders.uri)
if (req.headers.cookie) {
req.headers.cookie = 'XXXXXXX'
}
+ log({ err: 'couch', body: body, headers: responseHeaders })
+
const message = body.message || 'couch returned ' + statusCode
const errors = new Error(message)
errors.scope = 'couch'
@@ -251,7 +252,7 @@ module.exports = exports = function dbScope (cfg) {
}, cfg.requestDefaults)
// https://github.com/mikeal/request#requestjar
- const isJar = opts.jar || cfg.jar
+ const isJar = opts.jar || cfg.jar || (cfg.requestDefaults && cfg.requestDefaults.jar)
if (isJar) {
req.jar = cookieJar
@@ -343,7 +344,6 @@ module.exports = exports = function dbScope (cfg) {
// ?drilldown=["author","Dickens"]&drilldown=["publisher","Penguin"]
req.qsStringifyOptions = { arrayFormat: 'repeat' }
- log(req)
cfg.cookies = cookieJar.getCookiesSync(cfg.url)
// This where the HTTP request is made.
@@ -368,6 +368,15 @@ module.exports = exports = function dbScope (cfg) {
req.httpAgent = cfg.requestDefaults.agent || defaultHttpAgent
req.httpsAgent = cfg.requestDefaults.agent || defaultHttpsAgent
+ // scrub and log
+ const scrubbedReq = JSON.parse(JSON.stringify(req))
+ scrubbedReq.url = scrubURL(scrubbedReq.url)
+ if (scrubbedReq.auth) {
+ scrubbedReq.auth.username = SCRUBBED_STR
+ scrubbedReq.auth.password = SCRUBBED_STR
+ }
+ log(scrubbedReq)
+
// actually do the HTTP request
if (opts.stream) {
// return the Request object for streaming
[couchdb-nano] 04/04: convert examples to async/await style
Posted by gl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
glynnbird pushed a commit to branch 9.0.2prep
in repository https://gitbox.apache.org/repos/asf/couchdb-nano.git
commit 0c42c22a617b7af548004ca209c3a358ff7469a9
Author: Glynn Bird <gl...@apache.org>
AuthorDate: Tue Jan 12 09:31:45 2021 +0000
convert examples to async/await style
---
README.md | 282 +++++++++++++++++++-------------------------------------------
1 file changed, 87 insertions(+), 195 deletions(-)
diff --git a/README.md b/README.md
index 5c3b77f..5fc3d69 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ Note the minimum required version of Node.js is 10.
- [db.fetch(docnames, [params], [callback])](#dbfetchdocnames-params-callback)
- [db.fetchRevs(docnames, [params], [callback])](#dbfetchrevsdocnames-params-callback)
- [db.createIndex(indexDef, [callback])](#dbcreateindexindexdef-callback)
- - [db.changesReader...](#reading-changes-feed)
+ - [db.changesReader](#reading-changes-feed)
- [Partitioned database functions](#partition-functions)
- [db.partitionInfo(partitionKey, [callback])](#dbpartitioninfopartitionkey-callback))
- [db.partitionedList(partitionKey, [params], [callback])](#dbpartitionedlistpartitionkey-params-callback)
@@ -108,7 +108,7 @@ To use `nano` you need to connect it to your CouchDB install, to do that:
const nano = require('nano')('http://localhost:5984');
```
-The URL you supply may also contain authentication credentials e.g. `http://admin:mypassword@localhost:5984`.
+> Note: The URL you supply may also contain authentication credentials e.g. `http://admin:mypassword@localhost:5984`.
To create a new database:
@@ -180,24 +180,7 @@ async function asyncCall() {
asyncCall()
```
-or in the raw Promises-style
-
-```js
-const nano = require('nano')('http://localhost:5984');
-let alice;
-
-nano.db.destroy('alice').then((response) => {
- return nano.db.create('alice')
-}).then((response) => {
- alice = nano.use('alice')
- return alice.insert({ happy: true }, 'rabbit')
-}).then((response) => {
- console.log('you have inserted a document with an _id of rabbit')
- console.log(response);
-})
-```
-
-If you run either of these examples (after starting CouchDB) you will see:
+Running this example will produce:
```
you have inserted a document with an _id of rabbit.
@@ -251,28 +234,21 @@ const db = couch.use('foo');
### Pool size and open sockets
-A very important configuration parameter if you have a high traffic website and are using `nano` is setting up the `pool.size`. By default, the Node.js HTTP global agent (client) has a certain size of active connections that can run simultaneously, while others are kept in a queue. Pooling can be disabled by setting the `agent` property in `requestDefaults` to `false`, or adjust the global pool size using:
+A very important configuration parameter if you have a high traffic website and are using `nano` is the HTTP pool size. By default, the Node.js HTTP global agent has a infinite number of active connections that can run simultaneously. This can be limited to user-defined number (`maxSockets`) of requests that are "in flight", while others are kept in a queue. Here's an example explicitly using the Node.js HTTP agent configured with [custom options](https://nodejs.org/api/http.html#http_ne [...]
```js
-http.globalAgent.maxSockets = 20;
-```
-
-You can also increase the size in your calling context using `requestDefaults` if this is problematic. Refer to the [request] documentation and examples for further clarification.
-
-Here's an example explicitly using the keep alive agent (installed using `npm install agentkeepalive`), especially useful to limit your open sockets when doing high-volume access to CouchDB on localhost:
+const http = require('http')
+const myagent = new http.Agent({
+ keepAlive: true,
+ maxSockets: 25
+})
-```js
-const agentkeepalive = require('agentkeepalive');
-const myagent = new agentkeepalive({
- maxSockets: 50,
- maxKeepAliveRequests: 0,
- maxKeepAliveTime: 30000
+const db = require('nano')({
+ url: 'http://localhost:5984/foo',
+ requestDefaults : {
+ agent : myagent
+ }
});
-
-const db = require('nano')(
- { url: "http://localhost:5984/foo",
- requestDefaults : { "agent" : myagent }
- });
```
## TypeScript
@@ -325,9 +301,7 @@ db.insert(p).then((response) => {
Creates a CouchDB database with the given `name`:
```js
-nano.db.create('alice').then((body) => {
- console.log('database alice created!');
-})
+await nano.db.create('alice')
```
### nano.db.get(name, [callback])
@@ -335,9 +309,7 @@ nano.db.create('alice').then((body) => {
Get information about the database `name`:
```js
-nano.db.get('alice').then((body) => {
- console.log(body);
-})
+const info = await nano.db.get('alice')
```
### nano.db.destroy(name, [callback])
@@ -345,9 +317,7 @@ nano.db.get('alice').then((body) => {
Destroys the database `name`:
```js
-nano.db.destroy('alice').then((body) => {
- // database destroyed
-})
+await nano.db.destroy('alice')
```
### nano.db.list([callback])
@@ -355,12 +325,7 @@ nano.db.destroy('alice').then((body) => {
Lists all the CouchDB databases:
```js
-nano.db.list().then((body) => {
- // body is an array
- body.forEach((db) => {
- console.log(db);
- });
-});
+const dblist = await nano.db.list()
```
### nano.db.listAsStream()
@@ -384,10 +349,9 @@ has to exist, add `create_target:true` to `opts` to create it prior to
replication:
```js
-nano.db.replicate('alice', 'http://admin:password@otherhost.com:5984/alice',
- { create_target:true }).then((body) => {
- console.log(body);
-});
+const response = await nano.db.replicate('alice',
+ 'http://admin:password@otherhost.com:5984/alice',
+ { create_target:true })
```
### nano.db.replication.enable(source, target, [opts], [callback])
@@ -397,10 +361,9 @@ with options `opts`. `target` has to exist, add `create_target:true` to
`opts` to create it prior to replication. Replication will survive server restarts.
```js
-nano.db.replication.enable('alice', 'http://admin:password@otherhost.com:5984/alice',
- { create_target:true }).then((body) => {
- console.log(body);
-});
+const response = await nano.db.replication.enable('alice',
+ 'http://admin:password@otherhost.com:5984/alice',
+ { create_target:true })
```
### nano.db.replication.query(id, [opts], [callback])
@@ -409,12 +372,10 @@ Queries the state of replication using the new CouchDB API. The `id` comes from
given by the call to `replication.enable`:
```js
-nano.db.replication.enable('alice', 'http://admin:password@otherhost.com:5984/alice',
- { create_target:true }).then((body) => {
- return nano.db.replication.query(body.id);
-}).then((response) => {
- console.log(response);
-});
+const r = await nano.db.replication.enable('alice',
+ 'http://admin:password@otherhost.com:5984/alice',
+ { create_target:true })
+const q = await nano.db.replication.query(r.id)
```
### nano.db.replication.disable(id, [opts], [callback])
@@ -423,12 +384,10 @@ Disables replication using the new CouchDB API. The `id` comes from the response
by the call to `replication.enable`:
```js
-nano.db.replication.enable('alice', 'http://admin:password@otherhost.com:5984/alice',
- { create_target:true }).then((body) => {
- return nano.db.replication.disable(body.id);
-}).then((response) => {
- console.log(response);
-});
+const r = await nano.db.replication.enable('alice',
+ 'http://admin:password@otherhost.com:5984/alice',
+ { create_target:true })
+await nano.db.replication.disable(r.id);
```
### nano.db.changes(name, [params], [callback])
@@ -437,9 +396,7 @@ Asks for the changes feed of `name`, `params` contains additions
to the query string.
```js
-nano.db.changes('alice').then((body) => {
- console.log(body);
-});
+const c = await nano.db.changes('alice')
```
### nano.db.changesAsStream(name, [params])
@@ -455,9 +412,7 @@ nano.db.changes('alice').pipe(process.stdout);
Gets database information:
```js
-nano.db.info().then((body) => {
- console.log('got database info', body);
-});
+const info = await nano.db.info()
```
### nano.use(name)
@@ -466,11 +421,11 @@ Returns a database object that allows you to perform operations against that dat
```js
const alice = nano.use('alice');
-alice.insert({ happy: true }, 'rabbit').then((body) => {
- // do something
-});
+await alice.insert({ happy: true }, 'rabbit')
```
+The database object can be used to access the [Document Functions](#document-functions).
+
### nano.db.use(name)
Alias for `nano.use`
@@ -532,27 +487,21 @@ Inserts `doc` in the database with optional `params`. If params is a string, it'
```js
const alice = nano.use('alice');
-alice.insert({ happy: true }, 'rabbit').then((body) => {
- console.log(body);
-});
+const response = await alice.insert({ happy: true }, 'rabbit')
```
The `insert` function can also be used with the method signature `db.insert(doc,[callback])`, where the `doc` contains the `_id` field e.g.
```js
const alice = nano.use('alice')
-alice.insert({ _id: 'myid', happy: true }).then((body) => {
- console.log(body)
-})
+const response alice.insert({ _id: 'myid', happy: true })
```
and also used to update an existing document, by including the `_rev` token in the document being saved:
```js
const alice = nano.use('alice')
-alice.insert({ _id: 'myid', _rev: '1-23202479633c2b380f79507a776743d5', happy: false }).then((body) => {
- console.log(body)
-})
+const response = await alice.insert({ _id: 'myid', _rev: '1-23202479633c2b380f79507a776743d5', happy: false })
```
### db.destroy(docname, rev, [callback])
@@ -560,9 +509,7 @@ alice.insert({ _id: 'myid', _rev: '1-23202479633c2b380f79507a776743d5', happy: f
Removes a document from CouchDB whose `_id` is `docname` and who's revision is `_rev`:
```js
-alice.destroy('rabbit', '3-66c01cdf99e84c83a9b3fe65b88db8c0').then((body) => {
- console.log(body);
-});
+const response = await alice.destroy('rabbit', '3-66c01cdf99e84c83a9b3fe65b88db8c0')
```
### db.get(docname, [params], [callback])
@@ -570,17 +517,13 @@ alice.destroy('rabbit', '3-66c01cdf99e84c83a9b3fe65b88db8c0').then((body) => {
Gets a document from CouchDB whose `_id` is `docname`:
```js
-alice.get('rabbit').then((body) => {
- console.log(body);
-});
+const doc = await alice.get('rabbit')
```
or with optional query string `params`:
```js
-alice.get('rabbit', { revs_info: true }).then((body) => {
- console.log(body);
-});
+const doc = await alice.get('rabbit', { revs_info: true })
```
### db.head(docname, [callback])
@@ -588,9 +531,7 @@ alice.get('rabbit', { revs_info: true }).then((body) => {
Same as `get` but lightweight version that returns headers only:
```js
-alice.head('rabbit').then((headers) => {
- console.log(headers);
-});
+const headers = await alice.head('rabbit')
```
*Note:* if you call `alice.head` in the callback style, the headers are returned to you as the third argument of the callback function.
@@ -605,9 +546,7 @@ const documents = [
{ a:1, b:2 },
{ _id: 'tiger', striped: true}
];
-alice.bulk({docs:documents}).then((body) => {
- console.log(body);
-});
+const response = await alice.bulk({ docs: documents })
```
### db.list([params], [callback])
@@ -615,22 +554,16 @@ alice.bulk({docs:documents}).then((body) => {
List all the docs in the database .
```js
-alice.list().then((body) => {
- body.rows.forEach((doc) => {
- console.log(doc);
- });
+const doclist = await alice.list().then((body)
+doclist.rows.forEach((doc) => {
+ console.log(doc);
});
```
or with optional query string additions `params`:
```js
-alice.list({include_docs: true}).then((body) => {
- body.rows.forEach((doc) => {
- // output each document's body
- console.log(doc.doc);
- });
-});
+const doclist = await alice.list({include_docs: true})
```
### db.listAsStream([params])
@@ -652,9 +585,7 @@ to `true`.
```js
const keys = ['tiger', 'zebra', 'donkey'];
-alice.fetch({keys: keys}).then((data) => {
- console.log(data);
-});
+const datat = await alice.fetch({keys: keys})
```
### db.fetchRevs(docnames, [params], [callback])
@@ -676,9 +607,7 @@ const indexDef = {
index: { fields: ['foo'] },
name: 'fooindex'
};
-alice.createIndex(indexDef).then((result) => {
- console.log(result);
-});
+const response = await alice.createIndex(indexDef)
```
## Reading Changes Feed
@@ -996,9 +925,7 @@ const fs = require('fs');
fs.readFile('rabbit.png', (err, data) => {
if (!err) {
- alice.multipart.insert({ foo: 'bar' }, [{name: 'rabbit.png', data: data, content_type: 'image/png'}], 'mydoc').then((body) => {
- console.log(body);
- });
+ await alice.multipart.insert({ foo: 'bar' }, [{name: 'rabbit.png', data: data, content_type: 'image/png'}], 'mydoc')
}
});
```
@@ -1009,9 +936,7 @@ Get `docname` together with its attachments via `multipart/related` request with
[doc](http://wiki.apache.org/couchdb/HTTP_Document_API#Getting_Attachments_With_a_Document) for more details. The multipart response body is a `Buffer`.
```js
-alice.multipart.get('rabbit').then((buffer) => {
- console.log(buffer.toString());
-});
+const response = await alice.multipart.get('rabbit')
```
## Attachments functions
@@ -1027,10 +952,11 @@ const fs = require('fs');
fs.readFile('rabbit.png', (err, data) => {
if (!err) {
- alice.attachment.insert('rabbit', 'rabbit.png', data, 'image/png',
- { rev: '12-150985a725ec88be471921a54ce91452' }).then((body) => {
- console.log(body);
- });
+ await alice.attachment.insert('rabbit',
+ 'rabbit.png',
+ data,
+ 'image/png',
+ { rev: '12-150985a725ec88be471921a54ce91452' })
}
});
```
@@ -1048,18 +974,16 @@ Get `docname`'s attachment `attname` with optional query string additions
```js
const fs = require('fs');
-alice.attachment.get('rabbit', 'rabbit.png').then((body) => {
- fs.writeFile('rabbit.png', body);
-});
+const body = await alice.attachment.get('rabbit', 'rabbit.png')
+fs.writeFile('rabbit.png', body)
```
### db.attachment.getAsStream(docname, attname, [params])
```js
const fs = require('fs');
-
alice.attachment.getAsStream('rabbit', 'rabbit.png')
- .on('error', (e) => console.error('error', e))
+ .on('error', e => console.error)
.pipe(fs.createWriteStream('rabbit.png'));
```
@@ -1070,10 +994,7 @@ alice.attachment.getAsStream('rabbit', 'rabbit.png')
Destroy attachment `attname` of `docname`'s revision `rev`.
```js
-alice.attachment.destroy('rabbit', 'rabbit.png',
- {rev: '1-4701d73a08ce5c2f2983bf7c9ffd3320'}).then((body) => {
- console.log(body);
-});
+const response = await alice.attachment.destroy('rabbit', 'rabbit.png', {rev: '1-4701d73a08ce5c2f2983bf7c9ffd3320'})
```
## Views and design functions
@@ -1084,44 +1005,26 @@ Calls a view of the specified `designname` with optional query string `params`.
`{ keys: ['key1', 'key2', 'key_n'] }`, as `params`.
```js
-alice.view('characters', 'happy_ones', {
- 'key': 'Tea Party',
- 'include_docs': true
-}).then((body) => {
- body.rows.forEach((doc) => {
- console.log(doc.value);
- });
-});
+const body = await alice.view('characters', 'happy_ones', { key: 'Tea Party', include_docs: true })
+body.rows.forEach((doc) => {
+ console.log(doc.value)
+})
```
or
```js
-alice.view('characters', 'soldiers', {
- 'keys': ['Hearts', 'Clubs']
-}).then((body) => {
- body.rows.forEach((doc) => {
- console.log(doc.value);
- });
-});
+const body = await alice.view('characters', 'soldiers', { keys: ['Hearts', 'Clubs'] })
```
When `params` is not supplied, or no keys are specified, it will simply return all documents in the view:
```js
-alice.view('characters', 'happy_ones').then((body) => {
- body.rows.forEach((doc) => {
- console.log(doc.value);
- });
-});
+const body = await alice.view('characters', 'happy_ones')
```
```js
-alice.view('characters', 'happy_ones', { include_docs: true }).then((body) => {
- body.rows.forEach((doc) => {
- console.log(doc.value);
- });
-});
+const body = alice.view('characters', 'happy_ones', { include_docs: true })
```
### db.viewAsStream(designname, viewname, [params])
@@ -1139,9 +1042,7 @@ alice.viewAsStream('characters', 'happy_ones', {reduce: false})
Calls a list function fed by the given view from the specified design document.
```js
-alice.viewWithList('characters', 'happy_ones', 'my_list').then((body) => {
- console.log(body);
-});
+const body = await alice.viewWithList('characters', 'happy_ones', 'my_list')
```
### db.viewWithListAsStream(designname, viewname, listname, [params], [callback])
@@ -1149,9 +1050,9 @@ alice.viewWithList('characters', 'happy_ones', 'my_list').then((body) => {
Calls a list function fed by the given view from the specified design document as a stream.
```js
-alice.viewWithListAsStream('characters', 'happy_ones', 'my_list').then((body) => {
- console.log(body);
-});
+alice.viewWithListAsStream('characters', 'happy_ones', 'my_list')
+ .on('error', (e) => console.error('error', e))
+ .pipe(process.stdout);
```
### db.show(designname, showname, doc_id, [params], [callback])
@@ -1160,9 +1061,7 @@ Calls a show function from the specified design for the document specified by do
optional query string additions `params`.
```js
-alice.show('characters', 'format_doc', '3621898430').then((doc) => {
- console.log(doc);
-});
+const doc = await alice.show('characters', 'format_doc', '3621898430')
```
Take a look at the [couchdb wiki](http://wiki.apache.org/CouchDB/Formatting_with_Show_and_List#Showing_Documents)
@@ -1173,10 +1072,7 @@ for possible query paramaters and more information on show functions.
Calls the design's update function with the specified doc in input.
```js
-db.atomic("update", "inplace", "foobar",
-{field: "foo", value: "bar"}).then((response) => {
- console.log(response);
-});
+const response = await db.atomic('update', 'inplace', 'foobar', {field: 'foo', value: 'bar'})
```
Note that the data is sent in the body of the request.
@@ -1185,13 +1081,12 @@ An example update handler follows:
```js
"updates": {
"in-place" : "function(doc, req) {
- var request_body = JSON.parse(req.body);
-
- var field = request_body.field;
- var value = request_body.value;
- var message = 'set ' + field + ' to ' + value;
- doc[field] = value;
- return [doc, message];
+ var request_body = JSON.parse(req.body)
+ var field = request_body.field
+ var value = request_body.value
+ var message = 'set ' + field + ' to ' + value
+ doc[field] = value
+ return [doc, message]
}"
}
```
@@ -1201,18 +1096,14 @@ An example update handler follows:
Calls a view of the specified design with optional query string additions `params`.
```js
-alice.search('characters', 'happy_ones', { q: 'cat' }).then((doc) => {
- console.log(doc);
-});
+const response = await alice.search('characters', 'happy_ones', { q: 'cat' })
```
or
```js
const drilldown = [['author', 'Dickens']['publisher','Penguin']]
-alice.search('inventory', 'books', { q: '*:*', drilldown: drilldown }).then((doc) => {
- console.log(doc);
-});
+const response = await alice.search('inventory', 'books', { q: '*:*', drilldown: drilldown })
```
Check out the tests for a fully functioning example.
@@ -1239,9 +1130,7 @@ const q = {
fields: [ "name", "age", "tags", "url" ],
limit:50
};
-alice.find(q).then((doc) => {
- console.log(doc);
-});
+const response = await alice.find(q)
```
### db.findAsStream(selector)
@@ -1278,7 +1167,10 @@ const username = 'user'
const userpass = 'pass'
const db = nano.db.use('mydb')
+// authenticate
await nano.auth(username, userpass)
+
+// requests from now on are authenticated
const doc = await db.get('mydoc')
console.log(doc)
```
[couchdb-nano] 01/04: more verbose TypeScript descriptions and links
Posted by gl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
glynnbird pushed a commit to branch 9.0.2prep
in repository https://gitbox.apache.org/repos/asf/couchdb-nano.git
commit a71752e98f3ba2b6b87d0ac21363316590279327
Author: Glynn Bird <gl...@apache.org>
AuthorDate: Mon Jan 11 17:01:33 2021 +0000
more verbose TypeScript descriptions and links
---
lib/nano.d.ts | 473 ++++++++++++++++++++++++++++++++++++++++++----------------
1 file changed, 341 insertions(+), 132 deletions(-)
diff --git a/lib/nano.d.ts b/lib/nano.d.ts
index 3f21d25..857a9d8 100644
--- a/lib/nano.d.ts
+++ b/lib/nano.d.ts
@@ -20,29 +20,47 @@
import { EventEmitter } from "events";
+/** nano entry function */
declare function nano(
config: nano.Configuration | string
): nano.ServerScope;
declare namespace nano {
+ /** RequestDefaults.auth options */
interface RequestDefaultOptionsAuth {
username: string,
password: string
}
+
+ /** RequestDefaults options */
interface RequestDefaultsOptions {
- timeout: number;
- agent: any;
- headers: object;
- auth: RequestDefaultOptionsAuth;
+ timeout?: number;
+ agent?: any;
+ headers?: object;
+ auth?: RequestDefaultOptionsAuth;
+ jar?: boolean;
}
+ /** Nano configuration */
interface Configuration {
+ /** The URL of the CouchDB service, including username and password if required e.g.
+ * http://username:password@hostname:port
+ */
url: string;
+ /** For cookie authentication */
cookie?: string;
+ /** HTTP request options
+ * @see README: {@link https://www.npmjs.com/package/nano#pool-size-and-open-sockets}
+ */
requestDefaults?: RequestDefaultsOptions;
+ /** Logging function
+ * @see README: {@link https://www.npmjs.com/package/nano#logging}
+ */
log?(id: string, args: any): void;
+ /** Set to false to prevent parsing of url
+ * @see README: {@link https://www.npmjs.com/package/nano#configuration}
+ */
parseUrl?: boolean;
- request?(params: any): void;
}
type Callback<R> = (error: RequestError | null, response: R, headers?: any) => void;
@@ -71,24 +89,63 @@ declare namespace nano {
description?: string;
}
+ /** Server scope */
interface ServerScope {
+ /**
+ * An object containing the nano configurations.
+ * @see README: {@link https://www.npmjs.com/package/nano#nanoconfig}
+ */
readonly config: ServerConfig;
db: DatabaseScope;
+ /**
+ * Returns a database object that allows you to perform operations against that database.
+ * @see README: {@link https://www.npmjs.com/package/nano#nanousename}
+ */
use<D>(db: string): DocumentScope<D>;
+ /**
+ * Returns a database object that allows you to perform operations against that database.
+ * @see README: {@link https://www.npmjs.com/package/nano#nanoscopename}
+ */
scope<D>(db: string): DocumentScope<D>;
+ /**
+ * Initiates a custom request
+ * @see README: {@link https://www.npmjs.com/package/nano#nanorequestopts-callback}
+ **/
request(opts: RequestOptions | string, callback?: Callback<any>): Promise<any>;
+ /**
+ * Initiates a custom request
+ * @see README: {@link https://www.npmjs.com/package/nano#nanorequestopts-callback}
+ **/
relax(opts: RequestOptions | string, callback?: Callback<any>): Promise<any>;
+ /**
+ * Initiates a custom request
+ * @see README: {@link https://www.npmjs.com/package/nano#nanorequestopts-callback}
+ **/
dinosaur(opts: RequestOptions | string, callback?: Callback<any>): Promise<any>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/authn.html#cookie-authentication} */
+ /**
+ * Initiates new session for specified user credentials by providing Cookie value.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/authn.html#cookie-authentication} */
auth(username: string, userpass: string, callback?: Callback<DatabaseAuthResponse>): Promise<DatabaseAuthResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/authn.html#get--_session} */
+ /**
+ * Returns information about the authenticated user, including a User Context Object, the authentication method and database that were used, and a list of configured authentication handlers on the server.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/authn.html#get--_session} */
session(callback?: Callback<DatabaseSessionResponse>): Promise<DatabaseSessionResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
+ /**
+ * Returns a list of all database events in the CouchDB instance.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
updates(callback?: Callback<DatabaseUpdatesResponse>): Promise<DatabaseUpdatesResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
+ /**
+ * Returns a list of all database events in the CouchDB instance.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
updates(params: UpdatesParams, callback?: Callback<DatabaseUpdatesResponse>): Promise<DatabaseUpdatesResponse>;
- uuids(num: number, callback?: Callback<any>): Promise<UUIDObject>;
- /** @see {@link https://docs.couchdb.org/en/stable/api/server/common.html#api-server-root} */
+ /**
+ * Requests one or more Universally Unique Identifiers (UUIDs) from the CouchDB instance.
+ * @see Docs: {@link https://docs.couchdb.org/en/stable/api/server/common.html#uuids}
+ */
+ uuids(num?: number, callback?: Callback<any>): Promise<UUIDObject>;
+ /**
+ * Accessing the root of a CouchDB instance returns meta information about the instance.
+ * @see Docs: {@link https://docs.couchdb.org/en/stable/api/server/common.html#api-server-root} */
info(callback?: Callback<InfoResponse>): Promise<InfoResponse>;
}
@@ -96,7 +153,9 @@ declare namespace nano {
uuids: string[];
}
- /** @see {@link https://docs.couchdb.org/en/stable/api/server/common.html#api-server-root} */
+ /**
+ * Response to CouchDB root API call - cluster information.
+ * @see Docs: {@link https://docs.couchdb.org/en/stable/api/server/common.html#api-server-root} */
interface InfoResponse {
couchdb: string;
version: string;
@@ -106,59 +165,83 @@ declare namespace nano {
vendor: { name: string }
}
+ /**
+ * Database creation options
+ * @see Docs: {@link https://docs.couchdb.org/en/stable/api/database/common.html#put--db} */
interface DatabaseCreateParams {
n?: number;
partitioned?: boolean;
q?: number;
}
+ /** Database scope */
interface DatabaseScope {
replication: {
enable(source: string, target: string, opts0: object, callback0?: Callback<DatabaseCreateResponse>): Promise<DatabaseCreateResponse>;
disable(id:string, rev: string, opts0: object, callback0?: Callback<DatabaseCreateResponse>): Promise<DatabaseCreateResponse>;
query(id: string, opts0: object, callback0?: Callback<DatabaseGetResponse>): Promise<DatabaseGetResponse>;
};
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#put--db} */
+ /**
+ * Create database.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#put--db} */
create(name: string, params?: DatabaseCreateParams, callback?: Callback<DatabaseCreateResponse>): Promise<DatabaseCreateResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#get--db} */
+ /** Get database information.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#get--db} */
get(name: string, callback?: Callback<DatabaseGetResponse>): Promise<DatabaseGetResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#delete--db} */
+ /** Delete database.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#delete--db} */
destroy(name: string, callback?: Callback<OkResponse>): Promise<OkResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_all_dbs} */
+ /** List databases.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_all_dbs} */
list(callback?: Callback<string[]>): Promise<string[]>;
+ /** List databases as a stream.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_all_dbs} */
listAsStream(): NodeJS.ReadStream;
+ /** Use a specific database.
+ * @see README: {@link https://www.npmjs.com/package/nano#nanousename} */
use<D>(db: string): DocumentScope<D>;
+ /** Request compaction on a database.
+ * @see Docs: {@link https://docs.couchdb.org/en/stable/api/database/compact.html} */
compact(name: string, callback?: Callback<OkResponse>): Promise<OkResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/compact.html#post--db-_compact} */
+ /** Request compaction of a database's view indexes.
+ * @see Docs: {@link https://docs.couchdb.org/en/stable/api/database/compact.html} */
compact(name: string, designname: string, callback?: Callback<OkResponse>): Promise<OkResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
+ /** Request a replication operation.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
replicate<D>(
source: string | DocumentScope<D>,
target: string | DocumentScope<D>,
callback?: Callback<DatabaseReplicateResponse>
): Promise<DatabaseReplicateResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
+ /** Reqiest a replication
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
replicate<D>(
source: string | DocumentScope<D>,
target: string | DocumentScope<D>,
options: DatabaseReplicateOptions,
callback?: Callback<DatabaseReplicateResponse>
): Promise<DatabaseReplicateResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
+ /** Return sorted list of changes to a database.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
changes(name: string, callback?: Callback<DatabaseChangesResponse>): Promise<DatabaseChangesResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/compact.html#post--db-_compact} */
+ /** Return sorted list of changes to a database with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/compact.html#post--db-_compact} */
changes(name: string, params: DatabaseChangesParams, callback?: Callback<DatabaseChangesResponse>): Promise<DatabaseChangesResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
+ /** Return sorted list of changes to a database as a stream.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
changesAsStream(name: string): NodeJS.ReadStream;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/compact.html#post--db-_compact} */
+ /** Return sorted list of changes to a database with options as a stream.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/compact.html#post--db-_compact} */
changesAsStream(name: string, params: DatabaseChangesParams): NodeJS.ReadStream;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
+ /** Return a list of all database events.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
updates(callback?: Callback<DatabaseUpdatesResponse>): Promise<DatabaseUpdatesResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
+ /** Return a list of all database event with options
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
updates(params: UpdatesParams, callback?: Callback<DatabaseUpdatesResponse>): Promise<DatabaseUpdatesResponse>;
}
-
+ /** ChangesReader options */
interface ChangesReaderOptions {
/** number of changes per API call */
batchSize?: number;
@@ -178,6 +261,7 @@ declare namespace nano {
selector?: MangoSelector;
}
+ /** ChangesReader functions */
interface ChangesReaderScope {
/** fetch changes forever */
start(opts: ChangesReaderOptions): EventEmitter;
@@ -189,90 +273,128 @@ declare namespace nano {
stop(): void;
}
+ /** Documents scope */
interface DocumentScope<D> {
+ /**
+ * An object containing the nano configurations.
+ * @see README: {@link https://www.npmjs.com/package/nano#nanoconfig} */
readonly config: ServerConfig;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#get--db} */
+ /** Get database info
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#get--db} */
info(callback?: Callback<DatabaseGetResponse>): Promise<DatabaseGetResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
+ /** Request a replication opertation with this datbase as the target.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
replicate<D>(
target: string | DocumentScope<D>,
callback?: Callback<DatabaseReplicateResponse>
): Promise<DatabaseReplicateResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
+ /** Request a replication opertation with this datbase as the target with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
replicate(
target: string | DocumentScope<D>,
options: any,
callback?: Callback<DatabaseReplicateResponse>
): Promise<DatabaseReplicateResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/compact.html#post--db-_compact} */
+ /** Request compaction on this database.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/compact.html#post--db-_compact} */
compact(callback?: Callback<OkResponse>): Promise<OkResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
+ /** Return sorted list of changes to this database.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
changes(callback?: Callback<DatabaseChangesResponse>): Promise<DatabaseChangesResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
+ /** Return sorted list of changes to this database with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
changes(params: DatabaseChangesParams, callback?: Callback<DatabaseChangesResponse>): Promise<DatabaseChangesResponse>;
+ /** Changes feed follower.
+ * @see README: {@link https://www.npmjs.com/package/nano#reading-changes-feed} */
changesReader: ChangesReaderScope;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/authn.html#cookie-authentication} */
+ /** Initiates new session for specified user credentials by providing Cookie value.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/authn.html#cookie-authentication} */
auth(username: string, userpass: string, callback?: Callback<DatabaseAuthResponse>): Promise<DatabaseAuthResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/authn.html#get--_session} */
+ /** Returns information about the authenticated user, including a User Context Object, the authentication method and database that were used, and a list of configured authentication handlers on the server.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/authn.html#get--_session} */
session(callback?: Callback<DatabaseSessionResponse>): Promise<DatabaseSessionResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#post--db}
- * @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#put--db-docid} */
+ /** Insert a document into this database.
+ * @see POST Docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#post--db}
+ * @see PUT Docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#put--db-docid} */
insert(document: ViewDocument<D> | D & MaybeDocument, callback?: Callback<DocumentInsertResponse>): Promise<DocumentInsertResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#post--db}
- * @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#put--db-docid} */
+ /**
+ * Insert a document into this database with options.
+ * @see POST Docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#post--db}
+ * @see PUT Docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#put--db-docid} */
insert(
document: ViewDocument<D> | D & MaybeDocument,
params: DocumentInsertParams | string | null,
callback?: Callback<DocumentInsertResponse>
): Promise<DocumentInsertResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#get--db-docid} */
+ /** Fetch a document from this database.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#get--db-docid} */
get(docname: string, callback?: Callback<DocumentGetResponse & D>): Promise<DocumentGetResponse & D>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#get--db-docid} */
+ /** Fetch a document from this database with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#get--db-docid} */
get(docname: string, params?: DocumentGetParams, callback?: Callback<DocumentGetResponse & D>): Promise<DocumentGetResponse & D>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#head--db-docid} */
+ /** Fetch document meta data, useful for fetching a document's current revision.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#head--db-docid} */
head(docname: string, callback?: Callback<any>): Promise<any>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#delete--db-docid} */
+ /** Delete a document from this database.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#delete--db-docid} */
destroy(docname: string, rev: string, callback?: Callback<DocumentDestroyResponse>): Promise<DocumentDestroyResponse>;
+ /** Bulk insert/update/delete multiple documents in this database.
+ * @see Docs: {@link https://docs.couchdb.org/en/stable/api/database/bulk-api.html#db-bulk-docs} */
bulk(docs: BulkModifyDocsWrapper, callback?: Callback<DocumentBulkResponse[]>): Promise<DocumentBulkResponse[]>;
+ /** Bulk insert/update/delete multiple documents in this database, with options.
+ * @see Docs: {@link https://docs.couchdb.org/en/stable/api/database/bulk-api.html#db-bulk-docs} */
bulk(docs: BulkModifyDocsWrapper, params: any, callback?: Callback<DocumentInsertResponse[]>): Promise<DocumentInsertResponse[]>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
+ /** List documents from this database.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
list(callback?: Callback<DocumentListResponse<D>>): Promise<DocumentListResponse<D>>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
+ /** List documents from this database with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
list(params: DocumentListParams, callback?: Callback<DocumentListResponse<D>>): Promise<DocumentListResponse<D>>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
+ /** List document from this database as a stream.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
listAsStream(): NodeJS.ReadStream;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
+ /** List document from this database as a stream with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
listAsStream(params: DocumentListParams): NodeJS.ReadStream;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
+ /** Fetch a list of documents by _id.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
fetch(docnames: BulkFetchDocsWrapper, callback?: Callback<DocumentFetchResponse<D>>): Promise<DocumentFetchResponse<D>>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
+ /** Fetch a list of documents by _id with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
fetch(
docnames: BulkFetchDocsWrapper,
params: DocumentFetchParams,
callback?: Callback<DocumentFetchResponse<D>>
): Promise<DocumentFetchResponse<D>>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
+ /** Fetch revisions of a list of document _ids.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
fetchRevs(docnames: BulkFetchDocsWrapper, callback?: Callback<DocumentFetchRevsResponse<D>>): Promise<DocumentFetchRevsResponse<D>>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
+ /** Fetch revisions of a list of document _ids with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
fetchRevs(
docnames: BulkFetchDocsWrapper,
params: DocumentFetchParams,
callback?: Callback<DocumentFetchRevsResponse<D>>
): Promise<DocumentFetchRevsResponse<D>>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/find.html#db-index} */
+ /** Create a Mango index.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/find.html#db-index} */
createIndex(indexDef: CreateIndexRequest,
callback?: Callback<CreateIndexResponse>
): Promise<CreateIndexResponse>;
+ /** Multipart HTTP functions */
multipart: Multipart<D>;
+ /** Attachment functions */
attachment: Attachment;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#get--db-_design-ddoc-_show-func} */
+ /** Apply a show function to a document.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#get--db-_design-ddoc-_show-func} */
show(
designname: string,
showname: string,
doc_id: string,
callback?: Callback<any>
): Promise<any>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#get--db-_design-ddoc-_show-func} */
+ /** Apply a show function to a document.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#get--db-_design-ddoc-_show-func} */
show(
designname: string,
showname: string,
@@ -280,14 +402,16 @@ declare namespace nano {
params: any,
callback?: Callback<any>
): Promise<any>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#put--db-_design-ddoc-_update-func-docid} */
+ /** Executes an update function on the server side for the supplied document id.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#put--db-_design-ddoc-_update-func-docid} */
atomic<R>(
designname: string,
updatename: string,
docname: string,
callback?: Callback<R>
): Promise<R>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#put--db-_design-ddoc-_update-func-docid} */
+ /** Executes an update function on the server side for the supplied document id with body.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#put--db-_design-ddoc-_update-func-docid} */
atomic<R>(
designname: string,
updatename: string,
@@ -295,14 +419,16 @@ declare namespace nano {
body: any,
callback?: Callback<R>
): Promise<R>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#put--db-_design-ddoc-_update-func-docid} */
+ /** Executes an update function on the server side for the supplied document id.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#put--db-_design-ddoc-_update-func-docid} */
updateWithHandler(
designname: string,
updatename: string,
docname: string,
callback?: Callback<OkResponse>
): Promise<OkResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#put--db-_design-ddoc-_update-func-docid} */
+ /** Executes an update function on the server side for the supplied document id with body.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#put--db-_design-ddoc-_update-func-docid} */
updateWithHandler(
designname: string,
updatename: string,
@@ -310,17 +436,23 @@ declare namespace nano {
body: any,
callback?: Callback<OkResponse>
): Promise<OkResponse>;
+ /** Executes a search request against the named index.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/ddoc/search.html#db-design-design-doc-search-index-name} */
search<V>(
designname: string,
searchname: string,
params: DocumentSearchParams,
callback?: Callback<DocumentSearchResponse<V>>
): Promise<DocumentSearchResponse<V>>;
+ /** Executes a search request against the named index as a stream.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/ddoc/search.html#db-design-design-doc-search-index-name} */
searchAsStream<V>(
designname: string,
searchname: string,
params: DocumentSearchParams
): NodeJS.ReadStream;
+ /** Low-level wrapper that executes a view from a Design Document.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view} */
baseView<V>(
designname: string,
viewname: string,
@@ -328,42 +460,44 @@ declare namespace nano {
params?: any,
callback?: Callback<any>
): Promise<any>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view}
- * @see {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#post--db-_design-ddoc-_view-view} */
+ /** Executes a view from a Design Document.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view} */
view<V>(
designname: string,
viewname: string,
callback?: Callback<DocumentViewResponse<V,D>>
): Promise<DocumentViewResponse<V,D>>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view}
- * @see {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#post--db-_design-ddoc-_view-view} */
+ /** Executes a view from a Design Document, with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view} */
view<V>(
designname: string,
viewname: string,
params: DocumentViewParams,
callback?: Callback<DocumentViewResponse<V,D>>
): Promise<DocumentViewResponse<V,D>>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view}
- * @see {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#post--db-_design-ddoc-_view-view} */
+ /** Executes a view from a Design Document as a stream
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view} */
viewAsStream<V>(
designname: string,
viewname: string
): NodeJS.ReadStream;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view}
- * @see {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#post--db-_design-ddoc-_view-view} */
+ /** Executes a view from a Design Document, with options as a stream
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view} */
viewAsStream<V>(
designname: string,
viewname: string,
params: DocumentViewParams
): NodeJS.ReadStream;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#db-design-design-doc-list-list-name-view-name} */
+ /** Applies a list function to a view.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#db-design-design-doc-list-list-name-view-name} */
viewWithList(
designname: string,
viewname: string,
listname: string,
callback?: Callback<any>
): Promise<any>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#db-design-design-doc-list-list-name-view-name} */
+ /** Applies a list function to a view with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#db-design-design-doc-list-list-name-view-name} */
viewWithList(
designname: string,
viewname: string,
@@ -371,43 +505,60 @@ declare namespace nano {
params: DocumentViewParams,
callback?: Callback<any>
): Promise<any>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#db-design-design-doc-list-list-name-view-name} */
+ /** Applies a list function to a view as a stream.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#db-design-design-doc-list-list-name-view-name} */
viewWithListAsStream(
designname: string,
viewname: string,
listname: string,
callback?: Callback<any>
- ): Promise<any>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#db-design-design-doc-list-list-name-view-name} */
+ ): NodeJS.ReadStream;
+ /** Applies a list function to a view with options as a stream.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/render.html#db-design-design-doc-list-list-name-view-name} */
viewWithListAsStream(
designname: string,
viewname: string,
listname: string,
params: DocumentViewParams,
callback?: Callback<any>
- ): Promise<any>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/find.html#db-find} */
+ ): NodeJS.ReadStream;
+ /** Run Mango query.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/find.html#db-find} */
find(query: MangoQuery, callback?: Callback<MangoResponse<D>>): Promise <MangoResponse<D>>;
+ /** Server scope */
server: ServerScope;
- //https://docs.couchdb.org/en/latest/partitioned-dbs/index.html
+ /** Fetch information about a single partition in this database.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/partitioned-dbs.html#db-partition-partition} */
partitionInfo(partitionKey: string, callback?: Callback<PartitionInfoResponse>): Promise <PartitionInfoResponse>;
+ /** List documents in a single partition in this database.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/partitioned-dbs.html#db-partition-partition-all-docs} */
partitionedList(partitionKey: string, params?: DocumentFetchParams, callback?: Callback<DocumentListResponse<D>>): Promise<DocumentListResponse<D>>;
+ /** List documents in a single partition in this database as a stream.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/partitioned-dbs.html#db-partition-partition-all-docs} */
partitionedListAsStream(partitionKey: string, params?: DocumentFetchParams): NodeJS.ReadStream;
+ /** Run Mango query a single partition in this database.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/partitioned-dbs.html#db-partition-partition-id-find} */
partitionedFind(partitionKey: string, query: MangoQuery, callback?: Callback<MangoResponse<D>>): Promise <MangoResponse<D>>;
+ /** Run Mango query a single partition in this database, as a stream.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/partitioned-dbs.html#db-partition-partition-id-find} */
partitionedFindAsStream(partitionKey: string, query: MangoQuery): NodeJS.ReadStream;
- partitionedViewpartitionedSearch<V>(
+ /** Run a full-text search in a single partition in this database. */
+ partitionedSearch<V>(
partitionKey: string,
designname: string,
searchname: string,
params: DocumentSearchParams,
callback?: Callback<DocumentSearchResponse<V>>
): Promise<DocumentSearchResponse<V>>;
+ /** Run a full-text search in a single partition in this database, as a stream. */
partitionedSearchAsStream(
partitionKey: string,
designname: string,
searchname: string,
params: DocumentSearchParams
): NodeJS.ReadStream;
+ /** Executes the specified view function in a single partition from the specified design document.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/partitioned-dbs.html#db-partition-partition-design-design-doc-view-view-name} */
partitionedView<V>(
partitionKey: string,
designname: string,
@@ -415,6 +566,8 @@ declare namespace nano {
params: DocumentViewParams,
callback?: Callback<DocumentViewResponse<V,D>>
): Promise<DocumentViewResponse<V,D>>;
+ /** Executes the specified view function in a single partition from the specified design document, as a stream
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/partitioned-dbs.html#db-partition-partition-design-design-doc-view-view-name} */
partitionedViewAsStream<V>(
partitionKey: string,
designname: string,
@@ -423,24 +576,33 @@ declare namespace nano {
): NodeJS.ReadStream;
}
+ /** attachment data */
interface AttachmentData {
name: string;
data: any;
content_type: any;
}
+ /** Multi-part HTTP functions */
interface Multipart<D> {
- /** @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#creating-multiple-attachments} */
+ /** Create doc with multiple attachments using mutlipart HTTP request.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#creating-multiple-attachments} */
insert(doc: D, attachments: AttachmentData[], callback?: Callback<DocumentInsertResponse>): Promise<DocumentInsertResponse>;
- /** @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#creating-multiple-attachments} */
+ /** Create doc with multiple attachments using mutlipart HTTP request with options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#creating-multiple-attachments} */
insert(doc: D, attachments: AttachmentData[], params: any, callback?: Callback<DocumentInsertResponse>): Promise<DocumentInsertResponse>;
+ /** Fetch document and its attachments as a multipart HTTP request.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/document/common.html#efficient-multiple-attachments-retrieving} */
get(docname: string, callback?: Callback<any>): Promise<any>;
- get(docname: string, params: any, callback?: Callback<any>): Promise<any>;
+ /** Fetch document and its attachments as a multipart HTTP request with options.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/document/common.html#efficient-multiple-attachments-retrieving} */
+ get(docname: string, params: any, callback?: Callback<any>): Promise<any>;
}
+ /** Attachment functions */
interface Attachment {
- // NodeJS.WritableStream
- insert(docname: string, attname: string, att: null, contenttype: string, params?: any): Promise<DocumentInsertResponse>;
+ /** Insert an attachment.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/document/attachments.html#put--db-docid-attname} */
insert(
docname: string,
attname: string,
@@ -448,6 +610,8 @@ declare namespace nano {
contenttype: string,
callback?: Callback<DocumentInsertResponse>
): Promise<DocumentInsertResponse>;
+ /** Insert an attachment with options.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/document/attachments.html#put--db-docid-attname} */
insert(
docname: string,
attname: string,
@@ -456,15 +620,25 @@ declare namespace nano {
params: any,
callback?: Callback<DocumentInsertResponse>
): Promise<DocumentInsertResponse>;
+ /** Get an attachment.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/document/attachments.html#get--db-docid-attname} */
get(docname: string, attname: string, callback?: Callback<Buffer>): Promise<Buffer>;
+ /** Get an attachment as a stream.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/document/attachments.html#get--db-docid-attname} */
getAsStream(docname: string, attname: string): NodeJS.ReadStream;
+ /** Get an attachment with options.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/document/attachments.html#get--db-docid-attname} */
get(
docname: string,
attname: string,
params: any,
callback?: Callback<Buffer>
): Promise<Buffer>;
+ /** Delete an attachment.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/document/attachments.html#delete--db-docid-attname} */
destroy(docname: string, attname: string, callback?: Callback<any>): Promise<any>;
+ /** Delete an attachment with options.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/document/attachments.html#delete--db-docid-attname} */
destroy(
docname: string,
attname: string,
@@ -473,11 +647,14 @@ declare namespace nano {
): Promise<any>;
}
+ /** Server configuration */
interface ServerConfig {
url: string;
db: string;
}
+ /** Custom request options
+ * @see README: {@link https://www.npmjs.com/package/nano#nanorequestopts-callback}*/
interface RequestOptions {
db?: string;
method?: string;
@@ -492,7 +669,8 @@ declare namespace nano {
multipart?: any[];
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
+ /** Global changes feed paramters.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
interface UpdatesParams {
feed: "longpoll" | "continuous" | "eventsource";
timeout: number;
@@ -555,7 +733,8 @@ declare namespace nano {
// Database scope request and response
// -------------------------------------
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#put--db} */
+ /** Database creation options
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#put--db} */
interface DatabaseCreateResponse {
/** Operation status. Available in case of success */
ok?: boolean;
@@ -567,7 +746,8 @@ declare namespace nano {
reason?: string;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#get--db} */
+ /** Database information response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#get--db} */
interface DatabaseGetResponse {
/** Set to true if the database compaction routine is operating on this database. */
compact_running: boolean;
@@ -611,14 +791,16 @@ declare namespace nano {
update_seq: number;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#delete--db}
- * @see {@link http://docs.couchdb.org/en/latest/api/database/compact.html#post--db-_compact} */
+ /** OK response
+ * @see Delete docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#delete--db}
+ * @see Compaction docs: {@link http://docs.couchdb.org/en/latest/api/database/compact.html#post--db-_compact} */
interface OkResponse {
/** Operation status */
ok: boolean;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
+ /** Database _replicate options.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
interface DatabaseReplicateOptions {
/** Cancels the replication */
cancel?: boolean;
@@ -645,7 +827,8 @@ declare namespace nano {
target?: string;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
+ /** Database replication history.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
interface DatabaseReplicationHistoryItem {
/** Number of document write failures */
doc_write_failures: number;
@@ -681,7 +864,8 @@ declare namespace nano {
start_time: string;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
+ /** Database _replicate response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#post--_replicate} */
interface DatabaseReplicateResponse {
/** Replication history */
history: DatabaseReplicationHistoryItem[];
@@ -699,7 +883,8 @@ declare namespace nano {
source_last_seq: number;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
+ /** Database _changes parameters.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
interface DatabaseChangesParams {
/** List of document IDs to filter the changes feed as valid JSON array.
*
@@ -797,11 +982,12 @@ declare namespace nano {
*
* Documents counted as “passed” for view filter in case if map function emits at least one record for them.
*
- * @see {@link https://docs.couchdb.org/en/stable/api/database/changes.html#changes-filter-view|_view} for more info. */
+ * @see Docs: {@link https://docs.couchdb.org/en/stable/api/database/changes.html#changes-filter-view|_view} for more info. */
view?: string;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
+ /** Database change item.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
interface DatabaseChangesResultItem {
/** List of document’s leaves with single field rev. */
changes: Array<{ rev: string }>;
@@ -816,7 +1002,8 @@ declare namespace nano {
deleted: boolean;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
+ /** Database _changes response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/changes.html#get--db-_changes} */
interface DatabaseChangesResponse {
/** Last change update sequence */
last_seq: any;
@@ -828,7 +1015,8 @@ declare namespace nano {
results: DatabaseChangesResultItem[];
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/authn.html#cookie-authentication} */
+ /** Database authentication response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/authn.html#cookie-authentication} */
interface DatabaseAuthResponse {
/** Operation status */
ok: boolean;
@@ -840,7 +1028,8 @@ declare namespace nano {
roles: string[];
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/authn.html#get--_session} */
+ /** Database _session response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/authn.html#get--_session} */
interface DatabaseSessionResponse {
/** Operation status */
ok: boolean;
@@ -852,7 +1041,8 @@ declare namespace nano {
info: any;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
+ /** Database global changes result item.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
interface DatabaseUpdatesResultItem {
/** Database name. */
db_name: string;
@@ -864,7 +1054,8 @@ declare namespace nano {
seq: any;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
+ /** Global changes response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/server/common.html#get--_db_updates} */
interface DatabaseUpdatesResponse {
/** An array of database events.
*
@@ -879,6 +1070,7 @@ declare namespace nano {
// Document scope request and response
// -------------------------------------
+ /** Bulk API per-document response. */
interface DocumentResponseRowMeta {
id: string;
key: string;
@@ -888,11 +1080,13 @@ declare namespace nano {
error?: string;
}
+ /** Bulk API per-document response with document body. */
interface DocumentResponseRow<D> extends DocumentResponseRowMeta {
doc?: D & Document;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_bulk_docs} */
+ /** Bulk API response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_bulk_docs} */
interface DocumentBulkResponse {
/** Document ID. Available in all cases */
id: string;
@@ -907,8 +1101,9 @@ declare namespace nano {
reason?: string;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#post--db}
- * @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#put--db-docid} */
+ /** Document insert parameters.
+ * @see POST docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#post--db}
+ * @see PUT docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#put--db-docid} */
interface DocumentInsertParams {
/** Document’s revision if updating an existing document. Alternative to If-Match header or document key. */
rev?: string;
@@ -925,8 +1120,9 @@ declare namespace nano {
new_edits?: boolean;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/common.html#post--db}
- * @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#put--db-docid} */
+ /** Document insert response:
+ * @see POST docs: {@link http://docs.couchdb.org/en/latest/api/database/common.html#post--db}
+ * @see PUT docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#put--db-docid} */
interface DocumentInsertResponse {
/** Document ID */
id: string;
@@ -938,7 +1134,8 @@ declare namespace nano {
rev: string;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#delete--db-docid} */
+ /** Document delete response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#delete--db-docid} */
interface DocumentDestroyResponse {
/** Document ID */
id: string;
@@ -950,7 +1147,8 @@ declare namespace nano {
rev: string;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#get--db-docid} */
+ /** Document get parameters.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#get--db-docid} */
interface DocumentGetParams {
/** Includes attachments bodies in response.
*
@@ -1009,7 +1207,8 @@ declare namespace nano {
revs_info?: boolean;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#get--db-docid} */
+ /** Document get response:
+ * @see docs: {@link http://docs.couchdb.org/en/latest/api/document/common.html#get--db-docid} */
interface DocumentGetResponse {
/** Document ID. */
_id: string;
@@ -1043,23 +1242,8 @@ declare namespace nano {
_revisions?: any;
}
- interface DocumentCopyOptions {
- overwrite?: boolean;
- }
-
- /** @see {@link http://docs.couchdb.org/en/latest/api/document/common.html#copy--db-docid} */
- interface DocumentCopyResponse {
- /** Document ID */
- id: string;
-
- /** Operation status */
- ok: boolean;
-
- /** Revision MVCC token */
- rev: string;
- }
-
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
+ /** _all_docs parameters
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
interface DocumentListParams {
/** Includes conflicts information in response.
*
@@ -1132,7 +1316,8 @@ declare namespace nano {
update_seq?: boolean;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
+ /** _all_docs response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/bulk-api.html#get--db-_all_docs} */
interface DocumentListResponse<D> {
/** Offset where the document list started. */
offset: number;
@@ -1151,6 +1336,8 @@ declare namespace nano {
update_seq?: number;
}
+ /** Fetch with POST _all_docs parameters.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
interface DocumentFetchParams {
conflicts?: boolean;
descending?: boolean;
@@ -1158,7 +1345,7 @@ declare namespace nano {
end_key_doc_id?: string;
inclusive_end?: boolean;
key?: string;
- keys?: string; // This can be string[] too ???
+ keys?: string | string[];
limit?: number;
skip?: number;
stale?: string;
@@ -1166,11 +1353,15 @@ declare namespace nano {
start_key_doc_id?: string;
update_seq?: boolean;
}
+
+ /** Document fetch error */
interface DocumentLookupFailure {
key: string;
error: string;
}
+ /** Fetch with POST _all_docs response
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
interface DocumentFetchResponse<D> {
offset: number;
rows: Array<DocumentResponseRow<D> | DocumentLookupFailure>;
@@ -1178,6 +1369,8 @@ declare namespace nano {
update_seq?: number;
}
+ /** Fetch revisions response
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs} */
interface DocumentFetchRevsResponse<D> {
offset: number;
rows: Array<DocumentResponseRow<D> | DocumentLookupFailure>;
@@ -1185,6 +1378,8 @@ declare namespace nano {
update_seq?: number;
}
+ /** Search response
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/ddocs/search.html#queries} */
interface DocumentSearchResponse<V> {
/** Array of search results */
@@ -1213,7 +1408,8 @@ declare namespace nano {
}
- /** @see {@link https://docs.couchdb.org/en/latest/partitioned-dbs/index.html} */
+ /** Partitioned database info response.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/partitioned-dbs/index.html} */
interface PartitionInfoResponse {
/** Database name */
db_name: string;
@@ -1234,7 +1430,8 @@ declare namespace nano {
doc_del_count: number;
}
- /** @see {@link https://console.bluemix.net/docs/services/Cloudant/api/search.html#queries} */
+ /** Document search parameters:
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/ddocs/search.html#queries} */
interface DocumentSearchParams {
/** A bookmark that was received from a previous search. Used for pagination. */
bookmark?: string;
@@ -1310,7 +1507,8 @@ declare namespace nano {
stale?: boolean;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view} */
+ /** View query parameters.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view} */
interface DocumentViewParams {
/** Includes conflicts information in response.
*
@@ -1441,7 +1639,8 @@ declare namespace nano {
update_seq?: boolean;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view} */
+ /** View response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/ddoc/views.html#get--db-_design-ddoc-_view-view} */
interface DocumentViewResponse<V,D> {
/** Offset where the document list started. */
offset: number;
@@ -1463,19 +1662,24 @@ declare namespace nano {
update_seq: any;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/find.html#selector-syntax} */
+
type MangoValue = number | string | Date | boolean | object | null;
type MangoOperator = '$lt' | '$lte' | '$eq' | '$ne' | '$gte' | '$gt' |
'$exists' | '$type' |
'$in' | '$nin' | '$size' | '$mod' | '$regex' |
'$or' | '$and' | '$nor' | '$not' | '$all' | '$allMatch' | '$elemMatch';
+ /** Mango selector syntax.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/find.html#selector-syntax} */
type MangoSelector = {
[K in MangoOperator | string]: MangoSelector| MangoSelector[] | MangoValue | MangoValue[];
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/find.html#sort-syntax} */
+ /** Mango sort syntax
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/find.html#sort-syntax} */
type SortOrder = string | string[] | { [key: string]: 'asc' | 'desc' };
+ /** Mango query syntax.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/database/find.html#db-find} */
interface MangoQuery {
/** JSON object describing criteria used to select documents. */
selector: MangoSelector;
@@ -1493,7 +1697,7 @@ declare namespace nano {
*
* If it is omitted, the entire object is returned.
*
- * @see {@link http://docs.couchdb.org/en/latest/api/database/find.html#filtering-fields} */
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/find.html#filtering-fields} */
fields?: string[];
/* Instruct a query to use a specific index.
@@ -1530,6 +1734,8 @@ declare namespace nano {
execution_stats?: boolean;
}
+ /** Mango response.
+ * @see Docs: {@link https://docs.couchdb.org/en/latest/api/database/find.html#db-find} */
interface MangoResponse<D> {
/** Array of documents matching the search.
*
@@ -1549,7 +1755,8 @@ declare namespace nano {
execution_stats?: MangoExecutionStats;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/find.html#execution-statistics} */
+ /** Mango execution stats.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/find.html#execution-statistics} */
interface MangoExecutionStats {
/** Number of index keys examined. Currently always 0. */
total_keys_examined: number;
@@ -1571,7 +1778,8 @@ declare namespace nano {
execution_time_ms: number;
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/find.html#db-index} */
+ /** Mango create index parameters.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/find.html#db-index} */
interface CreateIndexRequest{
/** JSON object describing the index to create */
index: {
@@ -1597,7 +1805,8 @@ declare namespace nano {
partitioned?: boolean
}
- /** @see {@link http://docs.couchdb.org/en/latest/api/database/find.html#db-index} */
+ /** Mango create index response.
+ * @see Docs: {@link http://docs.couchdb.org/en/latest/api/database/find.html#db-index} */
interface CreateIndexResponse {
/** Flag to show whether the index was created or one already exists.
*
[couchdb-nano] 03/04: improved README
Posted by gl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
glynnbird pushed a commit to branch 9.0.2prep
in repository https://gitbox.apache.org/repos/asf/couchdb-nano.git
commit e6d3a177c06bea218bc4dcaf215c681fae94f209
Author: Glynn Bird <gl...@apache.org>
AuthorDate: Mon Jan 11 17:03:39 2021 +0000
improved README
---
README.md | 54 +++++++++++++++++++++++++++++++++---------------------
1 file changed, 33 insertions(+), 21 deletions(-)
diff --git a/README.md b/README.md
index 49e4ffb..5c3b77f 100644
--- a/README.md
+++ b/README.md
@@ -134,6 +134,19 @@ nano.db.create('alice').then((data) => {
})
```
+or in the async/await style:
+
+```js
+try {
+ const response = await nano.db.create('alice')
+ // succeeded
+ console.log(response)
+} catch (e) {
+ // failed
+ console.error(e)
+}
+```
+
2) Callbacks
```js
@@ -149,7 +162,7 @@ In `nano` the callback function receives always three arguments:
JSON parsed body, binary for non JSON responses.
* `header` - The HTTP _response header_ from CouchDB, if no error.
-The documentation will now follow the *Promises* style.
+The documentation will follow the *async/await* style.
------------------
@@ -216,13 +229,13 @@ You can also pass options to the require to specify further configuration option
```js
// nano parses the URL and knows this is a database
const opts = {
- url: "http://localhost:5984/foo",
- requestDefaults: { "proxy" : "http://someproxy" }
+ url: 'http://localhost:5984/foo',
+ requestDefaults: { proxy: { 'protocol': 'http', 'host': 'myproxy.net' } }
};
const db = require('nano')(opts);
```
-Please check [request] for more information on the defaults. They support features like cookie jar, proxies, ssl, etc.
+Please check [axios] for more information on the defaults. They support features like proxies, timeout etc.
You can tell nano to not parse the URL (maybe the server is behind a proxy, is accessed through a rewrite rule or other):
@@ -1255,16 +1268,19 @@ alice.findAsStream(q)
Nano supports making requests using CouchDB's [cookie authentication](http://guide.couchdb.org/editions/1/en/security.html#cookies) functionality. If you initialise *Nano* so that it is cookie-aware, you may call `nano.auth` first to get a session cookie. Nano will behave like a web browser, remembering your session cookie and refreshing it if a new one is received in a future HTTP response.
```js
-const nano = require('nano')({url: 'http://localhost:5984', requestDefaults: {jar:true}}),
- username = 'user',
- userpass = 'pass',
- db = nano.db.use('mydb');
+const nano = require('nano')({
+ url: 'http://localhost:5984',
+ requestDefaults: {
+ jar: true
+ }
+})
+const username = 'user'
+const userpass = 'pass'
+const db = nano.db.use('mydb')
-nano.auth(username, userpass).then((() => {
- return db.get('mydoc');
-}).then((doc) => {
- console.log(doc);
-});
+await nano.auth(username, userpass)
+const doc = await db.get('mydoc')
+console.log(doc)
```
The second request works because the `nano` library has remembered the `AuthSession` cookie that was invisibily returned by the `nano.auth` call.
@@ -1272,10 +1288,8 @@ The second request works because the `nano` library has remembered the `AuthSess
When you have a session, you can see what permissions you have by calling the `nano.session` function
```js
-nano.session().then((doc) => {
- console.log(doc)
- // { userCtx: { roles: [ '_admin', '_reader', '_writer' ], name: 'rita' }, ok: true }
-});
+const doc = await nano.session()
+// { userCtx: { roles: [ '_admin', '_reader', '_writer' ], name: 'rita' }, ok: true }
```
## Advanced features
@@ -1285,9 +1299,7 @@ nano.session().then((doc) => {
If your application needs to generate UUIDs, then CouchDB can provide some for you
```js
-nano.uuids(3).then((doc) => {
- console.log(doc);
-});
+const response = await nano.uuids(3)
// { uuids: [
// '5d1b3ef2bc7eea51f660c091e3dffa23',
// '5d1b3ef2bc7eea51f660c091e3e006ff',
@@ -1419,7 +1431,7 @@ npm run test
[2]: http://github.com/apache/couchdb-nano/issues
[4]: https://github.com/apache/couchdb-nano/blob/main/cfg/couch.example.js
[8]: http://webchat.freenode.net?channels=%23couchdb-dev
-[request]: https://github.com/request/request
+[axios]: https://github.com/axios/axios
http://freenode.org/