built.io-browserify/lib/role.js

SDK for Built.io Backend which is compatible with Browserify

var R                     = require('ramda');
var utility               = require('./utilities/utility');
var instanceMethodBuilder = require('./utilities/instanceMethodBuilder')();
var objectCons            = require('./object');
var constants             = require('./constants');


/**
* @class Role
* @classdesc
*   A role is logical grouping of a set of users. Role inherits from {@link Object}.
* @description
*   Constructs a role
* @param uid Uid of a role on Built.io Backend
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' is uid of a role object on Built.io Backend
* var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
* @return {Role}
*/
var roleCons = module.exports = R.curry(function(app,cls,headers,query,data,delta) {
	var returnObj  = objectCons(app,cls,headers,{},data,delta); 
	return instanceMethodBuilder.build(module.exports,returnObj);
});
utility.copyProperties(module.exports, objectCons);

/**
* Returns a query instance for Role Class
* @function getRoleQuery
* @static
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* var Role = Built.App('blt5d4sample2633b').Role;
* var query = Role.getRoleQuery();
* query
* .where('name','admin')
* .exec()
* .then(function(roles){
* .deltaDeletedFrom('2014-09-02')// roles is an array of SDK objects
* });
* @return {Query}
*/
module.exports.getRoleQuery = function(app){
	return function(){
		return app.Class(constants.APP_ROLE_CLS).Query();
	}
};

var addHelper = R.curry(function (parameter, entity, role){
	if(utility.isObject(entity) && entity.get('uid')){
		entity = entity.get('uid')
	}
	var newDelta        = getMixinedDelta(role);
	var newData         = getMixinedData(role)
	var newRoles        = getArrayByParameter(parameter,role);
	newRoles.push(entity)
	newDelta[parameter] = newRoles;
	newData[parameter]  = newRoles;
	return role.cls.ObjectCons(role.getHeaders(),{},newData,newDelta);
});

/**
* Adds a new role
* @function addRole
* @param {String|Object} role Accepts SDK's role object or its uid
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' is uid of a role object on Built.io Backend
*
* // Example using role's uid
* var role  = Built.App('blt5d4sample2633b').Role();
* role = role
*        .setName('developers')
*        .addRole('blt111sample24a6b');
* //Example using SDK object
* var role1 = Built.App('blt5d4sample2633b').Role('bltcd6168a6b9ad2add');
*
* var role  = Built.App('blt5d4sample2633b').Role();
* role = role
*        .setName('developers')
*        .addRole(role1)
* @return  {Role}
*/
module.exports.addRole = addHelper('roles');
instanceMethodBuilder.define('addRole',2);

/**
* Adds a new user to this role
* @function addUser
* @param {String|Object} user Accepts SDK's user object or its uid
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' is uid of a role object on Built.io Backend
*
* //Example using role's uid
* var role = Built.App('blt5d4sample2633b').Role();
* role = role
*        .setName('developers')
*        .addUser('blt111sample24a6b');
* //Example using SDK object
* var user = Built.App('blt5d4sample2633b').User('blt111sample24a6b');
*
* var role = Built.App('blt5d4sample2633b').Role();
* role = role
*        .setName('developers')
*        .addUser(user)
* @return  {Role}
*/
module.exports.addUser = addHelper('users');
instanceMethodBuilder.define('addUser',2);

/**
* Adds new sub roles within this role
* @function addRoles
* @param {Array} roles This can be an array of role uids or an array SDK objects  
* @instance
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' and 'blt222sample24a6b' is uid of a role object on Built.io Backend
*
* //Example using role's uid
* var role = Built.App('blt5d4sample2633b').Role();
* role = role
*        .setName('developers')
*        .addRoles(['blt111sample24a6b','blt222sample24a6b']);
* //Example using SDK object
* var role1 = Built.App('blt5d4sample2633b').Role('bltcd6168a6b9ad2add');
* var role2 = Built.App('blt5d4sample2633b').Role('bltcd6168a6b9ad2acc');
*
* var role = Built.App('blt5d4sample2633b').Role();
* role = role
*        .setName('developers')
*        .addRoles([role1,role2])
* @memberof Role
* @return  {Role}
*/
module.exports.addRoles = R.curry(function (newRoles, role){
	var newRole = R.mixin({}, role);
	newRoles.forEach(function(curRole){
		// Because of immutability we have to reassign it to newRole
		newRole = newRole.addRole(curRole)
	})
	return newRole
});
instanceMethodBuilder.define('addRoles',2);

