..	Copyright 2013-2014, 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.
..	You may obtain a copy of the License at
..
..	http://www.apache.org/licenses/LICENSE-2.0
..
..	Unless required by applicable law or agreed to in writing, software
..	distributed under the License is distributed on an "AS IS" BASIS,
..	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
..	See the License for the specific language governing permissions and
..	limitations under the License.

========================
JavaScript documentation
========================

Alongside Python-PouchDB, a couple of PouchDB plug-ins are developed.
They are also useful outside Python-PouchDB. The only thing that makes
them different from 'normal' PouchDB plug-ins is the fact that most of
their test suite is written in Python.

What follows is the JavaScript documentation for these plug-ins.

General
=======

Before using any of the plug-ins below, you need to register them as a
plug-in to PouchDB. That can be done using the :js:func:`PouchDB.plugin`
function. In NodeJS, you can just pass in the result of the
:js:func:`require` function. In the browser, you pass in the object the
plug-in file created. The name of the NodeJS package, and the browser
object, you can find in the tables after the plug-in section headers.

An example (using the list plug-in):

.. code-block:: javascript

   //NodeJS
   PouchDB.plugin(require("pouchdb-list"));

   //Browser - after the JavaScript file containing the plug-in has been
   //included via a script tag (or something similar).
   PouchDB.plugin(List);

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.


.. _pouchdb-list-plug-in:

Pouchdb List plug-in
====================
+----------------------+-----------------+
| NodeJS package name: | `pouchdb-list`_ |
+----------------------+-----------------+
| Browser object name: | ``window.List`` |
+----------------------+-----------------+

First, make sure you understand how list functions work in CouchDB. A
good start is `the CouchDB guide entry on lists`_.

.. _pouchdb-list: https://www.npmjs.org/package/pouchdb-list
.. _the CouchDB guide entry on lists: http://guide.couchdb.org/draft/transforming.html

.. js:function:: List.list(listPath[, options[, callback]])

   Runs a list function on a view. Both are specified via the
   ``listPath`` parameter.

   :param string listPath: a url of the form
       ``"designDocName/listFuncName/viewName"``
   :param object options: this object is supplemented with defaults
       until a complete `CouchDB request object`_ has been formed, which
       is then passed into the list function.
   :returns: When succesful, the list function's result in the form of a
       `CouchDB response object`_. Otherwise, an error object with one
       of the following statuses: 400, 404, 406 or 500.

.. _CouchDB request object: http://docs.couchdb.org/en/latest/json-structure.html#request-object
.. _CouchDB response object: http://docs.couchdb.org/en/latest/json-structure.html#response-object


.. _pouchdb-rewrite-plug-in:

Pouchdb Rewrite plug-in
=======================
+----------------------+--------------------+
| NodeJS package name: | `pouchdb-rewrite`_ |
+----------------------+--------------------+
| Browser object name: | ``window.Rewrite`` |
+----------------------+--------------------+

First, make sure you understand CouchDB rewrites. A good starting point
is `the rewrite documentation`_.

.. _pouchdb-rewrite: https://www.npmjs.org/package/pouchdb-rewrite
.. _the rewrite documentation: http://docs.couchdb.org/en/latest/api/ddoc/rewrites.html

.. js:function:: Rewrite.rewrite(rewritePath[, options[, callback]])

   Figures out where to redirect to, and then executes the corresponding
   PouchDB function, with the appropriate arguments gotten from the
   request object that has been generated from the ``options``
   parameter.

   :param string rewritePath: a path of the form
       ``"designDocName/rewrite/path"``. Specifies the design document
       to use the rewrites from, and the path you'd find in CouchDB
       after the ``/_rewrite`` part of the URL. Keep in mind that you
       can't specify a query parameter in the url form (i.e. no
       ``?a=b``). Instead use the ``options.query`` parameter.
   :param object options: A CouchDB request object stub. Important
       properties of those for rewrites are ``options.query`` and
       ``options.method``. An additional boolean option is available:
       ``options.withValidation``, if true, this function routes to
       ``db.validating*`` functions instead of ``db.*`` functions if
       relevant.
   :returns: whatever output the function that the rewrite routed to
       produced. Or, in the case of an 'http' database, a CouchDB
       response object.

