couchify
v0.5.0
Published
use next generation JS in your CouchDB apps
Downloads
22
Readme
couchify
use next generation JS in your CouchDB apps.
couchify
uses babel to transpile your modular ES2015 application code into ES5, and will recursively analyze the require()
calls in order to build a flat representation of your application's dependency tree in CouchDB.
Install
With npm
or yarn
, do:
npm install couchify
Example
Following example shows how you can create a show function which uses gamma
module from npm.
So, given this directory structure:
myapp/
├── shows/
│ └── foo.js
└── bar.js
foo.js
looks like this:
export default ({ require }) => () => {
const gamma = require('gamma')
return require('../bar').x + gamma(5) + '\n'
}
couchify
needs to know where your list/update/view/show/etc functions are located in the first place. By default, it assumes that they are under the baseDocumentsDir
you provided, so, by default, view functions are searched in the views
folder, show functions in the shows, and so on.
Unlike normal CouchDB functions, you need to explicitly provide the CouchDB globals (e.g. require
, emit
and so on) into these functions. This makes it possible to test your functions easily during development. Just use require()
in your design functions how you would normally use it in other places, and everything will be fine.
and bar.js
(which is only put there to demonstrate that you can require()
from anywhere):
export const x = 'fruits'
in this case, a hypothetical foo.js
test could look like this:
const assert = require('assert')
const foo = require('./shows/foo')({ require }) /* providing 'require' here */
const doc = { n: 555 }
assert.equal(foo(doc), 'fruits' + 3.345252661316333e+49)
and you can deploy it with:
λ ~ couchify myapp/ --name myapp --db mydb
{"ok":true,"id":"_design/myapp","rev":"41-c40f6ce36f17579bbbd2b4371d48c8ce"}
and test the show API using cURL
:
λ ~ curl -X GET http://127.0.0.1:5984/mydb/_design/myapp/_show/foo
fruits23.999999999999996
API
const couchify = require('couchify').couchify
couchify
expects some CouchifyOptions
and returns a Promise
. When this promise is resolved, you get a design document JSON back.
type CouchifyOptions = {
id?: string
baseDocumentsDir?: string
babelPlugins?: any[]
babelPresets?: any[]
filtersDir?: string
listsDir?: string
showsDir?: string
updatesDir?: string
viewsDir?: string
globIgnorePatterns?: string[]
}
id
is the design document ID (without the_design/
part).baseDocumentsDir
is where your source code is located. This directory should contain at least one of thefiltersDir
,listsDir
,showsDir
,updatesDir
orviewsDir
directories. These are respectively is been set to:filters
,lists
,shows
,updates
andviews
.- By default,
couchify
only applies ES2015 preset, you can add extra Babel plugins and presets withbabelPlugins
andbabelPresets
options.
Custom fields
You can customize the design document by adding a template.json
to the base
folder. Its contents will be merged with the final design document.
For more advanced templating, you can use a template.js
-file exporting a
function instead. The function will be called with the CouchifyOptions to
produce the template.
For example:
module.exports = options => ({
name: options.id,
version: require('../package.json').version,
rewrites: [
{
from: '',
to: 'index.html',
method: 'GET',
query: {}
}
]
})
Deploying
const deploy = require('couchify').deploy
Deploy a CouchDB design document.
type DeployOptions = {
remote: string
db: string
doc: DesignDocument
timeout?: number
}
CLI
couchify DIR [OPTIONS]
Options:
--db Database name. [default: default]
-n, --name Design document name. [default: default]
-r, --remote CouchDB endpoint. [default: http://localhost:5984]
-t, --timeout CouchDB timeout (ms). [default: 5000]
--filters-dir Filters directory. [default: filters]
--lists-dir Lists directory. [default: lists]
--shows-dir Shows directory. [default: shows]
--updates-dir Updates directory. [default: updates]
--views-dir Views directory. [default: views]
-y, --dry Dry run. [default: false]
-v, --version Show version number.
-h, --help Show this message.
Design document name must be unique per database. It is set to default
, by default.
When --dry
flag is set, couchify
will only output the design document JSON and not deploy it.
Limitations
- You can use
require()
inside the body of your design functions only, top-levelrequire()
calls are ignored. - Currently
require()
does not work in reduce functions. (See: https://wiki.apache.org/couchdb/CommonJS_Modules)
Roadmap
See the Issues page for a list of known bugs & planned features.
Development
To install dependencies, do:
yarn
Start TypeScript compiler in watch mode:
npm run build -- --watch
Run linter:
npm run lint
Run tests:
npm run test