/**
* Adds a new users to this role
* @function addUsers
* @param {Array} users This can be an array of user uids or an array SDK objects  
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' and 'bll222sample24a6b' is uid of a user object on Built.io Backend
*
* //Example using role's uid
* var role = Built.App('blt5d4sample2633b').Role();
* role = role
*        .setName('developers')
*        .addUsers(['blt111sample24a6b', 'bll222sample24a6b']);
* //Example using SDK object
* var user1 = Built.App('blt5d4sample2633b').User('bltcd6168a6b9ad2add');
* var user2 = Built.App('blt5d4sample2633b').User('bltcd6168a6b9ad2acc');
*
* var role = Built.App('blt5d4sample2633b').Role();
* role = role
*        .setName('developers')
*        .addUsers([user1, user2])
* @return  {Role}
*/
module.exports.addUsers = R.curry(function (newUsers, role){ 
	var newRole = R.mixin({}, role);
	newUsers.forEach(function(user){
		// Because of immutability we have to reassign it to newRole
		newRole = newRole.addUser(user)
	})
	return newRole
});
instanceMethodBuilder.define('addUsers', 2);

/**
* Fires a query on in-built ApplicationUser objects and the ones which fulfills the query condition are assigned againts the 'users' field.
* @function setUsersWithQuery
* @param  {Object} query The query to be executed on ApplicationUser objects. It can be a in json format or app.Class('class_uid').Query object.
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
*
* //Example using plain json object. Sets all the users who's username starts with pat
* var role = Built.App('blt5d4sample2633b').Role();
* role = role
*        .setName('developers')
*        .setUsersWithQuery({
*        		query:{
*        			"username": {
						    "$regex": "^pat",
						    "$options": "i"
						  }
*        		}
*        });
*        
* //Example using app.Class('class_uid').Query
* var app       = Built.App('blt5d4sample2633b')
* var role      = app.Role();
* var userQuery = app.Class('built_io_application_user').Query()
* userQuery     = queryQuery.matches("username", "^path")
* role = role
*        .setName('developers')
*        .setUsersWithQuery(userQuery)
 * @return {Role}
 */
module.exports.setUsersWithQuery = R.curry(function(query, role){
	var newDelta = getMixinedDelta(role)

	// If BuiltQuery object is provided
	if(query.app)
		query = query.data

	newDelta['users'] = query
	return role.cls.ObjectCons(role.getHeaders(), {}, role.data, newDelta)
})
instanceMethodBuilder.define('setUsersWithQuery', 2);

/**
* Gets the name of the role
* @function getName
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* var role  = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
* role.fetch()
* .then(function(role){
*    role.getName();
* })
* @return  {String}
*/
module.exports.getName = module.exports.get('name');
instanceMethodBuilder.define('getName',1);

/**
* Gets the sub-roles contained in this role. A sub-role is a subset of a role.
* @function getRoles
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* var role  = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
* role.fetch()
* .then(function(role){
*    role.getRoles();
* });
* @return  {Array}
*/
module.exports.getRoles = module.exports.get('roles');
instanceMethodBuilder.define('getRoles',1);

/**
* Gets the uid of the role
* @function getRoleUid
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' is uid of a role object on Built.io Backend
* var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
* var uid = role.getRoleUid(); 
* @return  {String}
*/
module.exports.getRoleUid = module.exports.get('uid');
instanceMethodBuilder.define('getRoleUid',1);

/**
* Gets the users belonging to this role
* @function getUsers
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' is uid of a role object on Built.io Backend
* var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
* role.fetch()
* .then(function(role){
*    role.getUsers();
* })
* @return  {Array}
*/
module.exports.getUsers = module.exports.get('users');
instanceMethodBuilder.define('getUsers',1);

