cdb-driver
Advanced tools
Comparing version 0.3.6 to 0.3.7
@@ -1,2 +0,6 @@ | ||
# CDBDriver | ||
title: CDBDriver | ||
description: A driver library for connecting to a CouchDB instance through JavaScript. | ||
<h1 id="couchdb-driver">CouchDB Driver</h1> | ||
**A driver library for connecting to a CouchDB instance through JavaScript.** | ||
@@ -23,3 +27,3 @@ | ||
```bash | ||
``` bash | ||
$ npm install --save cdb-driver | ||
@@ -32,6 +36,6 @@ # or | ||
```bash | ||
``` bash | ||
https://cdn.jsdelivr.net/npm/cdb-driver@[version] | ||
# or | ||
https://cdn.jsdelivr.net/npm/cdb-driver@[version]/dist/main.min.js | ||
# or | ||
https://cdn.jsdelivr.net/npm/cdb-driver@[version] | ||
``` | ||
@@ -47,10 +51,15 @@ Replace [version] with a semver-string just as used in npm. | ||
First require the module: | ||
```javascript | ||
``` javascript | ||
const CDBDriver = require('cdb-driver') | ||
``` | ||
Then initiate a new instance through one of the following methods: | ||
!!! info | ||
When using this library within a webpage directly instead of Node.js, you can leave this step out. | ||
The CDBDriver class will be registered on the window object and is available for all following scripts. | ||
Then initiate a new instance through one of the following methods. | ||
**Using configuration object:** | ||
```javascript | ||
``` javascript | ||
var driver = new CDBDriver({ | ||
@@ -66,3 +75,3 @@ host: 'http://localhost:5984/', | ||
**Using configuration string:** | ||
```javascript | ||
``` javascript | ||
var driver = new CDBDriver('http://admin:p4ssw0rd@localhost:5984/'); | ||
@@ -72,2 +81,5 @@ ``` | ||
The URL string gets parsed internally to a configuration object, thus both | ||
methdos result in the same instance at the end. | ||
methods result in the same instance at the end. | ||
## Here you go | ||
That's all, you're up and running. Continue with the [Reference page](/reference) to get known to the available methods. |
@@ -1,4 +0,184 @@ | ||
# Constructor | ||
```javascript | ||
new CDBDriver(config); | ||
title: Reference | ||
description: A brief overview about all available methods and options. | ||
path: blob/master/app | ||
source: module.js | ||
## Constructor | ||
``` javascript | ||
var driver = new CDBDriver(options) | ||
``` | ||
`options` has to be a plain object containing the following keys: | ||
| Key | Type | Required | Description | | ||
|:---:|:----:|:--------:|:------------| | ||
| `host` | string | yes | The database host URL. | | ||
| `user` | string | no | The username for authentication. | | ||
|Â `pass` |Â string | no |Â The password for authentication. | | ||
You can also pass in an URL string directly. CDBDriver then takes care of parsing that into a configuration object. | ||
!!! tip | ||
When using a configuration string, make sure it follows the [URL standards](https://url.spec.whatwg.org/#example-url-parsing). Otherwise you might run into errors. | ||
## Methods | ||
All methods are capable of synchroneous and asychroneous invokation. If you specify the `callback` parameter | ||
on any method as a function, the request will be made asynchroneous. | ||
The following object scheme applies to the return values of synchroneous calls, as well as for callback arguments of asynchroneous calls: | ||
``` javascript | ||
{ | ||
state: "number", // The http status code of the response | ||
response: "object" // The actual response body | ||
} | ||
``` | ||
### driver.info(...) | ||
_[Endpoint: /](http://docs.couchdb.org/en/latest/api/server/common.html#get--)_ | ||
Accessing the root of a CouchDB instance returns meta information about the instance. The response is a JSON structure containing information about the server, including a welcome message and the version of the server. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `callback` | function | no | [_Callback_](#methods) | | ||
!!! abstract "Developers Annotation" | ||
_This method is perfect for testing the connection to the database. | ||
In addition this can also be used to split further requests from the main process by providing a callback function. | ||
Within that callback you can perform synchroneous requests as you want without impacting the users performance._ | ||
### driver.allDbs(...) | ||
_[Endpoint: /_all_dbs](http://docs.couchdb.org/en/latest/api/server/common.html#get--_all_dbs)_ | ||
Returns a list of all the databases in the CouchDB instance. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `callback` | function | no | [_Callback_](#methods) | | ||
### driver.getDb(...) | ||
_[Endpoint: /{db}](http://docs.couchdb.org/en/2.1.1/api/database/common.html#get--db)_ | ||
Gets information about the specified database. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `dbIdentifier` | string |Â yes |Â The database id to get information from. | | ||
| `callback` | function | no | [_Callback_](#methods) | | ||
### driver.createDb(...) | ||
_[Endpoint: /{db}](http://docs.couchdb.org/en/2.1.1/api/database/common.html#put--db)_ | ||
Creates a new database. The database name {db} must be composed by following next rules: | ||
- Name must begin with a lowercase letter (`a-z`) | ||
- Lowercase characters (`a-z`) | ||
- Digits (`0-9`) | ||
- Any of the characters: `_`, `$`, `(`, `)`, `+`, `-` and `/` | ||
If youâre familiar with Regular Expressions, the rules above could be written as | ||
`^[a-z][a-z0-9_$()+/-]*$`. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `dbIdentifier` | string |Â yes |Â The database id to create. | | ||
| `callback` | function | no | [_Callback_](#methods) | | ||
### driver.getDocs(...) | ||
_[Endpoint: /{db}/_all_docs](http://docs.couchdb.org/en/2.1.1/api/database/bulk-api.html#get--db-_all_docs)_ | ||
Returns a JSON structure of all of the documents in a given database. The information is returned as a JSON structure containing meta information about the return structure, including a list of all documents and basic contents, consisting the ID, revision and key. The key is the from the documentâs `_id`. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `dbIdentifier` | string |Â yes |Â The database id to get the documents from. | | ||
| `callback` | function | no | [_Callback_](#methods) | | ||
### driver.storeDoc(...) | ||
_[Endpoint: /{db}](http://docs.couchdb.org/en/2.1.1/api/database/common.html#post--db)_ | ||
Creates a new document in the specified database, using the supplied JSON document structure. | ||
If the JSON structure includes the `_id` field, then the document will be created with the specified document ID. | ||
If the `_id` field is not specified, a new unique ID will be generated, following whatever UUID algorithm is configured for that server. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `dbIdentifier` | string |Â yes |Â The database id to store the document in. | | ||
| `data` | object | yes | The data to store as a document. | | ||
| `callback` | function | no | [_Callback_](#methods) | | ||
### driver.getDoc(...) | ||
_[Endpoint: /{db}/{doc}](http://docs.couchdb.org/en/2.1.1/api/document/common.html#get--db-docid)_ | ||
Returns document by the specified `doc` from the specified `db`. Unless you request a specific revision, the latest revision of the document will always be returned. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `dbIdentifier` | string |Â yes |Â The database id to get the document from. | | ||
| `docIdentifier` | string | yes | The document id to retrieve. | | ||
| `callback` | function | no | [_Callback_](#methods) | | ||
### driver.deleteDoc(...) | ||
_[Endpoint: /{db}/{doc}](http://docs.couchdb.org/en/2.1.1/api/document/common.html#delete--db-docid)_ | ||
Marks the specified document as deleted by adding a field `_deleted` with the value `true`. Documents with this field will not be returned within requests anymore, but stay in the database. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `dbIdentifier` | string |Â yes |Â The database id to delete the document from. | | ||
| `docIdentifier` | string | yes | The id of the document to delete. | | ||
| `docRevision` | string | yes |Â The latest revision id of the document. | | ||
| `callback` | function | no | [_Callback_](#methods) | | ||
### driver.updateDoc(...) | ||
_[Endpoint: /{db}/{doc}](http://docs.couchdb.org/en/2.1.1/api/document/common.html#put--db-docid)_ | ||
This method creates a new revision of the existing document. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `dbIdentifier` | string |Â yes |Â The database id to update the document from. | | ||
| `docIdentifier` | string | yes | The id of the document to update. | | ||
| `docRevision` | string | yes |Â The latest revision id of the document. | | ||
| `data` | object | yes | The new data to store. | | ||
| `callback` | function | no | [_Callback_](#methods) | | ||
### driver.storeUser(...) | ||
_[Endpoint: /_users/{user}](http://docs.couchdb.org/en/2.1.1/api/document/common.html#put--db-docid)_ | ||
Creates or updates a database user. | ||
Instead of single options, this method only accepts a plain object for configuration. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `options` | object |Â yes | Configures the behaviour of this method. | | ||
| `callback` | function | no | [_Callback_](#methods) | | ||
`options` has to implement the following scheme: | ||
``` javascript | ||
{ | ||
username: "string", // The username of the account | ||
password: "string", // The password of the account | ||
roles: "array", // (optional) The account roles | ||
additionals: "object" // (optional) Additional field that shall be stored in the user document. | ||
} | ||
``` | ||
!!! abstract "Developers Annotation" | ||
There's a whole bunch of background information provided in the [official documentation of CouchDB](http://docs.couchdb.org/en/latest/intro/security.html). | ||
Head up there for further reading on what is happening within this method and on the server-side. | ||
### driver.storeAdmin(...) | ||
_[Endpoint: /_node/_local/_config/admins/{user}](http://docs.couchdb.org/en/latest/intro/security.html#creating-new-admin-user)_ | ||
_[Legacy Endpoint: /_config/admins/{user}](http://docs.couchdb.org/en/1.6.1/intro/security.html#creating-new-admin-user)_ | ||
Creates or updates an admin user. | ||
| Argument | Type | Required | Description | | ||
|---------:|:----:|:--------:|:------------| | ||
| `username` | string |Â yes | The admins username. | | ||
| `password` | string |Â yes | The admins password. | | ||
| `callback` | function | no | [_Callback_](#methods) | |
{ | ||
"name": "cdb-driver", | ||
"version": "0.3.6", | ||
"version": "0.3.7", | ||
"description": "A driver library for connecting to a CouchDB instance through JavaScript.", | ||
@@ -5,0 +5,0 @@ "main": "app/module.js", |
@@ -10,3 +10,3 @@ # CDBDriver | ||
![GitHub last commit](https://img.shields.io/github/last-commit/mcstreetguy/cdb-driver.svg) | ||
[![Documentation Status](https://readthedocs.org/projects/cdbdriver/badge/?version=latest)](http://cdbdriver.readthedocs.io/en/latest/?badge=latest) | ||
[![Documentation Status](https://readthedocs.org/projects/cdb-driver/badge/?version=latest)](http://cdb-driver.readthedocs.io/en/latest/?badge=latest) | ||
@@ -13,0 +13,0 @@ CouchDB seems the perfect database for JavaScript applications since it uses |
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
579634
13
12851