leobm / db Goto Github PK

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

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.

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

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
});

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

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

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

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

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

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

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

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

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

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

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

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

Queries all design documents in the database.

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

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

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

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

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

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

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

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
• q - Object - (optional)
• callback(err,response) - Function

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

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.

Gets information about the database.

• callback(err,response) - Function

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

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.

Call an update handler. This are functions that clients can request to invoke server-side logic that will create or update a document.

README: http://wiki.apache.org/couchdb/Document_Update_Handlers

Parameters:

• name - String - name of the design doc to use
• update - String - name of the update handler function
• docid - String - (optional) id of the document to apply the update function to
• q - Object - (optional) Options for the invoke update-handler operation.
• callback(err, response) - Function - A function to accept results and/or errors. Document update conflicts are reported in the results array.

q Options:

• params - the url query params
• body - the POST/PUT body

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.