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

Johannes Jörg Schmidt b7c944c8dd Merge pull request #56 from apihlaja/insert-falsy-parameters Allow inserting falsy values, excluding undefined		8 years ago
test	allow inserting falsy values, excluding undefined	8 years ago
.gitignore	first commit	11 years ago
.travis.yml	chore(travis): ignore release tags [skip ci]	9 years ago
LICENSE	feat: change license from MIT to Apache 2.0	9 years ago
README.md	feat: change license from MIT to Apache 2.0	9 years ago
index.js	allow inserting falsy values, excluding undefined	8 years ago
package.json	chore(package): update tap to version 5.1.1	9 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