API Docs for: v4.0.0
Show:

Roles Class

Item Index

Methods

Properties

Methods

_addRoleToParent

(
  • roleName
  • parentName
)
private static

Parameters:

  • roleName String

    Name of role.

  • parentName String

    Name of parent role.

_addRoleToParentAsync

(
  • roleName
  • parentName
)
Promise private static

Parameters:

  • roleName String

    Name of role.

  • parentName String

    Name of parent role.

Returns:

Promise:

_addUserToRole

(
  • userId
  • roleName
  • options
)
private static

Add one user to one role.

Parameters:

  • userId String

    The user ID.

  • roleName String

    Name of the role to add the user to. The role have to exist.

  • options Object

    Options:

    • scope: name of the scope, or null for the global role
    • ifExists: if true, do not throw an exception if the role does not exist

_addUserToRoleAsync

(
  • userId
  • roleName
  • options
)
Promise private static

Add one user to one role.

Parameters:

  • userId String

    The user ID.

  • roleName String

    Name of the role to add the user to. The role have to exist.

  • options Object

    Options:

    • scope: name of the scope, or null for the global role
    • ifExists: if true, do not throw an exception if the role does not exist

Returns:

Promise:

_checkRoleName

(
  • roleName
)
private static

Throw an exception if roleName is an invalid role name.

Parameters:

  • roleName String

    A role name to match against.

_checkRoleName

(
  • scopeName
)
private static

Throw an exception if scopeName is an invalid scope name.

Parameters:

  • scopeName String

    A scope name to match against.

_checkRoleName

(
  • roleName
)
private static

Throw an exception if roleName is an invalid role name.

Parameters:

  • roleName String

    A role name to match against.

_checkScopeName

(
  • scopeName
)
private static

Throw an exception if scopeName is an invalid scope name.

Parameters:

  • scopeName String

    A scope name to match against.

_getInheritedRoleNames

(
  • role
)
private static

Returns an array of role names the given role name is a parent of.

Parameters:

  • role Object

    The role object

Example:

Roles._getInheritedRoleNames({ _id: 'admin', children; [] })

_getInheritedRoleNames

(
  • role
)
Promise private static

Returns an array of role names the given role name is a parent of.

Parameters:

  • role Object

    The role object

Returns:

Promise:

Example:

Roles._getInheritedRoleNames({ _id: 'admin', children; [] })

_getParentRoleNames

(
  • role
)
private static

Returns an array of role names the given role name is a child of.

Parameters:

  • role Object

    The role object

Example:

Roles._getParentRoleNames({ _id: 'admin', children; [] })

_getParentRoleNamesAsync

(
  • role
)
Promise private static

Returns an array of role names the given role name is a child of.

Parameters:

  • role Object

    The role object

Returns:

Promise:

Example:

Roles._getParentRoleNamesAsync({ _id: 'admin', children; [] })

_getUsersInRoleCursor

(
  • roles
  • [options]
  • [filter]
)
Object private static

Parameters:

  • roles Array | String

    Name of role or an array of roles. If array, ids of users are returned which have at least one of the roles assigned but need not have all roles. Roles do not have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope to restrict roles to; user's global roles will also be checked
    • anyScope: if set, role can be in any scope (scope option is ignored)

    Alternatively, it can be a scope name string.

  • [filter] Object optional

    Options which are passed directly through to RoleAssignmentCollection.find(query, options)

Returns:

Object:

Cursor to the assignment documents

_getUsersInRoleCursor

(
  • roles
  • [options]
  • [filter]
)
Object private static

Parameters:

  • roles Array | String

    Name of role or an array of roles. If array, ids of users are returned which have at least one of the roles assigned but need not have all roles. Roles do not have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope to restrict roles to; user's global roles will also be checked
    • anyScope: if set, role can be in any scope (scope option is ignored)

    Alternatively, it can be a scope name string.

  • [filter] Object optional

    Options which are passed directly through to RoleAssignmentCollection.find(query, options)

Returns:

Object:

Cursor to the assignment documents

_normalizeOptions

(
  • options
)
Object private static

Normalize options.

Parameters:

  • options Object

    Options to normalize.

Returns:

Object:

Normalized options.

_normalizeOptions

(
  • options
)
Object private static

Normalize options.

Parameters:

  • options Object

    Options to normalize.

Returns:

Object:

Normalized options.

_normalizeScopeName

(
  • scopeName
)
String private static

Normalize scope name.

Parameters:

  • scopeName String

    A scope name to normalize.

Returns:

String:

Normalized scope name.

_normalizeScopeName

