Rich document ids for CouchDB

You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

Go to file

Tobias Peters f7a90694bd unit test and adjustments for using optional parameter with a trailing slash		10 years ago
test	unit test and adjustments for using optional parameter with a trailing slash	10 years ago
.gitignore	first commit	11 years ago
.travis.yml	test on current versions	11 years ago
README.md	Remove global state, return rules directly	10 years ago
index.js	unit test and adjustments for using optional parameter with a trailing slash	10 years ago
package.json	Add a failing test for reliance on Object.keys	10 years ago

README.md

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)`

Create a single route. The route argument must be a routing string.

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

`route(strOrObj, [obj])`

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

route(str): parse DocURI string to object
route(obj): generate DocURI string from object
route(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

movie('movie/blade-runner');
// { id: 'blade-runner' }
movieAsset('movie/blade-runner');
// false
galleryImage({ movie_id: 'blade-runner', id: 12 });
// 'movie/blade-runner/gallery-image/12'
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