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(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 objectroute(obj)
: generate DocURI string from objectroute(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
;// { id: 'blade-runner' };// false;// 'movie/blade-runner/gallery-image/12';// '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 Apache 2.0 license.