Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    couchdb-builderpublic

    CouchDB builder

    A tool for building CouchDB documents from flat files.

    Current version image Current build status image Current coverage status image

    What does it do?

    CouchDB builder recursively reads a directory of flat files in various formats, and builds a JSON document suitable for use with CouchDB. The most common application is for CouchDB design documents, that typically contain embedded code.

    Usage

    Command line usage

    couchdb-builder <source-path> > <destination-path>
    

    Module usage

    CouchDB builder implements a promise-based interface:

    var couchdbBuilder = require('couchdb-builder');
     
    couchdbBuilder.build(sourcePath).then(
        function (result) {
            // handle result
        },
        function (error) {
            // handle error
        }
    );

    Supported file types

    CouchDB builder supports various file types. The type is determined solely from the extension, and files with unsupported extensions are ignored:

    Extension Type
    .js CommonJS module (JavaScript)
    .coffee CommonJS module (CoffeeScript)
    .json JSON document
    .txt text document
    <none> text document

    Example document

    Given the following directory structure and file contents:

    Directory:

    .
    ├── a/
    │   ├── b
    │   ├── c.txt
    │   ├── d.json
    │   └── e.other
    └── views/
        ├── view-a/
        │   └── map.js
        └── view-b/
            └── map.coffee
    

    a/b:

    String content A.
    

    a/c.txt:

    String content B.
    

    a/d.json:

    {
        "f": true,
        "g": 1.1
    }

    a/e.other:

    Ignored
    

    views/view-a/map.js:

    module.exports = function (doc) {
        emit(doc._id);
    };

    views/view-b/map.coffee:

    module.exports = (doc) ->
        emit doc._id
     
        return

    CouchDB builder will produce a document like the following:

    {
        "a": {
            "b": "String content A.",
            "c": "String content B.",
            "d": {
                "f": true,
                "g": 1.1
            }
        },
        "views": {
            "view-a": {
                "map": "<source of map.js with wrapper>"
            },
            "view-a": {
                "map": "<compiled source of map.coffee with wrapper>"
            }
        }
    }

    Differences to couchdb-compile

    Better support for CommonJS modules

    Module support in couchdb-compile involves using .toString() on the module's exports. This does not mix well with some common patterns of CommonJS modules. Take the following module as an example:

    var a = 'a';
     
    module.exports = function () {
        return a;
    };

    Using .toString() on this module would result in the following code:

    function () {
        return a;
    };

    Unfortunately, when this code is executed inside CouchDB, the variable a will be undefined, and hence the behavior has changed from the original module.

    CouchDB builder takes a different approach, and instead surrounds the original source code in a light-weight wrapper. This wrapper allows the original code to function identically when used inside CouchDB, and when require'd as a CommonJS module.

    The same module would look something like this when surrounded in the wrapper:

    if (!module) { var module = {}; }
     
    var a = 'a';
     
    module.exports = function () {
        return a;
    };
     
    module.exports;

    This works because CouchDB internally uses eval(), which returns the value of the last expression evaluated (i.e. module.exports).

    Built-in support for CoffeeScript

    CoffeeScript is not directly supported by couchdb-compile, although there is currently an open pull request designed to address this.

    With CouchDB builder, CoffeeScript is automatically compiled to JavaScript, then surrounded with the same light-weight wrapper as any other JavaScript file. This means that CoffeeScript "just works" without any special configuration.

    Although CouchDB does natively support CoffeeScript, it currently seems to re-compile on every execution. It is almost certainly more performant to compile once (it also simplifies the wrapper code).

    Deterministic output

    When generating JSON output, couchdb-compile internally uses JSON.stringify, which does not guarantee the order of properties in the output. If the resulting JSON is committed to a version control repository, this will sometimes produce "diff churn" (repeated commits to a file that do not change its content in a meaningful way).

    CouchDB builder utilizes json-stable-stringify instead of JSON.stringify, to ensure that its output is deterministic (always the same, given the same input).

    Unsupported features

    The following features of couchdb-compile are not currently supported. Please open an issue if further discussion is warranted:

    • Attachments.
    • Automatic generation of the _id key. If no _id is specified, the document will not have one.
    • Special treatment of index.js or index.coffee files as CommonJS modules. All .js and .coffee files are treated as modules in CouchDB builder.

    install

    npm i couchdb-builder

    Downloadsweekly downloads

    22

    version

    0.1.0

    license

    MIT

    repository

    githubgithub

    last publish

    collaborators

    • avatar