/**
* Assigns a name to this role
* @function setName
* @param {String} name Name to be assigned to this role
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* var role = Built.App('blt5d4sample2633b').Role();
* role = role.setName('developers');
* @return  {Role}
*/
module.exports.setName = module.exports.set('name');
instanceMethodBuilder.define('setName',2);
/**
* Assigns a uid to this role
* @function setRoleUid
* @param {String} uid Uid to be assigned to this role
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' is uid of a role object on Built.io Backend
* var role = Built.App('blt5d4sample2633b').Role();
* role = role.setRoleUid('blt111sample24a6b');
* @return  {Role}
*/
module.exports.setRoleUid = module.exports.set('uid');
instanceMethodBuilder.define('setRoleUid',2);

var hashelper = R.curry(function(type,uid,role){
	return R.contains(uid,getData(role)[type]);
});

/**
* Checks whether a sub-role exists in this role
* @function hasRole
* @param {String} role_uid Uid of the sub-role whose existence needs to be checked
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' is uid of a role object on Built.io Backend
*
* var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
* role.fetch()
* .then(fuction(role){
*    role.hasRole('blt444sample24a6b'); // pass sub role uid
* });
* @return  {Boolean}
*/
module.exports.hasRole = hashelper('roles');
instanceMethodBuilder.define('hasRole',2);
/**
* Checks whether a user belongs to this role
* @function hasUser
* @param {String} user_uid Uid of the user whose existence needs to be checked
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' is uid of a role object on Built.io Backend
*
* var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
* role.fetch()
* .then(fuction(role){
*    role.hasUser('blt444sample24a6b'); // pass user uid
* });
* @return  {Boolean}
*/
module.exports.hasUser = hashelper('users');
instanceMethodBuilder.define('hasUser',2);

var removeHelper = R.curry(function(type,uid,role){
	var newDelta = getMixinedDelta(role);
	var newData  = getMixinedData(role);
	var array    = getArrayByParameter(type,role);
	var index    = array.indexOf(uid);
	if(index > -1)
		array.splice(index,1);
	newDelta[type] = array;
	newData[type]  = array;  
	return role.cls.ObjectCons(role.getHeaders(),{},newData,newDelta);  
});

/**
* Removes a sub-role from the given role
* @function removeRole
* @param {String} role_uid Uid of the sub-role that needs to be removed from the role
* @instance
* @memberof Role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' is uid of a role object on Built.io Backend
* var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
* role.fetch()
* .then(function(role){
*    if(role.hasRole('blt444sample24a6b'));
*       return role.removeRole('blt444sample24a6b'); //pass role uid
*    else
*       return role;
* });
* @return  {Role}
*/
module.exports.removeRole = removeHelper('roles');
instanceMethodBuilder.define('removeRole',2);

/**
* Removes a user from a role
* @function removeUser
* @param {String} user_uid Uid of the user that needs to be removed from the role
* @example
* // 'blt5d4sample2633b' is a dummy Application API key
* // 'app.Role() returns a 'Role' instance
* // 'blt111sample24a6b' is uid of a role object on Built.io Backend
*  
* var role = Built.App('blt5d4sample2633b').Role('blt111sample24a6b');
* role.fetch()
* .then(function(role){
*    if(role.hasUser('blt444sample24a6b'));
*       return role.removeUser('blt444sample24a6b'); //pass user uid
*    else
*       return role;
* });
* @instance
* @memberof Role
* @return  {Role}
*/
module.exports.removeUser = removeHelper('users');
instanceMethodBuilder.define('removeUser',2);

function getMixinedDelta(role){
 return R.mixin({},getDelta(role));
};

function getMixinedData(role){
 return R.mixin({},getData(role));
};

function getDelta(role){
	return role.delta;
}

function getData(role){
	return role.data;
}

/*
	This function checks whether array (roles|users) exists in a role 
	It make a new array containing the same contents or retunrs a new array
*/
function getArrayByParameter(parameter,role){
	var array;
	if(getData(role)[parameter])
		var array  = [].concat(getData(role)[parameter]);
	else
		array  = [];
	return array;
}