(pouchdb/express-pouchdb#232) - Add test suite & documentation

.gitignore

@@ -1,2 +1,3 @@
-dist
 node_modules
+dist
+coverage

.travis.yml

@@ -0,0 +1,27 @@
+sudo: false
+language: node_js
+
+cache:
+  directories:
+    - node_modules
+
+node_js:
+  - "0.10"
+
+services:
+  - couchdb
+
+before_install:
+  - npm i -g npm@^2.0.0
+
+before_script:
+  - npm prune
+
+script: npm run $COMMAND
+
+env:
+  matrix:
+  - COMMAND='helper -- lint'
+  - COMMAND='helper -- js-test'
+  - COMMAND='build'
+

README.md

@@ -1,10 +1,126 @@
 pouchdb-validation
 ==================
 
-A PouchDB plug-in that allows you to re-use your CouchDB
-validate_doc_update functions on the client side. A browser version is
-available.
+[![Build Status](https://travis-ci.org/pouchdb/pouchdb-validation.svg?branch=master)](https://travis-ci.org/pouchdb/pouchdb-validation)
+[![Dependency Status](https://david-dm.org/pouchdb/pouchdb-validation.svg)](https://david-dm.org/pouchdb/pouchdb-validation)
+[![devDependency Status](https://david-dm.org/pouchdb/pouchdb-validation/dev-status.svg)](https://david-dm.org/pouchdb/pouchdb-validation#info=devDependencies)
 
-See also [pouchdb-validation's documentation](http://pythonhosted.org/Python-PouchDB/js-plugins.html#pouchdb-validation-plug-in)
+> A PouchDB plug-in that allows you to re-use your CouchDB validate_doc_update functions on the client side.
 
-[Website of this plug-in and a few others](http://python-pouchdb.marten-de-vries.nl/plugins.html)
+A browser version is available.
+
+- [NodeJS package](https://www.npmjs.org/package/pouchdb-validation)
+- Browser object name: ``window.validation``
+
+First, make sure you understand how validation functions work in CouchDB. A good
+start is [the CouchDB guide entry on validation functions](http://guide.couchdb.org/draft/validation.html).
+
+Usage
+-----
+
+First, you need to register the plug-in with PouchDB. That can be done using the
+``PouchDB.plugin()`` function. In NodeJS, you can just pass in the result of the
+``require()`` function. In the browser, you pass in the browser object name
+given above.
+
+An example (using the list plug-in):
+
+```javascript
+//NodeJS (and Browserify)
+PouchDB.plugin(require("pouchdb-validation"));
+
+//Browser - after the JavaScript file containing the plug-in has been
+//included via a script tag (or something similar).
+PouchDB.plugin(Validation);
+```
+
+All functions have two ways of returning the output to the user. One is
+a callback parameter, which should have the signature ``(err, resp)``.
+The other is the Promise all functions return. PouchDB itself uses the
+same system.
+
+### db.validatingPut(doc[, options[, callback]])
+Exactly the same as the ``db.put`` function, but checks with all validation
+functions ('validate_doc_update') in all design documents of the current
+database if it is ok to save ``doc``. In short, this method acts more like its
+CouchDB equivalent than the original PouchDB version does. The only thing you
+get to see of it is a few extra errors, i.e. of the 'unauthorized' or the
+'forbidden' type. It also has a few extra ``options`` (defaults are shown):
+
+- ``secObj``: e.g.:
+
+  ```javascript
+  {
+     admins: {
+        names: [],
+        roles: []
+     },
+     members: {
+        names: [],
+        roles: []
+     }
+  }
+  ```
+
+- ``userCtx``: e.g.:
+
+  ```javascript:
+  {
+     db: "test_db",
+     name: "username",
+     roles: [
+        "_admin"
+     ]
+  }
+  ```
+
+- ``checkHttp``: Set this to ``true`` if you want to validate HTTP database
+  documents offline too. Unnecessary for CouchDB, but handy for e.g.
+  pouchdb-express-router, which doesn't validate itself.
+
+### db.validatingPost(doc[, options[, callback]])
+
+See the ``db.validatingPut()`` function.
+
+### db.validatingRemove(doc[, options[, callback]])
+
+See the ``db.validatingPut()`` function.
+
+### db.validatingBulkDocs(bulkDocs[, options[, callback]])
+
+See the ``db.validatingPut()`` function. Returns an array, like
+``db.bulkDocs()``. The ``all_or_nothing`` attribute on ``bulkDocs`` is
+unsupported. Also, the result array might not be in the same order as
+the passed in documents.
+
+### db.validatingPutAttachment(docId, attachmentId, rev, attachment, type[, options[, callback]])
+
+See the ``db.validatingPut()`` function. Output is the same as
+``db.putAttachment()`` (except for a few extra errors being possible.)
+
+### db.validatingRemoveAttachment(docId, attachmentId, rev[, options[, callback]])
+
+See the ``db.validatingPut()`` function. Output is the same as
+``db.removeAttachment()`` (except for a few extra errors being possible.)
+
+### db.installValidationMethods()
+
+Installs the validation methods on this database. In other words, the ``db.*``
+methods are replaced by their ``db.validating*`` counterparts. This method is
+always synchronous.
+
+**Throws**: an error if the methods are already installed.
+**Returns**: nothing
+
+### db.uninstallValidationMethods()
+
+Undoes what ``db.installValidationMethods`` did. This method is always
+synchronous.
+
+**Throws**: an error if the methods aren't currently installed.
+**Returns**: nothing
+
+License
+-------
+
+Apache-2.0

index.js

@@ -1,5 +1,5 @@
 /*
-	Copyright 2013-2014, Marten de Vries
+	Copyright 2013-2015, Marten de Vries
 
 	Licensed under the Apache License, Version 2.0 (the "License");
 	you may not use this file except in compliance with the License.
@@ -60,9 +60,9 @@ function validate(validationFuncs, newDoc, oldDoc, options) {
   //passed all validation functions (no errors thrown) -> success
 }
 
-function doValidation(db, newDoc, options, callback) {
+function doValidation(db, newDoc, options) {
   var isHttp = ["http", "https"].indexOf(db.type()) !== -1;
-  if (isHttp && !(options || {}).checkHttp) {
+  if (isHttp && !options.checkHttp) {
     //CouchDB does the checking for itself. Validate succesful.
     return Promise.resolve();
   }
@@ -86,9 +86,6 @@ function doValidation(db, newDoc, options, callback) {
 }
 
 function completeValidationOptions(db, options) {
-  if (!options) {
-    options = {};
-  }
   if (!options.secObj) {
     options.secObj = {};
   }
@@ -106,7 +103,7 @@ function completeValidationOptions(db, options) {
   });
 }
 
-function getValidationFunctions(db, callback) {
+function getValidationFunctions(db) {
   return db.allDocs({
     startkey: "_design/",
     endkey: "_design0",
@@ -154,7 +151,7 @@ wrapperApi.bulkDocs = createBulkDocsWrapper(function (doc, args) {
 
 wrapperApi.putAttachment = function (orig, args) {
   return args.db.get(args.docId, {rev: args.rev, revs: true})
-    .catch(function (err) {
+    .catch(function () {
       return {_id: args.docId};
     })
     .then(function (doc) {

package.json

@@ -3,7 +3,10 @@
 	"version": "1.2.1",
 	"main": "index.js",
 	"description": "A PouchDB plug-in that allows you to re-use your CouchDB validate_doc_update functions on the client side.",
-	"repository": "pouchdb/pouchdb-validation",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/pouchdb/pouchdb-validation.git"
+	},
 	"homepage": "http://python-pouchdb.marten-de-vries.nl/plugins.html",
 	"keywords": [
 		"pouch",
@@ -21,17 +24,16 @@
 		"couchdb-eval": "^1.0.0",
 		"pouchdb-promise": "^0.0.0",
 		"random-uuid-v4": "^0.0.4",
-		"pouchdb-plugin-error": "^1.0.0",
+		"pouchdb-plugin-error": "^2.0.0",
 		"pouchdb-wrappers": "^1.0.0",
 		"pouchdb-bulkdocs-wrapper": "^1.0.0"
 	},
 	"devDependencies": {
-		"browserify": "^4.1.8",
-		"uglify-js": "^2.4.13",
-		"es3ify": "^0.1.3"
+		"pouchdb-plugin-helper": "^2.0.0"
 	},
-	"scripts": {
-		"build-js": "mkdir -p dist && browserify index.js -g es3ify -s Validation -o dist/pouchdb-validation.js",
-		"build": "npm run build-js; cd dist; uglifyjs pouchdb-validation.js -mc > pouchdb-validation.min.js"
+ 	"scripts": {
+		"helper": "./node_modules/.bin/pouchdb-plugin-helper",
+		"test": "npm run helper -- test",
+		"build": "npm run helper -- build Validation"
 	}
 }