From commits-return-6162-apmail-couchdb-commits-archive=couchdb.apache.org@couchdb.apache.org Sat Apr 16 19:32:51 2011 Return-Path: Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: (qmail 72408 invoked from network); 16 Apr 2011 19:32:51 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 16 Apr 2011 19:32:51 -0000 Received: (qmail 11023 invoked by uid 500); 16 Apr 2011 19:32:51 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 10970 invoked by uid 500); 16 Apr 2011 19:32:51 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 10963 invoked by uid 99); 16 Apr 2011 19:32:51 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 16 Apr 2011 19:32:51 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 16 Apr 2011 19:32:46 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id A94CB23889E1; Sat, 16 Apr 2011 19:32:26 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1094035 - /couchdb/trunk/share/www/script/jquery.couch.js Date: Sat, 16 Apr 2011 19:32:26 -0000 To: commits@couchdb.apache.org From: jan@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20110416193226.A94CB23889E1@eris.apache.org> Author: jan Date: Sat Apr 16 19:32:26 2011 New Revision: 1094035 URL: http://svn.apache.org/viewvc?rev=1094035&view=rev Log: Add inline documentation for jquery.couch.js Closes COUCHDB-1116 Patch by Dale Harvey. Modified: couchdb/trunk/share/www/script/jquery.couch.js Modified: couchdb/trunk/share/www/script/jquery.couch.js URL: http://svn.apache.org/viewvc/couchdb/trunk/share/www/script/jquery.couch.js?rev=1094035&r1=1094034&r2=1094035&view=diff ============================================================================== --- couchdb/trunk/share/www/script/jquery.couch.js [utf-8] (original) +++ couchdb/trunk/share/www/script/jquery.couch.js [utf-8] Sat Apr 16 19:32:26 2011 @@ -10,9 +10,38 @@ // License for the specific language governing permissions and limitations under // the License. +/** + * @namespace + * $.couch is used to communicate with a CouchDB server, the server methods can + * be called directly without creating an instance. Typically all methods are + * passed an options object which defines a success callback which + * is called with the data returned from the http request to CouchDB, you can + * find the other settings that can be used in the options object + * from + * jQuery.ajax settings + * 
$.couch.activeTasks({
+ *   success: function (data) {
+ *     console.log(data);
+ *   }
+ * });
+ * Outputs (for example): + * 
[
+ *  {
+ *   "pid" : "<0.11599.0>",
+ *   "status" : "Copied 0 of 18369 changes (0%)",
+ *   "task" : "recipes",
+ *   "type" : "Database Compaction"
+ *  }
+ *]
+ */ (function($) { + $.couch = $.couch || {}; + /** @lends $.couch */ + /** + * @private + */ function encodeDocId(docID) { var parts = docID.split("/"); if (parts[0] == "_design") { @@ -20,8 +49,11 @@ return "_design/" + encodeURIComponent(parts.join('/')); } return encodeURIComponent(docID); - }; + } + /** + * @private + */ function prepareUserDoc(user_doc, new_password) { if (typeof hex_sha1 == "undefined") { alert("creating a user doc requires sha1.js to be loaded in the page"); @@ -39,12 +71,23 @@ user_doc.roles = []; } return user_doc; - }; + } var uuidCache = []; $.extend($.couch, { urlPrefix: '', + + /** + * You can obtain a list of active tasks by using the /_active_tasks URL. + * The result is a JSON array of the currently running tasks, with each task + * being described with a single object. + * @see docs for /_active_tasks + * @param {ajaxSettings} options jQuery ajax settings + */ activeTasks: function(options) { ajax( {url: this.urlPrefix + "/_active_tasks"}, @@ -53,6 +96,14 @@ ); }, + /** + * Returns a list of all the databases in the CouchDB instance + * @see docs for /_all_dbs + * @param {ajaxSettings} options jQuery ajax settings + */ allDbs: function(options) { ajax( {url: this.urlPrefix + "/_all_dbs"}, @@ -61,6 +112,21 @@ ); }, + /** + * View and edit the CouchDB configuration, called with just the options + * parameter the entire config is returned, you can be more specific by + * passing the section and option parameters, if you specify a value that + * value will be stored in the configuration. + * @see docs for /_config + * @param {ajaxSettings} options + * + * jQuery ajax settings + * @param {String} [section] the section of the config + * @param {String} [option] the particular config option + * @param {String} [value] value to be set + */ config: function(options, section, option, value) { var req = {url: this.urlPrefix + "/_config/"}; if (section) { @@ -83,6 +149,12 @@ ); }, + /** + * Returns the session information for the currently logged in user. + * @param {ajaxSettings} options + * + * jQuery ajax settings + */ session: function(options) { options = options || {}; $.ajax({ @@ -103,6 +175,9 @@ }); }, + /** + * @private + */ userDb : function(callback) { $.couch.session({ success : function(resp) { @@ -112,6 +187,17 @@ }); }, + /** + * Create a new user on the CouchDB server, user_doc is an + * object with a name field and other information you want + * to store relating to that user, for example + * {"name": "daleharvey"} + * @param {Object} user_doc Users details + * @param {String} password Users password + * @param {ajaxSettings} options + * + * jQuery ajax settings + */ signup: function(user_doc, password, options) { options = options || {}; // prepare user doc based on name and password @@ -121,6 +207,13 @@ }); }, + /** + * Authenticate against CouchDB, the options parameter is + *expected to have name and password fields. + * @param {ajaxSettings} options + * + * jQuery ajax settings + */ login: function(options) { options = options || {}; $.ajax({ @@ -141,6 +234,14 @@ } }); }, + + + /** + * Delete your current CouchDB user session + * @param {ajaxSettings} options + * + * jQuery ajax settings + */ logout: function(options) { options = options || {}; $.ajax({ @@ -162,14 +263,27 @@ }); }, + /** + * @namespace + * $.couch.db is used to communicate with a specific CouchDB database + * 
var $db = $.couch.db("mydatabase");
+     *$db.allApps({
+     *  success: function (data) {
+     *    ... process data ...
+     *  }
+     *});
+     *
+ */ db: function(name, db_opts) { db_opts = db_opts || {}; var rawDocs = {}; function maybeApplyVersion(doc) { - if (doc._id && doc._rev && rawDocs[doc._id] && rawDocs[doc._id].rev == doc._rev) { + if (doc._id && doc._rev && rawDocs[doc._id] && + rawDocs[doc._id].rev == doc._rev) { // todo: can we use commonjs require here? if (typeof Base64 == "undefined") { - alert("please include /_utils/script/base64.js in the page for base64 support"); + alert("please include /_utils/script/base64.js in the page for " + + "base64 support"); return false; } else { doc._attachments = doc._attachments || {}; @@ -181,10 +295,19 @@ } } }; - return { + return /** @lends $.couch.db */{ name: name, uri: this.urlPrefix + "/" + encodeURIComponent(name) + "/", + /** + * Request compaction of the specified database. + * @see docs for /db/_compact + * @param {ajaxSettings} options + * + * jQuery ajax settings + */ compact: function(options) { $.extend(options, {successStatus: 202}); ajax({ @@ -195,6 +318,15 @@ "The database could not be compacted" ); }, + + /** + * Cleans up the cached view output on disk for a given view. + * @see docs for /db/_compact + * @param {ajaxSettings} options jQuery ajax settings + */ viewCleanup: function(options) { $.extend(options, {successStatus: 202}); ajax({ @@ -205,6 +337,19 @@ "The views could not be cleaned up" ); }, + + /** + * Compacts the view indexes associated with the specified design + * document. You can use this in place of the full database compaction + * if you know a specific set of view indexes have been affected by a + * recent database change. + * @see docs for /db/_compact/design-doc + * @param {String} groupname Name of design-doc to compact + * @param {ajaxSettings} options jQuery ajax settings + */ compactView: function(groupname, options) { $.extend(options, {successStatus: 202}); ajax({ @@ -215,6 +360,15 @@ "The view could not be compacted" ); }, + + /** + * Create a new database + * @see docs for PUT /db/ + * @param {ajaxSettings} options jQuery ajax settings + */ create: function(options) { $.extend(options, {successStatus: 201}); ajax({ @@ -225,6 +379,16 @@ "The database could not be created" ); }, + + /** + * Deletes the specified database, and all the documents and + * attachments contained within it. + * @see docs for DELETE /db/ + * @param {ajaxSettings} options jQuery ajax settings + */ drop: function(options) { ajax( {type: "DELETE", url: this.uri}, @@ -232,6 +396,15 @@ "The database could not be deleted" ); }, + + /** + * Gets information about the specified database. + * @see docs for GET /db/ + * @param {ajaxSettings} options jQuery ajax settings + */ info: function(options) { ajax( {url: this.uri}, @@ -239,15 +412,39 @@ "Database information could not be retrieved" ); }, + + /** + * @namespace + * $.couch.db.changes provides an API for subscribing to the changes + * feed + * 
var $changes = $.couch.db("mydatabase").changes();
+         *$changes.onChange = function (data) {
+         *    ... process data ...
+         * }
+         * $changes.stop();
+         *
+ */ changes: function(since, options) { + options = options || {}; // set up the promise object within a closure for this handler var timeout = 100, db = this, active = true, listeners = [], - promise = { + promise = /** @lends $.couch.db.changes */ { + /** + * Add a listener callback + * @see docs for /db/_changes + * @param {Function} fun Callback function to run when + * notified of changes. + */ onChange : function(fun) { listeners.push(fun); }, + /** + * Stop subscribing to the changes feed + */ stop : function() { active = false; } @@ -258,7 +455,8 @@ this(resp); }); }; - // when there is a change, call any listeners, then check for another change + // when there is a change, call any listeners, then check for + // another change options.success = function(resp) { timeout = 100; if (active) { @@ -298,6 +496,18 @@ } return promise; }, + + /** + * Fetch all the docs in this db, you can specify an array of keys to + * fetch by passing the keys field in the + * options + * parameter. + * @see docs for /db/all_docs/ + * @param {ajaxSettings} options jQuery ajax settings + */ allDocs: function(options) { var type = "GET"; var data = null; @@ -316,9 +526,24 @@ "An error occurred retrieving a list of all documents" ); }, + + /** + * Fetch all the design docs in this db + * @param {ajaxSettings} options jQuery ajax settings + */ allDesignDocs: function(options) { - this.allDocs($.extend({startkey:"_design", endkey:"_design0"}, options)); + this.allDocs($.extend( + {startkey:"_design", endkey:"_design0"}, options)); }, + + /** + * Fetch all the design docs with an index.html, options + * parameter expects an eachApp field which is a callback + * called on each app found. + * @param {ajaxSettings} options jQuery ajax settings + */ allApps: function(options) { options = options || {}; var self = this; @@ -334,7 +559,8 @@ index = ddoc.couchapp && ddoc.couchapp.index; if (index) { appPath = ['', name, ddoc._id, index].join('/'); - } else if (ddoc._attachments && ddoc._attachments["index.html"]) { + } else if (ddoc._attachments && + ddoc._attachments["index.html"]) { appPath = ['', name, ddoc._id, "index.html"].join('/'); } if (appPath) options.eachApp(appName, appPath, ddoc); @@ -347,6 +573,18 @@ alert("Please provide an eachApp function for allApps()"); } }, + + /** + * Returns the specified doc from the specified db. + * @see docs for GET /db/doc + * @param {String} docId id of document to fetch + * @param {ajaxSettings} options jQuery ajax settings + * @param {ajaxSettings} ajaxOptions jQuery ajax settings + */ openDoc: function(docId, options, ajaxOptions) { options = options || {}; if (db_opts.attachPrevRev || options.attachPrevRev) { @@ -376,6 +614,20 @@ ajaxOptions ); }, + + /** + * Create a new document in the specified database, using the supplied + * JSON document structure. If the JSON structure includes the _id + * field, then the document will be created with the specified document + * ID. If the _id field is not specified, a new unique ID will be + * generated. + * @see docs for GET /db/doc + * @param {String} doc document to save + * @param {ajaxSettings} options jQuery ajax settings + */ saveDoc: function(doc, options) { options = options || {}; var db = this; @@ -417,6 +669,16 @@ } }); }, + + /** + * Save a list of documents + * @see docs for /db/_bulk_docs + * @param {Object[]} docs List of documents to save + * @param {ajaxSettings} options jQuery ajax settings + */ bulkSave: function(docs, options) { var beforeSend = fullCommit(options); $.extend(options, {successStatus: 201, beforeSend : beforeSend}); @@ -429,6 +691,18 @@ "The documents could not be saved" ); }, + + /** + * Deletes the specified document from the database. You must supply + * the current (latest) revision and id of the document + * to delete eg removeDoc({_id:"mydoc", _rev: "1-2345"}) + * @see docs for DELETE /db/doc + * @param {Object} doc Document to delete + * @param {ajaxSettings} options jQuery ajax settings + */ removeDoc: function(doc, options) { ajax({ type: "DELETE", @@ -440,6 +714,16 @@ "The document could not be deleted" ); }, + + /** + * Remove a set of documents + * @see docs for /db/_bulk_docs + * @param {String[]} docs List of document id's to remove + * @param {ajaxSettings} options jQuery ajax settings + */ bulkRemove: function(docs, options){ docs.docs = $.each( docs.docs, function(i, doc){ @@ -456,6 +740,19 @@ "The documents could not be deleted" ); }, + + /** + * The COPY command (which is non-standard HTTP) copies an existing + * document to a new or existing document. + * @see docs for COPY /db/doc + * @param {String[]} docId document id to copy + * @param {ajaxSettings} options jQuery ajax settings + * @param {ajaxSettings} options jQuery ajax settings + */ copyDoc: function(docId, options, ajaxOptions) { ajaxOptions = $.extend(ajaxOptions, { complete: function(req) { @@ -478,15 +775,31 @@ ajaxOptions ); }, + + /** + * Creates (and executes) a temporary view based on the view function + * supplied in the JSON request. + * @see docs for /db/_temp_view + * @param {Function} mapFun Map function + * @param {Function} reduceFun Reduce function + * @param {Function} language Language the map / reduce funs are + * implemented in + * @param {ajaxSettings} options jQuery ajax settings + */ query: function(mapFun, reduceFun, language, options) { language = language || "javascript"; if (typeof(mapFun) !== "string") { - mapFun = mapFun.toSource ? mapFun.toSource() : "(" + mapFun.toString() + ")"; + mapFun = mapFun.toSource ? mapFun.toSource() + : "(" + mapFun.toString() + ")"; } var body = {language: language, map: mapFun}; if (reduceFun != null) { if (typeof(reduceFun) !== "string") - reduceFun = reduceFun.toSource ? reduceFun.toSource() : "(" + reduceFun.toString() + ")"; + reduceFun = reduceFun.toSource ? reduceFun.toSource() + : "(" + reduceFun.toString() + ")"; body.reduce = reduceFun; } ajax({ @@ -498,6 +811,19 @@ "An error occurred querying the database" ); }, + + /** + * Fetch a _list view output, you can specify a list of + * keys in the options object to recieve only those keys. + * @see + * docs for /db/_design/design-doc/_list/l1/v1 + * @param {String} list Listname in the form of ddoc/listname + * @param {String} view View to run list against + * @param {ajaxSettings} options jQuery ajax settings + */ list: function(list, view, options) { var list = list.split('/'); var options = options || {}; @@ -518,6 +844,19 @@ options, 'An error occured accessing the list' ); }, + + /** + * Executes the specified view-name from the specified design-doc + * design document, you can specify a list of keys + * in the options object to recieve only those keys. + * @see docs for /db/ + * _design/design-doc/_list/l1/v1 + * @param {String} name View to run list against + * @param {ajaxSettings} options jQuery ajax settings + */ view: function(name, options) { var name = name.split('/'); var options = options || {}; @@ -538,6 +877,17 @@ options, "An error occurred accessing the view" ); }, + + /** + * Fetch an arbitrary CouchDB database property + * @see docs for /db/_prop + * @param {String} propName Propery name to fetch + * @param {ajaxSettings} options jQuery ajax settings + * @param {ajaxSettings} ajaxOptions jQuery ajax settings + */ getDbProperty: function(propName, options, ajaxOptions) { ajax({url: this.uri + propName + encodeOptions(options)}, options, @@ -546,6 +896,17 @@ ); }, + /** + * Set an arbitrary CouchDB database property + * @see docs for /db/_prop + * @param {String} propName Propery name to fetch + * @param {String} propValue Propery value to set + * @param {ajaxSettings} options jQuery ajax settings + * @param {ajaxSettings} ajaxOptions jQuery ajax settings + */ setDbProperty: function(propName, propValue, options, ajaxOptions) { ajax({ type: "PUT", @@ -562,6 +923,17 @@ encodeDocId: encodeDocId, + /** + * Accessing the root of a CouchDB instance returns meta information about + * the instance. The response is a JSON structure containing information + * about the server, including a welcome message and the version of the + * server. + * @see + * docs for GET / + * @param {ajaxSettings} options jQuery ajax settings + */ info: function(options) { ajax( {url: this.urlPrefix + "/"}, @@ -570,6 +942,17 @@ ); }, + /** + * Request, configure, or stop, a replication operation. + * @see docs for POST /_replicate + * @param {String} source Path or url to source database + * @param {String} target Path or url to target database + * @param {ajaxSettings} ajaxOptions jQuery ajax settings + * @param {Object} repOpts Additional replication options + */ replicate: function(source, target, ajaxOptions, repOpts) { repOpts = $.extend({source: source, target: target}, repOpts); if (repOpts.continuous && !repOpts.cancel) { @@ -585,12 +968,20 @@ ); }, + /** + * Fetch a new UUID + * @see docs for /_uuids + * @param {Int} cacheNum Number of uuids to keep cached for future use + */ newUUID: function(cacheNum) { if (cacheNum === undefined) { cacheNum = 1; } if (!uuidCache.length) { - ajax({url: this.urlPrefix + "/_uuids", data: {count: cacheNum}, async: false}, { + ajax({url: this.urlPrefix + "/_uuids", data: {count: cacheNum}, async: + false}, { success: function(resp) { uuidCache = resp.uuids; } @@ -616,13 +1007,17 @@ if ( typeof data === "string" ) { if ( type === "json" || !type && ct.indexOf("json") >= 0 ) { data = $.parseJSON( data ); - } else if ( type === "script" || !type && ct.indexOf("javascript") >= 0 ) { + } else if ( type === "script" || + !type && ct.indexOf("javascript") >= 0 ) { $.globalEval( data ); } } return data; }; + /** + * @private + */ function ajax(obj, options, errorMessage, ajaxOptions) { options = $.extend({successStatus: 200}, options); ajaxOptions = $.extend({contentType: "application/json"}, ajaxOptions); @@ -654,7 +1049,8 @@ if (options.beforeSuccess) options.beforeSuccess(req, resp); if (options.success) options.success(resp); } else if (options.error) { - options.error(req.status, resp && resp.error || errorMessage, resp && resp.reason || "no response"); + options.error(req.status, resp && resp.error || + errorMessage, resp && resp.reason || "no response"); } else { alert(errorMessage + ": " + resp.reason); } @@ -662,6 +1058,9 @@ }, obj), ajaxOptions)); } + /** + * @private + */ function fullCommit(options) { var options = options || {}; if (typeof options.ensure_full_commit !== "undefined") { @@ -674,13 +1073,17 @@ } }; + /** + * @private + */ // Convert a options object to an url query string. // ex: {key:'value',key2:'value2'} becomes '?key="value"&key2="value2"' function encodeOptions(options) { var buf = []; if (typeof(options) === "object" && options !== null) { for (var name in options) { - if ($.inArray(name, ["error", "success", "beforeSuccess", "ajaxStart"]) >= 0) + if ($.inArray(name, + ["error", "success", "beforeSuccess", "ajaxStart"]) >= 0) continue; var value = options[name]; if ($.inArray(name, ["key", "startkey", "endkey"]) >= 0) { @@ -692,6 +1095,9 @@ return buf.length ? "?" + buf.join("&") : ""; } + /** + * @private + */ function toJSON(obj) { return obj !== null ? JSON.stringify(obj) : null; }