(
  • scopeName
)
String private static

Normalize scope name.

Parameters:

  • scopeName String

    A scope name to normalize.

Returns:

String:

Normalized scope name.

_removeRoleFromParent

(
  • roleName
  • parentName
)
private static

Parameters:

  • roleName String

    Name of role.

  • parentName String

    Name of parent role.

_removeRoleFromParentAsync

(
  • roleName
  • parentName
)
Promise private static

Parameters:

  • roleName String

    Name of role.

  • parentName String

    Name of parent role.

Returns:

Promise:

_removeUserFromRole

(
  • userId
  • roleName
  • options
)
private static

Remove one user from one role.

Parameters:

  • userId String

    The user ID.

  • roleName String

    Name of the role to add the user to. The role have to exist.

  • options Object

    Options:

    • scope: name of the scope, or null for the global role
    • anyScope: if set, role can be in any scope (scope option is ignored)

_removeUserFromRoleAsync

(
  • userId
  • roleName
  • options
)
Promise private static

Remove one user from one role.

Parameters:

  • userId String

    The user ID.

  • roleName String

    Name of the role to add the user to. The role have to exist.

  • options Object

    Options:

    • scope: name of the scope, or null for the global role
    • anyScope: if set, role can be in any scope (scope option is ignored)

Returns:

Promise:

addRolesToParent

(
  • rolesNames
  • parentName
)
static

Add role parent to roles.

Previous parents are kept (role can have multiple parents). For users which have the parent role set, new subroles are added automatically.

Parameters:

  • rolesNames Array | String

    Name(s) of role(s).

  • parentName String

    Name of parent role.

addRolesToParentAsync

(
  • rolesNames
  • parentName
)
Promise static

Add role parent to roles.

Previous parents are kept (role can have multiple parents). For users which have the parent role set, new subroles are added automatically.

Parameters:

  • rolesNames Array | String

    Name(s) of role(s).

  • parentName String

    Name of parent role.

Returns:

Promise:

addUsersToRoles

(
  • users
  • roles
  • [options]
)
static

Add users to roles.

Adds roles to existing roles for each user.

Parameters:

  • users Array | String

    User ID(s) or object(s) with an _id field.

  • roles Array | String

    Name(s) of roles to add users to. Roles have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope, or null for the global role
    • ifExists: if true, do not throw an exception if the role does not exist

    Alternatively, it can be a scope name string.

Example:

Roles.addUsersToRoles(userId, 'admin')
Roles.addUsersToRoles(userId, ['view-secrets'], 'example.com')
Roles.addUsersToRoles([user1, user2], ['user','editor'])
Roles.addUsersToRoles([user1, user2], ['glorious-admin', 'perform-action'], 'example.org')

addUsersToRolesAsync

(
  • users
  • roles
  • [options]
)
Promise static

Add users to roles.

Adds roles to existing roles for each user.

Parameters:

  • users Array | String

    User ID(s) or object(s) with an _id field.

  • roles Array | String

    Name(s) of roles to add users to. Roles have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope, or null for the global role
    • ifExists: if true, do not throw an exception if the role does not exist

Returns:

Promise:

Alternatively, it can be a scope name string.

Example:

Roles.addUsersToRolesAsync(userId, 'admin')
Roles.addUsersToRolesAsync(userId, ['view-secrets'], 'example.com')
Roles.addUsersToRolesAsync([user1, user2], ['user','editor'])
Roles.addUsersToRolesAsync([user1, user2], ['glorious-admin', 'perform-action'], 'example.org')

createRole

(
  • roleName
  • [options]
)
String static

Create a new role.

Parameters:

  • roleName String

    Name of role.

  • [options] Object optional

    Options:

    • unlessExists: if true, exception will not be thrown in the role already exists

Returns:

String:

ID of the new role or null.

createRoleAsync

(
  • roleName
  • [options]
)
Promise static

Create a new role.

Parameters:

  • roleName String

    Name of role.

  • [options] Object optional

    Options:

    • unlessExists: if true, exception will not be thrown in the role already exists

Returns:

Promise:

ID of the new role or null.

deleteRole

(
  • roleName
)
static

Delete an existing role.

If the role is set for any user, it is automatically unset.

Parameters:

  • roleName String

    Name of role.

deleteRoleAsync

(
  • roleName
)
Promise static

Delete an existing role.

If the role is set for any user, it is automatically unset.

Parameters:

  • roleName String

    Name of role.

Returns:

Promise:

getAllRoles

(
  • queryOptions
)
Cursor static

Retrieve cursor of all existing roles.

