API Docs for: v3.4.0
Show:

Roles Class

Defined in: roles/roles_common_async.js:37
Module: Roles

Item Index

Methods

Properties

Methods

_addRoleToParent

(
  • roleName
  • parentName
)
private static

Defined in roles/roles_common.js:211

Parameters:

  • roleName String

    Name of role.

  • parentName String

    Name of parent role.

_addRoleToParentAsync

(
  • roleName
  • parentName
)
Promise private static

Defined in roles/roles_common_async.js:273

Parameters:

  • roleName String

    Name of role.

  • parentName String

    Name of parent role.

Returns:

Promise:

_addUserToRole

(
  • userId
  • roleName
  • options
)
private static

Defined in roles/roles_common.js:443

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

_addUserToRole

(
  • userId
  • roleName
  • options
)
Promise private static

Defined in roles/roles_common_async.js:551

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:

_backwardMigrate

(
  • updateUser
  • updateRole
  • usingGroups
)
private static

Defined in roles/roles_server.js:351

Migrates Meteor.users and Meteor.roles to the old format.

We assume that we are converting back a failed migration, so values can only be what were valid values in the old format. So no group names starting with $ and no subroles.

Parameters:

  • updateUser Function

    Function which updates the user object. Default _defaultUpdateUser.

  • updateRole Function

    Function which updates the role object. Default _defaultUpdateRole.

  • usingGroups Boolean

    Should we use groups or not.

_backwardMigrate2

(
  • assignmentSelector
)
private static

Defined in roles/roles_server.js:386

Moves the assignments from Meteor.roleAssignment back to to Meteor.users.

Parameters:

  • assignmentSelector Object

    An opportunity to share the work among instances. It's advisable to do the division based on user-id.

_checkRoleName

(
  • roleName
)
private static

Defined in roles/roles_common.js:995

Throw an exception if roleName is an invalid role name.

Parameters:

  • roleName String

    A role name to match against.

_checkRoleName

(
  • scopeName
)
private static

Defined in roles/roles_common.js:1089

Throw an exception if scopeName is an invalid scope name.

Parameters:

  • scopeName String

    A scope name to match against.

_checkRoleName

(
  • roleName
)
private static

Defined in roles/roles_common_async.js:1206

Throw an exception if roleName is an invalid role name.

Parameters:

  • roleName String

    A role name to match against.

_checkRoleName

(
  • scopeName
)
private static

Defined in roles/roles_common_async.js:1305

Throw an exception if scopeName is an invalid scope name.

Parameters:

  • scopeName String

    A scope name to match against.

_convertToNewField

(
  • oldRoles
  • convertUnderscoresToDots
)
Array private static

Defined in roles/roles_server.js:134

Parameters:

  • oldRoles Array

    Meteor.users document roles field in the old format.

  • convertUnderscoresToDots Boolean

    Should we convert underscores to dots in group names.

Returns:

Array:

Converted roles to the new format.

_convertToNewRole

(
  • oldRole
)
Object private static

Defined in roles/roles_server.js:101

Parameters:

  • oldRole Object

    Meteor.roles document.

Returns:

Object:

Converted role to the new format.

_convertToOldField

(
  • newRoles
  • usingGroups
)
Array private static

Defined in roles/roles_server.js:178

Parameters:

  • newRoles Array

    Meteor.users document roles field in the new format.

  • usingGroups Boolean

    Should we use groups or not.

Returns:

Array:

Converted roles to the old format.

_convertToOldRole

(
  • newRole
)
Object private static

Defined in roles/roles_server.js:118

Parameters:

  • newRole Object

    Meteor.roles document.

Returns:

Object:

Converted role to the old format.

_defaultUpdateRole

(
  • oldRole
  • newRole
)
private static

Defined in roles/roles_server.js:253

Parameters:

  • oldRole Object

    Old Meteor.roles document.

  • newRole Object

    New Meteor.roles document.

_defaultUpdateUser

(
  • user
  • roles
)
private static

