@qikdev/sdk 1.0.12 → 1.0.13

package/src/api/qik.utils.js

@@ -5,9 +5,15 @@ import { isBrowser, isNode } from "browser-or-node";
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * @name utils
- * @classdesc Utility helper functions — id, ids, hashing, parsing, cleaning, and other general-purpose helpers
+ * @classdesc General helpers that run locally: ids (id, ids, isValidID, getTypeFromID), parsing and cleaning
+ * values (parseDate, parseURL, parseEmail, parseNumber, parseInt, parseBoolean, cleanValue, isValidValue),
+ * working with arrays (hash, extractFromArray, matchInArray, comma), money (formatCurrency, currencySymbol),
+ * field lists (mapFields, getAllFields), error messages, unique ids and loading external scripts or styles.
+ * @alias utils
  * @class
+ * @example
+ * const ids = sdk.utils.ids(records); // ['61eca...', ...]
+ * const byID = sdk.utils.hash(records, '_id');
  */
 
 const service = {};
@@ -17,14 +23,13 @@ const service = {};
 const loadedExternalScripts = {};
 
 /**
- * A function that dynamically include an external javascript resource
- * ensuring that it will only be included once
+ * Adds a <script> tag for an external JavaScript file, once per URL: later calls with the same URL return the
+ * same promise. Browser only.
  * @alias utils.loadExternalScript
- * @param  {String} url The url of the external script
- * @return {Promise}    A promise that will be resolved once the script has been loaded
+ * @param {String} url The script's URL.
+ * @returns {Promise<String>} Resolves with the URL once the script has loaded. It never settles if the script fails to load.
  * @example
- *
- * await sdk.utils.loadExternalScript('https://cdn.javascript.com/external/script.js');
+ * await sdk.utils.loadExternalScript('https://cdn.example.com/library.js');
  */
 
 service.loadExternalScript = function (url) {
@@ -64,14 +69,12 @@ service.loadExternalScript = function (url) {
 const loadedExternalStyles = {};
 
 /**
- * A function that dynamically include an external css resource
- * ensuring that it will only be included once
+ * Adds a <link rel="stylesheet"> tag for an external CSS file, once per URL. Browser only.
  * @alias utils.loadExternalStyle
- * @param  {String} url The url of the external css
- * @return {Promise}    A promise that will be resolved once the css has been loaded
+ * @param {String} url The stylesheet's URL.
+ * @returns {Promise<String>} Resolves with the URL once loaded (straight away if it was added before). It never settles if the stylesheet fails to load.
  * @example
- *
- * await sdk.utils.loadExternalStyle('https://cdn.css.com/external/style.css');
+ * await sdk.utils.loadExternalStyle('https://cdn.example.com/theme.css');
  */
 service.loadExternalStyle = function (url) {
   const promise = new Promise(createNewScript);
@@ -109,16 +112,17 @@ service.loadExternalStyle = function (url) {
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * A helper function for checking whether a value is truthy/falsy
+ * Checks whether a value counts as "provided": false for undefined, null, '' and the strings 'undefined'
+ * and 'null' (in any case); true for everything else, including 0, false and empty arrays.
  * @alias utils.exists
- * @param  {Anything} value The value to check
- * @return {Boolean}  whether the value is truthy
+ * @param {*} value The value to check.
+ * @returns {Boolean} Whether the value is provided.
  * @example
- *
  * sdk.utils.exists('undefined'); // false
- * sdk.utils.exists([]); // true
  * sdk.utils.exists(''); // false
  * sdk.utils.exists(undefined); // false
+ * sdk.utils.exists([]); // true
+ * sdk.utils.exists(0); // true
  */
 service.exists = function (value) {
   var isUndefinedOrNull;
@@ -160,14 +164,13 @@ service.exists = function (value) {
 //////////////////////////////////
 
 /**
- * A helper function for getting a javascript date object from some input
- * returns undefined if it can not be parsed
+ * Converts a value to a JavaScript Date.
  * @alias utils.parseDate
- * @param  {String|Number} input The value to parse as a date
- * @return {Date}  the javascript date object
+ * @param {String|Number|Date} input An ISO string, timestamp or Date.
+ * @returns {Date|undefined} The Date, or undefined when the input is empty or not a valid date.
  * @example
- *
- * sdk.utils.parseDate(input);
+ * sdk.utils.parseDate('2026-09-29T10:00:00Z'); // Date
+ * sdk.utils.parseDate('not a date'); // undefined
  */
 service.parseDate = function (input) {
   if (!input) {
@@ -190,16 +193,18 @@ service.parseDate = function (input) {
 };
 
 /**
- * A helper function for getting a full url string from some input
+ * Turns user input into a usable link: adds http:// when no scheme is given, turns a bare email address into
+ * a mailto: link, and leaves relative paths ('/about'), '://', mailto:, tel: and sms: links as they are.
+ * Spaces are removed. Returns false when the host isn't a valid domain name or IPv4 address.
  * @alias utils.parseURL
- * @param  {String} input The input value
- * @return {String}  the fully parsed URL
+ * @param {String} string The input.
+ * @returns {String|Boolean} The link, or false when it can't be made into one.
  * @example
- *
- * sdk.utils.parseURL('google.com'); // Returns https://google.com
- * sdk.utils.parseURL('mailto:hello@qik.dev'); // Returns 'mailto:hello@qik.dev'
- * sdk.utils.parseURL('://hello.com'); // Returns '://hello.com'
- * sdk.utils.parseURL('hello@email.com'); // Returns 'mailto:hello@email.com'
+ * sdk.utils.parseURL('example.com'); // 'http://example.com'
+ * sdk.utils.parseURL('https://example.com/a?b=c'); // 'https://example.com/a?b=c'
+ * sdk.utils.parseURL('hello@example.com'); // 'mailto:hello@example.com'
+ * sdk.utils.parseURL('/about'); // '/about'
+ * sdk.utils.parseURL('not a url'); // false
  */
 service.parseURL = function (string) {
   if (!string) {
@@ -294,18 +299,16 @@ service.parseURL = function (string) {
 ///////////////////////////////////////////////
 
 /**
- * A helper function for getting a number from some input
+ * Converts a value to a number, returning 0 when it isn't numeric.
  * @alias utils.parseNumber
- * @param  {String} value The input value
- * @param  {Number} decimalPoints The number of decimal points to round to
- * @return {Number}  the parsed number value
+ * @param {String|Number} input The value.
+ * @param {Number} [decimalPoints] Round to this many decimal places.
+ * @returns {Number} The number, or 0.
  * @example
- *
- * sdk.utils.parseNumber('123'); // Returns 123
- * sdk.utils.parseNumber('75.501', 2); // Returns 75.5
- * sdk.utils.parseNumber(''); // Returns 0
- * sdk.utils.parseNumber(null); // Returns 0
- * sdk.utils.parseNumber(); // Returns 0
+ * sdk.utils.parseNumber('123'); // 123
+ * sdk.utils.parseNumber('75.501', 2); // 75.5
+ * sdk.utils.parseNumber('abc'); // 0
+ * sdk.utils.parseNumber(null); // 0
  */
 service.parseNumber = function (input, decimalPoints) {
   if (!input) {
@@ -326,15 +329,13 @@ service.parseNumber = function (input, decimalPoints) {
 };
 
 /**
- * A helper function for getting a number from some input
+ * Checks whether a string is a valid email address.
  * @alias utils.isValidEmailAddress
- * @param  {String} emailAddress The email to validate
- * @return {Boolean} whether or not the input is a valid email address
+ * @param {String} email The text to check.
+ * @returns {Boolean} Whether it is a valid email address.
  * @example
- *
- * sdk.utils.isValidEmailAddress('123.com'); // Returns false
- * sdk.utils.isValidEmailAddress('hello@world.com'); // Returns true
- * sdk.utils.isValidEmailAddress('something@special.io'); // Returns true
+ * sdk.utils.isValidEmailAddress('123.com'); // false
+ * sdk.utils.isValidEmailAddress('hello@example.com'); // true
  */
 service.isValidEmailAddress = function (email) {
   var tester =
@@ -366,14 +367,13 @@ service.isValidEmailAddress = function (email) {
 };
 
 /**
- * A helper function for getting a formatted email address
+ * Lowercases an email address and checks it's valid.
  * @alias utils.parseEmail
- * @param  {String} emailAddress The input to parse as an email
- * @return {String|Boolean} a valid email address in lowercase, or false if parse is not possible
+ * @param {String} input The text to parse.
+ * @returns {String|Boolean} The lowercased address, or false when it isn't a valid email address.
  * @example
- *
- * sdk.utils.parseEmail('ToMack@gmail.com'); // returns 'tomack@gmail.com'
- * sdk.utils.isValidEmailAddress('hello.world.com'); // Returns false
+ * sdk.utils.parseEmail('ToMack@Example.com'); // 'tomack@example.com'
+ * sdk.utils.parseEmail('hello.world.com'); // false
  */
 service.parseEmail = function (input) {
   if (!input) {
@@ -393,15 +393,14 @@ service.parseEmail = function (input) {
 //////////////////////////////////
 
 /**
- * A helper function for getting an integer
+ * Converts a value to a whole number (dropping any decimals), returning 0 when it isn't numeric.
  * @alias utils.parseInt
- * @param  {String|Number} input The input to parse as an integer
- * @return {Integer} the resulting integer or 0
+ * @param {String|Number} input The value.
+ * @returns {Number} The integer, or 0.
  * @example
- *
- * sdk.utils.parseInt('134'); // returns 134
- * sdk.utils.parseInt('cows'); // returns 0
- * sdk.utils.parseInt(); // returns 0
+ * sdk.utils.parseInt('134'); // 134
+ * sdk.utils.parseInt('12.9'); // 12
+ * sdk.utils.parseInt('cows'); // 0
  */
 service.parseInt = function (input) {
   if (!input) {
@@ -417,19 +416,20 @@ service.parseInt = function (input) {
 };
 
 /**
- * A helper function for cleaning an input value to match
- * a required type
+ * Converts a value to a field data type: 'reference' gives the id, 'boolean' reads 'yes'/'true'/'1' style
+ * strings, 'url' and 'email' are parsed as by parseURL / parseEmail, 'key' gives a camelCase key, 'date' a Date,
+ * number types a number, 'object' only accepts plain objects, 'string' a string. Other types become strings.
  * @alias utils.cleanValue
- * @param  {*} data The input to clean
- * @param  {String} type The data type to parse
- * @param  {Object} options Additional options for parsing
- * @return {*} the resulting cleaned value
+ * @param {*} data The value.
+ * @param {String} type The data type.
+ * @param {Object} [options] Options.
+ * @param {Boolean} [options.strict] Return any provided value unchanged (booleans are still converted).
+ * @returns {*} The converted value; undefined (or false, for url and email) when it can't be converted.
  * @example
- *
- * sdk.utils.cleanValue({_id:'1234', title:'Item'...}, 'reference'); // returns '1234'
- * sdk.utils.cleanValue('true', 'boolean'); // returns true
- * sdk.utils.cleanValue('Mr Rogers House', 'key'); // returns 'mrRogersHouse';
- * sdk.utils.cleanValue('Hello.World@email.COM', 'email'); // returns 'hello.world@email.com';
+ * sdk.utils.cleanValue({ _id: '61eca4746971e75c1fc670cf', title: 'Item' }, 'reference'); // '61eca4746971e75c1fc670cf'
+ * sdk.utils.cleanValue('true', 'boolean'); // true
+ * sdk.utils.cleanValue('Mr Rogers House', 'key'); // 'mrRogersHouse'
+ * sdk.utils.cleanValue('Hello.World@Example.COM', 'email'); // 'hello.world@example.com'
  */
 service.cleanValue = function (data, type, options) {
   if (!options) {
@@ -529,6 +529,20 @@ service.cleanValue = function (data, type, options) {
   }
 };
 
+/**
+ * Checks whether a value is valid for a field data type ('url', 'key', 'date', 'email', 'number', 'decimal',
+ * 'float', 'integer', 'boolean', 'reference', 'string', 'object', 'array'). Values that aren't provided (see
+ * exists) are never valid; unknown types are never valid.
+ * @alias utils.isValidValue
+ * @param {*} value The value.
+ * @param {String} dataType The data type.
+ * @param {Boolean} [strict] Require the right JavaScript type (a real number, Date, boolean or string) rather than a convertible value.
+ * @returns {Boolean} Whether the value is valid.
+ * @example
+ * sdk.utils.isValidValue('42', 'integer'); // true
+ * sdk.utils.isValidValue('42', 'integer', true); // false: not a number
+ * sdk.utils.isValidValue('yes', 'boolean'); // true
+ */
 service.isValidValue = function (value, dataType, strict) {
   var isValue = service.exists(value);
   var valueIsNumber = typeof value == "number";
@@ -649,23 +663,15 @@ service.isValidValue = function (value, dataType, strict) {
 };
 
 /**
- * A helper function for parsing input as boolean values
+ * Converts a value to true or false. 'true', 'y', 'yes', '1' and 't' (any case) are true; 'false', 'n', 'no',
+ * '0', 'f', '-1', 'null', 'undefined' and '' are false; anything else is judged by JavaScript truthiness.
  * @alias utils.parseBoolean
- * @param  {*} value The input to parse
- * @return {Boolean} the resulting true/false value
+ * @param {*} value The value.
+ * @returns {Boolean} The boolean.
  * @example
- *
- * sdk.utils.parseBoolean('true'); // returns true
- * sdk.utils.parseBoolean('y'); // returns true
- * sdk.utils.parseBoolean('YES'); // returns true
- * sdk.utils.parseBoolean('1'); // returns true
- * sdk.utils.parseBoolean('t'); // returns true
- * sdk.utils.parseBoolean(''); // returns false
- * sdk.utils.parseBoolean('0'); // returns false
- * sdk.utils.parseBoolean('n'); // returns false
- * sdk.utils.parseBoolean('no'); // returns false
- * sdk.utils.parseBoolean('f'); // returns false
- * sdk.utils.parseBoolean('null'); // returns false
+ * sdk.utils.parseBoolean('YES'); // true
+ * sdk.utils.parseBoolean('0'); // false
+ * sdk.utils.parseBoolean('no'); // false
  */
 service.parseBoolean = function (value) {
   switch (String(value).toLowerCase()) {
@@ -694,12 +700,32 @@ service.parseBoolean = function (value) {
 
 ///////////////////////////////////////////////////////////////////////////////
 
+/**
+ * Deep-copies plain data through JSON. Dates become strings, and functions and undefined values are dropped.
+ * @alias utils.clone
+ * @param {*} input JSON-safe data.
+ * @returns {*} The copy.
+ * @example
+ * const copy = sdk.utils.clone(record);
+ */
 service.clone = function (input) {
   return JSON.parse(JSON.stringify(input));
 };
 
 ///////////////////////////////////////////////////////////////////////////////
 
+/**
+ * Lists every field of a content type or definition as a flat, filterable list sorted by title: its own
+ * fields, its definition fields (under `data`, or `formData` and `data` for form submissions), and for profiles
+ * the computed '_age' and '_dob'. Each entry is a field with `path` (e.g. 'data.shirtSize'), `trail` and a `title`
+ * that includes its parent groups ('Address › City'). Single-value object groups themselves are left out.
+ * @alias utils.getAllFields
+ * @param {Object} actualDefinition A glossary entry (see sdk.content.glossary) with `fields` and optionally `definedFields`.
+ * @returns {Array<Object>} The fields.
+ * @example
+ * const { profile } = await sdk.content.glossary({ hash: true });
+ * const paths = sdk.utils.getAllFields(profile).map((field) => field.path);
+ */
 service.getAllFields = function (actualDefinition) {
   const self = this;
   const isProfile =
@@ -800,6 +826,23 @@ service.getAllFields = function (actualDefinition) {
 };
 ///////////////////////////////////////////////////////////////////////////////
 
+/**
+ * Flattens a nested field list, adding to each field its `trail` (array of keys), `path` (dot path) and
+ * `titles` (titles of the field and its parent groups). Layout-only groups (groups without asObject) are
+ * walked through but not listed themselves.
+ * @alias utils.mapFields
+ * @param {Array<Object>} fields The fields.
+ * @param {Object} [options] Options.
+ * @param {Number} [options.depth] Stop descending after this many levels.
+ * @param {Boolean} [options.includeLayout] Also list layout-only groups.
+ * @param {Boolean} [options.includeArrayDelimeter] Add '[]' after the key of multi-value groups in paths, e.g. 'items[].title'.
+ * @param {String} [options.arrayDelimeter] The marker to use instead of '[]'.
+ * @param {Boolean} [options.original] Annotate and return the original field objects instead of copies.
+ * @returns {Array<Object>} The flattened fields.
+ * @example
+ * const flat = sdk.utils.mapFields(definition.fields, { includeArrayDelimeter: true });
+ * const paths = flat.map((field) => field.path);
+ */
 service.mapFields = function (fields, options) {
   if (!options) {
     options = {};
@@ -896,13 +939,14 @@ service.mapFields = function (fields, options) {
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * A helpful function that can take a keyed object literal and map it to url query string parameters
+ * Builds a URL query string from an object. Entries whose value is undefined, null, false, 0 or '' are left
+ * out; arrays become repeated keys. No leading '?' or '&'.
  * @alias utils.mapParameters
- * @param  {Object} parameters The object you want to transalte
- * @return {String}            The query string
+ * @param {Object} parameters The values.
+ * @returns {String} The query string.
  * @example
- * //Returns &this=that&hello=world
- * sdk.utils.mapParameters({"this":"that", "hello":"world"})
+ * sdk.utils.mapParameters({ this: 'that', hello: 'world', tags: ['a', 'b'] });
+ * // 'this=that&hello=world&tags=a&tags=b'
  */
 service.mapParameters = function (parameters) {
   parameters = parameters || {};
@@ -929,19 +973,15 @@ service.mapParameters = function (parameters) {
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * A function that will take an integer and a currency string and return a formatted numeric amount rounded to 2 decimal places
+ * Formats an amount in cents as money with a currency symbol ('£' for gbp, '€' for eur, '$' for everything else).
  * @alias utils.formatCurrency
- * @param  {Integer} value The amount in cents
- * @param  {String} currency The currency to format
- * @return {String}            The formatted value
+ * @param {Number} value The amount in cents (1000 = 10.00).
+ * @param {String} [currency] Currency code, e.g. 'aud', 'gbp'.
+ * @param {Number} [decimalPoints] Decimal places, default 2.
+ * @returns {String} The formatted amount.
  * @example
- *
- * //Returns £10.00
- * sdk.utils.formatCurrency(1000, 'gbp');
- *
- * //Returns $10.00
- * sdk.utils.formatCurrency(1000, 'usd');
- *
+ * sdk.utils.formatCurrency(1000, 'gbp'); // '£10.00'
+ * sdk.utils.formatCurrency(1999, 'aud'); // '$19.99'
  */
 service.formatCurrency = function (value, currency, decimalPoints) {
   if (!value || isNaN(value)) {
@@ -955,18 +995,13 @@ service.formatCurrency = function (value, currency, decimalPoints) {
 };
 
 /**
- * A function that will take an id and return the type key
+ * Works out the base type of a record from its id (characters 9-10 of every Qik id encode the type).
  * @alias utils.getTypeFromID
- * @param  {String} id The id of an object
- * @return {String}    The key
+ * @param {String|Object} id The id, or an object with an _id.
+ * @returns {String|undefined} The type key, e.g. 'profile', or undefined for an invalid or unknown id. Organisation definitions share their base type's id prefix.
  * @example
- *
- * // Returns 'user'
- * sdk.utils.getTypeFromID('52b523f775beea960013f6cd');
- *
- * // Returns 'role'
- * sdk.utils.getTypeFromID('62b59cb572fb4772e7b5fa93');
- *
+ * sdk.utils.getTypeFromID('52b523f775beea960013f6cd'); // 'user'
+ * sdk.utils.getTypeFromID('62b59cb572fb4772e7b5fa93'); // 'role'
  */
 service.getTypeFromID = function (id) {
   id = service.id(id);
@@ -1038,18 +1073,13 @@ service.getTypeFromID = function (id) {
 };
 
 /**
- * A function that will take a currency string and return the symbol
+ * Returns the symbol for a currency code: '£' for gbp, '€' for eur, '$' for anything else.
  * @alias utils.currencySymbol
- * @param  {String} currency The currency
- * @return {String}            The symbol
+ * @param {String} currency The currency code (any case).
+ * @returns {String} The symbol.
  * @example
- *
- * //Returns £
- * sdk.utils.currencySymbol('gbp');
- *
- * //Returns $
- * sdk.utils.currencySymbol('usd');
- *
+ * sdk.utils.currencySymbol('gbp'); // '£'
+ * sdk.utils.currencySymbol('usd'); // '$'
  */
 const CURRENCY_SYMBOLS = { gbp: "\u00A3", eur: "\u20AC" };
 
@@ -1066,6 +1096,15 @@ const SUPPORTED_CURRENCIES = [
   { code: "sgd", countries: ["SG"] },
 ];
 
+/**
+ * Lists the currencies Qik supports (usd, gbp, cad, aud, nzd, sgd) as picker options, optionally with the one
+ * for a country first.
+ * @alias utils.getAvailableCurrencies
+ * @param {String} [defaultCountryID] A two-letter country code (e.g. 'AU') whose currency should come first.
+ * @returns {Array<Object>} Options { name, value, countryCode }, e.g. { name: 'AUD ($)', value: 'aud', countryCode: { AU: true } }.
+ * @example
+ * const currencies = sdk.utils.getAvailableCurrencies('AU'); // AUD first
+ */
 service.getAvailableCurrencies = function (defaultCountryID) {
   let currencies = SUPPORTED_CURRENCIES.map(({ code, countries }) => ({
     name: `${code.toUpperCase()} (${service.currencySymbol(code)})`,
@@ -1087,15 +1126,17 @@ service.getAvailableCurrencies = function (defaultCountryID) {
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * Creates a fast keyed hash object from an array of items
+ * Turns an array into an object for quick lookups, keyed by a property of each item (later items win when keys
+ * repeat). Without a key the items themselves are the keys, e.g. for a set of ids.
  * @alias utils.hash
- * @param  {Array} array The array of items to convert into a hash
- * @param  {String} key The key or path to the property on each item to use as the hashed key
- * @return {Object} A key/value paired object
+ * @param {Array} items The items. Anything that isn't an array is treated as empty.
+ * @param {String} [key] The property (or dot path) to key by.
+ * @returns {Object} The lookup.
  * @example
- * //Returns { jimbo:{id:'jimbo', title:'Jim Jones'}, {id:'roger', title:'Roger Fellow'} }
- * sdk.utils.hash([{id:'jimbo', title:'Jim Jones'}, {id:'roger', title:'Roger Fellow'}], 'id');
+ * sdk.utils.hash([{ id: 'jim', title: 'Jim Jones' }, { id: 'roger', title: 'Roger Fellow' }], 'id');
+ * // { jim: { id: 'jim', title: 'Jim Jones' }, roger: { id: 'roger', title: 'Roger Fellow' } }
  *
+ * sdk.utils.hash(['a', 'b']); // { a: 'a', b: 'b' }
  */
 service.hash = function (items, key) {
   items = !Array.isArray(items) ? [] : items;
@@ -1109,23 +1150,20 @@ service.hash = function (items, key) {
 //////////////////////////////////////////////////
 
 /**
- * Returns a subset of values in an array that match a provided rule
+ * Pulls one property (dot path) out of every item of an array, optionally flattening, de-duplicating,
+ * dropping empty values or adding them up.
  * @alias utils.extractFromArray
- * @param  {Array} array The array you want to extract values from
- * @param  {String} key The path to the child property you want to extract
- * @param  {Boolean} sum Whether to sum the extracted values together in total
- * @param  {Boolean} flatten Whether to flatten nested child arrays
- * @param  {Boolean} unique Whether to only return unique values
- * @param  {Boolean} exclude Whether to exclude null or undefined values
- * @param  {Object} options Pass through extra options for how to extract the values
- * @return {Array} An array of all values retrieved from the array, unless provided arguments require otherwise
+ * @param {Array} array The items.
+ * @param {String} key The property or dot path to read from each item.
+ * @param {Boolean} [sum] Add the values together and return the total.
+ * @param {Boolean} [flatten] Flatten values that are arrays.
+ * @param {Boolean} [unique] Remove duplicate values.
+ * @param {Boolean} [exclude] Drop null, undefined and other empty values (0 and false are kept).
+ * @param {Object} [options] The same settings as an object: { sum, flatten, unique, excludeNull }.
+ * @returns {Array|Number} The values, or their total when summing.
  * @example
- * //Returns [12, 45] as all the values
- * sdk.utils.extractFromArray([{name:'Wendy', age:12}, {name:'Roger', age:45}], 'age');
- *
- * //Returns 32
- * sdk.utils.extractFromArray([{name:'Wendy', age:12}, {name:'Roger', age:20}], 'age', {sum:true});
- *
+ * sdk.utils.extractFromArray([{ name: 'Wendy', age: 12 }, { name: 'Roger', age: 45 }], 'age'); // [12, 45]
+ * sdk.utils.extractFromArray([{ name: 'Wendy', age: 12 }, { name: 'Roger', age: 20 }], 'age', true); // 32
  */
 service.extractFromArray = function (
   array,
@@ -1191,18 +1229,17 @@ service.extractFromArray = function (
 //////////////////////////////////////////////////////
 
 /**
- * A function that can return a selection of values that were found in an array that match a specific rule,
- * This is often used to evaluate expressions within form fields
+ * Returns the items of an array whose property (dot path) matches a value, for example when evaluating
+ * form field conditions.
  * @alias utils.matchInArray
- * @param  {Array} array The array to check
- * @param  {String} key The javascript dot notation path to extract
- * @param  {String} value The value to compare against
- * @param  {String} comparator The logical operator to use to compare the extracted value with the provided value ('>', '<', '>=', '<=', 'in', '==') Defaults to '==' (Is equal to)
- * @return {Array} Returns an array of matching values
+ * @param {Array} array The items.
+ * @param {String} key The property or dot path to compare.
+ * @param {*} v The value to compare with. With the default comparator and no value, items whose property is truthy match.
+ * @param {String} [comparator] '==' (default, loose equality), '>', '<', '>=', '<=', or 'in' (the property, an array or string, includes the value).
+ * @returns {Array} The matching items.
  * @example
- * //Returns [{name:'Michael', age:45}] as that is only item in the array that matches the criteria
- * sdk.utils.matchInArray([{name:'Wendy', age:12}, {name:'Michael', age:45}], 'age', 45, '>=');
- *
+ * sdk.utils.matchInArray([{ name: 'Wendy', age: 12 }, { name: 'Michael', age: 45 }], 'age', 45, '>=');
+ * // [{ name: 'Michael', age: 45 }]
  */
 service.matchInArray = function (array, key, v, comparator) {
   //Filter the array options by a certain v and comparator
@@ -1246,18 +1283,16 @@ service.matchInArray = function (array, key, v, comparator) {
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * A helpful class that can take an array of values and return them as a comma seperated
- * string, If the values are objects, then a property to use as the string representation can be specified
+ * Joins values into a comma-separated string, skipping null, undefined and empty strings. For objects, give a
+ * property to use.
  * @alias utils.comma
- * @param  {Array} array The array of values to translate
- * @param  {String} path  An optional property key to use for each value
- * @return {String}       The resulting comma seperated string
+ * @param {Array} array The values.
+ * @param {String} [path] The property (dot path) to use for each value.
+ * @param {Number} [limit] Only use the first this many values.
+ * @returns {String} e.g. 'cat, dog, bird'.
  * @example
- * //Returns 'cat, dog, bird'
- * sdk.utils.comma(['cat', 'dog', 'bird']);
- *
- * //Returns 'cat, dog, bird'
- * sdk.utils.comma([{title:'cat'}, {title:'dog'}, {title:'bird'}], 'title');
+ * sdk.utils.comma(['cat', 'dog', 'bird']); // 'cat, dog, bird'
+ * sdk.utils.comma([{ title: 'cat' }, { title: 'dog' }], 'title'); // 'cat, dog'
  */
 service.comma = function (array, path, limit) {
   if (limit) {
@@ -1283,22 +1318,14 @@ service.comma = function (array, path, limit) {
 //Helper function to get an id of an object
 
 /**
- * Returns a specified _id for an object
+ * Gets a record id from either an id string or an object with an _id, and checks it's a valid 24-character id.
  * @alias utils.id
- * @param  {Object} input      An object that is or has an _id property
- * @param  {Boolean} asObjectID Whether to convert to a Mongo ObjectId
- * @return {String}            Will return either a string or a Mongo ObjectId
- *
+ * @param {String|Object} source An id, or an object with an _id.
+ * @returns {String|undefined} The id, or undefined when there isn't a valid one.
  * @example
- *
- * //Returns '5cb3d8b3a2219970e6f86927'
- * sdk.utils.id('5cb3d8b3a2219970e6f86927')
- *
- * //Returns true
- * typeof service.id({_id:'5cb3d8b3a2219970e6f86927', title, ...}) == 'string';
-
- * //Returns true
- * typeof service.id({_id:'5cb3d8b3a2219970e6f86927'}, true) == 'object';
+ * sdk.utils.id('5cb3d8b3a2219970e6f86927'); // '5cb3d8b3a2219970e6f86927'
+ * sdk.utils.id({ _id: '5cb3d8b3a2219970e6f86927', title: 'Item' }); // '5cb3d8b3a2219970e6f86927'
+ * sdk.utils.id('not an id'); // undefined
  */
 service.id = function (source) {
   if (!source) {
@@ -1326,15 +1353,13 @@ service.id = function (source) {
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * Cleans and maps an array of objects to an array of IDs
+ * Maps an array of ids and/or objects with an _id to a list of unique valid ids; invalid and empty entries are dropped.
  * @alias utils.ids
- * @param  {Array} array      An array of objects or object ids
- * @param  {Boolean} asObjectID Whether or not to map the ids as Mongo ObjectIds
- * @return {Array}            An array of Ids
- *
+ * @param {Array} array Ids and/or objects with an _id.
+ * @returns {Array<String>} The unique ids (an empty array for no input).
  * @example
- * //Returns ['5cb3d8b3a2219970e6f86927', '5cb3d8b3a2219970e6f86927', '5cb3d8b3a2219970e6f86927']
- * sdk.utils.ids([{_id:'5cb3d8b3a2219970e6f86927'}, {_id:'5cb3d8b3a2219970e6f86927'}, null, '5cb3d8b3a2219970e6f86927'])
+ * sdk.utils.ids([{ _id: '5cb3d8b3a2219970e6f86927' }, null, '5cb3d8b3a2219970e6f86927', '5cb3d8b3a2219970e6f86928']);
+ * // ['5cb3d8b3a2219970e6f86927', '5cb3d8b3a2219970e6f86928']
  */
 
 service.ids = function (array) {
@@ -1367,6 +1392,15 @@ service.ids = function (array) {
 
 ///////////////////////////////////////////////////////////////////////////////
 
+/**
+ * Checks whether a value is a 24-character hexadecimal record id.
+ * @alias utils.isValidID
+ * @param {*} input The value.
+ * @returns {Boolean} Whether it's a valid id.
+ * @example
+ * sdk.utils.isValidID('5cb3d8b3a2219970e6f86927'); // true
+ * sdk.utils.isValidID('hello'); // false
+ */
 service.isValidID = function (input) {
   var checkForHexRegExp = new RegExp("^[0-9a-fA-F]{24}$");
   return checkForHexRegExp.test(String(input));
@@ -1375,10 +1409,17 @@ service.isValidID = function (input) {
 ///////////////////////////////////////////////////////////////////////////////
 
 /**
- * Helper function for retrieving a human readable error message from server error response objects
+ * Gets a readable message from an error, such as a failed sdk.api request: the server's message when there is
+ * one, otherwise the error's own message, otherwise the error as JSON.
  * @alias utils.errorMessage
- * @param  {Object} error The error object to translate
- * @return {String}     The resulting human readable error message
+ * @param {Object|Array} err The error (for an array, its first entry).
+ * @returns {String|undefined} The message, or undefined when no error is given.
+ * @example
+ * try {
+ *     await sdk.content.get(id);
+ * } catch (err) {
+ *     alert(sdk.utils.errorMessage(err));
+ * }
  */
 service.errorMessage = function (err) {
   if (!err) {
@@ -1406,12 +1447,11 @@ service.errorMessage = function (err) {
 ////////////////////////////////////
 
 /**
- * Generates a globally unique ID, helpful for adding unique keys for iterable loops
+ * Generates a random unique id (a UUID), e.g. for keys in rendered lists.
  * @alias utils.guid
- * @return {String}            The new globally unique identifier
+ * @returns {String} e.g. '3b241101-e2bb-4255-8caf-4136c566a962'.
  * @example
- * //Returns 4323a78br-z16h-289j-zwl1-938lda334asd
- * sdk.utils.guid()
+ * const key = sdk.utils.guid();
  */
 service.guid = function () {
   if (typeof crypto !== "undefined" && crypto.randomUUID) {
@@ -1429,10 +1469,13 @@ service.guid = function () {
 ////////////////////////////////////
 
 /**
- * Helper function for cleaning strings to use as database ids
+ * Turns text into a key: non-alphanumeric characters become word breaks and each part between underscores is
+ * camelCased.
  * @alias utils.machineName
- * @param  {String} string The string to clean eg. (Awesome Event!)
- * @return {String}     A cleaned and formatted string eg. (awesomeEvent)
+ * @param {String} string The text, e.g. 'Awesome Event!'.
+ * @returns {String|undefined} The key, e.g. 'awesomeEvent'; undefined for empty input.
+ * @example
+ * sdk.utils.machineName('Awesome Event!'); // 'awesomeEvent'
  */
 service.machineName = function (string) {
   if (!string || !string.length) {
@@ -1458,16 +1501,18 @@ export default service;
 /**
  * A lightweight event emitter that can be attached to any service object
  * to provide pub/sub event capabilities. Can be called with or without `new`.
+ * dispatch(event, ...details) passes every argument after the event name on to each listener.
  */
 export function EventDispatcher() {
   const handlers = new Map();
 
   const emitter = {
-    dispatch(event, details) {
+    dispatch(event, ...details) {
       const fns = handlers.get(event);
       if (fns) {
         for (const fn of fns) {
-          fn(details);
+          // Every argument after the event name is passed on to the listener
+          fn(...details);
         }
       }
     },