9.0.2prep (#251)
* more verbose TypeScript descriptions and links
* ensure creds are scrubbed from logged messages
* improved README
* convert examples to async/await style
Co-authored-by: Glynn Bird <glynnbird@apache.org>
diff --git a/README.md b/README.md
index 49e4ffb..5fc3d69 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@
- [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 @@
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:
@@ -134,6 +134,19 @@
})
```
+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 @@
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.
------------------
@@ -167,24 +180,7 @@
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.
@@ -216,13 +212,13 @@
```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):
@@ -238,28 +234,21 @@
### 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_new_agent_options):
```js
-http.globalAgent.maxSockets = 20;
-```
+const http = require('http')
+const myagent = new http.Agent({
+ keepAlive: true,
+ maxSockets: 25
+})
-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:
-
-```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
@@ -312,9 +301,7 @@
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])
@@ -322,9 +309,7 @@
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])
@@ -332,9 +317,7 @@
Destroys the database `name`:
```js
-nano.db.destroy('alice').then((body) => {
- // database destroyed
-})
+await nano.db.destroy('alice')
```
### nano.db.list([callback])
@@ -342,12 +325,7 @@
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()
@@ -371,10 +349,9 @@
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])
@@ -384,10 +361,9 @@
`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])
@@ -396,12 +372,10 @@
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])
@@ -410,12 +384,10 @@
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])
@@ -424,9 +396,7 @@
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])
@@ -442,9 +412,7 @@
Gets database information:
```js
-nano.db.info().then((body) => {
- console.log('got database info', body);
-});
+const info = await nano.db.info()
```
### nano.use(name)
@@ -453,11 +421,11 @@
```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`
@@ -519,27 +487,21 @@
```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])
@@ -547,9 +509,7 @@
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])
@@ -557,17 +517,13 @@
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])
@@ -575,9 +531,7 @@
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.
@@ -592,9 +546,7 @@
{ 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])
@@ -602,22 +554,16 @@
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])
@@ -639,9 +585,7 @@
```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])
@@ -663,9 +607,7 @@
index: { fields: ['foo'] },
name: 'fooindex'
};
-alice.createIndex(indexDef).then((result) => {
- console.log(result);
-});
+const response = await alice.createIndex(indexDef)
```
## Reading Changes Feed
@@ -983,9 +925,7 @@
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')
}
});
```
@@ -996,9 +936,7 @@
[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
@@ -1014,10 +952,11 @@
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' })
}
});
```
@@ -1035,18 +974,16 @@
```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'));
```
@@ -1057,10 +994,7 @@
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
@@ -1071,44 +1005,26 @@
`{ 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])
@@ -1126,9 +1042,7 @@
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])
@@ -1136,9 +1050,9 @@
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])
@@ -1147,9 +1061,7 @@
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)
@@ -1160,10 +1072,7 @@
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.
@@ -1172,13 +1081,12 @@
```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]
}"
}
```
@@ -1188,18 +1096,14 @@
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.
@@ -1226,9 +1130,7 @@
fields: [ "name", "age", "tags", "url" ],
limit:50
};
-alice.find(q).then((doc) => {
- console.log(doc);
-});
+const response = await alice.find(q)
```
### db.findAsStream(selector)
@@ -1255,16 +1157,22 @@
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);
-});
+// authenticate
+await nano.auth(username, userpass)
+
+// requests from now on are authenticated
+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 +1180,8 @@
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 +1191,7 @@
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 +1323,7 @@
[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/
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 @@
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 @@
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 @@
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 @@
selector?: MangoSelector;
}
+ /** ChangesReader functions */
interface ChangesReaderScope {
/** fetch changes forever */
start(opts: ChangesReaderOptions): EventEmitter;
@@ -189,90 +273,128 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
): 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 @@
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 @@
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 @@
): 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 @@
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 @@
// 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
*
* 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
// Document scope request and response
// -------------------------------------
+ /** Bulk API per-document response. */
interface DocumentResponseRowMeta {
id: string;
key: string;
@@ -888,11 +1080,13 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
_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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
}
- /** @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 @@
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 @@
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 @@
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 @@
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 @@
*
* 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 @@
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 @@
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 @@
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 @@
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.
*
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 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 @@
}
}
- 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 @@
return
}
- log({ err: 'couch', body: body, headers: responseHeaders })
-
// cloudant stacktrace
if (typeof body === 'string') {
body = { message: body }
@@ -164,12 +163,14 @@
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 @@
}, 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 @@
// ?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 @@
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
