# barista

> URL router & generator, similar to Rails / merb

Latest version **0.5.3** (published 2015-03-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install barista
pnpm add barista
yarn add barista
bun add barista
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.3 |
| Published | 2015-03-01 |
| First published | 2011-06-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.4.0 |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 111 |
| Author | Kieran Huggins |
| Maintainers | kieran |

## Links

- npm: https://www.npmjs.com/package/barista
- Repository: https://github.com/kieran/barista
- Homepage: http://kieran.github.io/barista/
- Issues: https://github.com/kieran/barista/issues
- npm.io page: https://npm.io/package/barista

## Dependencies (2)

- [inflection](https://npm.io/package/inflection.md) *
- [querystring](https://npm.io/package/querystring.md) 0.2.0

## Recent versions

- 0.5.3 (latest) — 2015-03-01
- 0.5.2 — 2015-02-24
- 0.5.1 — 2015-02-13
- 0.5.0 — 2015-02-13
- 0.4.0 — 2014-06-02
- 0.3.0 — 2014-05-28
- 0.2.0 — 2013-11-18
- 0.1.1 — 2013-08-13
- 0.1.0 — 2013-07-26
- 0.0.10 — 2013-07-26
- 0.0.9 — 2013-07-06
- 0.0.8 — 2012-10-13
- 0.0.7 — 2012-09-06
- 0.0.6 — 2012-09-05
- 0.0.5 — 2012-02-19
- … 4 more at https://npm.io/package/barista/versions

## README

[![npm](https://badge.fury.io/js/barista.svg)](http://badge.fury.io/js/barista) [![Bower](https://badge.fury.io/bo/barista.svg)](http://badge.fury.io/bo/barista)  [![Build Status](https://travis-ci.org/kieran/barista.svg?branch=master)](https://travis-ci.org/kieran/barista)

[![NPM](https://nodei.co/npm/barista.png?downloads=true&downloadRank=true)](https://nodei.co/npm/barista/)


Barista is a simple URL router for NodeJS.

In a nutshell
=============

```javascript
router.get( '/:beverage/near/:location(.:format)' )
      .to( 'beverage.byLocation' )

router.first( '/coffee/near/90210', 'GET' )
// -> { controller:'beverage', action:'byLocation', beverage:'coffee', location:90210 }

router.url({
  controller: 'beverage',
  action: 'byLocation',
  beverage: 'coffee',
  location: 90210,
  format: 'json'
})
// -> '/coffee/near/90210.json'
```


Getting Barista
===============

Install via npm, thusly:

```javascript
npm install --save barista
```

Running barista in the browser? Try bower:

```javascript
bower install --save barista
```

Using Barista
-------------

via node:
```javascript
var Router = require('barista').Router;

var router = new Router;
```

in the browser:
```javascript
var router = new Barista
```


Adding routes
-------------

### A simple example

```javascript
router.match( '/products', 'GET' )
      .to( 'products.index' )
```

### Rails-esque variable names

```javascript
router.match( '/products/:id', 'GET' )
      .to( 'products.show' )

router.match( '/profiles/:username', 'GET' )
      .to( 'users.show' )

router.match( '/products/:id(.:format)', 'GET' )
      .to( 'products.show' )
```

### Globs (they also capture slashes)

```javascript
router.get('/timezones/*tzname')
      .to( 'timezones.select' )

router.first( '/timezones/America/Toronto', 'GET' )
// -> { controller:'timezones', action:'select', tzname:'America/Toronto' }


router.match( '/*path(.:format)' ) // a "catch-all" route:
      .to( 'errors.notFound' )

router.first( '/somewhere/that/four-oh-fours.json', 'GET' )
// -> { controller:'errors', action:'notFound', path:'somewhere/that/four-oh-fours', format:'json' }
```

### Match conditions

```javascript
router.match( '/:beverage/near/:zipcode', 'GET' )
      .to( 'beverage.byZipCode' )
      .where({
        // an array of options
        beverage: [ 'coffee', 'tea', 'beer', 'warm_sake' ],
        // a regex pattern
        zipcode: /^\d{5}(-\d{4})?$/
      })

router.match( '/:beverage/near/:location', 'GET' )
      .to( 'beverage.byLocation' )
      .where({
        // could be a postal code
        // OR a zip code
        // OR the word 'me' (geolocation FTW)
        location: [ /^\d{5}(-\d{4})?$/, /^[ABCEGHJKLMNPRSTVXY]{1}\d{1}[A-Z]{1} *\d{1}[A-Z]{1}\d{1}$/, 'me' ]
      })
```

### Convenience methods

```javascript
router.get( '/products/:id(.:format)' )
      .to( 'products.show' )

router.put( '/products/:id(.:format)' )
      .to( 'products.update' )

router.post( '/products' )
      .to( 'products.create' )

router.del( '/products' )
      .to( 'products.destroy' )

router.options( '/products' )
      .to( 'products.options' )
```

### REST Resources

```javascript
router.resource( 'products' )
```

is equivalent to:

```javascript
router.get( '/products(.:format)' )
      .to( 'products.index' )

router.get( '/products/add(.:format)' )
      .to( 'products.add' )

router.get( '/products/:id(.:format)' )
      .to('products.show' )

router.get('/products/:id/edit(.:format)' )
      .to( 'products.edit' )

router.post('/products(.:format)' )
      .to( 'products.create' )

router.put('/products/:id(.:format)' )
      .to( 'products.update' )

router.del('/products/:id(.:format)' )
      .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)

```javascript
router.match( '/products/:id', 'GET' )
      .to( 'products.show' )
      .name('products_show')
```

### Removing a named route

```javascript

router.remove('products_show')

```

Resolution & dispatching
------------------------

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

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

OR

```javascript
router.first( '/products/15', 'GET', function( err, params ){
  if (err) {
    // couldn't find match
  }
  // dispatch the request or something
})
```

You can get all the matching routes like so:

```javascript
var params = router.all( '/products/15', 'GET' )

//=> [params, params, params....]
```

Route generation
----------------

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

```javascript
router.url( {
  controller: 'products',
  action: 'show',
  id: 5
} )
//=> '/products/5'

router.url( {
  controller: 'products',
  action: 'show',
  id: 5,
  format: 'json'
} )
//=> '/products/5.json'
```

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

```javascript
router.url({
  controller: 'products',
  action: 'show',
  id: 5,
  format: 'json',
  love: 'cheese'
}, true )
//=> '/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](mailto:kieran@kieran.ca) in Toronto, Canada.

---
_Source: https://npm.io/package/barista · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._