<commit_before>connect-acl
===========

Simple ACL for Connect/Express

It consists of three parts:
* Role class that represents user access data
* Connect middleware
* Template helpers

=== How to use<commit_msg>Added "How to use" doc<commit_after>connect-acl
===========

Simple ACL for Connect/Express.

connect-acl can work only with Roles and Permissions.

It consists of these parts:
* Connect middleware
* Routing helper
* Route handler helper
* Template helper

How to use
----------

```js
// Permissions and roles config.
var roles = {
    admin: {can: ['create article', 'read article', 'edit article']},
    user: {can: ['read article']}
};

// Create Acl instance
var role = require( 'connect-acl' )( roles );

// Global failure handlers (optional)
role.onAuthorizedFailure( function( req, res ){
    res.redirect( '/login' );
});
role.onUnauthorizedFailure( function( req, res ){
    res.redirect( '/' );
});

// Сonnect a middleware
app.use( role.middleware );


// Using router helper

// Simple authorized/unauthorized checking
app.get( '/', role.isAuthorized(), routes.getIndex );
app.get( '/login', role.isUnauthorized( someCustomeFailureHandler ), routes.getLogin );

// Authorizing
app.post( '/login', role.isUnauthorized(), function( req, res ){
    // ...
    
    // User should contains user.roles array, 
    // which is {string[]} and conrtains a list of role names.
    // If user.roles is falsy then user considered as authorized, but no one role won't be assigned
    req.session.user = user;
    
    // ..
});

// Check permissions
app.get( '/article/:id', role.can('read article'), routes.getArticle );
app.post( '/article/:id', role.can('edit article', someCustomFailureHandler), routes.editArticle );

// Check for role
app.get( '/settings', role.is('admin'), routes.getSettings );
app.get( '/settings', role.is('admin', someCustomFailureHandler), routes.getSettings );

// This checks whether user has 'admin' AND 'user' roles
app.get( '/user/settings', role.is(['admin', 'user']), routes.getSettings );

// This checks whether user has 'admin' OR 'user' roles
app.post( '/message/:id', role.isAny(['admin', 'user']), routes.postMessage );


// Using in route handler
app.get( '/some/path', function( req, res ){
    var role = req.role;
    if ( role.can('do something') )
        // ... 
    else if ( role.is('admin') )
        // ...
    else if ( role.isAuthorized() )
        // ...
    else 
        // ...
});

```
{'fraction_non_alphanumeric': 0.16720911310008138, 'fraction_numerical': 0.0, 'mean_word_length': 3.2914485165794067, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '154814', 'n_tokens_mistral': 741, 'n_tokens_neox': 728, 'n_words': 233}