relations

relations
=========

entity relationship, role, and permissions API for Node.js


relations is a simple permissions API which uses a natural language approach.

Contexts
--------

First, you'll create a context, which contains a list of roles which map to
actions. Here we'll create a context called repos, to model Github repositories.

``js
var relations = require('relations');

relations.define('repos', {
owner: ['pull', 'push', 'administrate'],
collaborator: ['pull', 'push'],
watcher: ['pull']
});
`

Defining the context makes available a method on relations that matches the
context name, in this case, relations.repos(). For permission checks, this is
the only method we'll need to call.

$3

To add or modify roles at runtime, you can also use the following methods:

`js
// add a role dynamically
relations.repos.addRole('scientist', ['test', 'hyphothesize']);
// update the actions for a role
relations.repos.updateRole('scientist', ['test', 'hypothesize', 'absquatulate']);
// remove a role
relations.repos.removeRole('scientist');
`

Please note that the role -> action map is defined exclusively in the code,
and not stored. If you run a cluster of servers, and choose to use dynamic roles,
you must call addRole() etc on ALL servers in the cluster (I suggest using
pub/sub).

Declarations
------------

Now, we need to tell our app who has those roles for which repos.

`js
relations.repos('Carlos is the owner of buffet.');
`

This assigns the role owner to the subject Carlos for the object buffet.

$3

Note that the API has multiple syntaxes, and this is functionally equivalent:

`js
relations.repos(':user is owner of :repo', {user: 'Carlos', repo: 'buffet'});
`

As is this:

`js
relations.repos('%s is an owner of %s', 'Carlos', 'buffet');
`

To assign a role which should apply to all objects, simply leave the object out
of the sentence:

`js
relations.repos('%s is a watcher.', 'Brian');
`

Note: Using token replacements is recommended, to prevent injection attacks!

$3

The syntax for a declaration consists of:

`
is [ a / an / the ] [ [ of / to / from / in / with ]