npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

couchdb-builder

v0.1.0

Published

A tool for building CouchDB documents from flat files.

Downloads

5

Readme

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.