Barista is a simple URL router for NodeJS.

In a nutshell

1router.get( '/:beverage/near/:location(.:format)' )
2      .to( 'beverage.byLocation' )
3
4router.first( '/coffee/near/90210', 'GET' )
5// -> { controller:'beverage', action:'byLocation', beverage:'coffee', location:90210 }
6
7router.url({
8  controller: 'beverage',
9  action: 'byLocation',
10  beverage: 'coffee',
11  location: 90210,
12  format: 'json'
13})
14// -> '/coffee/near/90210.json'

Getting Barista

Install via npm, thusly:

1npm install barista

Using Barista

1var Router = require('barista').Router;
2
3var router = new Router;

Adding routes

A simple example

1router.match( '/products', 'GET' )
2      .to( 'products.index' )

Rails-esque variable names

1router.match( '/products/:id', 'GET' )
2      .to( 'products.show' )
3
4router.match( '/profiles/:username', 'GET' )
5      .to( 'users.show' )
6
7router.match( '/products/:id(.:format)', 'GET' )
8      .to( 'products.show' )

Globs (they also capture slashes)

1router.get('/timezones/*tzname')
2      .to( 'timezones.select' )
3
4router.first( '/timezones/America/Toronto', 'GET' )
5// -> { controller:'timezones', action:'select', tzname:'America/Toronto' }
6
7
8router.match( '/*path(.:format)' ) // a "catch-all" route:
9      .to( 'errors.notFound' )
10
11router.first( '/somewhere/that/four-oh-fours.json', 'GET' )
12// -> { controller:'errors', action:'notFound', path:'somewhere/that/four-oh-fours', format:'json' }

Match conditions

1router.match( '/:beverage/near/:zipcode', 'GET' )
2      .to( 'beverage.byZipCode' )
3      .where({
4        // an array of options
5        beverage: [ 'coffee', 'tea', 'beer', 'warm_sake' ],
6        // a regex pattern
7        zipcode: /^\d{5}(-\d{4})?$/
8      })
9
10router.match( '/:beverage/near/:location', 'GET' )
11      .to( 'beverage.byLocation' )
12      .where({
13        // could be a postal code
14        // OR a zip code
15        // OR the word 'me' (geolocation FTW)
16        location: [ /^\d{5}(-\d{4})?$/, /^[ABCEGHJKLMNPRSTVXY]{1}\d{1}[A-Z]{1} *\d{1}[A-Z]{1}\d{1}$/, 'me' ]
17      })

Convenience methods

1router.get( '/products/:id(.:format)' )
2      .to( 'products.show' )
3
4router.put( '/products/:id(.:format)' )
5      .to( 'products.update' )
6
7router.post( '/products' )
8      .to( 'products.create' )
9
10router.del( '/products' )
11      .to( 'products.destroy' )
12
13router.options( '/products' )
14      .to( 'products.options' )

REST Resources

1router.resource( 'products' )

is equivalent to:

1router.get( '/products(.:format)' )
2      .to( 'products.index' )
3
4router.get( '/products/add(.:format)' )
5      .to( 'products.add' )
6
7router.get( '/products/:id(.:format)' )
8      .to('products.show' )
9
10router.get('/products/:id/edit(.:format)' )
11      .to( 'products.edit' )
12
13router.post('/products(.:format)' )
14      .to( 'products.create' )
15
16router.put('/products/:id(.:format)' )
17      .to( 'products.update' )
18
19router.del('/products/:id(.:format)' )
20      .to( 'products.destroy' )

Removing Routes

In some cases, you will need to remove routes on a running router. The router.remove( name ) method will work for this, but requires use of the otherwise unused route.name( name ) method.

Adding a name (currently only used with this functionality)

1router.match( '/products/:id', 'GET' )
2      .to( 'products.show' )
3      .name('products_show')

Removing a named route

1
2router.remove('products_show')
3

Resolution & dispatching

The router.first( url, method [, callback] ) method can be used in two ways:

1var params = router.first( '/products/15', 'GET' )

OR

1router.first( '/products/15', 'GET', function( err, params ){
2  if (err) { 
3    // couldn't find match 
4  }
5  // dispatch the request or something
6})

You can get all the matching routes like so:

1var params = router.all( '/products/15', 'GET' )
2
3//=> [params, params, params....]

Route generation

Pass in a params hash, get back a tasty string:

1router.url( {
2  controller: 'products',
3  action: 'show',
4  id: 5
5} )
6//=> '/products/5'
7
8router.url( {
9  controller: 'products',
10  action: 'show',
11  id: 5,
12  format: 'json'
13} )
14//=> '/products/5.json'

Set the optional second parameter to true if you want extra params appended as a query string:

1router.url({
2  controller: 'products',
3  action: 'show',
4  id: 5,
5  format: 'json',
6  love: 'cheese'
7}, true )
8//=> '/products/5.json?love=cheese'

TODOs

• Add namespace support
• Better support for named routes
• Customizable resources

Things I forgot...

...might be in the /docs folder...

...or might not exist at all.

It's broken!

Shit happens.

Write a test that fails and add it to the tests folder, then create an issue!

Patches welcome :-)

Who are you?

I'm Kieran Huggins in Toronto, Canada.