# [![limerun](./limerun.png)](http://limerun.com) lime-router

[![Build Status](https://api.shippable.com/projects/54e79e255ab6cc13528d2db6/badge?branchName=master)](https://app.shippable.com/projects/54e79e255ab6cc13528d2db6/builds/latest) [![NPM](https://img.shields.io/badge/owin--js-certified-99cc33.svg?style=flat-square)](http://owinjs.org)
[![NPM](https://img.shields.io/badge/limerun-middleware-3399cc.svg?style=flat-square)](https://nodei.co/npm/limerun/)
[![NPM](https://img.shields.io/badge/owin--d-connected-C3C3E5.svg?style=flat-square)](https://owind.org/)

[![NPM](https://nodei.co/npm/lime-router.png?downloads=true)](https://nodei.co/npm/lime-router/)

## About

This is a simple router for the `limerun` Project.

It routes HTTP and COAP requests, with simple uri templates and parameter/query string parsing.  

## NPM Package

This repository contains a Node Package Manager (NPM) package with a single factory constructor for the routing engine.   It is intended for use in Node applications that either run on an web server that conforms to the OWIN-JS specification or run using the OWIN-JS/owin-js HTTP or COAP bridges for use with node http or node-coap respectively.

## Usage

### Installation:

    npm install lime-router
    
### Hello World (using RazorView):
    
``` js
// Dependencies
const lime = require('limerun')
    , router = require('limerouter')
    , http = require('http');

// Create Factories
var app = new lime.app(); 
var route = router();

// App
app.use(route);
route.get('/', function(){
          console.log("GET: " +this.request.path);
          return  razor.renderViewAsync('index.js.html', this);
          });
http.createServer(app.buildHttp()).listen(8000);
``` 

## Methods

* `route.get`:  Match `GET` requests
* `route.post`: Match `POST` requests
* `route.put`:  Match `PUT` requests
* `route.head`: Match `HEAD` requests 
* `route.del`:  Match `DELETE` requests
* `route.options`:  Match `OPTIONS` requests
* `route.all`:  Match all above request methods.
* `route.debugget`:  Match `GET` for `scheme='debug'` requests
	
## API


If you want to grab a part of the path you can use capture groups in the pattern:

``` js
route.get('/id/{customer}', function() {
	var base = this.Params.base; // ex: if the path is /id/bar, then customer = bar
```

Query paramaters in the url are also added to `owin.Params`:

``` js
route.get('/id/{customer}', function() {
	var base = this.Params.base; // ex: if the path is /id/bar?name=dog, then customer = bar
	var name = this.Params.name; // ex: if the path is /id/bar?name=dog, then name = dog
});
```

The capture patterns matches until the next `/` or character present after the group

``` js
route.get('/{x}x{y}', function() {
	// if the path was /200x200, then his.Params = {x:'200', y:'200'}
});
```

Optional patterns are supported by adding a `?` at the end

``` js
route.get('/{prefix}?/{top}', function() {
	// matches both '/a/b' and '/b'
});
```

If you want to just match everything you can use a wildcard `*` which works like posix wildcards

``` js
route.get('/{prefix}/*', function() {
	// matches both '/a/', '/a/b', 'a/b/c' and so on.
	// the value of the wildcard is available through req.params.wildcard
});
```

If the standard capture groups aren't expressive enough for you can specify an optional inline regex 

``` js
route.get('/{digits}([0-9]+)', function() {
	// matches both '/24' and '/424' but not '/abefest' and so on.
});
```

You can also use regular expressions and the related capture groups instead:

``` js
route.get(/^\/foo\/(\w+)/, function(req, res) {
	var group = req.params[1]; // if path is /foo/bar, then group is bar
});
```

## Error handling

By default lime-router will simply move to next lime middleware function if no route matched.    The router is a Promise/A compatible async function that respects error bubbling, but has no specific handling built in.

You can provide a catch-all to a given route that is called if no route was matched:

    route.get(function() {
	// called if no other get route matched
	this.response.writeHead(404);
	this.response.end('no GET handler found');
    });

## Credits

This router was ported from [gett/router](https://github.com/gett/router) which was developed under MIT license by Mathias Buus Madsen and Ian Jorgensen.

It has been developed to be a core component of the limerun OWIN-JS ecosystem.