3.2. JavaScript

3.2.1. Design functions context

Each design function executes in a special context of predefined objects, modules and functions:

emit(key, value)

Emits a key-value pair for further processing by CouchDB after the map function is done.

function(doc){
    emit(doc._id, doc._rev);
}

getRow()

Extracts the next row from a related view result.

function(head, req){
    send('[');
    row = getRow();
    if (row){
        send(toJSON(row));
        while(row = getRow()){
            send(',');
            send(toJSON(row));
        }
    }
    return ']';
}

JSON

JSON2 object.

isArray(obj)

A helper function to check if the provided value is an Array.

log(message)

Log a message to the CouchDB log (at the INFO level).

function(doc){
    log('Procesing doc ' + doc['_id']);
    emit(doc['_id'], null);
}

After the map function has run, the following line can be found in CouchDB logs (e.g. at /var/log/couchdb/couch.log):

[Sat, 03 Nov 2012 17:38:02 GMT] [info] [<0.7543.0>] OS Process #Port<0.3289> Log :: Processing doc 8d300b86622d67953d102165dbe99467

provides(key, func)

Registers callable handler for specified MIME key.

registerType(key, \mimes*)

Registers list of MIME types by associated key.

Predefined mappings (key-array):

• all: */*
• text: text/plain; charset=utf-8, txt
• html: text/html; charset=utf-8
• xhtml: application/xhtml+xml, xhtml
• xml: application/xml, text/xml, application/x-xml
• js: text/javascript, application/javascript, application/x-javascript
• css: text/css
• ics: text/calendar
• csv: text/csv
• rss: application/rss+xml
• atom: application/atom+xml
• yaml: application/x-yaml, text/yaml
• multipart_form: multipart/form-data
• url_encoded_form: application/x-www-form-urlencoded
• json: application/json, text/x-json

require(path)

Loads CommonJS module by a specified path. The path should not start with a slash.

send(chunk)

Sends a single string chunk in response.

function(head, req){
    send('Hello,');
    send(' ');
    send('Couch');
    return ;
}

start(init_resp)

Initiates chunked response. As an option, a custom response object may be sent at this point. For list-functions only!

function(head, req){
    start({
        "code": 302,
        "headers": {
            "Location": "http://couchdb.apache.org"
        }
    });
    return "Relax!";
}

sum(arr)

Sum arr’s items.

toJSON(obj)

Encodes obj to JSON string. This is an alias for the JSON.stringify method.

3.2.2. CommonJS Modules

Support for CommonJS Modules (introduced in CouchDB 0.11.0) allows you to create modular design functions without the need for duplication of functionality.

Here’s a CommonJS module that checks user permissions:

function user_context(userctx, secobj) {
    var is_admin = function() {
        return userctx.indexOf('_admin') != -1;
    }
    return {'is_admin': is_admin}
}
exports['user'] = user_context

Each module has access to additional global variables:

• module (object): Contains information about the stored module
  • id (string): The module id; a JSON path in ddoc context
  • current (code): Compiled module code object
  • parent (object): Parent frame
  • exports (object): Export statements
• exports (object): Shortcut to the module.exports object

The CommonJS module can be added to a design document, like so:

{
    "views": {
        "lib": {
            "security": "function user_context(userctx, secobj) { ... }"
        }
    },
    "validate_doc_update": "function(newdoc, olddoc, userctx, secobj) {
        user = require('views/lib/security').user_context(userctx, secobj);
        return user.is_admin();
    }"
    "_id": "_design/test"
}

Modules paths are relative to the design document’s views object, but modules can only be loaded from the object referenced via lib. The lib structure can still be used for view functions as well, by simply storing view functions at e.g. views.lib.map, views.lib.reduce, etc.