Parameters:

  • queryOptions Object

    Options which are passed directly through to RolesCollection.find(query, options).

Returns:

Cursor:

Cursor of existing roles.

getAllRoles

(
  • [queryOptions]
)
Cursor static

Retrieve cursor of all existing roles.

Parameters:

  • [queryOptions] Object optional

    Options which are passed directly through to RolesCollection.find(query, options).

Returns:

Cursor:

Cursor of existing roles.

getGroupsForUser

() deprecated static

Deprecated. Use getScopesForUser instead.

getGroupsForUserAsync

() Promise deprecated static

Deprecated. Use getScopesForUser instead.

Returns:

Promise:

getRolesForUser

(
  • user
  • [options]
)
Array static

Retrieve user's roles.

Parameters:

  • user String | Object

    User ID or an actual user object.

  • [options] Object | String optional

    Options:

    • scope: name of scope to provide roles for; if not specified, global roles are returned
    • anyScope: if set, role can be in any scope (scope and onlyAssigned options are ignored)
    • onlyScoped: if set, only roles in the specified scope are returned
    • onlyAssigned: return only assigned roles and not automatically inferred (like subroles)
    • fullObjects: return full roles objects (true) or just names (false) (onlyAssigned option is ignored) (default false) If you have a use-case for this option, please file a feature-request. You shouldn't need to use it as it's result strongly dependent on the internal data structure of this plugin.

    Alternatively, it can be a scope name string.

Returns:

Array:

Array of user's roles, unsorted.

getRolesForUserAsync

(
  • user
  • [options]
)
Promise static

Retrieve user's roles.

Parameters:

  • user String | Object

    User ID or an actual user object.

  • [options] Object | String optional

    Options:

    • scope: name of scope to provide roles for; if not specified, global roles are returned
    • anyScope: if set, role can be in any scope (scope and onlyAssigned options are ignored)
    • onlyScoped: if set, only roles in the specified scope are returned
    • onlyAssigned: return only assigned roles and not automatically inferred (like subroles)
    • fullObjects: return full roles objects (true) or just names (false) (onlyAssigned option is ignored) (default false) If you have a use-case for this option, please file a feature-request. You shouldn't need to use it as it's result strongly dependent on the internal data structure of this plugin.

    Alternatively, it can be a scope name string.

Returns:

Promise:

Array of user's roles, unsorted.

getScopesForUser

(
  • user
  • [roles]
)
Array static

Retrieve users scopes, if any.

Parameters:

  • user String | Object

    User ID or an actual user object.

  • [roles] Array | String optional

    Name of roles to restrict scopes to.

Returns:

Array:

Array of user's scopes, unsorted.

getScopesForUserAsync

(
  • user
  • [roles]
)
Promise static

Retrieve users scopes, if any.

Parameters:

  • user String | Object

    User ID or an actual user object.

  • [roles] Array | String optional

    Name of roles to restrict scopes to.

Returns:

Promise:

Array of user's scopes, unsorted.

getUserAssignmentsForRole

(
  • roles
  • [options]
)
Cursor static

Retrieve all assignments of a user which are for the target role.

Options:

Parameters:

  • roles Array | String

    Name of role or an array of roles. If array, users returned will have at least one of the roles specified but need not have all roles. Roles do not have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope to restrict roles to; user's global roles will also be checked
    • anyScope: if set, role can be in any scope (scope option is ignored)
    • queryOptions: options which are passed directly through to RoleAssignmentCollection.find(query, options)

    Alternatively, it can be a scope name string.

Returns:

Cursor:

Cursor of user assignments for roles.

getUserAssignmentsForRole

(
  • roles
  • [options]
)
Cursor static

Retrieve all assignments of a user which are for the target role.

Options:

Parameters:

  • roles Array | String

    Name of role or an array of roles. If array, users returned will have at least one of the roles specified but need not have all roles. Roles do not have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope to restrict roles to; user's global roles will also be checked
    • anyScope: if set, role can be in any scope (scope option is ignored)
    • queryOptions: options which are passed directly through to RoleAssignmentCollection.find(query, options)

    Alternatively, it can be a scope name string.

Returns:

Cursor:

Cursor of user assignments for roles.

getUsersInRole

(
  • roles
  • [options]
  • [queryOptions]
)
Cursor static

Retrieve all users who are in target role.

Options:

