Rich document ids for CouchDB
Pull request Compare This branch is 33 commits behind jo:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
test
.gitignore
.travis.yml
README.md
index.js
package.json

README.md

DocURI Build Status

Rich document ids for CouchDB:

'movie/blade-runner/gallery-image/12/medium'

Advantages

  • You can access the doc type everywhere (eg. in changes feed, response, view results...)
  • They sort well in Futon and_all_docs
  • DocURIs can tell a lot about the document
  • You can rely on a schema and construct ids of dependend documents (eg. a specific version of an image)
  • Easily delete related documents (eg. by requesting a range from _all_docs)

Give DocURIs a try!

Usage

Define methods for certain DocURI fragments and provide a routes hash that pairs routes to methods.
DocURI is inspired by Backbone.Router.

Routes can contain parameter parts, :param, which match a single DocURI component between slashes; and splat parts *splat, which can match any number of DocURI components. Part of a route can be made optional by surrounding it in parentheses (/:optional).

For example, a route of 'movie/:movie_id/gallery-image' will generate a function which parses

'movie/blade-runner/gallery-image/12'
// =>
{
  movie_id: 'blade-runner',
  id: '12'
}

and vice versa.

A route of 'movie/:movie_id/:type/*path' will generate a function which parses

'movie/blade-runner/gallery-image/12'
// =>
{
  movie_id: 'blade-runner',
  type: 'gallery-image',
  path: ['12']
}
// and
'movie/blade-runner/gallery-image/12/medium'
// =>
{
  movie_id: 'blade-runner',
  type: 'gallery-image',
  path: ['12', 'medium']
}

The route 'movie/:movie_id/gallery-image/:id(/:version)' will generate a function which parses

'movie/blade-runner/gallery-image/12'
// =>
{
  movie_id: 'blade-runner',
  id: '12'
}
// as well as
'movie/blade-runner/gallery-image/12/medium'
// =>
{
  movie_id: 'blade-runner',
  id: '12',
  version: 'medium'
}

docuri.route(route, name)

Create a single route. The route argument must be a routing string. The name argument will be the identifier for the resulting function: docuri[name]. Routes added later may override previously declared routes.

// parses 'page/home' as { id: 'home' }:
docuri.route('page/:id', 'page');

docuri.routes(map)

Install a routes hash which maps DocURIs with parameters to functions:

docuri.routes({
  'movie/:id': 'movie',
  'movie/:movie_id/:type/*path': 'movieAsset'
  'movie/:movie_id/gallery-image/:id(/:version)': 'galleryImage',
});

docuri[name](strOrObj, [obj])

The functions generated by DocURI can have a different behaviour, depending on the type and number of the supplied arguments:

  • name(str): parse DocURI string to object
  • name(obj): generate DocURI string from object
  • name(str, obj): change DocURI string parts with values provided by object returning a string

The function returns false if a string can not be parsed, enabling type checks.

Example

docuri.movie('movie/blade-runner');
// { id: 'blade-runner' }
docuri.movieAsset('movie/blade-runner');
// false
docuri.galleryImage({ movie_id: 'blade-runner', id: 12 });
// 'movie/blade-runner/gallery-image/12'
docuri.galleryImage('movie/blade-runner/gallery-image/12', { version: 'large' });
// 'movie/blade-runner/gallery-image/12/large'

Browser support

To use DocURI in your client-side application, browserify it like this:

browserify -s DocURI path/to/docuri/index.js > path/to/your/assets

Or grab it from browserify-as-a-service: docuri@latest.

Development

To run the unit tests:

npm test

License

Copyright (c) 2014 Johannes J. Schmidt, null2 GmbH
Licensed under the MIT license.