diff --git a/History.md b/History.md index 0586e4b..cac88de 100644 --- a/History.md +++ b/History.md @@ -1,5 +1,11 @@ # Changelog +## v3.6.1 + +* Added types for async functions [#386](/~https://github.com/Meteor-Community-Packages/meteor-roles/pull/386) [@storytellercz](/~https://github.com/sponsors/StorytellerCZ) +* Updated docs with async functions [@storytellercz](/~https://github.com/sponsors/StorytellerCZ) +* Updated `zodern:types` to v1.0.10 + ## v3.6.0 * Added async versions of functions [#361](/~https://github.com/Meteor-Community-Packages/meteor-roles/pull/361) [#378](/~https://github.com/Meteor-Community-Packages/meteor-roles/pull/378) [@bratelefant](/~https://github.com/bratelefant) [@storytellercz](/~https://github.com/sponsors/StorytellerCZ) [@jankapunkt](/~https://github.com/sponsors/jankapunkt) diff --git a/definitions.d.ts b/definitions.d.ts index 56da737..2277565 100644 --- a/definitions.d.ts +++ b/definitions.d.ts @@ -69,6 +69,11 @@ declare namespace Roles { roles: string | string[], options?: string | { scope?: string; ifExists?: boolean } ): void + function addUsersToRolesAsync( + users: string | string[] | Meteor.User | Meteor.User[], + roles: string | string[], + options?: string | { scope?: string; ifExists?: boolean } + ): Promise /** * Create a new role. @@ -80,6 +85,7 @@ declare namespace Roles { * @return {String} ID of the new role or null. */ function createRole(roleName: string, options?: { unlessExists: boolean }): string + function createRoleAsync(roleName: string, options?: { unlessExists: boolean }): Promise /** * Delete an existing role. @@ -90,6 +96,7 @@ declare namespace Roles { * @param {String} roleName Name of role. */ function deleteRole(roleName: string): void + function deleteRoleAsync(roleName: string): Promise /** * Rename an existing role. @@ -99,6 +106,7 @@ declare namespace Roles { * @param {String} newName New name of a role. */ function renameRole(oldName: string, newName: string): void + function renameRoleAsync(oldName: string, newName: string): Promise /** * Add role parent to roles. @@ -111,6 +119,7 @@ declare namespace Roles { * @param {String} parentName Name of parent role. */ function addRolesToParent(rolesNames: string | string[], parentName: string): void + function addRolesToParentAsync(rolesNames: string | string[], parentName: string): Promise /** * Remove role parent from roles. @@ -123,6 +132,7 @@ declare namespace Roles { * @param {String} parentName Name of parent role. */ function removeRolesFromParent(rolesNames: string | string[], parentName: string): void + function removeRolesFromParentAsync(rolesNames: string | string[], parentName: string): Promise /** * Retrieve cursor of all existing roles. @@ -144,6 +154,7 @@ declare namespace Roles { * @return {Array} Array of user's groups, unsorted. Roles.GLOBAL_GROUP will be omitted */ function getGroupsForUser(user: string | Meteor.User, role?: string): string[] + function getGroupsForUserAsync(user: string | Meteor.User, role?: string): Promise /** * Retrieve users scopes, if any. @@ -155,6 +166,7 @@ declare namespace Roles { * @return {Array} Array of user's scopes, unsorted. */ function getScopesForUser(user: string | Meteor.User, roles?: string | string[]): string[] + function getScopesForUserAsync(user: string | Meteor.User, roles?: string | string[]): Promise /** * Rename a scope. @@ -166,6 +178,7 @@ declare namespace Roles { * @param {String} newName New name of a scope. */ function renameScope(oldName: string, newName: string): void + function renameScopeAsync(oldName: string, newName: string): Promise /** * Remove a scope. @@ -177,6 +190,7 @@ declare namespace Roles { * */ function removeScope(name: String): void + function removeScopeAsync(name: String): Promise /** * Find out if a role is an ancestor of another role. @@ -189,6 +203,7 @@ declare namespace Roles { * @return {Boolean} */ function isParentOf(parentRoleName: string, childRoleName: string): boolean + function isParentOfAsync(parentRoleName: string, childRoleName: string): Promise /** * Retrieve user's roles. @@ -214,6 +229,13 @@ declare namespace Roles { onlyAssigned?: boolean; fullObjects?: boolean }): string[] + function getRolesForUserAsync(user: string | Meteor.User, options?: string | { + scope?: string; + anyScope?: boolean; + onlyScoped?: boolean; + onlyAssigned?: boolean; + fullObjects?: boolean + }): Promise /** * Retrieve all assignments of a user which are for the target role. @@ -269,6 +291,11 @@ declare namespace Roles { options?: string | { scope?: string; anyScope?: boolean; onlyScoped?: boolean; queryOptions?: QueryOptions }, queryOptions?: QueryOptions ): Mongo.Cursor + function getUsersInRoleAsync( + roles: string | string[], + options?: string | { scope?: string; anyScope?: boolean; onlyScoped?: boolean; queryOptions?: QueryOptions }, + queryOptions?: QueryOptions + ): Promise> /** * Remove users from assigned roles. @@ -292,6 +319,11 @@ declare namespace Roles { roles?: string | string[], options?: string | { scope?: string; anyScope?: boolean } ): void + function removeUsersFromRolesAsync( + users: string | string[] | Meteor.User | Meteor.User[], + roles?: string | string[], + options?: string | { scope?: string; anyScope?: boolean } + ): Promise /** * Set users' roles. @@ -319,6 +351,11 @@ declare namespace Roles { roles: string | string[], options?: string | { scope?: string; anyScope?: boolean; ifExists?: boolean } ): void + function setUserRolesAsync( + users: string | string[] | Meteor.User | Meteor.User[], + roles: string | string[], + options?: string | { scope?: string; anyScope?: boolean; ifExists?: boolean } + ): Promise /** * Check if user has specified roles. @@ -353,13 +390,20 @@ declare namespace Roles { roles: string | string[], options?: string | { scope?: string; anyScope?: boolean } ): boolean + function userIsInRoleAsync( + user: string | string[] | Meteor.User | Meteor.User[], + roles: string | string[], + options?: string | { scope?: string; anyScope?: boolean } + ): Promise + // The schema for the roles collection interface Role { _id: string name: string children: { _id: string }[] } + // The schema for the role-assignment collection interface RoleAssignment { _id: string user: { diff --git a/package.js b/package.js index 7f3ad49..da41fa9 100644 --- a/package.js +++ b/package.js @@ -2,7 +2,7 @@ Package.describe({ summary: 'Authorization package for Meteor', - version: '3.6.0', + version: '3.6.1', git: '/~https://github.com/Meteor-Community-Packages/meteor-roles.git', name: 'alanning:roles' }) @@ -20,7 +20,7 @@ Package.onUse(function (api) { 'check' ], both) - api.use('zodern:types@1.0.9') + api.use('zodern:types@1.0.10') api.use(['blaze@2.7.1'], 'client', { weak: true }) diff --git a/roles/roles_common_async.js b/roles/roles_common_async.js index 7d3369c..6ca1a9f 100644 --- a/roles/roles_common_async.js +++ b/roles/roles_common_async.js @@ -69,7 +69,7 @@ Object.assign(Roles, { /** * Create a new role. * - * @method createRole + * @method createRoleAsync * @param {String} roleName Name of role. * @param {Object} [options] Options: * - `unlessExists`: if `true`, exception will not be thrown in the role already exists @@ -116,7 +116,7 @@ Object.assign(Roles, { * * If the role is set for any user, it is automatically unset. * - * @method deleteRole + * @method deleteRoleAsync * @param {String} roleName Name of role. * @returns {Promise} * @static @@ -180,7 +180,7 @@ Object.assign(Roles, { /** * Rename an existing role. * - * @method renameRole + * @method renameRoleAsync * @param {String} oldName Old name of a role. * @param {String} newName New name of a role. * @returns {Promise} @@ -255,7 +255,7 @@ Object.assign(Roles, { * Previous parents are kept (role can have multiple parents). For users which have the * parent role set, new subroles are added automatically. * - * @method addRolesToParent + * @method addRolesToParentAsync * @param {Array|String} rolesNames Name(s) of role(s). * @param {String} parentName Name of parent role. * @returns {Promise} @@ -271,7 +271,7 @@ Object.assign(Roles, { }, /** - * @method _addRoleToParent + * @method _addRoleToParentAsync * @param {String} roleName Name of role. * @param {String} parentName Name of parent role. * @returns {Promise} @@ -340,7 +340,7 @@ Object.assign(Roles, { * Other parents are kept (role can have multiple parents). For users which have the * parent role set, removed subrole is removed automatically. * - * @method removeRolesFromParent + * @method removeRolesFromParentAsync * @param {Array|String} rolesNames Name(s) of role(s). * @param {String} parentName Name of parent role. * @returns {Promise} @@ -356,7 +356,7 @@ Object.assign(Roles, { }, /** - * @method _removeRoleFromParent + * @method _removeRoleFromParentAsync * @param {String} roleName Name of role. * @param {String} parentName Name of parent role. * @returns {Promise} @@ -432,12 +432,12 @@ Object.assign(Roles, { * Adds roles to existing roles for each user. * * @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') + * 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') * - * @method addUsersToRoles + * @method addUsersToRolesAsync * @param {Array|String} users User ID(s) or object(s) with an `_id` field. * @param {Array|String} roles Name(s) of roles to add users to. Roles have to exist. * @param {Object|String} [options] Options: @@ -488,12 +488,12 @@ Object.assign(Roles, { * Replaces all existing roles with a new set of roles. * * @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') + * 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') * - * @method setUserRoles + * @method setUserRolesAsync * @param {Array|String} users User ID(s) or object(s) with an `_id` field. * @param {Array|String} roles Name(s) of roles to add users to. Roles have to exist. * @param {Object|String} [options] Options: @@ -713,11 +713,11 @@ Object.assign(Roles, { * Remove users from assigned roles. * * @example - * Roles.removeUsersFromRoles(userId, 'admin') - * Roles.removeUsersFromRoles([userId, user2], ['editor']) - * Roles.removeUsersFromRoles(userId, ['user'], 'group1') + * await Roles.removeUsersFromRolesAsync(userId, 'admin') + * await Roles.removeUsersFromRolesAsync([userId, user2], ['editor']) + * await Roles.removeUsersFromRolesAsync(userId, ['user'], 'group1') * - * @method removeUsersFromRoles + * @method removeUsersFromRolesAsync * @param {Array|String} users User ID(s) or object(s) with an `_id` field. * @param {Array|String} roles Name(s) of roles to remove users from. Roles have to exist. * @param {Object|String} [options] Options: @@ -792,17 +792,17 @@ Object.assign(Roles, { * * @example * // global roles - * Roles.userIsInRole(user, 'admin') - * Roles.userIsInRole(user, ['admin','editor']) - * Roles.userIsInRole(userId, 'admin') - * Roles.userIsInRole(userId, ['admin','editor']) + * 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) - * Roles.userIsInRole(user, 'admin', 'group1') - * Roles.userIsInRole(userId, ['admin','editor'], 'group1') - * Roles.userIsInRole(userId, ['admin','editor'], {scope: 'group1'}) + * await Roles.userIsInRoleAsync(user, 'admin', 'group1') + * await Roles.userIsInRoleAsync(userId, ['admin','editor'], 'group1') + * await Roles.userIsInRoleAsync(userId, ['admin','editor'], {scope: 'group1'}) * - * @method userIsInRole + * @method userIsInRoleAsync * @param {String|Object} user User ID or an actual user object. * @param {Array|String} roles Name of role or an array of roles to check against. If array, * will return `true` if user is in _any_ role. @@ -869,7 +869,7 @@ Object.assign(Roles, { /** * Retrieve user's roles. * - * @method getRolesForUser + * @method getRolesForUserAsync * @param {String|Object} user User ID or an actual user object. * @param {Object|String} [options] Options: * - `scope`: name of scope to provide roles for; if not specified, global roles are returned @@ -971,7 +971,7 @@ Object.assign(Roles, { * * Options: * - * @method getUsersInRole + * @method getUsersInRoleAsync * @param {Array|String} roles 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. @@ -1095,7 +1095,7 @@ Object.assign(Roles, { /** * Deprecated. Use `getScopesForUser` instead. * - * @method getGroupsForUser + * @method getGroupsForUserAsync * @returns {Promise} * @static * @deprecated @@ -1115,7 +1115,7 @@ Object.assign(Roles, { /** * Retrieve users scopes, if any. * - * @method getScopesForUser + * @method getScopesForUserAsync * @param {String|Object} user User ID or an actual user object. * @param {Array|String} [roles] Name of roles to restrict scopes to. * @@ -1158,7 +1158,7 @@ Object.assign(Roles, { * * Roles assigned with a given scope are changed to be under the new scope. * - * @method renameScope + * @method renameScopeAsync * @param {String} oldName Old name of a scope. * @param {String} newName New name of a scope. * @returns {Promise} @@ -1192,7 +1192,7 @@ Object.assign(Roles, { * * Roles assigned with a given scope are removed. * - * @method removeScope + * @method removeScopeAsync * @param {String} name The name of a scope. * @returns {Promise} * @static @@ -1226,7 +1226,7 @@ Object.assign(Roles, { * * WARNING: If you check this on the client, please make sure all roles are published. * - * @method isParentOf + * @method isParentOfAsync * @param {String} parentRoleName The role you want to research. * @param {String} childRoleName The role you expect to be among the children of parentRoleName. * @returns {Promise} diff --git a/yuidoc.json b/yuidoc.json index 18329a2..de1aa90 100644 --- a/yuidoc.json +++ b/yuidoc.json @@ -1,7 +1,7 @@ { "name": "The meteor-roles API", "description": "The meteor-roles API: an authorization package for Meteor", - "version": "v3.4.0", + "version": "v3.6.0", "options": { "outdir": "./docs", "exclude": ".meteor,.build,tests",