static abilities

Static abilities generator for role based authorization.

Having to write hard-coded roles and abilities can be boring and hard to maintain. This library tries to help and speed up the way you write the roles and abilities needed to your application.

Installation

You can install it using Bower:

$ bower install static-abilities

or using npm:

$ npm install static-abilities

API

Abilities.define(role[, callback])

It defines a role. This is the staring point of creating roles and associating permissions to it.

Abilities.define('role', function(can, extend) {
    // ...
});

The callback is optional but it wouldn't make much sense to define a role without any abilities, right?

NOTE: callback function gets can and extend as parameters. Those will be explained below.

can(permissions[, resource])

Adds a permission (or a set of them) to the role you are defining.

If you omit resource you are going to associate a single and specific permission to the role.

Abilities.define('role', function(can, extend) {
    can('specific_permission');
});

Otherwise, if you pass a resource it will build a permission as a concatenation of permission and resource like <permission>_<resource>.

Check the example below:

Abilities.define('role', function(can, extend) {
    can('read', 'resource'); // read_resource
    can(['read', 'edit', 'delete'], 'resource2'); // read_resource2, edit_resource2, delete_resource2
});

extend(roles)

Extends a role based on a role that was previously defined. It expects a String or Array.

Abilities.define('role', function(can, extend) {
    extend('role2');
    extend(['role3', 'role4']);
});

Abilities.alias

Creates an alias to permission(s).

It's useful to avoid duplication of abilities definitions, especially when you are handling a CRUD application.

Abilities.alias('crud', ['create', 'read', 'update', 'delete']);

Abilities.define('role', function(can, extend) {
    can('crud', 'resource');
});

The example above means the same thing as below:

Abilities.define('role', function(can, extend) {
    can('create', 'resource');
    can('read', 'resource');
    can('update', 'resource');
    can('deleted', 'resource');
    
    // or
    
    can(['create', 'read', 'update', 'delete'], 'resource');
});

NOTE: A built-in alias manage is defined for read, edit and delete.

Abilities.toJSON

Returns the JSON map reference for what you've written.

Let's suppose that we've defined something like:

Abilities.define('role', function(can, extend) {
    can('specific_permission');
    can('read', 'resource');
});

The Abilities.toJSON() call would return:

{
    role: {
        'specific_permission',
        'read_resource'
    }
}

Abilities.flush

It flushes all the previously defined roles.

Abilities.flush();

This can be quite useful if you, for example, build your own role based authorization and want to test it.

Testing

You'll need to have nodejs and grunt-cli package installed.

Then just run grunt jasmine.

License

The MIT License (MIT)

Copyright © 2015 Vítor Avelino <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.