cdb-driver - npm Package Compare versions

Comparing version 0.3.6 to 0.3.7

docs/index.md

@@ -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.

docs/reference.md

@@ -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) |

package.json

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

README.md

@@ -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

No alert changes

Improved metrics

Total package byte prevSize

579634

increased by1.85%

Number of package files

13

increased by18.18%

Lines of code

12851

increased by0.19%

No dependency changes