docuri/README.md

# DocURI [![Build Status](https://travis-ci.org/jo/docuri.svg?branch=master)](https://travis-ci.org/jo/docuri)
Rich document ids for CouchDB:

```js
'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](http://backbonejs.org/#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
```js
'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
```js
'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
```js
'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.

```js
// 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:
```js
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
```js
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:
```shell
browserify -s DocURI path/to/docuri/index.js > path/to/your/assets
```
Or grab it from [browserify-as-a-service: docuri@latest](http://www.modulefarm.com/standalone/docuri@latest).


## Development
To run the unit tests:
```shell
npm test
```

## License
Copyright (c) 2014 Johannes J. Schmidt, null2 GmbH   
Licensed under the MIT license.