DB Module

This contains the core functions for dealing with CouchDB. That includes document CRUD operations, querying views and creating/deleting databases.

Installation

Add db to your dependencies section in kanso.json.

  ...
  "dependencies": {
    "db": null,
    ...
  }

run kanso install to fetch the package

You also need jQuery to be included on your page, since this module uses jQuery.ajax to make requests.

Events

The db module is an EventEmitter. See the events package for more information.

unauthorized

Emitted by the db module when a request results in a 401 Unauthorized response. This is listened to used by the session module to help detect session timeouts etc.

var db = require("db");

db.on('unauthorized', function (req) {
    // req is the ajax request object which returned 401
});

API

guessCurrent([loc])

Attempts to guess the database name and design doc id from the current URL, or the loc paramter. Returns an object with 'db', 'design_doc' and 'root' properties, or null for a URL not matching the expected format (perhaps behing a vhost).

You wouldn't normally use this function directly, but use db.current() to return a DB object bound to the current database instead.

• loc - String - An alternative URL to use instead of window.location (optional)

returns: Object|null

escapeUrlParams([obj])

Converts an object to a string of properly escaped URL parameters.

• obj - Object - An object containing url parameters, with parameter names stored as property names (or keys).

returns: String

encode(str)

Encodes a document id or view, list or show name. This also will make sure the forward-slash is not escaped for documents with id's beginning with "\_design/".

• str - String - the name or id to escape

returns: String

stringifyQuery(query)

Properly encodes query parameters to CouchDB views etc. Handle complex keys and other non-string parameters by passing through JSON.stringify. Returns a shallow-copied clone of the original query after complex values have been stringified.

• query - Object

returns: Object

request(options, callback)

Make a request, with some default settings, proper callback handling, and optional caching. Used behind-the-scenes by most other DB module functions.

• options - Object
• callback(err,response) - Function

createDatabase(name, callback)

Creates a CouchDB database.

If you're running behind a virtual host you'll need to set up appropriate rewrites for a DELETE request to '/' either turning off safe rewrites or setting up a new vhost entry.

• name - String
• callback(err,response) - Function

deleteDatabase(name, callback)

Deletes a CouchDB database.

If you're running behind a virtual host you'll need to set up appropriate rewrites for a DELETE request to '/' either turning off safe rewrites or setting up a new vhost entry.

• name - String
• callback(err,response) - Function

allDbs(callback)

Lists all databses

If you're running behind a virtual host you'll need to set up appropriate rewrites for a DELETE request to '/' either turning off safe rewrites or setting up a new vhost entry.

• callback(err,response) - Function

newUUID(cacheNum, callback)

Returns a new UUID generated by CouchDB. Its possible to cache multiple UUIDs for later use, to avoid making too many requests.

• cacheNum - Number - (optional, default: 1)
• callback(err,response) - Function

use(url)

Creates a new DB object with methods operating on the database at 'url'

The DB object also exposes the same module-level methods (eg, createDatabase) so it can be used in-place of the db exports object, for example:

var db = require('db').use('mydb');

db.createDatabase('example', function (err, resp) {
    // do something
});

• url - String - The url to bind the new DB object to

returns: DB

current()

Attempts to guess the current DB name and return a DB object using that. Should work reliably unless running behind a virtual host.

Throws an error if the current database url cannot be detected.

The DB object also exposes the same module-level methods (eg, createDatabase) so it can be used in-place of the db exports object, for example:

var db = require('db').current();

db.createDatabase('example', function (err, resp) {
    // do something
});

returns: DB

DB.getRewrite(name, path, [q], callback)

Fetches a rewrite from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

• name - String - the name of the design doc
• path - String
• q - Object - (optional)
• callback(err,response) - Function

DB.allDesignDocs([q], callback)

Queries all design documents in the database.

• q - Object - query parameters to pass to /_all_docs (optional)
• callback(err,response) - Function

DB.allDocs([q], callback)

Queries all documents in the database (include design docs).

• q - Object - query parameters to pass to /_all_docs (optional)
• callback(err,response) - Function

DB.getDoc(id, [q], callback)

Fetches a document from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

• id - String
• q - Object - (optional)
• callback(err,response) - Function

DB.saveDoc(doc, callback)

Saves a document to the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

• doc - Object
• callback(err,response) - Function

DB.removeDoc(doc, callback)

Deletes a document from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

• doc - Object
• callback(err,response) - Function

DB.getView(name, view, [q], callback)

Fetches a view from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

• name - String - name of the design doc to use
• view - String - name of the view
• q - Object - (optional)
• callback(err,response) - Function

DB.getList(name, list, view, [otherddoc], [q], callback)

Transforms and fetches a view through a list from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

• name - String - name of the design doc to use
• list - String - name of the list function
• view - String - name of the view to apply the list function to
• otherddoc - String - (optional) name of the other design document
• q - Object - (optional)
• callback(err,response) - Function

DB.getShow(name, show, docid, [q], callback)

Transforms and fetches a document through a show from the database the app is running on. Results are passed to the callback, with the first argument of the callback reserved for any exceptions that occurred (node.js style).

• name - String - name of the design doc to use
• show - String - name of the show function
• docid - String - id of the document to apply the show function to
• q - Object - (optional)
• callback(err,response) - Function

DB.getDesignDoc(name, callback)

Fetch a design document from CouchDB.

• name - The name of (i.e. path to) the design document without the preceeding "_design/".
• callback - The callback to invoke when the request completes.

DB.info(callback)

Gets information about the database.

• callback(err,response) - Function

DB.changes([q], callback)

Listen to the changes feed for a database.

_Options:_

• _filter_ - the filter function to use
• _since_ - the update_seq to start listening from
• _heartbeat_ - the heartbeat time (defaults to 10 seconds)
• _include_docs_ - whether to include docs in the results

Returning false from the callback will cancel the changes listener

• q - Object - (optional) query parameters (see options above)
• callback(err,response) - Function

DB.bulkSave(docs, [options], callback)

Saves a list of documents, without using separate requests. This function uses CouchDB's HTTP bulk document API (_bulk_docs). The return value is an array of objects, each containing an 'id' and a 'rev' field. The return value is passed to the callback you provide via its second argument; the first argument of the callback is reserved for any exceptions that occurred (node.js style).

Options:

• all_or_nothing - Require that all documents be saved successfully (or saved with a conflict); otherwise roll back the operation.

• docs - Array - An array of documents; each document is an object

• options - Object - (optional) Options for the bulk-save operation.

• callback(err,response) - Function - A function to accept results and/or errors. Document update conflicts are reported in the results array.

DB.bulkGet(keys, [q], callback)

Requests a list of documents, using only a single HTTP request. This function uses CouchDB's HTTP bulk document API (_all_docs). The return value is an array of objects, each of which is a document. The return value is passed to the callback you provide via its second argument; the first argument of the callback is reserved for any exceptions that occurred (node.js style).

• keys - Array - An array of documents identifiers (i.e. strings).
• q - Object - (optional) Query parameters for the bulk-read operation.
• callback(err,response) - Function - A function to accept results and/or errors. Document update conflicts are reported in the results array.