Rich document ids for CouchDB
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 33 commits behind jo:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

DocURI Build Status

Rich document ids for CouchDB:



  • 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!


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_id: 'blade-runner',
  id: '12'

and vice versa.

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

// =>
  movie_id: 'blade-runner',
  type: 'gallery-image',
  path: ['12']
// and
// =>
  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_id: 'blade-runner',
  id: '12'
// as well as
// =>
  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');


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

  '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.

// { id: '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.


To run the unit tests:

npm test


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