role-hierarchy v2.1.2

Role Hierarchy Data Model

This is a data model for a hierarchy of roles, suitable for mongodb users or meteor.

Given a definition of a role hierarchy :

  let hierarchyObj = {
      "name": "admin",
      "subordinates": [
        {
          "name": "user-admin",
          "subordinates": [
            {
              "name": "schoolAdmin",
              "subordinates": [
                {
                  "name": "teacher",
                  "subordinates": [
                    {
                      "name": "student",
                      // a student can see the following fields
                      "visibleUserFields": {
                        "_id": 1,
                        "username": 1,
                        "profile.name": 1,
                        "roles": 1
                      }
                    }
                  ],
                  // new users created by a teacher get the student role
                  "defaultNewUserRoles": [
                    "student"
                  ],
                  // new users created by a teacher get the teacher's profile.school and profile.classId
                  "profileFilters": [
                    "school",
                    "classId"
                  ],
                  // a teacher can see everything a student can see, also email addresses
                  "visibleUserFields": {
                    "emails": 1
                  }
                }
              ],
              "profileFilters": [
                "school"
              ]
            },
            {
              "name":"footballCoach",
              "subordinates":[
                {
                  "name": "footballCaptain",
                  "subordinates" :[
                    {
                      "name":"footballPlayer"
                    }
                  ]
                }
              ]
            }
          ],
          "defaultNewUserRoles": [
            "teacher"
          ]
        }
      ],
      "defaultNewUserRoles": [
        "teacher"
      ]
    }

    let roleHierarchy = new RoleHierarchy(
      {
        "rolesHierarchy": hierarchyObj),
        "loggingConfig": { level: "debug" },
        treeModelConfig: { "childrenPropertyName": "subordinates" },
      }      
    );

And a user :

  let myUserObj = {
    _id: 'abc123',
    profile: {
      organizations: ['springfield school', 'springfield football team']
    },
    "roles": {
      "springfield school": [
        "schoolAdmin",
        "footballCaptain"
      ],
      "springfield football team": [
        "footballCoach"
      ]

    }
  };

You can find information about the user's subordinates.

let subordinatesMap = roleHierarchy.getAllUserSubordinatesAsMap(myUserObj);
/*
{
        "springfield school": ["teacher", "student", "footballPlayer"],
        "springfield football team": ["footballCaptain", "footballPlayer"]
      }
*/

Or about a role's subordinates

let subordinatesArray = roleHierarchy.getAllSubordinateRolesAsArray('schoolAdmin');
/*
["teacher", "student"]
*/

Tests

Look in the test/test.js file, it gives you a pretty good idea of how to use this library.

To run the tests, simply :

npm test

API

docs generated with jsdoc2md

RoleHierarchy

Kind: global class

• RoleHierarchy
  • new RoleHierarchy(paramsObj)
  • instance
    • .reparse(rolesHierarchy)
    • ._getOrganizationsForUser(myUserObj)
    • .findRoleInHierarchy(roleName) ⇒ object
    • .getRoleSubordinate(seniorRoleName, subordinateRoleName) ⇒ object
    • .getAllSubordinateRolesAsArray(seniorRoleName) ⇒ Array
    • .getAllUserSubordinatesAsMap(myUserObj) ⇒ Object
    • .getAllMyFieldsAsObject(myUserObj) ⇒ object
    • .isUserHasMoreSeniorRole(myUserObj, roleName, organizationName) ⇒ boolean
    • .isUserDescendantOfUser(seniorUserObj, subordinateUserObj, organizationName) ⇒ boolean
    • .getProfileCriteriaFromUser(userWithProfile, profileFilterCriteria, organizationName) ⇒ object
  • static
    • .getOrganizationsForUser(myUserObj) ⇒ Array.<String>
    • .getRolesForUser(user, organization) ⇒ Array
    • ._getRolesForUser(user, organization)

new RoleHierarchy(paramsObj)

create a new instance of RoleHierarchy

roleHierarchy.reparse(rolesHierarchy)

re-create the hierarchy with a new object structure.

Kind: instance method of RoleHierarchy

roleHierarchy._getOrganizationsForUser(myUserObj)

Deprecated - use RoleHierarchy.getOrganizationsForUser instead.

Kind: instance method of RoleHierarchy

roleHierarchy.findRoleInHierarchy(roleName) ⇒ object

Find a role in the hierarchy by name

Kind: instance method of RoleHierarchy Returns: object - - the node in the tree that matches

roleHierarchy.getRoleSubordinate(seniorRoleName, subordinateRoleName) ⇒ object

Return the subordinate roles of the given seniorRoleName

Kind: instance method of RoleHierarchy Returns: object - - the role of the subordinate, or false if not found.

roleHierarchy.getAllSubordinateRolesAsArray(seniorRoleName) ⇒ Array

Get the names of subordinate roles as an array

Kind: instance method of RoleHierarchy Returns: Array - - the subordinate role names if any, otherwise undefined.

roleHierarchy.getAllUserSubordinatesAsMap(myUserObj) ⇒ Object

Get a map of all of the role names that the provided user can administer, grouped by organization

Kind: instance method of RoleHierarchy Returns: Object - an object of subordinate {organization:roleName, roleName} arrays that the provided user can administer

roleHierarchy.getAllMyFieldsAsObject(myUserObj) ⇒ object

Get an object of all of the Meteor.user fields that the provided user can see

Kind: instance method of RoleHierarchy Returns: object - an object of the format {orgName: {field1: 1, field2: 2}}, the values being Meteor.user field names that the provided user can see, suitable for inclusion as a "fields" property in a mongodb Collection query.

roleHierarchy.isUserHasMoreSeniorRole(myUserObj, roleName, organizationName) ⇒ boolean

returns true if the given object is more senior than the given role in the given organization.

Kind: instance method of RoleHierarchy Returns: boolean - true if the user is more senior than the given role

roleHierarchy.isUserDescendantOfUser(seniorUserObj, subordinateUserObj, organizationName) ⇒ boolean

returns true if the given senior user is higher in the hierarchy than the given subordinate user for the given organization.

Kind: instance method of RoleHierarchy Returns: boolean - true if the subordinateUser is below seniorUser in the hierarchy for at least one organization in common.

roleHierarchy.getProfileCriteriaFromUser(userWithProfile, profileFilterCriteria, organizationName) ⇒ object

Copy the given user's profile properties (as specified in roles hierarchy as profileFilters) as profile properties suitable for adding to a new user.

Kind: instance method of RoleHierarchy Returns: object - the query criteria, suitable for mongodb, to ensure only users with the same values for the specified fields will be returned.

RoleHierarchy.getOrganizationsForUser(myUserObj) ⇒ Array.<String>

Get the organizations that the user belongs to, as an array.

Kind: static method of RoleHierarchy Returns: Array.<String> - an array of the organizations that the user belongs to.

RoleHierarchy.getRolesForUser(user, organization) ⇒ Array

Retrieve users roles

Kind: static method of RoleHierarchy Returns: Array - Array of user's roles, unsorted.

RoleHierarchy._getRolesForUser(user, organization)

Deprecated. Use RoleHierarchy.getRolesForUser instead.

Kind: static method of RoleHierarchy