Parameters:

  • roles Array | String

    Name of role or an array of roles. If array, users returned will have at least one of the roles specified but need not have all roles. Roles do not have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope to restrict roles to; user's global roles will also be checked
    • anyScope: if set, role can be in any scope (scope option is ignored)
    • onlyScoped: if set, only roles in the specified scope are returned
    • queryOptions: options which are passed directly through to Meteor.users.find(query, options)

    Alternatively, it can be a scope name string.

  • [queryOptions] Object optional

    Options which are passed directly through to Meteor.users.find(query, options)

Returns:

Cursor:

Cursor of users in roles.

getUsersInRoleAsync

(
  • roles
  • [options]
  • [queryOptions]
)
Promise static

Retrieve all users who are in target role.

Options:

Parameters:

  • roles Array | String

    Name of role or an array of roles. If array, users returned will have at least one of the roles specified but need not have all roles. Roles do not have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope to restrict roles to; user's global roles will also be checked
    • anyScope: if set, role can be in any scope (scope option is ignored)
    • onlyScoped: if set, only roles in the specified scope are returned
    • queryOptions: options which are passed directly through to Meteor.users.find(query, options)

    Alternatively, it can be a scope name string.

  • [queryOptions] Object optional

    Options which are passed directly through to Meteor.users.find(query, options)

Returns:

Promise:

Cursor of users in roles.

isParentOf

(
  • parentRoleName
  • childRoleName
)
static

Find out if a role is an ancestor of another role.

WARNING: If you check this on the client, please make sure all roles are published.

Parameters:

  • parentRoleName String

    The role you want to research.

  • childRoleName String

    The role you expect to be among the children of parentRoleName.

isParentOfAsync

(
  • parentRoleName
  • childRoleName
)
Promise static

Find out if a role is an ancestor of another role.

WARNING: If you check this on the client, please make sure all roles are published.

Parameters:

  • parentRoleName String

    The role you want to research.

  • childRoleName String

    The role you expect to be among the children of parentRoleName.

Returns:

Promise:

removeRolesFromParent

(
  • rolesNames
  • parentName
)
static

Remove role parent from roles.

Other parents are kept (role can have multiple parents). For users which have the parent role set, removed subrole is removed automatically.

Parameters:

  • rolesNames Array | String

    Name(s) of role(s).

  • parentName String

    Name of parent role.

removeRolesFromParentAsync

(
  • rolesNames
  • parentName
)
Promise static

Remove role parent from roles.

Other parents are kept (role can have multiple parents). For users which have the parent role set, removed subrole is removed automatically.

Parameters:

  • rolesNames Array | String

    Name(s) of role(s).

  • parentName String

    Name of parent role.

Returns:

Promise:

removeScope

(
  • name
)
static

Remove a scope.

Roles assigned with a given scope are removed.

Parameters:

  • name String

    The name of a scope.

removeScopeAsync

(
  • name
)
Promise static

Remove a scope.

Roles assigned with a given scope are removed.

Parameters:

  • name String

    The name of a scope.

Returns:

Promise:

removeUsersFromRoles

(
  • users
  • roles
  • [options]
)
static

Remove users from assigned roles.

Parameters:

  • users Array | String

    User ID(s) or object(s) with an _id field.

  • roles Array | String

    Name(s) of roles to remove users from. Roles have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope, or null for the global role
    • anyScope: if set, role can be in any scope (scope option is ignored)

    Alternatively, it can be a scope name string.

Example:

Roles.removeUsersFromRoles(userId, 'admin')
Roles.removeUsersFromRoles([userId, user2], ['editor'])
Roles.removeUsersFromRoles(userId, ['user'], 'group1')

removeUsersFromRolesAsync

(
  • users
  • roles
  • [options]
)
Promise static

Remove users from assigned roles.

Parameters:

  • users Array | String

    User ID(s) or object(s) with an _id field.

  • roles Array | String

    Name(s) of roles to remove users from. Roles have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope, or null for the global role
    • anyScope: if set, role can be in any scope (scope option is ignored)

Returns:

Promise:

Alternatively, it can be a scope name string.

Example:

await Roles.removeUsersFromRolesAsync(userId, 'admin')
await Roles.removeUsersFromRolesAsync([userId, user2], ['editor'])
await Roles.removeUsersFromRolesAsync(userId, ['user'], 'group1')

renameRole

(
  • oldName
  • newName
)
static

Rename an existing role.

Parameters:

  • oldName String

    Old name of a role.

  • newName String

    New name of a role.

renameRoleAsync

(
  • oldName
  • newName
)
Promise static

Rename an existing role.

Parameters:

  • oldName String

    Old name of a role.

  • newName String

    New name of a role.

Returns:

Promise:

renameScope

(
  • oldName
  • newName
)
static

Rename a scope.

Roles assigned with a given scope are changed to be under the new scope.

