docuri

Rich document ids for CouchDB

DocURI

Rich document ids for CouchDB:

'movie/blade-runner/gallery-image/12/medium'
  • 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/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'
}

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:

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

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.

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' 

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.