finger

Finger is a powerful and fast nodejs router

###Rule Rule is a class that can match and build urls described in special syntax.

var Rule = require('finger').Rule;

####Rule new Rule(String ruleString[, Object options[, Object data]]) Creates new rule.

var rule = new Rule('/');

#####String ruleString

ruleString is a string that consists of pathname description nad optional query string description

######Pathname description

Pathname rule is a string that should describe url.

/news/

Pathname rule may include parameters.

/news/<postId>

The rule above both valid for any url that starts with /news/ and ends with any character sequence except of /.

Parameters can have a type.

/news/<Number:postId>

Number is a type of postId parameter. It is a named type. Number type is included in set of builtin common types.

Types may also be anonymous.

/news/<{\\d+}:postId>

Regular expression may be passed between the {}. Parameter are for retrieving values while matching and passing while building urls.

Pathname consists of required and optional parts.

/news/(<postId>/)

In the rule above postId parameter including trailing / is optional. The rule both valid for /news/ and /news/42/ urls.

######Query description

Query description is a sequence of query parameters rules. Query parameter may be required or optional.

/news&postId?rnd

The rule above describes /news/ pathname with any query, but postId parameter is required. /news?postId=42 is valid, but /news is invalid. rnd parameter is optional.

Any query parameter may also have a type.

/news/&Number:postId

One parameter rule describes one parameter by default. But parameter rules may be multiple.

/news/?Number:tag+

The rule above describes news feed, that can be filtered by tags.

#####Object options Rule object support some options

######Boolean options.ignoreCase Disables case sensitivity for pathname rule

var rule = new Rule('/news/', {
    ignoreCase: true
});

For this rule both /news/ and /NeWs/ urls are identical.

######Boolean options.appendSlash Allows url to do not contain trailing slash

var rule = new Rule('/news/', {
    appendSlash: true
});

For this rule both /news/ and /news urls are valid.

######String options.queryEq A character which separates query argument name and value. Defaults to '='.

var rule = new Rule('/', {
    queryEq: ':'
});
rule.match('/?foo:bar'); // -> {foo: 'bar'}

######String options.querySep A character which separates query arguments. Defaults to '&'.

var rule = new Rule('/', {
    querySep: ','
});
rule.match('/?foo=bar,bar=baz'); // -> {foo: 'bar', bar: 'baz'}

######String options.basePath Base urls path.

var rule = new Rule('/news/', {
    basePath: '/site/'
});
rule.match('/news/'); // -> null
rule.match('/site/news/'); // -> {}
rule.build(); // -> /site/news/

#####Object data The data will be appended to rule

var rule = new Rule('/news/', {
    appendSlash: true
}, {
    name: 'news'
});

####Object|null rule.match(String url) Matches the url to the rule. Returns the set of values according to described arguments

var rule = new Rule('/news/(<postId>/)');
rule.match('/news/'); // -> {postId: undefined}
rule.match('/news/146/?date=42'); // -> {postId: '146', date: '42'}
rule.match('/forum/'); // -> null

####String rule.build([Object args]) Builds url from rule

var rule = new Rule('/news/(<postId>/)');

rule.build(); // -> '/news/'
rule.build({postId: 146}); // -> '/news/146/'
rule.build({date: 42}); // -> /news/?date=42
rule.build({postId: 146, date: 42}); // -> /news/146/?date=42

###Matcher

Matcher is a set of rules that gives an interface to manage rules e.g. adding, deleting, matching.

var Matcher = require('finger').Matcher;

####Matcher new Matcher([Object options]) Creates new matcher object. options is a general options for all rules.

####Rule matcher.addRule(String ruleString[, Object data]) Adds a rule to matcher. ruleString is a rule declaration that I mentioned above. data is an object that will be associated with rule. data.name is required, it will be random generated if omitted.

var matcher = new Matcher();
var rule = matcher.addRule('/', {name: 'index', foo: 42});
rule.data.name // -> 'index'
rule.data.foo // -> 42

####Rule|null matcher.delRule(String name) Deletes the rule from set

var matcher = new Matcher();
var rule = matcher.addRule('/', {name: 'index'});
assert.strictEqual(rule, matcher.delRule('index'));

####Rule|void matcher.getRule(String name) Returns the rule by name

var matcher = new Matcher();
var rule = matcher.addRule('/', {name: 'index'});
assert.strictEqual(rule, matcher.getRule('index'));

####Array<Object> matcher.findMatches(String url) Returns all match results

var matcher = new Matcher();
matcher.addRule('/news/', {name: 'news'})
matcher.addRule('/<page>/', {name: 'other'});
assert.deepEqual(matcher.matchAll('/news/'), [
    {
        name: 'news', 
        args: {}
    }, 
    {
        name: 'other', 
        args: {
            page: 'news'
        }
    }
]);

####Matcher matcher.setBasePath(String basePath) Set basePath to all existing rules. Also basePath will be applied to all new rules.

var matcher = new Matcher();
matcher.addRule('/news/', {name: 'news'});
matcher.findMatches('/site/news/'); // -> []
matcher.setBasePath('/site/');
matcher.findMatches('/site/news/'); // -> [{name: 'news', args: {}}]

###Router

Router is a subclass of Matcher.

var Router = require('finger');

Router is a Matcher that optimized and improved to match http requests.

Router's rules had extended rule string. Router's rules may describe not only url, but also request method and some options.

POST,PUT /upload/ si

That means that the should match url only if request method are POST or PUT. Also two last characters at the and of rule means that rule should ignore case and append slash to url. Flags in lower letter case enables options, but in upper, disables.

If method does not specified, that GET should be implicitly added. Special value for method is *. * means that any method will be matched.

####Array<String> router.findVerbs(String url)

Find all methods that allowed for passed url.

####Array<Rule> router.getAllowedRules(String verb)

Returns all rules that allowed for passed verb.

####Array<Match> router.findMatchesFor(String url, Array<Rule>)

Returns all matches for passed url and rules.

###Common usage

var matches = router.getAllowedMatches(req.method, req.url);
if (!matches.length) {
    res.statusCode = 404;
    res.end();
    return;
}
doSomethingWithMatches(matches);

###Advanced usage

// Get all rules that potentially may handle request
var allowedRules = router.getAllowedRules(req.method);
if (!allowedRules.length) {
    // The method is not implemented
    res.statusCode = 501;
    res.end();
    return;
}
// Find all matched
var matches = router.findMatchesFor(req.url, allowedRules);
if (!matches.length) {
    // No matches found. Maybe incorrect request method
    var allowedVerbs = router.findVerbs(req.url);
    if (!allowedVerbs.length) {
        // No any handlers. Document Not Found
        res.statusCode = 404;
        res.end();
        return;
    }    
    // Found other rules, that can handle the request
    res.setHeader('Allow', allowedVerbs.join(','));
    // Method Not Allowed
    res.statusCode = 405;
    res.end();
    return;
}
// Score!
doSomethingWithMatches(matches);

LICENSE MIT