Parameters:

  • oldName String

    Old name of a scope.

  • newName String

    New name of a scope.

renameScopeAsync

(
  • oldName
  • newName
)
Promise static

Rename a scope.

Roles assigned with a given scope are changed to be under the new scope.

Parameters:

  • oldName String

    Old name of a scope.

  • newName String

    New name of a scope.

Returns:

Promise:

setUserRoles

(
  • users
  • roles
  • [options]
)
static

Set users' roles.

Replaces all existing roles with a new set of roles.

Parameters:

  • users Array | String

    User ID(s) or object(s) with an _id field.

  • roles Array | String

    Name(s) of roles to add users to. Roles have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope, or null for the global role
    • anyScope: if true, remove all roles the user has, of any scope, if false, only the one in the same scope
    • ifExists: if true, do not throw an exception if the role does not exist

    Alternatively, it can be a scope name string.

Example:

Roles.setUserRoles(userId, 'admin')
Roles.setUserRoles(userId, ['view-secrets'], 'example.com')
Roles.setUserRoles([user1, user2], ['user','editor'])
Roles.setUserRoles([user1, user2], ['glorious-admin', 'perform-action'], 'example.org')

setUserRolesAsync

(
  • users
  • roles
  • [options]
)
Promise static

Set users' roles.

Replaces all existing roles with a new set of roles.

Parameters:

  • users Array | String

    User ID(s) or object(s) with an _id field.

  • roles Array | String

    Name(s) of roles to add users to. Roles have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope, or null for the global role
    • anyScope: if true, remove all roles the user has, of any scope, if false, only the one in the same scope
    • ifExists: if true, do not throw an exception if the role does not exist

Returns:

Promise:

Alternatively, it can be a scope name string.

Example:

await Roles.setUserRolesAsync(userId, 'admin')
await Roles.setUserRolesAsync(userId, ['view-secrets'], 'example.com')
await Roles.setUserRolesAsync([user1, user2], ['user','editor'])
await Roles.setUserRolesAsync([user1, user2], ['glorious-admin', 'perform-action'], 'example.org')

userIsInRole

(
  • user
  • roles
  • [options]
)
Boolean static

Check if user has specified roles.

Parameters:

  • user String | Object

    User ID or an actual user object.

  • roles Array | String

    Name of role or an array of roles to check against. If array, will return true if user is in any role. Roles do not have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope; if supplied, limits check to just that scope the user's global roles will always be checked whether scope is specified or not
    • anyScope: if set, role can be in any scope (scope option is ignored)

    Alternatively, it can be a scope name string.

Returns:

Boolean:

true if user is in any of the target roles

Example:

// global roles
Roles.userIsInRole(user, 'admin')
Roles.userIsInRole(user, ['admin','editor'])
Roles.userIsInRole(userId, 'admin')
Roles.userIsInRole(userId, ['admin','editor'])

// scope roles (global roles are still checked)
Roles.userIsInRole(user, 'admin', 'group1')
Roles.userIsInRole(userId, ['admin','editor'], 'group1')
Roles.userIsInRole(userId, ['admin','editor'], {scope: 'group1'})

userIsInRoleAsync

(
  • user
  • roles
  • [options]
)
Promise static

Check if user has specified roles.

Parameters:

  • user String | Object

    User ID or an actual user object.

  • roles Array | String

    Name of role or an array of roles to check against. If array, will return true if user is in any role. Roles do not have to exist.

  • [options] Object | String optional

    Options:

    • scope: name of the scope; if supplied, limits check to just that scope the user's global roles will always be checked whether scope is specified or not
    • anyScope: if set, role can be in any scope (scope option is ignored)

    Alternatively, it can be a scope name string.

Returns:

Promise:

true if user is in any of the target roles

Example:

// global roles
await Roles.userIsInRoleAsync(user, 'admin')
await Roles.userIsInRoleAsync(user, ['admin','editor'])
await Roles.userIsInRoleAsync(userId, 'admin')
await Roles.userIsInRoleAsync(userId, ['admin','editor'])

// scope roles (global roles are still checked)
await Roles.userIsInRoleAsync(user, 'admin', 'group1')
await Roles.userIsInRoleAsync(userId, ['admin','editor'], 'group1')
await Roles.userIsInRoleAsync(userId, ['admin','editor'], {scope: 'group1'})

Properties

GLOBAL_GROUP

Unknown deprecated static

Used as a global group (now scope) name. Not used anymore.

GLOBAL_GROUP

Unknown deprecated static

Used as a global group (now scope) name. Not used anymore.