@qikdev/sdk 1.0.10 → 1.0.13

package/src/api/qik.filter.js

@@ -1,7 +1,13 @@
 /**
- * @name filter
- * @classdesc Provides functions helpful for interacting with the filtering system
+ * @classdesc Helpers for filter configurations — the { operator, filters } objects used as the `filter` of
+ * sdk.content.list. A filter group is { operator: 'and' | 'or' | 'nor', filters: [...] }, where each entry is
+ * either a nested group or a condition { key, comparator, value, value2, values }. These helpers work out which
+ * conditions are "active" (complete enough to apply), e.g. to show a count of applied filters or to know when
+ * a filter has changed. They run locally.
+ * @alias filter
  * @class
+ * @example
+ * const count = sdk.filter.activeFilters(filter).filter((entry) => !entry.operator).length;
  */
 
 
@@ -40,7 +46,20 @@ function compactFunction(val) {
 
 ///////////////////////
 
+/**
+ * @description Normalises a filter key: drops anything after a '|' and a leading '.'.
+ * @alias filter.cleanKey
+ * @param {String} key The key.
+ * @returns {String} The cleaned key ('' when the key is missing).
+ * @example
+ * sdk.filter.cleanKey('.data.colour|label'); // 'data.colour'
+ */
 service.cleanKey = function(key) {
+    // A missing key is empty, not the text 'undefined' or 'null'
+    if (key === undefined || key === null) {
+        return '';
+    }
+
     key = String(key).split('|')[0];
 
     if (key[0] == '.') {
@@ -53,16 +72,18 @@ service.cleanKey = function(key) {
 ///////////////////////
 
 /**
- * @description Check if an object is a valid filter
+ * @description Checks whether a filter condition or group is complete enough to apply. A condition needs a key and
+ * either a value, a value2 or a non-empty values array — except comparators that need no value ('empty',
+ * 'notempty', 'datetoday', 'datenottoday', 'datebeforetoday', 'dateaftertoday', 'dateweektoday', 'datemonthtoday',
+ * 'datebeforenow', 'dateafternow', 'datethisweek', 'datethismonth'). A group is valid when at least one of its entries is.
+ * The comparator name itself isn't checked.
  * @alias filter.isValidFilter
- * @param  {Object} filter The filter block to check
+ * @param {Object} filter A condition { key, comparator, value, value2, values } or a group { operator, filters }.
+ * @returns {Boolean} True when it can be applied (a truthy number for a condition that only has `values`).
  * @example
- * // Missing a 'key'
- * const invalidFilter = sdk.filter.isValidFilter({comparator:'in', values:['Red', 'Green', 'Blue']})
- * // returns false
- * 
- * const validFilter = sdk.filter.isValidFilter({key:'favoriteColor', comparator:'in', values:['Red', 'Green', 'Blue']})
- * // returns true
+ * sdk.filter.isValidFilter({ key: 'data.colour', comparator: 'in', values: [] }); // falsy: nothing to compare with
+ * sdk.filter.isValidFilter({ key: 'data.colour', comparator: 'in', values: ['Red', 'Green'] }); // truthy
+ * sdk.filter.isValidFilter({ key: 'data.notes', comparator: 'empty' }); // true
  */
 service.isValidFilter = function(filter) {
     if (!filter) {
@@ -185,51 +206,30 @@ service.isValidFilter = function(filter) {
 ////////////////////////////////////////////////
 
 /**
- * 
- * @description Returns an array of all active filters
+ * @description Collects every valid (active) entry in a filter configuration, walking nested groups. Valid groups are
+ * included as well as valid conditions, so filter out entries with an `operator` to get just the conditions.
  * @alias filter.activeFilters
- * @param  {Object} filterConfiguration A filter configuration object
+ * @param {Object} filterConfiguration A filter group { operator, filters }.
+ * @returns {Array<Object>} The valid groups and conditions, outermost first.
  * @example
- * 
- * const filterConfiguration =  {
- *     "operator": "and",
- *     "filters": [
- *       {
- *         "operator": "and",
- *         "filters": [
- *           {
- *             "key": "formData.person.firstName",
- *             "comparator": "startswith",
- *             "value": "c"
- *           },
- *           {
- *             "key": "invalid no comparator",
- *             "value": "e"
- *           }
- *           {
- *             "key": "formData.person.lastName",
- *             "comparator": "endswith",
- *             "value": "e"
- *           }
- *         ]
- *       }
- *     ]
- *   }
+ * const filterConfiguration = {
+ *     operator: 'and',
+ *     filters: [
+ *         {
+ *             operator: 'or',
+ *             filters: [
+ *                 { key: 'formData.person.firstName', comparator: 'startswith', value: 'c' },
+ *                 { key: 'formData.person.lastName', comparator: 'endswith' }, // no value, so not active
+ *                 { key: 'formData.person.lastName', comparator: 'endswith', value: 'e' },
+ *             ],
+ *         },
+ *     ],
+ * };
  *
- * const activeFilters = sdk.filter.activeFilters(filterConfiguration);
- * 
- * const returns = [
- *           {
- *             "key": "formData.person.firstName",
- *             "comparator": "startswith",
- *             "value": "c"
- *           }, 
- *           {
- *             "key": "formData.person.lastName",
- *             "comparator": "endswith",
- *             "value": "e"
- *           }]
- * 
+ * sdk.filter.activeFilters(filterConfiguration);
+ * // [outer group, inner group,
+ * //  { key: 'formData.person.firstName', comparator: 'startswith', value: 'c' },
+ * //  { key: 'formData.person.lastName', comparator: 'endswith', value: 'e' }]
  */
 service.activeFilters = function(filterConfiguration) {
     var memo = [];
@@ -263,40 +263,30 @@ service.activeFilters = function(filterConfiguration) {
 
 
 /**
- * 
- * @description Returns an array of all keys that are being actively filtered on
+ * @description Lists the distinct field keys used by active conditions. Anything after a '|' in a key and a leading '.'
+ * are removed, and so are '[]' array markers unless options.trimArrayDelimeters is false.
  * @alias filter.activeFilterKeys
- * @param  {Object} filterConfiguration A filter configuration object
+ * @param {Object} filterConfiguration A filter group { operator, filters }.
+ * @param {Object} [options] Options.
+ * @param {Boolean} [options.trimArrayDelimeters] Set to false to keep '[]' in keys such as 'items[].title'.
+ * @returns {Array<String>} The keys.
  * @example
- * 
- * const filterConfiguration =  {
- *     "operator": "and",
- *     "filters": [
- *       {
- *         "operator": "and",
- *         "filters": [
- *           {
- *             "key": "formData.person.firstName",
- *             "comparator": "startswith",
- *             "value": "c"
- *           },
- *           {
- *             "key": "invalid no comparator",
- *             "value": "e"
- *           }
- *           {
- *             "key": "formData.person.lastName",
- *             "comparator": "endswith",
- *             "value": "e"
- *           }
- *         ]
- *       }
- *     ]
- *   }
+ * const filterConfiguration = {
+ *     operator: 'and',
+ *     filters: [
+ *         {
+ *             operator: 'or',
+ *             filters: [
+ *                 { key: 'formData.person.firstName', comparator: 'startswith', value: 'c' },
+ *                 { key: 'formData.person.lastName', comparator: 'endswith' }, // no value, so not active
+ *                 { key: 'formData.person.lastName', comparator: 'endswith', value: 'e' },
+ *             ],
+ *         },
+ *     ],
+ * };
  *
- * const activeFilters = sdk.filter.activeFilterKeys(filterConfiguration);
- * // Returns ['formData.person.firstName', 'formData.person.lastName']
- * 
+ * sdk.filter.activeFilterKeys(filterConfiguration);
+ * // ['formData.person.firstName', 'formData.person.lastName']
  */
 service.activeFilterKeys = function(filterConfiguration, options) {
     options = options || {}
@@ -323,40 +313,27 @@ service.activeFilterKeys = function(filterConfiguration, options) {
 
 
 /**
- * 
- * @description Returns an array of all comparators that are being actively filtered
+ * @description Lists the distinct comparators used by active conditions.
  * @alias filter.activeFilterComparators
- * @param  {Object} filterConfiguration A filter configuration object
+ * @param {Object} filterConfiguration A filter group { operator, filters }.
+ * @returns {Array<String>} The comparator names.
  * @example
- * 
- * const filterConfiguration =  {
- *     "operator": "and",
- *     "filters": [
- *       {
- *         "operator": "and",
- *         "filters": [
- *           {
- *             "key": "formData.person.firstName",
- *             "comparator": "startswith",
- *             "value": "c"
- *           },
- *           {
- *             "key": "invalid no comparator",
- *             "value": "e"
- *           }
- *           {
- *             "key": "formData.person.lastName",
- *             "comparator": "endswith",
- *             "value": "e"
- *           }
- *         ]
- *       }
- *     ]
- *   }
+ * const filterConfiguration = {
+ *     operator: 'and',
+ *     filters: [
+ *         {
+ *             operator: 'or',
+ *             filters: [
+ *                 { key: 'formData.person.firstName', comparator: 'startswith', value: 'c' },
+ *                 { key: 'formData.person.lastName', comparator: 'endswith' }, // no value, so not active
+ *                 { key: 'formData.person.lastName', comparator: 'endswith', value: 'e' },
+ *             ],
+ *         },
+ *     ],
+ * };
  *
- * const activeFilters = sdk.filter.activeFilterKeys(filterConfiguration);
- * // Returns ['startswith', 'endswith']
- * 
+ * sdk.filter.activeFilterComparators(filterConfiguration);
+ * // ['startswith', 'endswith']
  */
 service.activeFilterComparators = function(filterConfiguration) {
     var comparators = service.activeFilters(filterConfiguration)
@@ -373,40 +350,27 @@ service.activeFilterComparators = function(filterConfiguration) {
 }
 
 /**
- * 
- * @description Returns an array of all comparators that are being actively filtered
+ * @description Lists the distinct operators ('and', 'or', 'nor') of the groups that contain at least one active condition.
  * @alias filter.activeFilterOperators
- * @param  {Object} filterConfiguration A filter configuration object
+ * @param {Object} filterConfiguration A filter group { operator, filters }.
+ * @returns {Array<String>} The operators.
  * @example
- * 
- * const filterConfiguration =  {
- *     "operator": "and",
- *     "filters": [
- *       {
- *         "operator": "nor",
- *         "filters": [
- *           {
- *             "key": "formData.person.firstName",
- *             "comparator": "startswith",
- *             "value": "c"
- *           },
- *           {
- *             "key": "invalid no comparator",
- *             "value": "e"
- *           }
- *           {
- *             "key": "formData.person.lastName",
- *             "comparator": "endswith",
- *             "value": "e"
- *           }
- *         ]
- *       }
- *     ]
- *   }
+ * const filterConfiguration = {
+ *     operator: 'and',
+ *     filters: [
+ *         {
+ *             operator: 'or',
+ *             filters: [
+ *                 { key: 'formData.person.firstName', comparator: 'startswith', value: 'c' },
+ *                 { key: 'formData.person.lastName', comparator: 'endswith' }, // no value, so not active
+ *                 { key: 'formData.person.lastName', comparator: 'endswith', value: 'e' },
+ *             ],
+ *         },
+ *     ],
+ * };
  *
- * const activeFilterOperators = sdk.filter.activeFilterOperators(filterConfiguration);
- * // Returns ['and', 'nor']
- * 
+ * sdk.filter.activeFilterOperators(filterConfiguration);
+ * // ['and', 'or']
  */
 service.activeFilterOperators = function(filterConfiguration) {
     var operators = service.activeFilters(filterConfiguration)
@@ -423,40 +387,29 @@ service.activeFilterOperators = function(filterConfiguration) {
 
 
 /**
- * 
- * @description Returns an array of all values that are being actively used by a filter
+ * @description Lists the values used by active conditions (value, value2 and every entry of values). Object values are
+ * reduced to their _id, id, title or name. Empty values are dropped; duplicates are kept.
  * @alias filter.activeFilterValues
- * @param  {Object} filterConfiguration A filter configuration object
+ * @param {Object} filterConfiguration A filter group { operator, filters }.
+ * @param {Object} [options] Not used; accepted for compatibility.
+ * @returns {Array<*>} The values.
  * @example
- * 
- * const filterConfiguration =  {
- *     "operator": "and",
- *     "filters": [
- *       {
- *         "operator": "nor",
- *         "filters": [
- *           {
- *             "key": "formData.person.firstName",
- *             "comparator": "startswith",
- *             "value": "c"
- *           },
- *           {
- *             "key": "invalid no comparator",
- *             "value": "e"
- *           }
- *           {
- *             "key": "formData.person.lastName",
- *             "comparator": "endswith",
- *             "value": "a"
- *           }
- *         ]
- *       }
- *     ]
- *   }
+ * const filterConfiguration = {
+ *     operator: 'and',
+ *     filters: [
+ *         {
+ *             operator: 'or',
+ *             filters: [
+ *                 { key: 'formData.person.firstName', comparator: 'startswith', value: 'c' },
+ *                 { key: 'formData.person.lastName', comparator: 'endswith' }, // no value, so not active
+ *                 { key: 'formData.person.lastName', comparator: 'endswith', value: 'e' },
+ *             ],
+ *         },
+ *     ],
+ * };
  *
- * const activeFilterValues = sdk.filter.activeFilterValues(filterConfiguration);
- * // Returns ['c', 'a']
- * 
+ * sdk.filter.activeFilterValues(filterConfiguration);
+ * // ['c', 'e']
  */
 service.activeFilterValues = function(filterConfiguration, options) {
 
@@ -490,40 +443,28 @@ service.activeFilterValues = function(filterConfiguration, options) {
 
 
 /**
- * 
- * @description Returns an string representation of a filter configuration. 
- * Often used to check if a user has changed the filter in any way, the string only takes into consideration active valid filters
+ * @description Turns the active parts of a filter configuration into a string, so you can tell whether the filter
+ * that would actually be applied has changed (incomplete conditions don't affect it).
  * @alias filter.filterChangeString
- * @param  {Object} filterConfiguration A filter configuration object
+ * @param {Object} config A filter group { operator, filters }.
+ * @returns {String} A JSON string of the active entries.
  * @example
- * 
- * const filterConfiguration =  {
- *     "operator": "and",
- *     "filters": [
- *       {
- *         "operator": "nor",
- *         "filters": [
- *           {
- *             "key": "formData.person.firstName",
- *             "comparator": "startswith",
- *             "value": "c"
- *           },
- *           {
- *             "key": "invalid no comparator",
- *             "value": "e"
- *           }
- *           {
- *             "key": "formData.person.lastName",
- *             "comparator": "endswith",
- *             "value": "a"
- *           }
- *         ]
- *       }
- *     ]
- *   }
+ * const filterConfiguration = {
+ *     operator: 'and',
+ *     filters: [
+ *         {
+ *             operator: 'or',
+ *             filters: [
+ *                 { key: 'formData.person.firstName', comparator: 'startswith', value: 'c' },
+ *                 { key: 'formData.person.lastName', comparator: 'endswith' }, // no value, so not active
+ *                 { key: 'formData.person.lastName', comparator: 'endswith', value: 'e' },
+ *             ],
+ *         },
+ *     ],
+ * };
  *
- * // Watch this string for changes
- * const changeString = sdk.filter.filterChangeString(filterConfiguration); 
+ * // Re-run the list only when the effective filter changes
+ * const changeString = sdk.filter.filterChangeString(filterConfiguration);
  */
 service.filterChangeString = function(config) {
 

package/src/api/qik.geo.js

@@ -1,8 +1,9 @@
 ///////////////////////////////////////////////////
 
 /**
- * Creates a new QikGeo instance.
- * This module provides a number of geolocation features and functions
+ * Location helpers: the device's position (browser geolocation, which asks the user's permission), the
+ * distance between two points, and the organisation's default timezone and country, plus lists of
+ * countries and timezones.
  * @alias geo
  * @constructor
  * @hideconstructor
@@ -31,18 +32,18 @@ export default function(qik) {
     }
 
     /**
-     * 
-     * Get the distance between two geo location points
+     * Calculates the straight-line (great-circle) distance between two points, in metres.
      * @alias geo.distance
-     * @param  {Object} positionOne The first position
-     * @param  {Number} positionOne.lat The first positions latitude
-     * @param  {Number} positionOne.lon The first positions longitude
-     * @param  {Object} positionTwo The second position
-     * @param  {Number} positionTwo.lat The second positions latitude
-     * @param  {Number} positionTwo.lon The second positions longitude
+     * @param {Object} positionOne The first point.
+     * @param {Number} positionOne.lat Latitude in degrees.
+     * @param {Number} positionOne.lon Longitude in degrees.
+     * @param {Object} positionTwo The second point.
+     * @param {Number} positionTwo.lat Latitude in degrees.
+     * @param {Number} positionTwo.lon Longitude in degrees.
+     * @returns {Number} The distance in metres.
      * @example
-     * const meters = await sdk.geo.distance({lat, lon}, {lat, lon})
-     * // Returns 634
+     * const metres = sdk.geo.distance({ lat: -37.8136, lon: 144.9631 }, { lat: -33.8688, lon: 151.2093 });
+     * // about 713000
      */
     service.distance = function({ lat: lat1, lon: lon1 }, { lat: lat2, lon: lon2 }) {
         function deg2rad(deg) {
@@ -62,13 +63,12 @@ export default function(qik) {
     }
 
     /**
-     * 
-     * Start watching the user's geolocation
+     * Asks the browser for the device's current position once (the user may be prompted for permission).
      * @alias geo.getPosition
-     * @param  {Function} callback A function that will be called with updated position data
+     * @returns {Promise<Object>} A GeolocationPosition: { coords: { latitude, longitude, accuracy, altitude, ... }, timestamp }. Rejects with { message: 'Geolocation is not enabled' } outside a browser or without geolocation, or with the browser's error if the user refuses.
      * @example
-     * const position = await sdk.geo.getPosition()
-     * // Returns {coords:{latitude, longitude, altitude, accuracy, ...}}
+     * const { coords } = await sdk.geo.getPosition();
+     * console.log(coords.latitude, coords.longitude);
      */
     service.getPosition = async function() {
 
@@ -83,13 +83,14 @@ export default function(qik) {
     }
 
     /**
-     * 
-     * Start watching the user's geolocation
+     * Starts watching the device's position; the callback runs every time it changes.
      * @alias geo.watchPosition
-     * @param  {Function} callback A function that will be called with updated position data
+     * @param {Function} positionDataReceived Called with a GeolocationPosition ({ coords, timestamp }) on every update.
+     * @returns {Promise<Object>} { id }: the watch id, needed to stop watching. Rejects with { message: 'Geolocation is not enabled' } when geolocation isn't available.
      * @example
-     * const result = await sdk.geo.watchPosition(callback)
-     * // Returns {id:<watcherID>}
+     * const { id } = await sdk.geo.watchPosition((position) => {
+     *     console.log(position.coords.latitude, position.coords.longitude);
+     * });
      */
     service.watchPosition = async function(positionDataReceived) {
 
@@ -107,13 +108,14 @@ export default function(qik) {
     }
 
     /**
-     * 
-     * Start watching the user's geolocation
+     * Stops a watch started with watchPosition.
      * @alias geo.stopWatchPosition
-     * @param  {String} watchID the id of the watcher to stop
+     * @param {Number} watchID The id returned by watchPosition (its `id`).
+     * @returns {Promise<Boolean>} true. Rejects with { message: 'Geolocation is not enabled' } when geolocation isn't available.
      * @example
-     * const result = await sdk.geo.stopWatchPosition(watchID)
-     * // Returns true after the watcher has been stopped
+     * const { id } = await sdk.geo.watchPosition(onPosition);
+     * // later
+     * await sdk.geo.stopWatchPosition(id);
      */
     service.stopWatchPosition = async function(watchID) {
         if (!isEnabled()) {
@@ -121,7 +123,7 @@ export default function(qik) {
         }
 
         console.log('qik:geo: watch stopped');
-        navigator.geolocation.clearWatch(this.watchID);
+        navigator.geolocation.clearWatch(watchID);
         return true;
     }
 
@@ -129,18 +131,17 @@ export default function(qik) {
     ///////////////////////////////////////////////////
 
     /**
-     * 
-     * Retrieves the default timezone for the current user/application
-     * will attempt to retrieve an accurate timezone either from the user's organisation or available services within the browser
+     * Returns the timezone to use by default: the signed-in user's organisation timezone, otherwise the
+     * browser's (also used when signed out).
      * @alias geo.getDefaultTimezone
+     * @returns {String|undefined} An IANA timezone name such as 'Australia/Melbourne', or undefined outside a browser with no organisation timezone.
      * @example
-     * const result = sdk.geo.getDefaultTimezone()
-     * // Would return something similar to:
-     * // Australia/Melbourne
+     * const timezone = sdk.geo.getDefaultTimezone(); // 'Australia/Melbourne'
      */
     service.getDefaultTimezone = function() {
 
-        const {session:currentUser} = qik.auth.getCurrentUser();
+        // getCurrentUser() is null when signed out
+        const currentUser = qik.auth.getCurrentUser()?.session;
 
         if(currentUser) {
             const defaultUserTimezone = currentUser?.organisation?.timezone;
@@ -161,6 +162,12 @@ export default function(qik) {
 
     ///////////////////////////////////////////////////
 
+    /**
+     * Country names keyed by two-letter ISO code, e.g. countryLookup.AU === 'Australia'.
+     * @alias geo.countryLookup
+     * @example
+     * const name = sdk.geo.countryLookup['NZ']; // 'New Zealand'
+     */
     service.countryLookup = {
         "AC": "Ascension Island",
         "AD": "Andorra",
@@ -424,8 +431,20 @@ export default function(qik) {
         "ZW": "Zimbabwe"
     }
 
+    /**
+     * Every country name from countryLookup, as an array.
+     * @alias geo.countryNames
+     * @example
+     * const names = sdk.geo.countryNames; // ['Ascension Island', 'Andorra', ...]
+     */
     service.countryNames = Object.values(service.countryLookup);
 
+    /**
+     * Every IANA timezone name, e.g. for a timezone picker.
+     * @alias geo.timezones
+     * @example
+     * const options = sdk.geo.timezones.map((zone) => ({ title: zone, value: zone }));
+     */
     service.timezones = [
                 "Africa/Abidjan",
                 "Africa/Accra",
@@ -864,17 +883,15 @@ export default function(qik) {
             ]
 
     /**
-     * 
-     * Retrieves the default country for the current user/application
-     * will attempt to retrieve the country from the user or application's organisation or from services available within the browser
+     * Returns the signed-in user's organisation country.
      * @alias geo.getDefaultCountry
+     * @returns {Object|undefined} { code, name }, e.g. { code: 'AU', name: 'Australia' }, or undefined when signed out or the organisation has no country set.
      * @example
-     * const result = sdk.geo.getDefaultCountry()
-     * // Would return something similar to:
-     * // { code:'AU', name:'Australia' }
+     * const country = sdk.geo.getDefaultCountry(); // { code: 'AU', name: 'Australia' }
      */
     service.getDefaultCountry = function() {
-        const {session:currentUser} = qik.auth.getCurrentUser();
+        // getCurrentUser() is null when signed out
+        const currentUser = qik.auth.getCurrentUser()?.session;
 
         if(currentUser) {
             const code = currentUser?.organisation?.countryCode;