<commit_before>/**
 * This file contains the readily availbile functions which interact with the
 * ITSLanguage group API.
 */

import {authorisedRequest} from './communication';

// The URL for the group handler(s).
const url = '/groups';


/**
 * Create a new group.
 *
 * @param {Object} group - The group to create.
 *
 * @returns {Promise} - The group creation promise.
 */
export function create(group) {
  return authorisedRequest('POST', url, group);
}


/**
 * Get a single group by its ID.
 *
 * @param {string} id - The ID of the desired group.
 *
 * @returns {Promise} - The promise for the group.
 */
export function getById(id) {
  return authorisedRequest('GET', `${url}/${id}`);
}


/**
 * Get a all groups.
 *
 * By default all groups are fetched though it is allowed to pass
 * filters as a `URLSearchParams` object.
 *
 * @param {URLSearchParams} [filters] - The filters to apply to the category
 *                                      list.
 *
 * @throws {Promise.<string>} - If the given optional filters are not an
 *                              instance of `URLSearchParams`.
 *
 * @returns {Promise} - The promise for the groups.
 */
export function getAll(filters) {
  let urlWithFilters = url;

  if (filters) {
    if (!(filters instanceof URLSearchParams)) {
      return Promise.reject('The filters should be a `URLSearchParams` object.');
    }

    urlWithFilters += `?${filters.toString()}`;
  }

  return authorisedRequest('GET', urlWithFilters);
}
<commit_msg>docs: improve docs for groups<commit_after>/**
 * This file contains the readily availbile functions which interact with the
 * ITSLanguage group API.
 *
 * Users can be part of zero or multiple groups.
 *
 * @see https://itslanguage.github.io/itslanguage-docs/api/groups/index.html
 */

import {authorisedRequest} from './communication';

// The URL for the group handler(s).
const url = '/groups';


/**
 * Create a new group.
 *
 * @param {Object} group - The group to create.
 * @param {string} [group.id] - A unique identifier. If none is given, one is generated.
 * @param {Array} group.name - The name of the group.
 *
 * @returns {Promise} - The group creation promise.
 */
export function create(group) {
  return authorisedRequest('POST', url, group);
}


/**
 * Get a single group by its ID.
 *
 * @param {string} id - The ID of the desired group.
 *
 * @returns {Promise} - The promise for the group.
 */
export function getById(id) {
  return authorisedRequest('GET', `${url}/${id}`);
}


/**
 * Get a all groups.
 *
 * By default all groups are fetched though it is allowed to pass
 * filters as a `URLSearchParams` object.
 *
 * @param {URLSearchParams} [filters] - The filters to apply to the category
 *                                      list.
 *
 * @throws {Promise.<string>} - If the given optional filters are not an
 *                              instance of `URLSearchParams`.
 *
 * @returns {Promise} - The promise for the groups.
 */
export function getAll(filters) {
  let urlWithFilters = url;

  if (filters) {
    if (!(filters instanceof URLSearchParams)) {
      return Promise.reject('The filters should be a `URLSearchParams` object.');
    }

    urlWithFilters += `?${filters.toString()}`;
  }

  return authorisedRequest('GET', urlWithFilters);
}

{'fraction_non_alphanumeric': 0.12496190185918928, 'fraction_numerical': 0.0, 'mean_word_length': 2.9305389221556886, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5855277', 'n_tokens_mistral': 941, 'n_tokens_neox': 941, 'n_words': 352}