DocURI

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.