Defined in roles/roles_server.js:232

Parameters:

  • user Object

    Meteor.users document.

  • roles Array | Object

    Value to which user's roles field should be set.

_dropCollectionIndex

(
  • collection
  • indexName
)
private static

Defined in roles/roles_server.js:266

Parameters:

  • collection Object

    Collection on which to drop the index.

  • indexName String

    Name of the index to drop.

_forwardMigrate

(
  • updateUser
  • updateRole
  • convertUnderscoresToDots
)
private static

Defined in roles/roles_server.js:286

Migrates Meteor.users and Meteor.roles to the new format.

Parameters:

  • updateUser Function

    Function which updates the user object. Default _defaultUpdateUser.

  • updateRole Function

    Function which updates the role object. Default _defaultUpdateRole.

  • convertUnderscoresToDots Boolean

    Should we convert underscores to dots in group names.

_forwardMigrate2

(
  • userSelector
)
private static

Defined in roles/roles_server.js:319

Moves the assignments from Meteor.users to Meteor.roleAssignment.

Parameters:

  • userSelector Object

    An opportunity to share the work among instances. It's advisable to do the division based on user-id.

_getInheritedRoleNames

(
  • role
)
private static

Defined in roles/roles_common.js:526

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

Defined in roles/roles_common_async.js:679

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

Defined in roles/roles_common.js:497

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; [] })

_getParentRoleNames

(
  • role
)
Promise private static

Defined in roles/roles_common_async.js:647

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

Parameters:

  • role Object

    The role object

Returns:

Promise:

Example:

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

_getUsersInRoleCursor

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

Defined in roles/roles_common.js:850

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 Meteor.roleAssignment.find(query, options)

Returns:

Object:

Cursor to the assignment documents

_getUsersInRoleCursor

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

Defined in roles/roles_common_async.js:1039

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 Meteor.roleAssignment.find(query, options)

Returns:

Object:

Cursor to the assignment documents

_isNewField

(
  • roles
)
Boolean private static

Defined in roles/roles_server.js:72

Parameters:

  • roles Array

    Meteor.users document roles field.

Returns:

Boolean:

Returns true if the roles field is in the new format. If it is ambiguous or it is not, returns false.

_isNewRole

(
  • role
)
Boolean private static

Defined in roles/roles_server.js:46

Parameters:

  • role Object

    Meteor.roles document.

Returns:

Boolean:

Returns true if the role is in the new format. If it is ambiguous or it is not, returns false.

_isOldField

(
  • roles
)
Boolean private static

Defined in roles/roles_server.js:85

Parameters:

  • roles Array

    Meteor.users document roles field.

Returns:

Boolean:

Returns true if the roles field is in the old format. If it is ambiguous or it is not, returns false.

_isOldRole

(
  • role
)
Boolean private static

Defined in roles/roles_server.js:59

Parameters:

  • role Object

    Meteor.roles document.

Returns:

Boolean:

Returns true if the role is in the old format. If it is ambiguous or it is not, returns false.

_normalizeOptions

(
  • options
)
Object private static

Defined in roles/roles_common.js:1050

Normalize options.

Parameters:

  • options Object

    Options to normalize.

Returns:

Object:

Normalized options.

_normalizeOptions

(
  • options
)
Object private static

Defined in roles/roles_common_async.js:1266

Normalize options.

Parameters:

  • options Object

    Options to normalize.

Returns:

Object:

Normalized options.

_normalizeScopeName

(
  • scopeName
)
String private static

Defined in roles/roles_common.js:1071

Normalize scope name.

Parameters:

  • scopeName String

    A scope name to normalize.

Returns:

String:

Normalized scope name.

_normalizeScopeName

(
  • scopeName
)
String private static

Defined in roles/roles_common_async.js:1287

Normalize scope name.

Parameters:

  • scopeName String

    A scope name to normalize.

Returns:

String:

Normalized scope name.

_removeRoleFromParent

(
  • roleName
  • parentName
)
private static