.. js:function:: Rewrite.rewriteResultRequestObject(rewritePath[, options[, callback]])

   See the :js:func:`Rewrite.rewrite` function for information on the
   parameters. The difference with it is that this function doesn't try
   to route the rewrite to a function.

   :returns: A CouchDB request object that points to the resource
       obtained by following the redirect.


.. _pouchdb-show-plug-in:

Pouchdb Show plug-in
====================
+----------------------+-----------------+
| NodeJS package name: | `pouchdb-show`_ |
+----------------------+-----------------+
| Browser object name: | ``window.Show`` |
+----------------------+-----------------+

First, make sure you understand how show functions work in CouchDB. A
good start is `the CouchDB guide entry on shows`_.

.. _pouchdb-show: https://www.npmjs.org/package/pouchdb-show
.. _the CouchDB guide entry on shows: http://guide.couchdb.org/draft/formats.html

.. js:function:: Show.show(showPath[, options[, callback]])

   Similar to the :js:func:`List.list` function, but then for show
   functions. Only differences are documented.

   :param string showPath: specifies the show (and optionally the
       document) to use. Has the following form:
       ``designDocName/showName[/docId]``

.. _pouchdb-update-plug-in:

Pouchdb Update plug-in
======================
+----------------------+-------------------+
| NodeJS package name: | `pouchdb-update`_ |
+----------------------+-------------------+
| Browser object name: | ``window.Update`` |
+----------------------+-------------------+

First, make sure you understand how update handlers work in CouchDB. A
good start is `the wiki entry on update handlers`_.

.. _pouchdb-update: https://www.npmjs.org/package/pouchdb-update
.. _the wiki entry on update handlers: https://wiki.apache.org/couchdb/Document_Update_Handlers

.. js:function:: Update.update(updatePath[, options[, callback]])

   Runs the update function specified by ``updatePath``, saving part of
   its result in the database and returning the other part in the form
   of a CouchDB response object.

   :param string updatePath: has the following form:
       ``"designDocName/updateHandlerName[/docId]"``. The last being
       optional, like in CouchDB.
   :param object options: a request object stub. There's also
       ``options.withValidation``, if true, this function saves the
       update handler result using the
       :js:func:`Validation.validatingPut` function instead of using the
       :js:func:`PouchDB.prototype.put` function.


.. _pouchdb-validation-plug-in:

Pouchdb Validation plug-in
==========================
+----------------------+-----------------------+
| NodeJS package name: | `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`_.

.. _pouchdb-validation: https://www.npmjs.org/package/pouchdb-validation
.. _the CouchDB guide entry on validation functions: http://guide.couchdb.org/draft/validation.html

.. js:function:: Validation.validatingPut(doc[, options[, callback]])

   Exactly the same as the :js:func:`PouchDB.prototype.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.

.. js:function:: Validation.validatingPost(doc[, options[, callback]])

   See the :js:func:`Validation.validatingPut` function.

.. js:function:: Validation.validatingRemove(doc[, options[, callback]])

   See the :js:func:`Validation.validatingPut` function.

.. js:function:: Validation.validatingBulkDocs(bulkDocs[, options[, callback]])

   See the :js:func:`Validation.validatingPut` function. Returns an
   array, like :js:func:`PouchDB.prototype.bulkDocs`. The
   ``all_or_nothing`` attribute on ``bulkDocs`` is unsupported. Also,
   the result array might not be in the same order as ``bulkDocs.docs``.

.. js:function:: Validation.validatingPutAttachment(docId, attachmentId, rev, attachment, type[, options[, callback]])

   See the :js:func:`Validation.validatingPut` function. Output is the
   same as :js:func:`PouchDB.prototype.putAttachment` (except for a
   few extra errors being possible.)

.. js:function:: Validation.validatingRemoveAttachment(docId, attachmentId, rev[, options[, callback]])

   See the :js:func:`Validation.validatingPut` function. Output is the
   same as :js:func:`PouchDB.prototype.removeAttachment` (except for a
   few extra errors being possible.)

Examples
========

The NodeJS test suite, which just does one basic check per function, but
because of that provides nice and simple examples:

.. literalinclude:: ../js/python-pouchdb-js/test/test.js
   :language: javascript
   :linenos: