(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:https://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:https://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:https://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:https://python-pouchdb.marten-de-vries.nl/plugins.html",
  "keywords": [
  "pouch",
@@ -26,12 +29,11 @@
  "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"
  }
 }