Sandbox implementation with permission management for modular architecture
- Crossbrowser (IE8+)/Crossplatform
- tested with ~100% coverage
- support for event-driven architecture
- order of listeners and notifications doesn't matter, data will be cached and cache will be cleaned (when message is delivered or by timeout/debounce) - really useful for AMD and upcoming ES6 modules
- parent-siblings-child permissions management via grant/revoke
- sandbox can be destroyed to free resources
- if you plan to use sandbox as data proxy you can immutable plain arrays/objects by default
- caching strategies can be defined on various levels
- familiar API
License
bower install simple-permissions
npm install simple-permissions
To launch tests you have to run npm install then npm test.
If you want to contribute make sure to run grunt githooks first thing after clone.
It will create pre-commit hook and run tests and jshint before you commit.
Please use git flow - create a feature branch for your feature and send a pull request to dev.
Please don't include dist folder in your commit.
/**
* constructs a sandbox
* @param {String} [name] sandbox name
* @param {*} [data] stores data
* @name Sandbox
*/
function Sandbox(name, data) {
}
/**
* returns sandbox instance name
* @return {String} sandbox name
*/
Sandbox.prototype.name = function getSandboxName() {
};
/**
* sets sandbox specific settings for cache adjustments, etc
* @param {Object} settings cache adjustment, etc
*/
Sandbox.prototype.settings = function setSandboxSettings(settings) {
};
/**
* Settings example (those are defaults)
*/
var defaultSettings = {
cache: {
store: true,
expire: 0, //off
debounce: true
}
};
/**
* creates a new Sandbox instance, changes current parent, so that Sandbox constructor can create
* parent-child relations
* @return {Sandbox}
*/
Sandbox.prototype.kid = function createSandboxKid() {
};
/**
* returns immutable sandbox instance data
* @return {*} sandbox data
*/
Sandbox.prototype.data = function getSandboxData() {
};
/**
* subscribes handler to event
* @param {String} eventName event name
* @param {Function} handler event handler
* @param {Object} [thisBinding=this] this binding
*/
Sandbox.prototype.on = function sandboxOn(eventName, handler, thisBinding) {
};
/**
* unsubscribes handlers from event
* @param {String} eventName event name
*/
Sandbox.prototype.off = function sandboxOff(eventName) {
};
/**
* emits event with given data
* @param {String} eventName event name
* @param {*} [data] event data
*/
Sandbox.prototype.emit = function sandboxEmit(eventName, data) {
};
/**
* @see emit
*/
Sandbox.prototype.trigger = Sandbox.prototype.emit;
/**
* grants permissions
* @param {String|String[]} [to] sandbox name(s) to grant permissions to
* @param {Object.<String, String[]>} permissionsMap permissions map
*/
Sandbox.prototype.grant = function () {to, permissionsMap}
/**
* revokes permissions
* @param {String|String[]} [from] sandbox name(s) to revoke permissions from
* @param {Object.<String, String[]>} permissionsMap permissions map
*/
Sandbox.prototype.revoke = function () {from, permissionsMap}
/**
* frees resources by removing links to private and info data
*/
Sandbox.prototype.destroy = function destroySandbox() {
};##Examples:
//anonymous
var a = new Sandbox();
a.name(); //random string
//named
var bar = new Sandbox('BAR');
bar.name(); //'BAR'
//data
var bar = new Sandbox(5);
bar.data(); //5
//named with data
var bar = new Sandbox('BAR', 5);
bar.name(); //'BAR'
bar.data(); //5
//plain objects or arrays are immutable
var x = {a: 10};
var bar = new Sandbox(x);
bar.data().a; //10
bar.data().a = 20;
bar.data().a; //20
x.a; //10
//after destroy
var x = new Sandbox(5);
x.destroy();
x.data(); //throws Sandbox exception
//children sandboxes creation
var appSandbox = new Sandbox('APP');
var moduleASandbox = appSandbox.kid('ModuleA');
var moduleBSandbox = appSandbox.kid('ModuleB');
var moduleAASandbox = moduleASandbox.kid('ModuleAA');
//but following will throw, because siblings should have unique names
var moduleAlphaSandbox = appSandbox.kid('ModuleA');##Subscribe/publish and caching
var foo = new Sandbox();
var test = {
value: 'abc',
getValue: function getValue() {
return this.value;
}
};
foo.on('someEvent', function testListener() {}, test);
foo.emit('someEvent'); //testListener was called with this set to test object
foo.off('someEvent'); //un-subscribed
//order doesn't matter, can subscribe late (even after emit) and you'll still get data
foo.emit('bla', 1);
foo.on('bla', function (e, number) { //will fire right away
console.log(number);
});
setTimeout(function () {
foo.emit('bla', 2); //still listening, will log 2
}, 100);
//event expiration time for event debounce by default (also possible to set expiration settings for sandbox instance)
var foo = new Sandbox('FOO');
foo.settings({
cache: {
expire: 1000
}
});
foo.emit('eventName');
foo.on('eventName', function eventListener() {}); //will be called right away
setTimeout(function () {
foo.on('eventName', function anotherListener() {}); //event is cached, execute the callback
}, 750);
setTimeout(function () {
//event is still cached event though expiration time exceeded, cause by default expiration time debounce
foo.on('eventName', function yetAnotherListener() {});
}, 1500);
setTimeout(function () {
//now event expired
foo.on('eventName', function lastTry() {});
}, 3000);
//get default caching settings
var defaults = Sandbox.defaults(); //{cache: {store: true, expire: 0, debounce: true}}
//set caching settings globally
Sandbox.defaults({
cache: {
expire: 1000, //events will expire after 1s
debounce: false
}
});
foo.emit('hoho', [0, 'abc']);
foo.on('hoho', function (e, alpha, beta) { //will log 'hoho', 0, 'abc'
console.log(e.type);
console.log(alpha);
console.log(beta);
});
setTimeout(function () {
foo.emit('hoho', [1, 'abc']); //logs to console: 'hoho', 1, 'abc'
}, 550);
setTimeout(function () {
foo.emit('hoho', [2, 'abc']); //nothing, event expired because of global settings
}, 1100);
//no store settings
Sandbox.defaults({
cache: {
store: false
}
});
var foo = new Sandbox('FOO');
foo.emit('heyAnyOne');
foo.on('heyAnyOne', function hello() {}); //hello will not execute
foo.emit('heyAnyOne'); //hello will be called##Permissions management
//setup code
var Parent = new Sandbox('Parent', {
a: 1,
b: 2
});
var Father = Parent.kid('Father');
var Mother = Parent.kid('Mother');
var Son = Mother.kid('Son');
//sandbox can get data from itself
Parent.on('someEvent', listener);
Parent.emit('someEvent', data); //listener called once
Parent.on('someEvent', listener2); //listener called second time, listener2 called once
Parent.off('someEvent'); //unsubscribe
Parent.emit('someEvent', data); //nothing changed
//kids from parents - no permissions:
Father.on('ping', listener);
Parent.emit('ping'); //Father's listener didn't execute because of lack of permissions
//kids from parents - with permissions:
//grant Father and Mother permissions to get events from Parent's ping event
Parent.grant(['Father', 'Mother'], {Parent: ['ping']});
Father.on('ping', listener);
Mother.on('ping', listener);
Parent
.emit('ping') //will call listener twice (for Father and Mother)
.revoke(['Father', 'Mother'], {Parent: ['ping']}) //revoke permissions
.emit('ping'); //listener call count didn't change
//kids from kids - no permissions:
Father.on('ping', listener);
Mother.emit('ping'); //Father's listener didn't execute because of lack of permissions
//kids from kids - with permissions:
//grant Father access to Mother's ping and grant Mother access to Father's pong :)
Parent
.grant(Father.name(), {Mother: ['ping']})
.grant(Mother.name(), {Father: ['pong']});
Father.on('ping', listener);
Mother.on('pong', listener2);
Mother.emit('ping'); //called right away
Father.emit('pong'); //called right away
//revoke permissions
Parent
.revoke(Father.name(), {Mother: ['ping']})
.revoke(Mother.name(), {Father: ['pong']});
Mother.emit('ping'); //nothing happens
Father.emit('pong'); //nothing happens
//parents from kids - no permissions
Mother.on('ping', listener);
Son.emit('ping'); //Father's listener didn't execute because of lack of permissions
//parents from kids - with permissions
//grant Mother permissions to Son's ping and subscribe
Mother
.grant({Son: ['ping']})
.on('ping', listener);
Son.emit('ping'); //listener was called
Mother //revoke permissions
.revoke({Son: ['ping']});
Son.emit('ping'); //nothing##Real world example When populate cities module gets new cities data, initialize popup links in different module
//in core.js
var coreSandbox = new Sandbox('Core');
require(['searchBar'], function (module) {
var moduleProps = {
searchUrl: appSettings.searchUrl
};
var moduleSandbox = coreSandbox.kid('searchBar', moduleProps);
module.init(moduleSandbox);
});
require(['populateCities'], function (module) {
var moduleProps = {
citiesJsonUrl: appSettings.citiesJsonUrl,
citiesList: this.listNode
};
var moduleSandbox = coreSandbox.kid('populateCities', moduleProps);
//allow searchBar to get 'new-search-popup-links'
//loading order doesn't matter as long as your caching settings set properly
coreSandbox.grant('searchBar', {populateCities: ['new-search-popup-links']});
module.init(moduleSandbox);
});
//inside search-bar.js
//...
sandbox.on('new-search-popup-links', function (e, data) {
makePopupLinks(data.links);
});
//...
//inside populate-cities.js
//...
sandbox.emit('new-search-popup-links', [{
links: sandbox.data().citiesList.find('a.search-popup')
}]);
//...Check tests and source for more