couchdb-builder
v0.1.0
Published
A tool for building CouchDB documents from flat files.
Downloads
5
Maintainers
Readme
CouchDB builder
A tool for building CouchDB documents from flat files.
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
orindex.coffee
files as CommonJS modules. All.js
and.coffee
files are treated as modules in CouchDB builder.