Defined in roles/roles_common.js:280

Parameters:

  • roleName String

    Name of role.

  • parentName String

    Name of parent role.

_removeRoleFromParentAsync

(
  • roleName
  • parentName
)
Promise private static

Defined in roles/roles_common_async.js:358

Parameters:

  • roleName String

    Name of role.

  • parentName String

    Name of parent role.

Returns:

Promise:

_removeUserFromRole

(
  • userId
  • roleName
  • options
)
private static

Defined in roles/roles_common.js:599

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)

_removeUserFromRole

(
  • userId
  • roleName
  • options
)
Promise private static

Defined in roles/roles_common_async.js:759

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

Defined in roles/roles_common.js:191

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

Defined in roles/roles_common_async.js:252

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

Defined in roles/roles_common.js:329

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

Defined in roles/roles_common_async.js:429

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

Defined in roles/roles_common.js:55

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

Defined in roles/roles_common_async.js:69

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

Defined in roles/roles_common.js:82

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

Defined in roles/roles_common_async.js:114

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

Defined in roles/roles_common.js:773

Retrieve cursor of all existing roles.

Parameters:

  • queryOptions Object

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

Returns:

Cursor:

Cursor of existing roles.

getAllRoles

(
  • [queryOptions]
)
Cursor static

Defined in roles/roles_common_async.js:954

Retrieve cursor of all existing roles.

Parameters:

  • [queryOptions] Object optional

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

Returns:

Cursor:

Cursor of existing roles.

getGroupsForUser

() deprecated static

Defined in roles/roles_common.js:898

Deprecated. Use getScopesForUser instead.

getGroupsForUserAsync

() Promise deprecated static

Defined in roles/roles_common_async.js:1095

Deprecated. Use getScopesForUser instead.

Returns:

Promise:

getRolesForUser

(
  • user
  • [options]
)
Array static

Defined in roles/roles_common.js:697

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

Defined in roles/roles_common_async.js:869

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

Defined in roles/roles_common.js:914

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

Defined in roles/roles_common_async.js:1115

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

Defined in roles/roles_common.js:818

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 Meteor.roleAssignment.find(query, options)

    Alternatively, it can be a scope name string.

Returns:

Cursor:

Cursor of user assignments for roles.

getUserAssignmentsForRole

(
  • roles
  • [options]
)
Cursor static

Defined in roles/roles_common_async.js:1004

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 Meteor.roleAssignment.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

Defined in roles/roles_common.js:788

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

Defined in roles/roles_common_async.js:969

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

Defined in roles/roles_common.js:1009

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

Defined in roles/roles_common_async.js:1224

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

Defined in roles/roles_common.js:260

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

Defined in roles/roles_common_async.js:337

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

Defined in roles/roles_common.js:980

Remove a scope.

Roles assigned with a given scope are removed.

Parameters:

  • name String

    The name of a scope.

removeScopeAsync

(
  • name
)
Promise static

Defined in roles/roles_common_async.js:1190

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

Defined in roles/roles_common.js:553

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

Defined in roles/roles_common_async.js:712

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

Defined in roles/roles_common.js:132

Rename an existing role.

Parameters:

  • oldName String

    Old name of a role.

  • newName String

    New name of a role.

renameRoleAsync

(
  • oldName
  • newName
)
Promise static

Defined in roles/roles_common_async.js:180

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

Defined in roles/roles_common.js:951

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

Defined in roles/roles_common_async.js:1156

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

Defined in roles/roles_common.js:381

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

Defined in roles/roles_common_async.js:485

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

Defined in roles/roles_common.js:629

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

Defined in roles/roles_common_async.js:790

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

Defined in roles/roles_common.js:46

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

GLOBAL_GROUP

Unknown deprecated static

Defined in roles/roles_common_async.js:60

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

subscription

Object static

Defined in roles/client/subscriptions.js:3

Subscription handle for the collection of all existing roles.

Example:

Roles.subscription.ready(); // true if roles have been loaded