services.groups.md

services.groups

Service for communication with group-related part of Topcoder API.

NOTE: Through this file, and in related contexts, by loading a user group, or user groups data, we refer to loading the information about descendant user groups; i.e. given some user group(s) we speak about loading the sub- three of related child groups.

By group maps we refer to the object having group IDs as the keys, and group data objects as the values. Any group object included into a group map has its "subGroups" array (if present) replaced by "subGroupIds", that lists only the IDs of immediate child groups; actual child group objects from "subGroups" are recursively added to the top level of the group map. Also each group in the group map is timestamped to keep caching of the loaded data.

• services.groups
  • static
    • .addDescendantGroups(groupIds, knownGroups) ⇒ Array.<String>
    • .checkGroupsStatus(groupIds, knownGroups, loadingGroups) ⇒ Object
    • .checkUserGroups(groupIds, userGroups, knownGroups) ⇒ Boolean
    • .getService(tokenV3) ⇒ GroupService
  • inner
    • ~GroupService
      • new GroupService(tokenV3)
      • .addMember(groupId, memberId, membershipType) ⇒ Promise
      • .getGroup(groupId, withSubGroups) ⇒ Promise
      • .getGroupMap(groupIds) ⇒ Promise
      • .getMembers(groupId) ⇒ Promise
      • .getMembersCount(groupId, withSubGroups) ⇒ Promise
    • ~handleApiResponse(response) ⇒ Promise
    • ~mergeGroup(groups, group)

services.groups.addDescendantGroups(groupIds, knownGroups) ⇒ Array.<String>

Given an array of IDs (or a single ID) of user groups, and a map of known user groups, it returns the array including all specified user groups, and all their known descendant groups.

Kind: static method of services.groups

Param	Type
groupIds	String | Array.<String>
knownGroups	Object

services.groups.checkGroupsStatus(groupIds, knownGroups, loadingGroups) ⇒ Object

Splits the given list of group IDs into the lists of groups being loaded, loaded, and others.

Kind: static method of services.groups
Returns: Object - Resulting object may hold four arrays with group IDs from "groupIds" (empty arrays will not be included into the result object):

• "loaded" - the groups that are present in "knownGroups" and are not outdated;
• "loading" - the groups that are not present in "knownGroups" (or present, but outdated); but they are already being loaded;
• "missing" - the groups that are not present in "knownGroups" (or outdated), and are not being loaded.
• "unknown" - the groups that are absent in "knownGroups" map.

Param	Type	Description
groupIds	String | Array.<String>	ID, or an array of IDs, of the group(s) we are interested in.
knownGroups	Object	Optional. The map of already known groups (some of them may be outdated, though). This should be of the same format as the object on "groups.groups" path of the Redux store. Defaults to empty object.
loadingGroups	Object	Optional. Set of groups beign loaded now. This should be of the same format as the object on "groups.loading" path of the Redux store. Defaults to empty object.

services.groups.checkUserGroups(groupIds, userGroups, knownGroups) ⇒ Boolean

Returns "true" if "userGroups" arrays includes any group specified by "groupIds", or any group descendant from a group specified by "groupIds". The is the map of known groups

Kind: static method of services.groups

Param	Type	Description
groupIds	String | Array.<String>
userGroups	Array.<Object> | Array.<String>	Array of user's groups or their IDs.
knownGroups	Object	Map of known groups.

services.groups.getService(tokenV3) ⇒ GroupService

Returns a new or existing instance of challenge service, which works with the specified auth token.

Kind: static method of services.groups
Returns: GroupService - Instance of the service.

Param	Type	Description
tokenV3	String	Optional. Topcoder API v3 auth token.

services.groups~GroupService

Service class.

Kind: inner class of services.groups

• ~GroupService
  • new GroupService(tokenV3)
  • .addMember(groupId, memberId, membershipType) ⇒ Promise
  • .getGroup(groupId, withSubGroups) ⇒ Promise
  • .getGroupMap(groupIds) ⇒ Promise
  • .getMembers(groupId) ⇒ Promise
  • .getMembersCount(groupId, withSubGroups) ⇒ Promise

new GroupService(tokenV3)

Param	Type	Description
tokenV3	String	Optional. Auth token for Topcoder API v3.

groupService.addMember(groupId, memberId, membershipType) ⇒ Promise

Adds new member to the group.

Kind: instance method of GroupService

Param	Type
groupId	String
memberId	String
membershipType	String

groupService.getGroup(groupId, withSubGroups) ⇒ Promise

Gets detailed information about the group.

Notice, when "withSubGroups" argument is true (default) this method returns a tree of group data objects, connected via their "subGroups" fields. getMap(..) method below wraps this functionality in a more practical way!

Kind: instance method of GroupService
Returns: Promise - On success resolves to the group data object.

Param	Type	Default	Description
groupId	String
withSubGroups	Boolean	true	Optional. Defaults to true. Specifies, whether the response should information about sub-groups, if any.

groupService.getGroupMap(groupIds) ⇒ Promise

Gets detailed information about the specified user group(s) and their descendant sub-groups.

Kind: instance method of GroupService
Returns: Promise - Resolves to the group map. That object will have group IDs as the keys, and corresponding group data objects as the values. In each group data object the "subGroups" field, if any, will be replaced by "subGroupIds" (array of IDs of the immediate child groups), and the actual data on the sub-groups will be moved to the root of the map object. It also timestamps each fetched group.

Param	Type	Description
groupIds	String | Array.<String>	Group ID, or an array of group IDs, to query from Topcoder API.

groupService.getMembers(groupId) ⇒ Promise

Gets group members.

Kind: instance method of GroupService
Returns: Promise - On sucess resolves to the array of member objects, which include user IDs, membership time, and some bookkeeping data.

Param	Type
groupId	String

groupService.getMembersCount(groupId, withSubGroups) ⇒ Promise

Gets the number of members in the group.

Kind: instance method of GroupService
Returns: Promise - Resolves to the members count.

Param	Type	Description
groupId	Number | String	ID of the group.
withSubGroups	Boolean	Optional. When this flag is set, the count will include members of sub-groups of the specified group.

services.groups~handleApiResponse(response) ⇒ Promise

Private. Handles given response from the groups API.

Kind: inner method of services.groups
Returns: Promise - On success resolves to the data fetched from the API.

Param	Type
response	Object

services.groups~mergeGroup(groups, group)

Private. Merges given user group (possibly a tree of user groups) into groups map. This function intended only for internal use inside this module, as it may mutate both arguments (hence, the corresponding ESLint rule is disabled within this function), thus should be used only where it is safe. For external use a similar function is provided by "utils/tc" module.

Kind: inner method of services.groups

Param	Type
groups	Object
group	Object