@aemforms/af-core 0.22.23 → 0.22.26

package/lib/cjs/index.cjs

@@ -1,25 +1,169 @@
-/*************************************************************************
-* ADOBE CONFIDENTIAL
-* ___________________
-*
-* Copyright 2022 Adobe
-* All Rights Reserved.
-*
-* NOTICE: All information contained herein is, and remains
-* the property of Adobe and its suppliers, if any. The intellectual
-* and technical concepts contained herein are proprietary to Adobe
-* and its suppliers and are protected by all applicable intellectual
-* property laws, including trade secret and copyright laws.
-* Dissemination of this information or reproduction of this material
-* is strictly forbidden unless prior written permission is obtained
-* from Adobe.
-
-* Adobe permits you to use and modify this file solely in accordance with
-* the terms of the Adobe license agreement accompanying it.
-*************************************************************************/
-
 'use strict';
 
+const translationProps = ['description', 'placeholder', 'enum', 'enumNames', 'label.value', 'constraintMessages.accept',
+    'constraintMessages.enum', 'constraintMessages.exclusiveMinimum', 'constraintMessages.exclusiveMaximum', 'constraintMessages.format', 'constraintMessages.maxFileSize', 'constraintMessages.maxLength',
+    'constraintMessages.maximum', 'constraintMessages.maxItems', 'constraintMessages.minLength', 'constraintMessages.minimum', 'constraintMessages.minItems', 'constraintMessages.pattern', 'constraintMessages.required',
+    'constraintMessages.step', 'constraintMessages.type', 'constraintMessages.validationExpression'];
+const constraintProps = ['accept', 'enum', 'exclusiveMinimum', 'exclusiveMaximum',
+    'format', 'maxFileSize', 'maxLength', 'maximum', 'maxItems',
+    'minLength', 'minimum', 'minItems', 'pattern', 'required', 'step', 'validationExpression', 'enumNames'];
+
+class ValidationError {
+    fieldName;
+    errorMessages;
+    constructor(fieldName = '', errorMessages = []) {
+        this.errorMessages = errorMessages;
+        this.fieldName = fieldName;
+    }
+}
+
+const objToMap = (o) => new Map(Object.entries(o));
+const stringViewTypes = objToMap({ 'date': 'date-input', 'data-url': 'file-input', 'binary': 'file-input' });
+const typeToViewTypes = objToMap({
+    'number': 'number-input',
+    'boolean': 'checkbox',
+    'object': 'panel',
+    'array': 'panel',
+    'file': 'file-input',
+    'file[]': 'file-input'
+});
+const arrayTypes = ['string[]', 'boolean[]', 'number[]', 'array'];
+const defaultFieldTypes = (schema) => {
+    const type = schema.type || 'string';
+    if ('enum' in schema) {
+        const enums = schema.enum;
+        if (enums.length > 2 || arrayTypes.indexOf(type) > -1) {
+            return 'drop-down';
+        }
+        else {
+            return 'checkbox';
+        }
+    }
+    if (type === 'string' || type === 'string[]') {
+        return stringViewTypes.get(schema.format) || 'text-input';
+    }
+    return typeToViewTypes.get(type) || 'text-input';
+};
+const fieldSchema = (input) => {
+    if ('items' in input) {
+        const fieldset = input;
+        const items = fieldset.items;
+        if (fieldset.type === 'array') {
+            return {
+                type: 'array',
+                items: fieldSchema(items[0]),
+                minItems: fieldset?.minItems,
+                maxItems: fieldset?.maxItems
+            };
+        }
+        else {
+            const iter = items.filter(x => x.name != null);
+            return {
+                type: 'object',
+                properties: Object.fromEntries(iter.map(item => [item.name, fieldSchema(item)])),
+                required: iter.filter(x => x.required).map(x => x.name)
+            };
+        }
+    }
+    else {
+        const field = input;
+        const schemaProps = ['type', 'maxLength', 'minLength', 'minimum', 'maximum', 'format', 'pattern', 'step', 'enum'];
+        const schema = schemaProps.reduce((acc, prop) => {
+            const p = prop;
+            if (prop in field && field[p] != undefined) {
+                acc[prop] = field[p];
+            }
+            return acc;
+        }, {});
+        if (field.dataRef === 'none' || Object.keys(schema).length == 0) {
+            return undefined;
+        }
+        return {
+            title: field.label?.value,
+            description: field.description,
+            ...schema
+        };
+    }
+};
+const exportDataSchema = (form) => {
+    return fieldSchema(form);
+};
+
+const getProperty = (data, key, def) => {
+    if (key in data) {
+        return data[key];
+    }
+    else if (!key.startsWith(':')) {
+        const prefixedKey = `:${key}`;
+        if (prefixedKey in data) {
+            return data[prefixedKey];
+        }
+    }
+    return def;
+};
+const isFile = function (item) {
+    return (item?.type === 'file' || item?.type === 'file[]') ||
+        ((item?.type === 'string' || item?.type === 'string[]') &&
+            (item?.format === 'binary' || item?.format === 'data-url'));
+};
+const checkIfConstraintsArePresent = function (item) {
+    return constraintProps.some(cp => item[cp] !== undefined);
+};
+const isCheckbox = function (item) {
+    const fieldType = item?.fieldType || defaultFieldTypes(item);
+    return fieldType === 'checkbox';
+};
+const isCheckboxGroup = function (item) {
+    const fieldType = item?.fieldType || defaultFieldTypes(item);
+    return fieldType === 'checkbox-group';
+};
+const isDateField = function (item) {
+    const fieldType = item?.fieldType || defaultFieldTypes(item);
+    return (fieldType === 'text-input' && item?.format === 'date') || fieldType === 'date-input';
+};
+function deepClone(obj, idGenerator) {
+    let result;
+    if (obj instanceof Array) {
+        result = [];
+        result = obj.map(x => deepClone(x, idGenerator));
+    }
+    else if (typeof obj === 'object' && obj !== null) {
+        result = {};
+        Object.entries(obj).forEach(([key, value]) => {
+            result[key] = deepClone(value, idGenerator);
+        });
+    }
+    else {
+        result = obj;
+    }
+    if (idGenerator && result && result.id) {
+        result.id = idGenerator();
+    }
+    return result;
+}
+function checkIfKeyAdded(currentObj, prevObj, objKey) {
+    if (currentObj != null && prevObj != null) {
+        const newPrvObj = { ...prevObj };
+        newPrvObj[objKey] = currentObj[objKey];
+        const newJsonStr = jsonString(currentObj).replace(jsonString(newPrvObj), '');
+        return newJsonStr === '';
+    }
+    else {
+        return false;
+    }
+}
+const jsonString = (obj) => {
+    return JSON.stringify(obj, null, 2);
+};
+const isRepeatable = (obj) => {
+    return ((obj.repeatable &&
+        ((obj.minOccur === undefined && obj.maxOccur === undefined) ||
+            (obj.minOccur !== undefined && obj.maxOccur !== undefined && obj.maxOccur !== 0) ||
+            (obj.minOccur !== undefined && obj.maxOccur !== undefined && obj.minOccur !== 0 && obj.maxOccur !== 0) ||
+            (obj.minOccur !== undefined && obj.minOccur >= 0) ||
+            (obj.maxOccur !== undefined && obj.maxOccur !== 0))) || false);
+};
+
 class ActionImpl {
     _metadata;
     _type;
@@ -543,12 +687,12 @@ const resolveData = (data, input, create) => {
     return result;
 };
 
-function __decorate(decorators, target, key, desc) {
+var __decorate$3 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
+};
 const editableProperties = [
     'value',
     'label',
@@ -979,177 +1123,22 @@ class BaseNode {
         }
     }
 }
-__decorate([
+__decorate$3([
     dependencyTracked()
 ], BaseNode.prototype, "index", null);
-__decorate([
+__decorate$3([
     dependencyTracked()
 ], BaseNode.prototype, "description", null);
-__decorate([
+__decorate$3([
     dependencyTracked()
 ], BaseNode.prototype, "visible", null);
-__decorate([
+__decorate$3([
     dependencyTracked()
 ], BaseNode.prototype, "label", null);
-__decorate([
+__decorate$3([
     dependencyTracked()
 ], BaseNode.prototype, "properties", null);
 
-const translationProps = ['description', 'placeholder', 'enum', 'enumNames', 'label.value', 'constraintMessages.accept',
-    'constraintMessages.enum', 'constraintMessages.exclusiveMinimum', 'constraintMessages.exclusiveMaximum', 'constraintMessages.format', 'constraintMessages.maxFileSize', 'constraintMessages.maxLength',
-    'constraintMessages.maximum', 'constraintMessages.maxItems', 'constraintMessages.minLength', 'constraintMessages.minimum', 'constraintMessages.minItems', 'constraintMessages.pattern', 'constraintMessages.required',
-    'constraintMessages.step', 'constraintMessages.type', 'constraintMessages.validationExpression'];
-const constraintProps = ['accept', 'enum', 'exclusiveMinimum', 'exclusiveMaximum',
-    'format', 'maxFileSize', 'maxLength', 'maximum', 'maxItems',
-    'minLength', 'minimum', 'minItems', 'pattern', 'required', 'step', 'validationExpression', 'enumNames'];
-
-const objToMap = (o) => new Map(Object.entries(o));
-const stringViewTypes = objToMap({ 'date': 'date-input', 'data-url': 'file-input', 'binary': 'file-input' });
-const typeToViewTypes = objToMap({
-    'number': 'number-input',
-    'boolean': 'checkbox',
-    'object': 'panel',
-    'array': 'panel',
-    'file': 'file-input',
-    'file[]': 'file-input'
-});
-const arrayTypes = ['string[]', 'boolean[]', 'number[]', 'array'];
-const defaultFieldTypes = (schema) => {
-    const type = schema.type || 'string';
-    if ('enum' in schema) {
-        const enums = schema.enum;
-        if (enums.length > 2 || arrayTypes.indexOf(type) > -1) {
-            return 'drop-down';
-        }
-        else {
-            return 'checkbox';
-        }
-    }
-    if (type === 'string' || type === 'string[]') {
-        return stringViewTypes.get(schema.format) || 'text-input';
-    }
-    return typeToViewTypes.get(type) || 'text-input';
-};
-const fieldSchema = (input) => {
-    if ('items' in input) {
-        const fieldset = input;
-        const items = fieldset.items;
-        if (fieldset.type === 'array') {
-            return {
-                type: 'array',
-                items: fieldSchema(items[0]),
-                minItems: fieldset?.minItems,
-                maxItems: fieldset?.maxItems
-            };
-        }
-        else {
-            const iter = items.filter(x => x.name != null);
-            return {
-                type: 'object',
-                properties: Object.fromEntries(iter.map(item => [item.name, fieldSchema(item)])),
-                required: iter.filter(x => x.required).map(x => x.name)
-            };
-        }
-    }
-    else {
-        const field = input;
-        const schemaProps = ['type', 'maxLength', 'minLength', 'minimum', 'maximum', 'format', 'pattern', 'step', 'enum'];
-        const schema = schemaProps.reduce((acc, prop) => {
-            const p = prop;
-            if (prop in field && field[p] != undefined) {
-                acc[prop] = field[p];
-            }
-            return acc;
-        }, {});
-        if (field.dataRef === 'none' || Object.keys(schema).length == 0) {
-            return undefined;
-        }
-        return {
-            title: field.label?.value,
-            description: field.description,
-            ...schema
-        };
-    }
-};
-const exportDataSchema = (form) => {
-    return fieldSchema(form);
-};
-
-const getProperty = (data, key, def) => {
-    if (key in data) {
-        return data[key];
-    }
-    else if (!key.startsWith(':')) {
-        const prefixedKey = `:${key}`;
-        if (prefixedKey in data) {
-            return data[prefixedKey];
-        }
-    }
-    return def;
-};
-const isFile = function (item) {
-    return (item?.type === 'file' || item?.type === 'file[]') ||
-        ((item?.type === 'string' || item?.type === 'string[]') &&
-            (item?.format === 'binary' || item?.format === 'data-url'));
-};
-const checkIfConstraintsArePresent = function (item) {
-    return constraintProps.some(cp => item[cp] !== undefined);
-};
-const isCheckbox = function (item) {
-    const fieldType = item?.fieldType || defaultFieldTypes(item);
-    return fieldType === 'checkbox';
-};
-const isCheckboxGroup = function (item) {
-    const fieldType = item?.fieldType || defaultFieldTypes(item);
-    return fieldType === 'checkbox-group';
-};
-const isDateField = function (item) {
-    const fieldType = item?.fieldType || defaultFieldTypes(item);
-    return (fieldType === 'text-input' && item?.format === 'date') || fieldType === 'date-input';
-};
-function deepClone(obj, idGenerator) {
-    let result;
-    if (obj instanceof Array) {
-        result = [];
-        result = obj.map(x => deepClone(x, idGenerator));
-    }
-    else if (typeof obj === 'object' && obj !== null) {
-        result = {};
-        Object.entries(obj).forEach(([key, value]) => {
-            result[key] = deepClone(value, idGenerator);
-        });
-    }
-    else {
-        result = obj;
-    }
-    if (idGenerator && result && result.id) {
-        result.id = idGenerator();
-    }
-    return result;
-}
-function checkIfKeyAdded(currentObj, prevObj, objKey) {
-    if (currentObj != null && prevObj != null) {
-        const newPrvObj = { ...prevObj };
-        newPrvObj[objKey] = currentObj[objKey];
-        const newJsonStr = jsonString(currentObj).replace(jsonString(newPrvObj), '');
-        return newJsonStr === '';
-    }
-    else {
-        return false;
-    }
-}
-const jsonString = (obj) => {
-    return JSON.stringify(obj, null, 2);
-};
-const isRepeatable = (obj) => {
-    return ((obj.repeatable &&
-        ((obj.minOccur === undefined && obj.maxOccur === undefined) ||
-            (obj.minOccur !== undefined && obj.maxOccur !== undefined && obj.maxOccur !== 0) ||
-            (obj.minOccur !== undefined && obj.maxOccur !== undefined && obj.minOccur !== 0 && obj.maxOccur !== 0) ||
-            (obj.minOccur !== undefined && obj.minOccur >= 0) ||
-            (obj.maxOccur !== undefined && obj.maxOccur !== 0))) || false);
-};
-
 class Scriptable extends BaseNode {
     _events = {};
     _rules = {};
@@ -1312,6 +1301,12 @@ class Scriptable extends BaseNode {
     }
 }
 
+var __decorate$2 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
 class Container extends Scriptable {
     _children = [];
     _childrenReference;
@@ -1581,13 +1576,13 @@ class Container extends Scriptable {
         }
     }
 }
-__decorate([
+__decorate$2([
     dependencyTracked()
 ], Container.prototype, "maxItems", null);
-__decorate([
+__decorate$2([
     dependencyTracked()
 ], Container.prototype, "minItems", null);
-__decorate([
+__decorate$2([
     dependencyTracked()
 ], Container.prototype, "activeChild", null);
 
@@ -2453,16 +2448,17 @@ class Form extends Container {
             super.dispatch(action);
         }
     }
+    executeAction(action) {
+        if ((action.type !== 'submit') || this._invalidFields.length === 0) {
+            super.executeAction(action);
+        }
+    }
     submit(action, context) {
         if (this.validate().length === 0) {
             const payload = action?.payload || {};
             submit(context, payload?.success, payload?.error, payload?.submit_as, payload?.data);
         }
     }
-    reset() {
-        super.reset();
-        this._invalidFields = [];
-    }
     getElement(id) {
         if (id == this.id) {
             return this;
@@ -2489,6 +2485,7 @@ class Form extends Container {
     }
 }
 
+// Type constants used to define functions.
 var dataTypes = {
   TYPE_NUMBER: 0,
   TYPE_ANY: 1,
@@ -2560,9 +2557,11 @@ const {
   TYPE_CLASS: TYPE_CLASS$1,
   TYPE_ARRAY_ARRAY,
 } = dataTypes;
+
 const {
   TOK_EXPREF: TOK_EXPREF$3,
 } = tokenDefinitions;
+
 const TYPE_NAME_TABLE = {
   [TYPE_NUMBER]: 'number',
   [TYPE_ANY$1]: 'any',
@@ -2577,10 +2576,13 @@ const TYPE_NAME_TABLE = {
   [TYPE_CLASS$1]: 'class',
   [TYPE_ARRAY_ARRAY]: 'Array<array>',
 };
+
 function getTypeName(inputObj, useValueOf = true) {
   if (inputObj === null) return TYPE_NULL;
   let obj = inputObj;
   if (useValueOf) {
+    // check for the case where there's a child named 'valueOf' that's not a function
+    // if so, then it's an object...
     if (typeof inputObj.valueOf === 'function') obj = inputObj.valueOf.call(inputObj);
     else return TYPE_OBJECT;
   }
@@ -2596,6 +2598,8 @@ function getTypeName(inputObj, useValueOf = true) {
     case '[object Null]':
       return TYPE_NULL;
     case '[object Object]':
+      // Check if it's an expref.  If it has, it's been
+      // tagged with a jmespathType attr of 'Expref';
       if (obj.jmespathType === TOK_EXPREF$3) {
         return TYPE_EXPREF;
       }
@@ -2604,17 +2608,23 @@ function getTypeName(inputObj, useValueOf = true) {
       return TYPE_OBJECT;
   }
 }
+
 function getTypeNames(inputObj) {
+  // return the types with and without using valueOf
+  // needed for the cases where we really need an object passed to a function -- not it's value
   const type1 = getTypeName(inputObj);
   const type2 = getTypeName(inputObj, false);
   return [type1, type2];
 }
+
 function matchType(actuals, expectedList, argValue, context, toNumber, toString) {
   const actual = actuals[0];
   if (expectedList.findIndex(
     type => type === TYPE_ANY$1 || actual === type,
   ) !== -1
   ) return argValue;
+  // Can't coerce Objects to any other type,
+  // and cannot coerce anything to a Class
   let wrongType = false;
   if (actual === TYPE_OBJECT || (expectedList.length === 1 && expectedList[0] === TYPE_CLASS$1)) {
     wrongType = true;
@@ -2634,9 +2644,11 @@ function matchType(actuals, expectedList, argValue, context, toNumber, toString)
   if (wrongType) {
     throw new Error(`TypeError: ${context} expected argument to be type ${TYPE_NAME_TABLE[expectedList[0]]} but received type ${TYPE_NAME_TABLE[actual]} instead.`);
   }
+  // no exact match in the list of possible types, see if we can coerce an array type
   let expected = -1;
   if (actual === TYPE_ARRAY$1) {
     if (expectedList.includes(TYPE_ARRAY_STRING$1) && expectedList.includes(TYPE_ARRAY_NUMBER)) {
+      // choose the array type based on the first element
       if (argValue.length > 0 && typeof argValue[0] === 'string') expected = TYPE_ARRAY_STRING$1;
       else expected = TYPE_ARRAY_NUMBER;
     }
@@ -2646,6 +2658,7 @@ function matchType(actuals, expectedList, argValue, context, toNumber, toString)
       e => [TYPE_ARRAY_STRING$1, TYPE_ARRAY_NUMBER, TYPE_ARRAY$1].includes(e),
     );
   }
+  // no match, just take the first type
   if (expected === -1) [expected] = expectedList;
   if (expected === TYPE_ANY$1) return argValue;
   if (expected === TYPE_ARRAY_STRING$1
@@ -2655,8 +2668,12 @@ function matchType(actuals, expectedList, argValue, context, toNumber, toString)
       if (actual === TYPE_ARRAY_NUMBER || actual === TYPE_ARRAY_STRING$1) return argValue;
       return argValue === null ? [] : [argValue];
     }
+    // The expected type can either just be array,
+    // or it can require a specific subtype (array of numbers).
     const subtype = expected === TYPE_ARRAY_NUMBER ? TYPE_NUMBER : TYPE_STRING$1;
     if (actual === TYPE_ARRAY$1) {
+      // Otherwise we need to check subtypes.
+      // We're going to modify the array, so take a copy
       const returnArray = argValue.slice();
       for (let i = 0; i < returnArray.length; i += 1) {
         const indexType = getTypeNames(returnArray[i]);
@@ -2677,6 +2694,7 @@ function matchType(actuals, expectedList, argValue, context, toNumber, toString)
   } else {
     if (expected === TYPE_NUMBER) {
       if ([TYPE_STRING$1, TYPE_BOOLEAN, TYPE_NULL].includes(actual)) return toNumber(argValue);
+      /* TYPE_ARRAY, TYPE_EXPREF, TYPE_OBJECT, TYPE_ARRAY, TYPE_ARRAY_NUMBER, TYPE_ARRAY_STRING */
       return 0;
     }
     if (expected === TYPE_STRING$1) {
@@ -2699,31 +2717,42 @@ function isArray(obj) {
   }
   return false;
 }
+
 function isObject(obj) {
   if (obj !== null) {
     return Object.prototype.toString.call(obj) === '[object Object]';
   }
   return false;
 }
+
 function getValueOf(a) {
   if (a === null || a === undefined) return a;
   if (isArray(a)) {
     return a.map(i => getValueOf(i));
   }
+  // if we have a child named 'valueOf' then we're an object,
+  // and just return the object.
   if (typeof (a.valueOf) !== 'function') return a;
   return a.valueOf();
 }
+
 function strictDeepEqual(lhs, rhs) {
   const first = getValueOf(lhs);
   const second = getValueOf(rhs);
+  // Check the scalar case first.
   if (first === second) {
     return true;
   }
+
+  // Check if they are the same type.
   const firstType = Object.prototype.toString.call(first);
   if (firstType !== Object.prototype.toString.call(second)) {
     return false;
   }
+  // We know that first and second have the same type so we can just check the
+  // first type from now on.
   if (isArray(first) === true) {
+    // Short circuit if they're not the same length;
     if (first.length !== second.length) {
       return false;
     }
@@ -2735,7 +2764,9 @@ function strictDeepEqual(lhs, rhs) {
     return true;
   }
   if (isObject(first) === true) {
+    // An object is equal if it has the same key/value pairs.
     const keysSeen = {};
+    // eslint-disable-next-line no-restricted-syntax
     for (const key in first) {
       if (hasOwnProperty.call(first, key)) {
         if (strictDeepEqual(first[key], second[key]) === false) {
@@ -2744,6 +2775,9 @@ function strictDeepEqual(lhs, rhs) {
         keysSeen[key] = true;
       }
     }
+    // Now check that there aren't any keys in second that weren't
+    // in first.
+    // eslint-disable-next-line no-restricted-syntax
     for (const key2 in second) {
       if (hasOwnProperty.call(second, key2)) {
         if (keysSeen[key2] !== true) {
@@ -2769,22 +2803,42 @@ const {
   TOK_NE: TOK_NE$2,
   TOK_FLATTEN: TOK_FLATTEN$2,
 } = tokenDefinitions;
+
 const {
   TYPE_STRING,
   TYPE_ARRAY_STRING,
   TYPE_ARRAY,
 } = dataTypes;
+
 function isFalse(value) {
+  // From the spec:
+  // A false value corresponds to the following values:
+  // Empty list
+  // Empty object
+  // Empty string
+  // False boolean
+  // null value
+  // (new) use JS truthy evaluation.  This changes the spec behavior.
+  // Where in the past a zero (0) would be True, it's now false
+
+  // First check the scalar values.
   if (value === null) return true;
+  // in case it's an object with a valueOf defined
   const obj = getValueOf(value);
   if (obj === '' || obj === false || obj === null) {
     return true;
   }
   if (isArray(obj) && obj.length === 0) {
+    // Check for an empty array.
     return true;
   }
   if (isObject(obj)) {
+    // Check for an empty object.
+    // eslint-disable-next-line no-restricted-syntax
     for (const key in obj) {
+      // If there are any keys, then
+      // the object is not empty so the object
+      // is not false.
       if (Object.prototype.hasOwnProperty.call(obj, key)) {
         return false;
       }
@@ -2793,9 +2847,11 @@ function isFalse(value) {
   }
   return !obj;
 }
+
 function objValues(obj) {
   return Object.values(obj);
 }
+
 class TreeInterpreter {
   constructor(runtime, globals, toNumber, toString, debug, language) {
     this.runtime = runtime;
@@ -2805,20 +2861,27 @@ class TreeInterpreter {
     this.debug = debug;
     this.language = language;
   }
+
   search(node, value) {
     return this.visit(node, value);
   }
+
   visit(n, v) {
     const visitFunctions = {
       Field: (node, value) => {
+        // we used to check isObject(value) here -- but it is possible for an array-based
+        // object to have properties.  So we'll allow the child check on objects and arrays.
         if (value !== null && (isObject(value) || isArray(value))) {
           let field = value[node.name];
+          // fields can be objects with overridden methods. e.g. valueOf
+          // so don't resolve to a function...
           if (typeof field === 'function') field = undefined;
           if (field === undefined) {
             try {
               this.debug.push(`Failed to find: '${node.name}'`);
               const available = Object.keys(value).map(a => `'${a}'`).toString();
               if (available.length) this.debug.push(`Available fields: ${available}`);
+            // eslint-disable-next-line no-empty
             } catch (e) {}
             return null;
           }
@@ -2826,6 +2889,7 @@ class TreeInterpreter {
         }
         return null;
       },
+
       Subexpression: (node, value) => {
         let result = this.visit(node.children[0], value);
         for (let i = 1; i < node.children.length; i += 1) {
@@ -2834,10 +2898,12 @@ class TreeInterpreter {
         }
         return result;
       },
+
       IndexExpression: (node, value) => {
         const left = this.visit(node.children[0], value);
         return this.visit(node.children[1], left);
       },
+
       Index: (node, value) => {
         if (isArray(value)) {
           let index = this.toNumber(this.visit(node.value, value));
@@ -2863,6 +2929,7 @@ class TreeInterpreter {
         this.debug.push(`left side of index expression ${value} is not an array or object.`);
         return null;
       },
+
       Slice: (node, value) => {
         if (!isArray(value)) return null;
         const sliceParams = node.children.slice(0).map(
@@ -2882,7 +2949,9 @@ class TreeInterpreter {
         }
         return result;
       },
+
       Projection: (node, value) => {
+      // Evaluate left child.
         const base = this.visit(node.children[0], value);
         if (!isArray(base)) return null;
         const collected = [];
@@ -2894,7 +2963,9 @@ class TreeInterpreter {
         });
         return collected;
       },
+
       ValueProjection: (node, value) => {
+      // Evaluate left child.
         const projection = this.visit(node.children[0], value);
         if (!isObject(getValueOf(projection))) return null;
         const collected = [];
@@ -2905,6 +2976,7 @@ class TreeInterpreter {
         });
         return collected;
       },
+
       FilterProjection: (node, value) => {
         const base = this.visit(node.children[0], value);
         if (!isArray(base)) return null;
@@ -2912,6 +2984,7 @@ class TreeInterpreter {
           const matched = this.visit(node.children[2], b);
           return !isFalse(matched);
         });
+
         const finalResults = [];
         filtered.forEach(f => {
           const current = this.visit(node.children[1], f);
@@ -2919,9 +2992,11 @@ class TreeInterpreter {
         });
         return finalResults;
       },
+
       Comparator: (node, value) => {
         const first = this.visit(node.children[0], value);
         const second = this.visit(node.children[1], value);
+
         if (node.name === TOK_EQ$2) return strictDeepEqual(first, second);
         if (node.name === TOK_NE$2) return !strictDeepEqual(first, second);
         if (node.name === TOK_GT$2) return first > second;
@@ -2930,6 +3005,7 @@ class TreeInterpreter {
         if (node.name === TOK_LTE$2) return first <= second;
         throw new Error(`Unknown comparator: ${node.name}`);
       },
+
       [TOK_FLATTEN$2]: (node, value) => {
         const original = this.visit(node.children[0], value);
         if (!isArray(original)) return null;
@@ -2943,11 +3019,14 @@ class TreeInterpreter {
         });
         return merged;
       },
+
       Identity: (_node, value) => value,
+
       MultiSelectList: (node, value) => {
         if (value === null) return null;
         return node.children.map(child => this.visit(child, value));
       },
+
       MultiSelectHash: (node, value) => {
         if (value === null) return null;
         const collected = {};
@@ -2956,21 +3035,26 @@ class TreeInterpreter {
         });
         return collected;
       },
+
       OrExpression: (node, value) => {
         let matched = this.visit(node.children[0], value);
         if (isFalse(matched)) matched = this.visit(node.children[1], value);
         return matched;
       },
+
       AndExpression: (node, value) => {
         const first = this.visit(node.children[0], value);
+
         if (isFalse(first) === true) return first;
         return this.visit(node.children[1], value);
       },
+
       AddExpression: (node, value) => {
         const first = this.visit(node.children[0], value);
         const second = this.visit(node.children[1], value);
         return this.applyOperator(first, second, '+');
       },
+
       ConcatenateExpression: (node, value) => {
         let first = this.visit(node.children[0], value);
         let second = this.visit(node.children[1], value);
@@ -2978,6 +3062,7 @@ class TreeInterpreter {
         second = matchType(getTypeNames(second), [TYPE_STRING, TYPE_ARRAY_STRING], second, 'concatenate', this.toNumber, this.toString);
         return this.applyOperator(first, second, '&');
       },
+
       UnionExpression: (node, value) => {
         let first = this.visit(node.children[0], value);
         let second = this.visit(node.children[1], value);
@@ -2985,52 +3070,72 @@ class TreeInterpreter {
         second = matchType(getTypeNames(second), [TYPE_ARRAY], second, 'union', this.toNumber, this.toString);
         return first.concat(second);
       },
+
       SubtractExpression: (node, value) => {
         const first = this.visit(node.children[0], value);
         const second = this.visit(node.children[1], value);
         return this.applyOperator(first, second, '-');
       },
+
       MultiplyExpression: (node, value) => {
         const first = this.visit(node.children[0], value);
         const second = this.visit(node.children[1], value);
         return this.applyOperator(first, second, '*');
       },
+
       DivideExpression: (node, value) => {
         const first = this.visit(node.children[0], value);
         const second = this.visit(node.children[1], value);
         return this.applyOperator(first, second, '/');
       },
+
       PowerExpression: (node, value) => {
         const first = this.visit(node.children[0], value);
         const second = this.visit(node.children[1], value);
         return this.applyOperator(first, second, '^');
       },
+
       NotExpression: (node, value) => {
         const first = this.visit(node.children[0], value);
         return isFalse(first);
       },
+
       UnaryMinusExpression: (node, value) => {
         const first = this.visit(node.children[0], value);
         return first * -1;
       },
+
       Literal: node => node.value,
+
       Number: node => node.value,
+
       [TOK_PIPE$2]: (node, value) => {
         const left = this.visit(node.children[0], value);
         return this.visit(node.children[1], left);
       },
+
       [TOK_CURRENT$2]: (_node, value) => value,
+
       [TOK_GLOBAL$2]: node => {
         const result = this.globals[node.name];
         return result === undefined ? null : result;
       },
+
       Function: (node, value) => {
+      // Special case for if()
+      // we need to make sure the results are called only after the condition is evaluated
+      // Otherwise we end up with both results invoked -- which could include side effects
+      // For "if", the last parameter to callFunction is false (bResolved) to indicate there's
+      // no point in validating the argument type.
         if (node.name === 'if') return this.runtime.callFunction(node.name, node.children, value, this, false);
         const resolvedArgs = node.children.map(child => this.visit(child, value));
         return this.runtime.callFunction(node.name, resolvedArgs, value, this);
       },
+
       ExpressionReference: node => {
         const [refNode] = node.children;
+        // Tag the node with a specific attribute so the type
+        // checker verify the type.
         refNode.jmespathType = TOK_EXPREF$2;
         return refNode;
       },
@@ -3039,6 +3144,8 @@ class TreeInterpreter {
     if (!fn) throw new Error(`Unknown/missing node type ${(n && n.type) || ''}`);
     return fn(n, v);
   }
+
+  // eslint-disable-next-line class-methods-use-this
   computeSliceParams(arrayLength, sliceParams) {
     function capSliceRange(arrayLen, actual, stp) {
       let actualValue = actual;
@@ -3052,6 +3159,7 @@ class TreeInterpreter {
       }
       return actualValue;
     }
+
     let [start, stop, step] = sliceParams;
     if (step === null) {
       step = 1;
@@ -3061,11 +3169,13 @@ class TreeInterpreter {
       throw error;
     }
     const stepValueNegative = step < 0;
+
     if (start === null) {
       start = stepValueNegative ? arrayLength - 1 : 0;
     } else {
       start = capSliceRange(arrayLength, start, step);
     }
+
     if (stop === null) {
       stop = stepValueNegative ? -1 : arrayLength;
     } else {
@@ -3073,8 +3183,10 @@ class TreeInterpreter {
     }
     return [start, stop, step];
   }
+
   applyOperator(first, second, operator) {
     if (isArray(first) && isArray(second)) {
+      // balance the size of the arrays
       const shorter = first.length < second.length ? first : second;
       const diff = Math.abs(first.length - second.length);
       shorter.length += diff;
@@ -3085,8 +3197,10 @@ class TreeInterpreter {
       }
       return result;
     }
+
     if (isArray(first)) return first.map(a => this.applyOperator(a, second, operator));
     if (isArray(second)) return second.map(a => this.applyOperator(first, a, operator));
+
     if (operator === '*') return this.toNumber(first) * this.toNumber(second);
     if (operator === '&') return first + second;
     if (operator === '+') {
@@ -3104,6 +3218,8 @@ class TreeInterpreter {
   }
 }
 
+/* eslint-disable no-underscore-dangle */
+
 const {
   TOK_UNQUOTEDIDENTIFIER: TOK_UNQUOTEDIDENTIFIER$1,
   TOK_QUOTEDIDENTIFIER: TOK_QUOTEDIDENTIFIER$1,
@@ -3143,8 +3259,16 @@ const {
   TOK_LPAREN: TOK_LPAREN$1,
   TOK_LITERAL: TOK_LITERAL$1,
 } = tokenDefinitions;
+
+// The "&", "[", "<", ">" tokens
+// are not in basicToken because
+// there are two token variants
+// ("&&", "[?", "<=", ">=").  This is specially handled
+// below.
+
 const basicTokens = {
   '.': TOK_DOT$1,
+  // "*": TOK_STAR,
   ',': TOK_COMMA$1,
   ':': TOK_COLON$1,
   '{': TOK_LBRACE$1,
@@ -3154,6 +3278,7 @@ const basicTokens = {
   ')': TOK_RPAREN$1,
   '@': TOK_CURRENT$1,
 };
+
 const globalStartToken = '$';
 const operatorStartToken = {
   '<': true,
@@ -3161,34 +3286,42 @@ const operatorStartToken = {
   '=': true,
   '!': true,
 };
+
 const skipChars = {
   ' ': true,
   '\t': true,
   '\n': true,
 };
+
 function isNum(ch) {
   return (ch >= '0' && ch <= '9') || (ch === '.');
 }
+
 function isAlphaNum(ch) {
   return (ch >= 'a' && ch <= 'z')
            || (ch >= 'A' && ch <= 'Z')
            || (ch >= '0' && ch <= '9')
            || ch === '_';
 }
+
 function isIdentifier(stream, pos) {
   const ch = stream[pos];
+  // $ is special -- it's allowed to be part of an identifier if it's the first character
   if (ch === '$') {
     return stream.length > pos && isAlphaNum(stream[pos + 1]);
   }
+  // return whether character 'isAlpha'
   return (ch >= 'a' && ch <= 'z')
           || (ch >= 'A' && ch <= 'Z')
           || ch === '_';
 }
+
 class Lexer {
   constructor(allowedGlobalNames = [], debug = []) {
     this._allowedGlobalNames = allowedGlobalNames;
     this.debug = debug;
   }
+
   tokenize(stream) {
     const tokens = [];
     this._current = 0;
@@ -3197,6 +3330,7 @@ class Lexer {
     let token;
     while (this._current < stream.length) {
       const prev = tokens.length ? tokens.slice(-1)[0].type : null;
+
       if (this._isGlobal(prev, stream, this._current)) {
         tokens.push(this._consumeGlobal(stream));
       } else if (isIdentifier(stream, this._current)) {
@@ -3221,6 +3355,8 @@ class Lexer {
         token = this._consumeNumber(stream);
         tokens.push(token);
       } else if (stream[this._current] === '[') {
+        // No need to increment this._current.  This happens
+        // in _consumeLBracket
         token = this._consumeLBracket(stream);
         tokens.push(token);
       } else if (stream[this._current] === '"') {
@@ -3250,6 +3386,7 @@ class Lexer {
       } else if (operatorStartToken[stream[this._current]] !== undefined) {
         tokens.push(this._consumeOperator(stream));
       } else if (skipChars[stream[this._current]] !== undefined) {
+        // Ignore whitespace.
         this._current += 1;
       } else if (stream[this._current] === '&') {
         start = this._current;
@@ -3258,6 +3395,9 @@ class Lexer {
           this._current += 1;
           tokens.push({ type: TOK_AND$1, value: '&&', start });
         } else if (prev === TOK_COMMA$1 || prev === TOK_LPAREN$1) {
+          // based on previous token we'll know if this & is a JMESPath expression-type
+          // or if it's a concatenation operator
+          // if we're a function arg then it's an expression-type
           tokens.push({ type: TOK_EXPREF$1, value: '&', start });
         } else {
           tokens.push({ type: TOK_CONCATENATE$1, value: '&', start });
@@ -3277,6 +3417,8 @@ class Lexer {
       } else if (stream[this._current] === '*') {
         start = this._current;
         this._current += 1;
+        // based on previous token we'll know if this asterix is a star -- not a multiply
+        // might be better to list the prev tokens that are valid for multiply?
         const prevToken = tokens.length && tokens.slice(-1)[0].type;
         if (tokens.length === 0 || [
           TOK_LBRACKET$1,
@@ -3316,6 +3458,7 @@ class Lexer {
     }
     return tokens;
   }
+
   _consumeUnquotedIdentifier(stream) {
     const start = this._current;
     this._current += 1;
@@ -3324,12 +3467,14 @@ class Lexer {
     }
     return stream.slice(start, this._current);
   }
+
   _consumeQuotedIdentifier(stream) {
     const start = this._current;
     this._current += 1;
     const maxLength = stream.length;
     let foundNonAlpha = !isIdentifier(stream, start + 1);
     while (stream[this._current] !== '"' && this._current < maxLength) {
+      // You can escape a double quote and you can escape an escape.
       let current = this._current;
       if (!isAlphaNum(stream[current])) foundNonAlpha = true;
       if (stream[current] === '\\' && (stream[current + 1] === '\\'
@@ -3342,19 +3487,26 @@ class Lexer {
     }
     this._current += 1;
     const val = stream.slice(start, this._current);
+    // Check for unnecessary double quotes.
+    // json-formula uses double quotes to escape characters that don't belong in names names.
+    // e.g. "purchase-order".address
+    // If we find a double-quoted entity with spaces or all legal characters, issue a warning
     try {
       if (!foundNonAlpha || val.includes(' ')) {
         this.debug.push(`Suspicious quotes: ${val}`);
         this.debug.push(`Did you intend a literal? '${val.replace(/"/g, '')}'?`);
       }
+    // eslint-disable-next-line no-empty
     } catch (e) {}
     return JSON.parse(val);
   }
+
   _consumeRawStringLiteral(stream) {
     const start = this._current;
     this._current += 1;
     const maxLength = stream.length;
     while (stream[this._current] !== "'" && this._current < maxLength) {
+      // You can escape a single quote and you can escape an escape.
       let current = this._current;
       if (stream[current] === '\\' && (stream[current + 1] === '\\'
                                              || stream[current + 1] === "'")) {
@@ -3368,6 +3520,7 @@ class Lexer {
     const literal = stream.slice(start + 1, this._current - 1);
     return literal.replaceAll("\\'", "'");
   }
+
   _consumeNumber(stream) {
     const start = this._current;
     this._current += 1;
@@ -3384,11 +3537,13 @@ class Lexer {
     }
     return { type: TOK_NUMBER$1, value, start };
   }
+
   _consumeUnaryMinus() {
     const start = this._current;
     this._current += 1;
     return { type: TOK_UNARY_MINUS$1, value: '-', start };
   }
+
   _consumeLBracket(stream) {
     const start = this._current;
     this._current += 1;
@@ -3402,22 +3557,28 @@ class Lexer {
     }
     return { type: TOK_LBRACKET$1, value: '[', start };
   }
+
   _isGlobal(prev, stream, pos) {
+    // global tokens occur only at the start of an expression
     if (prev !== null && prev === TOK_DOT$1) return false;
     const ch = stream[pos];
     if (ch !== globalStartToken) return false;
+    // $ is special -- it's allowed to be part of an identifier if it's the first character
     let i = pos + 1;
     while (i < stream.length && isAlphaNum(stream[i])) i += 1;
     const global = stream.slice(pos, i);
     return this._allowedGlobalNames.includes(global);
   }
+
   _consumeGlobal(stream) {
     const start = this._current;
     this._current += 1;
     while (this._current < stream.length && isAlphaNum(stream[this._current])) this._current += 1;
     const global = stream.slice(start, this._current);
+
     return { type: TOK_GLOBAL$1, name: global, start };
   }
+
   _consumeOperator(stream) {
     const start = this._current;
     const startingChar = stream[start];
@@ -3443,17 +3604,20 @@ class Lexer {
       }
       return { type: TOK_GT$1, value: '>', start };
     }
+    // startingChar is '='
     if (stream[this._current] === '=') {
       this._current += 1;
       return { type: TOK_EQ$1, value: '==', start };
     }
     return { type: TOK_EQ$1, value: '=', start };
   }
+
   _consumeLiteral(stream) {
     function _looksLikeJSON(str) {
       if (str === '') return false;
       if ('[{"'.includes(str[0])) return true;
       if (['true', 'false', 'null'].includes(str)) return true;
+
       if ('-0123456789'.includes(str[0])) {
         try {
           JSON.parse(str);
@@ -3465,6 +3629,7 @@ class Lexer {
         return false;
       }
     }
+
     this._current += 1;
     const start = this._current;
     const maxLength = stream.length;
@@ -3472,12 +3637,14 @@ class Lexer {
     let inQuotes = false;
     while ((inQuotes || stream[this._current] !== '`') && this._current < maxLength) {
       let current = this._current;
+      // bypass escaped double quotes when we're inside quotes
       if (inQuotes && stream[current] === '\\' && stream[current + 1] === '"') current += 2;
       else {
         if (stream[current] === '"') inQuotes = !inQuotes;
         if (inQuotes && stream[current + 1] === '`') current += 2;
         else if (stream[current] === '\\' && (stream[current + 1] === '\\'
                                               || stream[current + 1] === '`')) {
+        // You can escape a literal char or you can escape the escape.
           current += 2;
         } else {
           current += 1;
@@ -3490,13 +3657,16 @@ class Lexer {
     if (_looksLikeJSON(literalString)) {
       literal = JSON.parse(literalString);
     } else {
+      // Try to JSON parse it as "<literal>"
       literal = JSON.parse(`"${literalString}"`);
     }
+    // +1 gets us to the ending "`", +1 to move on to the next char.
     this._current += 1;
     return literal;
   }
 }
 
+/* eslint-disable no-underscore-dangle */
 const {
   TOK_LITERAL,
   TOK_COLON,
@@ -3538,6 +3708,7 @@ const {
   TOK_LBRACKET,
   TOK_LPAREN,
 } = tokenDefinitions;
+
 const bindingPower = {
   [TOK_EOF]: 0,
   [TOK_UNQUOTEDIDENTIFIER]: 0,
@@ -3577,10 +3748,12 @@ const bindingPower = {
   [TOK_LBRACKET]: 55,
   [TOK_LPAREN]: 60,
 };
+
 class Parser {
   constructor(allowedGlobalNames = []) {
     this._allowedGlobalNames = allowedGlobalNames;
   }
+
   parse(expression, debug) {
     this._loadTokens(expression, debug);
     this.index = 0;
@@ -3595,12 +3768,14 @@ class Parser {
     }
     return ast;
   }
+
   _loadTokens(expression, debug) {
     const lexer = new Lexer(this._allowedGlobalNames, debug);
     const tokens = lexer.tokenize(expression);
     tokens.push({ type: TOK_EOF, value: '', start: expression.length });
     this.tokens = tokens;
   }
+
   expression(rbp) {
     const leftToken = this._lookaheadToken(0);
     this._advance();
@@ -3613,21 +3788,28 @@ class Parser {
     }
     return left;
   }
+
   _lookahead(number) {
     return this.tokens[this.index + number].type;
   }
+
   _lookaheadToken(number) {
     return this.tokens[this.index + number];
   }
+
   _advance() {
     this.index += 1;
   }
+
   _getIndex() {
     return this.index;
   }
+
   _setIndex(index) {
     this.index = index;
   }
+
+  // eslint-disable-next-line consistent-return
   nud(token) {
     let left;
     let right;
@@ -3656,6 +3838,8 @@ class Parser {
       case TOK_STAR:
         left = { type: 'Identity' };
         if (this._lookahead(0) === TOK_RBRACKET) {
+          // This can happen in a multiselect,
+          // [a, b, *]
           right = { type: 'Identity' };
         } else {
           right = this._parseProjectionRHS(bindingPower.Star);
@@ -3702,6 +3886,8 @@ class Parser {
         this._errorToken(token);
     }
   }
+
+  // eslint-disable-next-line consistent-return
   led(tokenName, left) {
     let condition;
     let right;
@@ -3722,6 +3908,7 @@ class Parser {
           right = this._parseDotRHS(rbp);
           return { type: 'Subexpression', children: [left, right] };
         }
+        // Creating a projection.
         this._advance();
         right = this._parseProjectionRHS(rbp);
         return { type: 'ValueProjection', children: [left, right] };
@@ -3799,6 +3986,7 @@ class Parser {
         this._errorToken(this._lookaheadToken(0));
     }
   }
+
   _match(tokenType) {
     if (this._lookahead(0) === tokenType) {
       this._advance();
@@ -3809,6 +3997,8 @@ class Parser {
       throw error;
     }
   }
+
+  // eslint-disable-next-line class-methods-use-this
   _errorToken(token) {
     const error = new Error(`Invalid token (${
       token.type}): "${
@@ -3816,14 +4006,17 @@ class Parser {
     error.name = 'ParserError';
     throw error;
   }
+
   _parseChainedIndexExpression() {
     const oldIndex = this._getIndex();
     if (this._lookahead(0) === TOK_COLON) {
       return this._parseSliceExpression();
     }
+    // look ahead of the first expression to determine the type
     const first = this.expression(0);
     const token = this._lookahead(0);
     if (token === TOK_COLON) {
+      // now that we know the type revert back to the old position and parse
       this._setIndex(oldIndex);
       return this._parseSliceExpression();
     }
@@ -3833,6 +4026,7 @@ class Parser {
       value: first,
     };
   }
+
   _parseUnchainedIndexExpression() {
     const oldIndex = this._getIndex();
     const firstToken = this._lookahead(0);
@@ -3861,6 +4055,7 @@ class Parser {
     this._setIndex(oldIndex);
     return this._parseMultiselectList();
   }
+
   _projectIfSlice(left, right) {
     const indexExpr = { type: 'IndexExpression', children: [left, right] };
     if (right.type === 'Slice') {
@@ -3871,16 +4066,20 @@ class Parser {
     }
     return indexExpr;
   }
+
   _parseSliceExpression() {
+    // [start:end:step] where each part is optional, as well as the last
+    // colon.
     const parts = [null, null, null];
     let index = 0;
     let currentToken = this._lookahead(0);
     while (currentToken !== TOK_RBRACKET && index < 3) {
-      if (currentToken === TOK_COLON && index < 2) {
+      if (currentToken === TOK_COLON && index < 2) { // there can't be more than 2 colons
         index += 1;
         this._advance();
       } else {
         parts[index] = this.expression(0);
+        // check next token to be either colon or rbracket
         const t = this._lookahead(0);
         if (t !== TOK_COLON && t !== TOK_RBRACKET) {
           const error = new Error(`Syntax error, unexpected token: ${
@@ -3897,10 +4096,13 @@ class Parser {
       children: parts,
     };
   }
+
   _parseComparator(left, comparator) {
     const right = this.expression(bindingPower[comparator]);
     return { type: 'Comparator', name: comparator, children: [left, right] };
   }
+
+  // eslint-disable-next-line consistent-return
   _parseDotRHS(rbp) {
     const lookahead = this._lookahead(0);
     const exprTokens = [TOK_UNQUOTEDIDENTIFIER, TOK_QUOTEDIDENTIFIER, TOK_STAR];
@@ -3916,6 +4118,7 @@ class Parser {
       return this._parseMultiselectHash();
     }
   }
+
   _parseProjectionRHS(rbp) {
     let right;
     if (bindingPower[this._lookahead(0)] < 10) {
@@ -3936,6 +4139,7 @@ class Parser {
     }
     return right;
   }
+
   _parseMultiselectList() {
     const expressions = [];
     while (this._lookahead(0) !== TOK_RBRACKET) {
@@ -3951,6 +4155,7 @@ class Parser {
     this._match(TOK_RBRACKET);
     return { type: 'MultiSelectList', children: expressions };
   }
+
   _parseMultiselectHash() {
     const pairs = [];
     const identifierTypes = [TOK_UNQUOTEDIDENTIFIER, TOK_QUOTEDIDENTIFIER];
@@ -3983,6 +4188,20 @@ class Parser {
   }
 }
 
+/*
+Copyright 2021 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+// get the offset in MS, given a date and timezone
+// timezone is an IANA name. e.g. 'America/New_York'
 function offsetMS(dateObj, timeZone) {
   const tzOffset = new Intl.DateTimeFormat('en-US', { timeZone, timeZoneName: 'longOffset' }).format(dateObj);
   const offset = /GMT([+\-−])?(\d{1,2}):?(\d{0,2})?/.exec(tzOffset);
@@ -3991,11 +4210,16 @@ function offsetMS(dateObj, timeZone) {
   const result = (((hours || 0) * 60) + 1 * (minutes || 0)) * 60 * 1000;
   return sign === '-' ? result * -1 : result;
 }
+
 function round(num, digits) {
   const precision = 10 ** digits;
   return Math.round(num * precision) / precision;
 }
+
 const MS_IN_DAY = 24 * 60 * 60 * 1000;
+
+// If we create a non-UTC date, then we need to adjust from the default JavaScript timezone
+// to the default timezone
 function adjustTimeZone(dateObj, timeZone) {
   if (dateObj === null) return null;
   let baseDate = Date.UTC(
@@ -4008,10 +4232,32 @@ function adjustTimeZone(dateObj, timeZone) {
     dateObj.getMilliseconds(),
   );
   baseDate += offsetMS(dateObj, timeZone);
+
+  // get the offset for the default JS environment
+  // return days since the epoch
   return new Date(baseDate);
 }
+
 function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
   return {
+    /**
+     * Returns the logical AND result of all parameters.
+     * If the parameters are not boolean they will be cast to boolean as per the following rules
+     * * null -> false
+     * * number -> false if the number is 0, true otherwise
+     * * string -> false if the string is empty, true otherwise. String "false" resolves to true
+     * * array -> true
+     * * object -> true
+     * @param {any} firstOperand logical expression
+     * @param {...any} [additionalOperands] any number of additional expressions
+     * @returns {boolean} The logical result of applying AND to all parameters
+     * @example
+     * and(10 > 8, length('foo') < 5) // returns true
+     * @example
+     * and(`null`, length('foo') < 5) // returns false
+     * @function
+     * @category openFormula
+     */
     and: {
       _func: resolvedArgs => {
         let result = !!valueOf(resolvedArgs[0]);
@@ -4022,6 +4268,17 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
       },
       _signature: [{ types: [dataTypes.TYPE_ANY], variadic: true }],
     },
+
+    /**
+     * Returns a lower-case string of the `input` string using locale-specific mappings.
+     * e.g. Strings with German lowercase letter 'ß' can be compared to 'ss'
+     * @param {string} input string to casefold
+     * @returns {string} A new string converted to lower case
+     * @function casefold
+     * @example
+     * casefold('AbC') // returns 'abc'
+     * @category JSONFormula
+     */
     casefold: {
       _func: (args, _data, interpreter) => {
         const str = toString(args[0]);
@@ -4031,6 +4288,34 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
+    /**
+     * Return difference between two date values.
+     * @param {number} start_date The starting date.
+     * Dates should be entered by using the [datetime]{@link datetime} function
+     * @param {number} end_date The end date -- must be greater or equal to start_date.
+     * Dates should be entered by using the [datetime]{@link datetime} function
+     * @param {string} unit  One of:
+     * * `y` the number of whole years between start_date and end_date
+     * * `m` the number of whole months between start_date and end_date.
+     * * `d` the number of days between start_date and end_date
+     * * `md` the number of days between start_date and end_date after subtracting whole months.
+     * * `ym` the number of whole months between start_date and end_date
+     * after subtracting whole years.
+     * * `yd` the number of days between start_date and end_date, assuming start_date
+     * and end_date were no more than one year apart
+     * @returns {integer} The number of days/months/years difference
+     * @function
+     * @category openFormula
+     * @example
+     * datedif(datetime(2001, 1, 1), datetime(2003, 1, 1), 'y') // returns 2
+     * @example
+     * datedif(datetime(2001, 6, 1), datetime(2003, 8, 15), 'D') // returns 440
+     * // 440 days between June 1, 2001, and August 15, 2002 (440)
+     * @example
+     * datedif(datetime(2001, 6, 1), datetime(2003, 8, 15), 'YD') // returns 440
+     * // 75 days between June 1 and August 15, ignoring the years of the dates (75)
+     */
     datedif: {
       _func: args => {
         const d1 = toNumber(args[0]);
@@ -4044,6 +4329,7 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         const yearDiff = date2.getFullYear() - date1.getFullYear();
         let monthDiff = date2.getMonth() - date1.getMonth();
         const dayDiff = date2.getDate() - date1.getDate();
+
         if (unit === 'y') {
           let y = yearDiff;
           if (monthDiff < 0) y -= 1;
@@ -4072,6 +4358,32 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
+    /**
+     * Return a date/time value.
+     * @param {integer} year Integer value representing the year.
+     * Values from 0 to 99 map to the years 1900 to 1999. All other values are the actual year
+     * @param {integer} month Integer value representing the month, beginning with 1 for
+     * January to 12 for December.
+     * @param {integer} day Integer value representing the day of the month.
+     * @param {integer} [hours] Integer value between 0 and 23 representing the hour of the day.
+     * Defaults to 0.
+     * @param {integer} [minutes] Integer value representing the minute segment of a time.
+     * The default is 0 minutes past the hour.
+     * @param {integer} [seconds] Integer value representing the second segment of a time.
+     * The default is 0 seconds past the minute.
+     * @param {integer} [milliseconds] Integer value representing the millisecond segment of a time.
+     * The default is 0 milliseconds past the second.
+     * @param {string} [timeZoneName] according to IANA time zone names. e.g. "America/Toronto"
+     * @returns {number} A date/time value represented by number of seconds since 1 January 1970.
+     * @kind function
+     * @function
+     * @category JSONFormula
+     * @example
+     * datetime(2010, 10, 10) // returns representation of October 10, 2010
+     * @example
+     * datetime(2010, 2, 28) // returns representation of February 28, 2010
+     */
     datetime: {
       _func: args => {
         const year = toNumber(args[0]);
@@ -4082,6 +4394,7 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         const seconds = args.length > 5 ? toNumber(args[5]) : 0;
         const ms = args.length > 6 ? toNumber(args[6]) : 0;
         const tz = args.length > 7 ? toString(args[7]) : null;
+        // javascript months starts from 0
         let jsDate = new Date(year, month - 1, day, hours, minutes, seconds, ms);
         if (tz) {
           jsDate = adjustTimeZone(jsDate, tz);
@@ -4099,6 +4412,18 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING], optional: true },
       ],
     },
+
+    /**
+     * Returns the day of a date, represented by a serial number.
+     * The day is given as an integer ranging from 1 to 31.
+     * @param {number} The date of the day you are trying to find.
+     * Dates should be entered by using the [datetime]{@link datetime} function
+     * @return {number}
+     * @function day
+     * @category openFormula
+     * @example
+     * day(datetime(2008,5,23)) //returns 23
+     */
     day: {
       _func: args => {
         const date = toNumber(args[0]);
@@ -4109,6 +4434,19 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Searches a nested hierarchy of objects to return an array of elements that match a `name`.
+     * The name can be either a key into a map or an array index.
+     * This is similar to the JSONPath deep scan operator (..)
+     * @param {object} object The starting object or array where we start the search
+     * @param {string} name The name (or index position) of the elements to find
+     * @returns {any}
+     * @function
+     * @category JSONFormula
+     * @example
+     * deepScan({a : {b1 : {c : 2}, b2 : {c : 3}}}, 'c') //returns [2, 3]
+     */
     deepScan: {
       _func: resolvedArgs => {
         const [source, n] = resolvedArgs;
@@ -4129,6 +4467,16 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING, dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * returns an array of a given object's property `[key, value]` pairs.
+     * @param {object} obj Object whose `[key, value]` pairs need to be extracted
+     * @returns {any[]} an array of [key, value] pairs
+     * @function entries
+     * @category JSONFormula
+     * @example
+     * entries({a: 1, b: 2}) //returns [['a', 1], ['b', 2]]
+     */
     entries: {
       _func: args => {
         const obj = valueOf(args[0]);
@@ -4146,11 +4494,27 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         },
       ],
     },
+
+    /**
+     * Returns the serial number of the end of a month, given `startDate` plus `monthAdd` months
+     * @param {number} startDate The base date to start from.
+     * Dates should be entered by using the [datetime]{@link datetime} function
+     * @param {integer} monthAdd Number of months to add to start date
+     * @return {integer} the number of days in the computed month
+     * @function
+     * @category openFormula
+     * @example
+     * eomonth(datetime(2011, 1, 1), 1) //returns datetime(2011, 2, 28)
+     * @example
+     * eomonth(datetime(2011, 1, 1), -3) //returns datetime(2010, 10, 31)
+     */
     eomonth: {
       _func: args => {
         const date = toNumber(args[0]);
         const months = toNumber(args[1]);
         const jsDate = new Date(date * MS_IN_DAY);
+        // We can give the constructor a month value > 11 and it will increment the years
+        // Since day is 1-based, giving zero will yield the last day of the previous month
         const newDate = new Date(jsDate.getFullYear(), jsDate.getMonth() + months + 1, 0);
         return newDate.getTime() / MS_IN_DAY;
       },
@@ -4159,6 +4523,16 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Returns e (the base of natural logarithms) raised to a power x. (i.e. e<sup>x</sup>)
+     * @param x {number} A numeric expression representing the power of e.
+     * @returns {number} e (the base of natural logarithms) raised to a power x
+     * @function exp
+     * @category openFormula
+     * @example
+     * exp(10) //returns e^10
+     */
     exp: {
       _func: args => {
         const value = toNumber(args[0]);
@@ -4168,10 +4542,37 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Return constant boolean false value.
+     * Note that expressions may also use the JSON literal false: `` `false` ``
+     * @returns {boolean} constant boolean value `false`
+     * @function
+     * @category openFormula
+     */
     false: {
       _func: () => false,
       _signature: [],
     },
+
+    /**
+     * finds and returns the index of query in text from a start position
+     * @param {string} query string to search
+     * @param {string} text text in which the query has to be searched
+     * @param {number} [start] starting position: defaults to 0
+     * @returns {number|null} the index of the query to be searched in the text. If not found
+     * returns null
+     * @function
+     * @category openFormula
+     * @example
+     * find('m', 'abm') //returns 2
+     * @example
+     * find('M', 'abMcdM', 3) //returns 2
+     * @example
+     * find('M', 'ab') //returns `null`
+     * @example
+     * find('M', 'abMcdM', 2) //returns 2
+     */
     find: {
       _func: args => {
         const query = toString(args[0]);
@@ -4189,6 +4590,16 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER], optional: true },
       ],
     },
+
+    /**
+     * returns an object by transforming a list of key-value `pairs` into an object.
+     * @param {any[]} pairs list of key-value pairs to create the object from
+     * @returns {object}
+     * @category JSONFormula
+     * @function fromEntries
+     * @example
+     * fromEntries([['a', 1], ['b', 2]]) //returns {a: 1, b: 2}
+     */
     fromEntries: {
       _func: args => {
         const array = args[0];
@@ -4198,19 +4609,51 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_ARRAY_ARRAY] },
       ],
     },
+
+    /**
+     * Extract the hour (0 through 23) from a time/datetime representation
+     * @param {number} The datetime/time for which the hour is to be returned.
+     * Dates should be specified using the [datetime]{@link datetime} or [time]{@link time} function
+     * @return {number}
+     * @function hour
+     * @category openFormula
+     * @example
+     * hour(datetime(2008,5,23,12, 0, 0)) //returns 12
+     * hour(time(12, 0, 0)) //returns 12
+     */
     hour: {
       _func: args => {
+        // grab just the fraction part
         const time = toNumber(args[0]) % 1;
         if (time < 0) {
           return null;
         }
+        // Normally we'd round to 15 digits, but since we're also multiplying by 24,
+        // a reasonable precision is around 14 digits.
+
         const hour = round(time * 24, 14);
+
         return Math.floor(hour % 24);
       },
       _signature: [
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Return one of two values `result1` or `result2`, depending on the `condition`
+     * @returns {boolean} True
+     * @param {any} condition logical expression to evaluate
+     * @param {any} result1 if logical condition is true
+     * @param {any} result2 if logical condition is false
+     * @return {any} either result1 or result2
+     * @function
+     * @category openFormula
+     * @example
+     * if(true(), 1, 2) // returns 1
+     * @example
+     * if(false(), 1, 2) // returns 2
+     */
     if: {
       _func: (unresolvedArgs, data, interpreter) => {
         const conditionNode = unresolvedArgs[0];
@@ -4227,6 +4670,22 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_ANY] },
         { types: [dataTypes.TYPE_ANY] }],
     },
+
+    /**
+     * Return a selected number of text characters from the left or
+     * in case of array selected number of elements from the start
+     * @param {string|array} subject The text/array of characters/elements to extract.
+     * @param {number} [elements] number of elements to pick. Defaults to 1
+     * @return {string|array}
+     * @function left
+     * @category openFormula
+     * @example
+     * left('Sale Price', 4) //returns 'Sale'
+     * @example
+     * left('Sweden') // returns 'S'
+     * @example
+     * left([4, 5, 6], 2) // returns [4, 5]
+     */
     left: {
       _func: args => {
         const numEntries = args.length > 1 ? toNumber(args[1]) : 1;
@@ -4242,6 +4701,18 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER], optional: true },
       ],
     },
+
+    /**
+     * Converts all the alphabetic characters in a string to lowercase. If the value
+     * is not a string it will be converted into string
+     * using the default toString method
+     * @param {string} input input string
+     * @returns {string} the lower case value of the input string
+     * @function lower
+     * @category openFormula
+     * @example
+     * lower('E. E. Cummings') //returns e. e. cummings
+     */
     lower: {
       _func: args => {
         const value = toString(args[0]);
@@ -4251,6 +4722,27 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
+    /**
+     * Returns extracted text, given an original text, starting position, and length.
+     * or in case of array, extracts a subset of the array from start till the length
+     * number of elements.
+     * Returns null if the `startPos` is greater than the length of the array
+     * @param {string|array} subject the text string or array of characters or elements to extract.
+     * @param {number} startPos the position of the first character or element to extract.
+     * The position starts with 0
+     * @param {number} length The number of characters or elements to return from text. If it
+     * is greater then the length of `subject` the argument is set to the length of the subject.
+     * @return {string|array}
+     * @function mid
+     * @category openFormula
+     * @example
+     * mid("Fluid Flow",1,5) //returns 'Fluid'
+     * @example
+     * mid("Fluid Flow",7,20) //returns 'Flow'
+     * @example
+     * mid("Fluid Flow",20,5) //returns `null`
+     */
     mid: {
       _func: args => {
         const startPos = toNumber(args[1]);
@@ -4268,12 +4760,27 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Extract the minute (0 through 59) from a time/datetime representation
+     * @param {number} The datetime/time for which the minute is to be returned.
+     * Dates should be specified using the [datetime]{@link datetime} or [time]{@link time} function
+     * @return {number}
+     * @function minute
+     * @category openFormula
+     * @example
+     * month(datetime(2008,5,23,12, 10, 0)) //returns 10
+     * month(time(12, 10, 0)) //returns 10
+     */
     minute: {
       _func: args => {
         const time = toNumber(args[0]) % 1;
         if (time < 0) {
           return null;
         }
+
+        // Normally we'd round to 15 digits, but since we're also multiplying by 1440,
+        // a reasonable precision is around 10 digits.
         const minute = Math.round(time * 1440, 10);
         return Math.floor(minute % 60);
       },
@@ -4281,6 +4788,20 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Return the remainder when one number is divided by another number.
+     * The sign is the same as divisor
+     * @param {number} dividend The number for which to find the remainder.
+     * @param {number} divisor The number by which to divide number.
+     * @return {number} Computes the remainder of `dividend`/`divisor`.
+     * @function mod
+     * @category openFormula
+     * @example
+     * mod(3, 2) //returns 1
+     * @example
+     * mod(-3, 2) //returns 1
+     */
     mod: {
       _func: args => {
         const p1 = toNumber(args[0]);
@@ -4292,28 +4813,97 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Returns the month of a date represented by a serial number.
+     * The month is given as an integer, ranging from 1 (January) to 12 (December).
+     * @param {number} The date for which the month is to be returned.
+     * Dates should be entered by using the [datetime]{@link datetime} function
+     * @return {number}
+     * @function month
+     * @category openFormula
+     * @example
+     * month(datetime(2008,5,23)) //returns 5
+     */
     month: {
       _func: args => {
         const date = toNumber(args[0]);
         const jsDate = new Date(date * MS_IN_DAY);
+        // javascript months start from 0ß
         return jsDate.getMonth() + 1;
       },
       _signature: [
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Compute logical NOT of a `value`. If the parameter is not boolean it will be cast to boolean
+     * as per the following rules
+     * * null -> false
+     * * number -> false if the number is 0, true otherwise
+     * * string -> false if the string is empty, true otherwise. String "false" resolves to true
+     * * array -> true
+     * * object -> true
+     * Note that it is also possible to use the logical and operator: `A && B`
+     * @param {any} value - any data type
+     * @returns {boolean} The logical NOT applied to the input parameter
+     * @example
+     * not(length('bar') > 0) // returns false
+     * @example
+     * not(false()) // returns true
+     * @example
+     * not('abcd') // returns false
+     * @example
+     * not('') // returns true
+     * @function
+     * @category openFormula
+     */
     not: {
       _func: resolveArgs => !valueOf(resolveArgs[0]),
       _signature: [{ types: [dataTypes.TYPE_ANY] }],
     },
+
+    /**
+     * returns the time since epoch with days as exponent and time of day as fraction
+     * @return {number} representation of current time as a number
+     * @function now
+     * @category openFormula
+     */
     now: {
       _func: () => Date.now() / MS_IN_DAY,
       _signature: [],
     },
+
+    /**
+     * Return constant null value.
+     * Note that expressions may also use the JSON literal null: `` `null` ``
+     * @returns {boolean} True
+     * @function
+     * @category JSONFormula
+     */
     null: {
       _func: () => null,
       _signature: [],
     },
+
+    /**
+     * Returns the logical OR result of two parameters.
+     * If the parameters are not boolean they will be cast to boolean as per the following rules
+     * * null -> false
+     * * number -> false if the number is 0, true otherwise
+     * * string -> false if the string is empty, true otherwise. String "false" resolves to true
+     * * array -> true
+     * * object -> true
+     * @param {any} first logical expression
+     * @param {...any} [operand] any number of additional expressions
+     * @returns {boolean} The logical result of applying OR to all parameters
+     * @example
+     * or((x / 2) == y, (y * 2) == x)
+     * // true
+     * @function
+     * @category openFormula
+     */
     or: {
       _func: resolvedArgs => {
         let result = !!valueOf(resolvedArgs[0]);
@@ -4324,6 +4914,17 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
       },
       _signature: [{ types: [dataTypes.TYPE_ANY], variadic: true }],
     },
+
+    /**
+     * Computes `a` raised to a power `x`. (a<sup>x</sup>)
+     * @param {number} a The base number. It can be any real number.
+     * @param {number} x The exponent to which the base number is raised.
+     * @return {number}
+     * @function power
+     * @category openFormula
+     * @example
+     * power(10, 2) //returns 100 (10 raised to power 2)
+     */
     power: {
       _func: args => {
         const base = toNumber(args[0]);
@@ -4335,6 +4936,21 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Return the input string with the first letter of each word converted to an
+     * uppercase letter and the rest of the letters in the word converted to lowercase.
+     * @param {string} text the text to partially capitalize.
+     * @returns {string}
+     * @function proper
+     * @category openFormula
+     * @example
+     * proper('this is a TITLE') //returns 'This Is A Title'
+     * @example
+     * proper('2-way street') //returns '2-Way Street'
+     * @example
+     * proper('76BudGet') //returns '76Budget'
+     */
     proper: {
       _func: args => {
         const text = toString(args[0]);
@@ -4347,6 +4963,24 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
+    /**
+     * Returns text where an old text is substituted at a given start position and
+     * length, with a new text.
+     * @param {string} text original text
+     * @param {number} start index in the original text from where to begin the replacement.
+     * @param {number} length number of characters to be replaced
+     * @param {string} replacement string to replace at the start index
+     * @returns {string}
+     * @function replace
+     * @category openFormula
+     * @example
+     * replace('abcdefghijk', 6, 5, '*') //returns abcde*k
+     * @example
+     * replace('2009',3,2,'10') //returns  2010
+     * @example
+     * replace('123456',1,3,'@') //returns @456
+     */
     replace: {
       _func: args => {
         const oldText = toString(args[0]);
@@ -4356,6 +4990,7 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         if (startNum < 0) {
           return null;
         }
+
         const lhs = oldText.substr(0, startNum);
         const rhs = oldText.substr(startNum + numChars);
         return lhs + newText + rhs;
@@ -4367,6 +5002,17 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
+    /**
+     * Return text repeated Count times.
+     * @param {string} text text to repeat
+     * @param {number} count number of times to repeat the text
+     * @returns {string}
+     * @function rept
+     * @category openFormula
+     * @example
+     * rept('x', 5) //returns 'xxxxx'
+     */
     rept: {
       _func: args => {
         const text = toString(args[0]);
@@ -4381,6 +5027,23 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Return a selected number of text characters from the right of a `subject` or
+     * in case of array selected number of elements from the end of `subject` array
+     * Returns null if the number of elements is less than 0
+     * @param {string|array} subject The text/array containing the characters/elements to extract.
+     * @param {number} [elements] number of elements to pick. Defaults to 1
+     * @return {string|array}
+     * @function right
+     * @category openFormula
+     * @example
+     * right('Sale Price', 4) //returns 'rice'
+     * @example
+     * left('Sweden') // returns 'n'
+     * @example
+     * left([4, 5, 6], 2) // returns [5, 6]
+     */
     right: {
       _func: args => {
         const numEntries = args.length > 1 ? toNumber(args[1]) : 1;
@@ -4398,6 +5061,29 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER], optional: true },
       ],
     },
+
+    /**
+     * Round a number to a specified `precision`.
+     * ### Remarks
+     * * If `precision` is greater than zero, round to the specified number of decimal places.
+     * * If `precision` is 0, round to the nearest integer.
+     * * If `precision` is less than 0, round to the left of the decimal point.
+     * @param {number} num number to round off
+     * @param {number} precision number is rounded to the specified precision.
+     * @returns {number}
+     * @function round
+     * @category openFormula
+     * @example
+     * round(2.15, 1) //returns 2.2
+     * @example
+     * round(626.3,-3) //returns 1000 (Rounds 626.3 to the nearest multiple of 1000)
+     * @example
+     * round(626.3, 0) //returns 626
+     * @example
+     * round(1.98,-1) //returns 0 (Rounds 1.98 to the nearest multiple of 10)
+     * @example
+     * round(-50.55,-2) // -100 (round -50.55 to the nearest multiple of 100)
+     */
     round: {
       _func: args => {
         const number = toNumber(args[0]);
@@ -4409,15 +5095,38 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Perform a wildcard search.  The search is case-sensitive and supports two forms of wildcards:
+     * "*" finds a a sequence of characters and "?" finds a single character.
+     * To use "*" or "?" as text values, precede them with a tilde ("~") character.
+     * Note that the wildcard search is not greedy.
+     * e.g. search('a*b', 'abb') will return [0, 'ab'] Not [0, 'abb']
+     * @param {string} findText the search string -- which may include wild cards.
+     * @param {string} withinText The string to search.
+     * @param {integer} startPos The zero-based position of withinText to start searching.
+     * Defaults to zero.
+     * @returns {array} returns an array with two values:
+     * The start position of the found text and the text string that was found.
+     * If a match was not found, an empty array is returned.
+     * @function search
+     * @category openFormula
+     * @example
+     * search('a?c', 'acabc') //returns [2, 'abc']
+     */
     search: {
       _func: args => {
         const findText = toString(args[0]);
         const withinText = toString(args[1]);
         const startPos = toNumber(args[2]);
         if (findText === null || withinText === null || withinText.length === 0) return [];
+        // escape all characters that would otherwise create a regular expression
         const reString = findText.replace(/([[.\\^$()+{])/g, '\\$1')
+          // add the single character wildcard
           .replace(/~?\?/g, match => match === '~?' ? '\\?' : '.')
+          // add the multi-character wildcard
           .replace(/~?\*/g, match => match === '~*' ? '\\*' : '.*?')
+          // get rid of the escape characters
           .replace(/~~/g, '~');
         const re = new RegExp(reString);
         const result = withinText.substring(startPos).match(re);
@@ -4429,13 +5138,28 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING] },
         { types: [dataTypes.TYPE_NUMBER], optional: true },
       ],
+
     },
+    /**
+     * Extract the second (0 through 59) from a time/datetime representation
+     * @param {number} The datetime/time for which the second is to be returned.
+     * Dates should be specified using the [datetime]{@link datetime} or [time]{@link time} function
+     * @return {number}
+     * @function second
+     * @category openFormula
+     * @example
+     * second(datetime(2008,5,23,12, 10, 53)) //returns 53
+     * second(time(12, 10, 53)) //returns 53
+     */
     second: {
       _func: args => {
         const time = toNumber(args[0]) % 1;
         if (time < 0) {
           return null;
         }
+
+        // Normally we'd round to 15 digits, but since we're also multiplying by 86400,
+        // a reasonable precision is around 10 digits.
         const seconds = round(time * 86400, 10);
         return Math.floor(seconds % 60);
       },
@@ -4443,6 +5167,19 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * split a string into an array, given a separator
+     * @param {string} string string to split
+     * @param {string} separator separator where the split should occur
+     * @return {string[]}
+     * @function split
+     * @category openFormula
+     * @example
+     * split('abcdef', '') //returns ['a', 'b', 'c', 'd', 'e', 'f']
+     * @example
+     * split('abcdef', 'e') //returns ['abcd', 'f']
+     */
     split: {
       _func: args => {
         const str = toString(args[0]);
@@ -4454,6 +5191,16 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
+    /**
+     * Return the square root of a number
+     * @param {number} num number whose square root has to be calculated
+     * @return {number}
+     * @function sqrt
+     * @category openFormula
+     * @example
+     * sqrt(4) //returns 2
+     */
     sqrt: {
       _func: args => {
         const result = Math.sqrt(toNumber(args[0]));
@@ -4466,6 +5213,20 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Estimates standard deviation based on a sample.
+     * `stdev` assumes that its arguments are a sample of the entire population.
+     * If your data represents a entire population,
+     * then compute the standard deviation using [stdevp]{@link stdevp}.
+     * @param {number[]} numbers The array of numbers comprising the population
+     * @returns {number}
+     * @category openFormula
+     * @function stdev
+     * @example
+     * stdev([1345, 1301, 1368]) //returns 34.044089061098404
+     * stdevp([1345, 1301, 1368]) //returns 27.797
+     */
     stdev: {
       _func: args => {
         const values = args[0] || [];
@@ -4477,6 +5238,7 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         const sumSquare = coercedValues.reduce((a, b) => a + b * b, 0);
         const result = Math.sqrt((sumSquare - values.length * mean * mean) / (values.length - 1));
         if (Number.isNaN(result)) {
+          // this would never happen
           return null;
         }
         return result;
@@ -4485,6 +5247,20 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_ARRAY_NUMBER] },
       ],
     },
+
+    /**
+     * Calculates standard deviation based on the entire population given as arguments.
+     * `stdevp` assumes that its arguments are the entire population.
+     * If your data represents a sample of the population,
+     * then compute the standard deviation using [stdev]{@link stdev}.
+     * @param {number[]} numbers The array of numbers comprising the population
+     * @returns {number}
+     * @category openFormula
+     * @function stdevp
+     * @example
+     * stdevp([1345, 1301, 1368]) //returns 27.797
+     * stdev([1345, 1301, 1368]) //returns 34.044
+     */
     stdevp: {
       _func: args => {
         const values = args[0] || [];
@@ -4496,6 +5272,7 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         const meanSumSquare = coercedValues.reduce((a, b) => a + b * b, 0) / values.length;
         const result = Math.sqrt(meanSumSquare - mean * mean);
         if (Number.isNaN(result)) {
+          // this would never happen
           return null;
         }
         return result;
@@ -4504,18 +5281,43 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_ARRAY_NUMBER] },
       ],
     },
+
+    /**
+     * Returns input `text`, with text `old` replaced by text `new` (when searching from the left).
+     * If `which` parameter is omitted, every occurrence of `old` is replaced with `new`;
+     * If `which` is provided, only that occurrence of `old` is replaced by `new`
+     * (starting the count from 1).
+     * If there is no match, or if `old` has length 0, `text` is returned unchanged.
+     * Note that `old` and `new` may have different lengths. If `which` < 1, return `text` unchanged
+     * @param {string} text The text for which to substitute characters.
+     * @param {string} old The text to replace.
+     * @param {string} new The text to replace `old` with.
+     * @param {integer} [which] The one-based occurrence of `old` text to replace with `new` text.
+     * @returns {string} replaced string
+     * @function
+     * @category openFormula
+     * @example
+     * substitute('Sales Data', 'Sales', 'Cost') //returns 'Cost Data'
+     * @example
+     * substitute('Quarter 1, 2008', '1', '2', 1) //returns 'Quarter 2, 2008'
+     * @example
+     * substitute('Quarter 1, 1008', '1', '2', 2) //returns 'Quarter 1, 2008'
+     */
     substitute: {
       _func: args => {
         const src = toString(args[0]);
         const old = toString(args[1]);
         const replacement = toString(args[2]);
+        // no third parameter? replace all instances
         if (args.length <= 3) return src.replaceAll(old, replacement);
         const whch = toNumber(args[3]);
         if (whch < 1) return src;
+        // find the instance to replace
         let pos = -1;
         for (let i = 0; i < whch; i += 1) {
           pos += 1;
           const nextFind = src.slice(pos).indexOf(old);
+          // no instance to match 'Which'
           if (nextFind === -1) return src;
           pos += nextFind;
         }
@@ -4528,6 +5330,21 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER], optional: true },
       ],
     },
+
+    /**
+     * Construct and returns time from hours, minutes, and seconds.
+     * @param {integer} hours Integer value between 0 and 23 representing the hour of the day.
+     * Defaults to 0.
+     * @param {integer} minutes Integer value representing the minute segment of a time.
+     * The default is 0 minutes past the hour.
+     * @param {integer} seconds Integer value representing the second segment of a time.
+     * The default is 0 seconds past the minute.
+     * @return {number} Returns the fraction of the day consumed by the given time
+     * @function time
+     * @category openFormula
+     * @example
+     * time(12, 0, 0) //returns 0.5 (half day)
+     */
     time: {
       _func: args => {
         const hours = toNumber(args[0]);
@@ -4545,23 +5362,65 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * returns the number of days since epoch
+     * @return number
+     * @function today
+     * @category openFormula
+     */
     today: {
       _func: () => Math.floor(Date.now() / MS_IN_DAY),
       _signature: [],
     },
+
+    /**
+     * Remove leading and trailing spaces, and replace all internal multiple spaces
+     * with a single space.
+     * @param {string} text string to trim
+     * @return {string} removes all leading and trailing space.
+     * Any other sequence of 2 or more spaces is replaced with a single space.
+     * @function trim
+     * @category openFormula
+     * @example
+     * trim('   ab    c   ') //returns 'ab c'
+     */
     trim: {
       _func: args => {
         const text = toString(args[0]);
+        // only removes the space character
+        // other whitespace characters like \t \n left intact
         return text.split(' ').filter(x => x).join(' ');
       },
       _signature: [
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
+    /**
+     * Return constant boolean true value.
+     * Note that expressions may also use the JSON literal true: `` `true` ``
+     * @returns {boolean} True
+     * @function
+     * @category openFormula
+     */
     true: {
       _func: () => true,
       _signature: [],
     },
+
+    /**
+     * Truncates a number to an integer by removing the fractional part of the number.
+     * @param {number} numA number to truncate
+     * @param {number} [numB] A number specifying the precision of the truncation. Default is 0
+     * @return {number}
+     * @function trunc
+     * @category openFormula
+     * @example
+     * trunc(8.9) //returns 8
+     * trunc(-8.9) //returns -8
+     * trunc(8.912, 2) //returns 8.91
+     */
     trunc: {
       _func: args => {
         const number = toNumber(args[0]);
@@ -4574,8 +5433,20 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER], optional: true },
       ],
     },
+
+    /**
+     * takes an array and returns unique elements within it
+     * @param {array} input input array
+     * @return {array} array with duplicate elements removed
+     * @function unique
+     * @category JSONFormula
+     * @example
+     * unique([1, 2, 3, 4, 1, 1, 2]) //returns [1, 2, 3, 4]
+     */
     unique: {
       _func: args => {
+        // create an array of values for searching.  That way if the array elements are
+        // represented by objects with a valueOf(), then we'll locate them in the valueArray
         const valueArray = args[0].map(a => valueOf(a));
         return args[0].filter((v, index) => valueArray.indexOf(valueOf(v)) === index);
       },
@@ -4583,6 +5454,18 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_ARRAY] },
       ],
     },
+
+    /**
+     * Converts all the alphabetic characters in a string to uppercase.
+     * If the value is not a string it will be converted into string
+     * using the default toString method
+     * @param {string} input input string
+     * @returns {string} the upper case value of the input string
+     * @function upper
+     * @category openFormula
+     * @example
+     * upper('abcd') //returns 'ABCD'
+     */
     upper: {
       _func: args => {
         const value = toString(args[0]);
@@ -4592,6 +5475,19 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
+    /**
+     * Perform an indexed lookup on a map or array
+     * @param {map | array} object on which to perform the lookup
+     * @param {string | integer} index: a named child for a map or an integer offset for an array
+     * @returns {any} the result of the lookup -- or `null` if not found.
+     * @function
+     * @category JSONFormula
+     * @example
+     * value({a: 1, b:2, c:3}, a) //returns 1
+     * @example
+     * value([1, 2, 3, 4], 2) //returns 3
+     */
     value: {
       _func: args => {
         const obj = args[0] || {};
@@ -4601,6 +5497,7 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
           debug.push(`Failed to find: '${index}'`);
           const available = Object.keys(obj).map(a => `'${a}'`).toString();
           if (available.length) debug.push(`Available fields: ${available}`);
+
           return null;
         }
         return result;
@@ -4610,18 +5507,43 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING, dataTypes.TYPE_NUMBER] },
       ],
     },
+
+    /**
+     * Extract the day of the week from a date; if text, uses current locale to convert to a date.
+     * @param {number} The datetime for which the day of the week is to be returned.
+     * Dates should be entered by using the [datetime]{@link datetime} function
+     * @param {number} [returnType] A number that determines the
+     * numeral representation (a number from 0 to 7) of the
+     * day of week. Default is 1. Supports the following values
+     * * 1 : Sunday (1), Monday (2), ..., Saturday (7)
+     * * 2 : Monday (1), Tuesday (2), ..., Sunday(7)
+     * * 3 : Monday (0), Tuesday (2), ...., Sunday(6)
+     * @returns {number} day of the week
+     * @function weekday
+     * @category openFormula
+     * @example
+     * weekday(datetime(2006,5,21)) // 1
+     * @example
+     * weekday(datetime(2006,5,21), 2) // 7
+     * @example
+     * weekday(datetime(2006,5,21), 3) // 6
+     */
     weekday: {
       _func: args => {
         const date = toNumber(args[0]);
         const type = args.length > 1 ? toNumber(args[1]) : 1;
         const jsDate = new Date(date * MS_IN_DAY);
         const day = jsDate.getDay();
+        // day is in range [0-7) with 0 mapping to sunday
         switch (type) {
           case 1:
+            // range = [1, 7], sunday = 1
             return day + 1;
           case 2:
+            // range = [1, 7] sunday = 7
             return ((day + 6) % 7) + 1;
           case 3:
+            // range = [0, 6] sunday = 6
             return (day + 6) % 7;
           default:
             return null;
@@ -4632,6 +5554,17 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER], optional: true },
       ],
     },
+
+    /**
+     * Returns the year of a date represented by a serial number.
+     * @param {number} The date for which the year is to be returned.
+     * Dates should be entered by using the [datetime]{@link datetime} function
+     * @return {number}
+     * @function year
+     * @category openFormula
+     * @example
+     * year(datetime(2008,5,23)) //returns 2008
+     */
     year: {
       _func: args => {
         const date = toNumber(args[0]);
@@ -4642,6 +5575,7 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
     charCode: {
       _func: args => {
         const code = toNumber(args[0]);
@@ -4654,6 +5588,7 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_NUMBER] },
       ],
     },
+
     codePoint: {
       _func: args => {
         const text = toString(args[0]);
@@ -4666,24 +5601,28 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
     encodeUrlComponent: {
       _func: args => encodeURIComponent(args[0]),
       _signature: [
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
     encodeUrl: {
       _func: args => encodeURI(args[0]),
       _signature: [
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
     decodeUrlComponent: {
       _func: args => decodeURIComponent(args[0]),
       _signature: [
         { types: [dataTypes.TYPE_STRING] },
       ],
     },
+
     decodeUrl: {
       _func: args => decodeURI(args[0]),
       _signature: [
@@ -4693,6 +5632,27 @@ function openFormulaFunctions(valueOf, toString, toNumber, debug = []) {
   };
 }
 
+/*
+Copyright 2014 James Saryerwinnie
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+NOTICE:
+This file is substantially modified from the original source taken from:
+https://github.com/jmespath/jmespath.js
+
+*/
+
 function functions(
   runtime,
   isObject,
@@ -4715,6 +5675,7 @@ function functions(
     TYPE_ARRAY_NUMBER,
     TYPE_ARRAY_STRING,
   } = dataTypes;
+
   function createKeyFunction(exprefNode, allowedTypes) {
     return x => {
       const current = runtime.interpreter.visit(exprefNode, x);
@@ -4726,11 +5687,46 @@ function functions(
       return current;
     };
   }
+
   const functionMap = {
+    // name: [function, <signature>]
+    // The <signature> can be:
+    //
+    // {
+    //   args: [[type1, type2], [type1, type2]],
+    //   variadic: true|false
+    // }
+    //
+    // Each arg in the arg list is a list of valid types
+    // (if the function is overloaded and supports multiple
+    // types.  If the type is "any" then no type checking
+    // occurs on the argument.  Variadic is optional
+    // and if not provided is assumed to be false.
+    /**
+     * Returns the absolute value of the provided argument `value`.
+     * @param {number} value argument whose absolute value has to be returned
+     * @return {number} returns the absolute value of the `value` argument
+     * @function abs
+     * @example
+     * abs(-1) //returns 1
+     * @category jmespath
+     */
     abs: {
       _func: resolvedArgs => Math.abs(resolvedArgs[0]),
       _signature: [{ types: [TYPE_NUMBER] }],
     },
+    /**
+     * Returns the average of the elements in the provided array.
+     * An empty array will produce a return value of `null`.
+     * @param {number[]} elements array of elements whose average has to be computed
+     * @return {number} average value
+     * @function avg
+     * @example
+     * avg([]) //returns null
+     * @example
+     * avg([1, 2, 3]) //returns 2
+     * @category jmespath
+     */
     avg: {
       _func: resolvedArgs => {
         let sum = 0;
@@ -4742,15 +5738,59 @@ function functions(
       },
       _signature: [{ types: [TYPE_ARRAY_NUMBER] }],
     },
+
+    /**
+     * Returns the next highest integer value of the argument `num` by rounding up if necessary.
+     * @param {number} num number whose next highest integer value has to be computed
+     * @return {number}
+     * @function ceil
+     * @example
+     * ceil(10) //returns 10
+     * @example
+     * ceil(10.4) //return 11
+     * @category jmespath
+     */
     ceil: {
       _func: resolvedArgs => Math.ceil(resolvedArgs[0]),
       _signature: [{ types: [TYPE_NUMBER] }],
     },
+    /**
+     * Returns true if the given `subject` contains the provided `search` string.
+     * If `subject` is an array, this function returns true if one of the elements
+     * in the array is equal to the provided `search` value. If the provided `subject`
+     *  is a string, this function returns true if the string contains the provided
+     * `search` argument.
+     * @param {array|string} subject the subject in which the element has to be searched
+     * @param {string|boolean|number|date} search element to search
+     * @return {boolean}
+     * @function contains
+     * @example
+     * contains([1, 2, 3, 4], 2) //returns true
+     * @example
+     * contains([1, 2, 3, 4], -1) //returns false
+     * @example
+     * contains('Abcd', 'd') //returns true
+     * @example
+     * contains('Abcd', 'x') //returns false
+     * @category jmespath
+     */
     contains: {
       _func: resolvedArgs => valueOf(resolvedArgs[0]).indexOf(valueOf(resolvedArgs[1])) >= 0,
       _signature: [{ types: [TYPE_STRING, TYPE_ARRAY] },
         { types: [TYPE_ANY] }],
     },
+    /**
+     * Returns true if the `subject` ends with the `suffix`, otherwise this function returns false.
+     * @param {string} subject subject in which the `suffix` is being searched for
+     * @param {string} suffix suffix to search in the subject
+     * @return {boolean}
+     * @function endsWith
+     * @example
+     * endsWith('Abcd', 'd') //returns true
+     * @example
+     * endsWith('Abcd', 'A') //returns false
+     * @category jmespath
+     */
     endsWith: {
       _func: resolvedArgs => {
         const searchStr = valueOf(resolvedArgs[0]);
@@ -4759,10 +5799,34 @@ function functions(
       },
       _signature: [{ types: [TYPE_STRING] }, { types: [TYPE_STRING] }],
     },
+
+    /**
+     * Returns the next lowest integer value of the argument `num` by rounding down if necessary.
+     * @param {number} num number whose next lowest integer value has to be returned
+     * @return {number}
+     * @function floor
+     * @example
+     * floor(10.4) //returns 10
+     * @example
+     * floor(10) //returns 10
+     * @category jmespath
+     */
     floor: {
       _func: resolvedArgs => Math.floor(resolvedArgs[0]),
       _signature: [{ types: [TYPE_NUMBER] }],
     },
+
+    /**
+     * Returns all the elements from the provided `stringsarray`
+     * array joined together using the `glue` argument as a separator between each.
+     * @param {string} glue
+     * @param {string[]} stringsarray
+     * @return {string}
+     * @function join
+     * @example
+     * join(',', ['a', 'b', 'c']) //returns 'a,b,c'
+     * @category jmespath
+     */
     join: {
       _func: resolvedArgs => {
         const joinChar = resolvedArgs[0];
@@ -4774,6 +5838,17 @@ function functions(
         { types: [TYPE_ARRAY_STRING] },
       ],
     },
+
+    /**
+     * Returns an array containing the keys of the provided object `obj`. If the passed
+     * object is null, the value returned is an empty array
+     * @param {object} obj the object whose keys need to be extracted
+     * @return {array}
+     * @function keys
+     * @example
+     * keys({a : 3, b : 4}) //returns ['a', 'b']
+     * @category jmespath
+     */
     keys: {
       _func: resolvedArgs => {
         if (resolvedArgs[0] === null) return [];
@@ -4781,14 +5856,54 @@ function functions(
       },
       _signature: [{ types: [TYPE_ANY] }],
     },
+
+    /**
+     * Returns the length of the given argument `subject` using the following types rules:
+     * * string: returns the number of code points in the string
+     * * array: returns the number of elements in the array
+     * * object: returns the number of key-value pairs in the object
+     * @param {string | array | object} subject subject whose length has to be calculated
+     * @return {number}
+     * @function length
+     * @example
+     * length([]) //returns 0
+     * @example
+     * length('') //returns 0
+     * @example
+     * length('abcd') //returns 4
+     * @example
+     * length([1, 2, 3, 4]) //returns 4
+     * @example
+     * length({}) // returns 0
+     * @example
+     * length({a : 3, b : 4}) //returns 2
+     * @category jmespath
+     */
     length: {
       _func: resolvedArgs => {
         const arg = valueOf(resolvedArgs[0]);
         if (isObject(arg)) return Object.keys(arg).length;
+
         return isArray(arg) ? arg.length : toString(arg).length;
       },
       _signature: [{ types: [TYPE_STRING, TYPE_ARRAY, TYPE_OBJECT] }],
     },
+
+    /**
+     * Apply the `expr` to every element in the `elements` array and return the array of results.
+     * An elements of length N will produce a return array of length N. Unlike a projection,
+     * `[*].bar`, `map()` will include the result of applying the `expr` for every element
+     * in the elements array, even if the result is `null`.
+     * @param {expression} expr expression to evaluate on each element
+     * @param {array} elements array of elements on which the expression will be evaluated
+     * @return {array}
+     * @function map
+     * @example
+     * map(&(@ + 1), [1, 2, 3, 4]) // returns [2, 3, 4, 5]
+     * @example
+     * map(&length(@), ['doe', 'nick', 'chris']) // returns [3,4, 5]
+     * @category jmespath
+     */
     map: {
       _func: resolvedArgs => {
         const exprefNode = resolvedArgs[0];
@@ -4796,15 +5911,35 @@ function functions(
       },
       _signature: [{ types: [TYPE_EXPREF] }, { types: [TYPE_ARRAY] }],
     },
+
+    /**
+     * Returns the highest value in the provided `collection` arguments.
+     * If all collections are empty `null` is returned.
+     * max() can work on numbers or strings.
+     * If a mix of numbers and strings are provided, the type of the first value will be used.
+     * @param {number[]|string[]} collection array in which the maximum element is to be calculated
+     * @return {number}
+     * @function max
+     * @example
+     * max([1, 2, 3], [4, 5, 6], 7) //returns 7
+     * @example
+     * max([]) // returns null
+     * @example
+     * max(['a', 'a1', 'b']) // returns 'b'
+     * @category jmespath
+     */
     max: {
       _func: args => {
+        // flatten the args into a single array
         const array = args.reduce((prev, cur) => {
           if (Array.isArray(cur)) prev.push(...cur);
           else prev.push(cur);
           return prev;
         }, []);
+
         const first = array.find(r => r !== null);
         if (array.length === 0 || first === undefined) return null;
+        // use the first value to determine the comparison type
         const isNumber = getTypeName(first, true) === TYPE_NUMBER;
         const compare = isNumber
           ? (prev, cur) => {
@@ -4815,10 +5950,25 @@ function functions(
             const current = toString(cur);
             return prev.localeCompare(current) === 1 ? prev : current;
           };
+
         return array.reduce(compare, isNumber ? toNumber(first) : toString(first));
       },
       _signature: [{ types: [TYPE_ARRAY, TYPE_ARRAY_NUMBER, TYPE_ARRAY_STRING], variadic: true }],
     },
+
+    /**
+     * Returns the maximum element in an array using the expression `expr` as the comparison key.
+     * The entire element is returned.
+     * @param {array} elements the array in which the maximum element is to be found
+     * @param {expression} expr the expr to use as the `comparison` key
+     * @return {any}
+     * @function maxBy
+     * @example
+     * maxBy(['abcd', 'e', 'def'], &length(@)) //returns 'abcd'
+     * @example
+     * maxBy([{year: 2010}, {year: 2020}, {year: 1910}], &year) //returns {year: 2020}
+     * @category jmespath
+     */
     maxBy: {
       _func: resolvedArgs => {
         const exprefNode = resolvedArgs[1];
@@ -4838,6 +5988,22 @@ function functions(
       },
       _signature: [{ types: [TYPE_ARRAY] }, { types: [TYPE_EXPREF] }],
     },
+
+    /**
+     * Accepts 0 or more objects as arguments, and returns a single object with
+     * subsequent objects merged. Each subsequent object’s key/value pairs are
+     * added to the preceding object. This function is used to combine multiple
+     * objects into one. You can think of this as the first object being the base object,
+     * and each subsequent argument being overrides that are applied to the base object.
+     * @param {...object} args
+     * @return {object}
+     * @function merge
+     * @example
+     * merge({a: 1, b: 2}, {c : 3, d: 4}) // returns {a :1, b: 2, c: 3, d: 4}
+     * @example
+     * merge({a: 1, b: 2}, {a : 3, d: 4}) // returns {a :3, b: 2, d: 4}
+     * @category jmespath
+     */
     merge: {
       _func: resolvedArgs => {
         const merged = {};
@@ -4850,15 +6016,35 @@ function functions(
       },
       _signature: [{ types: [TYPE_OBJECT], variadic: true }],
     },
+
+    /**
+     * Returns the lowest value in the provided `collection` arguments.
+     * If all collections are empty `null` is returned.
+     * min() can work on numbers or strings.
+     * If a mix of numbers and strings are provided, the type of the first value will be used.
+     * @param {number[]|string[]} collection array in which the minimum element is to be calculated
+     * @return {number}
+     * @function min
+     * @example
+     * min([1, 2, 3], [4, 5, 6], 7) //returns 1
+     * @example
+     * min([]) // returns null
+     * @example
+     * min(['a', 'a1', 'b']) // returns 'a'
+     * @category jmespath
+     */
     min: {
       _func: args => {
+        // flatten the args into a single array
         const array = args.reduce((prev, cur) => {
           if (Array.isArray(cur)) prev.push(...cur);
           else prev.push(cur);
           return prev;
         }, []);
+
         const first = array.find(r => r !== null);
         if (array.length === 0 || first === undefined) return null;
+        // use the first value to determine the comparison type
         const isNumber = getTypeName(first, true) === TYPE_NUMBER;
         const compare = isNumber
           ? (prev, cur) => {
@@ -4869,10 +6055,25 @@ function functions(
             const current = toString(cur);
             return prev.localeCompare(current) === 1 ? current : prev;
           };
+
         return array.reduce(compare, isNumber ? toNumber(first) : toString(first));
       },
       _signature: [{ types: [TYPE_ARRAY, TYPE_ARRAY_NUMBER, TYPE_ARRAY_STRING], variadic: true }],
     },
+
+    /**
+     * Returns the minimum element in `elements` array using the expression `expr`
+     * as the comparison key.
+     * @param {array} elements
+     * @param {expression} expr expression that returns either a string or a number
+     * @return {any}
+     * @function minBy
+     * @example
+     * minBy(['abcd', 'e', 'def'], &length(@)) //returns 'e'
+     * @example
+     * minBy([{year: 2010}, {year: 2020}, {year: 1910}], &year) //returns {year: 1910}
+     * @category jmespath
+     */
     minBy: {
       _func: resolvedArgs => {
         const exprefNode = resolvedArgs[1];
@@ -4892,10 +6093,48 @@ function functions(
       },
       _signature: [{ types: [TYPE_ARRAY] }, { types: [TYPE_EXPREF] }],
     },
+
+    /**
+     * Returns the first argument that does not resolve to `null`.
+     * This function accepts one or more arguments, and will evaluate
+     * them in order until a non null argument is encounted. If all
+     * arguments values resolve to null, then a value of null is returned.
+     * @param {...any} argument
+     * @return {any}
+     * @function notNull
+     * @example
+     * notNull(1, 2, 3, 4, `null`) //returns 1
+     * @example
+     * notNull(`null`, 2, 3, 4, `null`) //returns 2
+     * @category jmespath
+     */
     notNull: {
       _func: resolvedArgs => resolvedArgs.find(arg => getTypeName(arg) !== TYPE_NULL) || null,
       _signature: [{ types: [TYPE_ANY], variadic: true }],
     },
+
+    /**
+     * executes a user-supplied reducer expression `expr` on each element of the
+     * array, in order, passing in the return value from the calculation on the preceding element.
+     * The final result of running the reducer across all elements of the `elements` array is a
+     * single value.
+     * The expression can access the following properties
+     * * accumulated: accumulated value based on the previous calculations. Initial value is `null`
+     * * current: current element to process
+     * * index: index of the `current` element in the array
+     * * array: original array
+     * @param {expression} expr reducer expr to be executed on each element
+     * @param {array} elements array of elements on which the expression will be evaluated
+     * @return {any}
+     * @function reduce
+     * @example
+     * reduce(&(accumulated + current), [1, 2, 3]) //returns 6
+     * @example
+     * reduce(&(accumulated - current), [3, 3, 3]) //returns -9
+     * @example
+     * reduce(&if(accumulated == `null`, current, accumulated * current), [3, 3, 3]) //returns 27
+     * @category jmespath
+     */
     reduce: {
       _func: resolvedArgs => {
         const exprefNode = resolvedArgs[0];
@@ -4912,10 +6151,23 @@ function functions(
         { types: [TYPE_ANY], optional: true },
       ],
     },
+
+    /**
+     * Register a function to allow code re-use.  The registered function may take one parameter.
+     * If more parameters are needed, combine them in an array or map.
+     * @param {string} functionName Name of the function to register
+     * @param {expression} expr Expression to execute with this function call
+     * @return {{}} returns an empty object
+     * @function register
+     * @example
+     * register('product', &@[0] * @[1]) // can now call: product([2,21]) => returns 42
+     * @category jmespath
+     */
     register: {
       _func: resolvedArgs => {
         const functionName = resolvedArgs[0];
         const exprefNode = resolvedArgs[1];
+
         if (functionMap[functionName]) {
           debug.push(`Cannot re-register '${functionName}'`);
           return {};
@@ -4931,6 +6183,15 @@ function functions(
         { types: [TYPE_EXPREF] },
       ],
     },
+    /**
+     * Reverses the order of the `argument`.
+     * @param {string|array} argument
+     * @return {array}
+     * @function reverse
+     * @example
+     * reverse(['a', 'b', 'c']) //returns ['c', 'b', 'a']
+     * @category jmespath
+     */
     reverse: {
       _func: resolvedArgs => {
         const originalStr = valueOf(resolvedArgs[0]);
@@ -4948,6 +6209,18 @@ function functions(
       },
       _signature: [{ types: [TYPE_STRING, TYPE_ARRAY] }],
     },
+
+    /**
+     * This function accepts an array `list` argument and returns the sorted elements of
+     * the `list` as an array. The array must be a list of strings or numbers.
+     * Sorting strings is based on code points. Locale is not taken into account.
+     * @param {number[]|string[]} list
+     * @return {number[]|string[]}
+     * @function sort
+     * @example
+     * sort([1, 2, 4, 3, 1]) // returns [1, 1, 2, 3, 4]
+     * @category jmespath
+     */
     sort: {
       _func: resolvedArgs => {
         const sortedArray = resolvedArgs[0].slice(0);
@@ -4965,6 +6238,24 @@ function functions(
       },
       _signature: [{ types: [TYPE_ARRAY, TYPE_ARRAY_STRING, TYPE_ARRAY_NUMBER] }],
     },
+
+    /**
+     * Sort an array using an expression `expr` as the sort key. For each element
+     * in the array of elements, the `expr` expression is applied and the resulting
+     * value is used as the key used when sorting the elements. If the result of
+     * evaluating the `expr` against the current array element results in type
+     * other than a number or a string, a type error will occur.
+     * @param {array} elements
+     * @param {expression} expr
+     * @return {array}
+     * @function sortBy
+     * @example
+     * sortBy(['abcd', 'e', 'def'], &length(@)) //returns ['e', 'def', 'abcd']
+     * @example
+     * // returns [{year: 1910}, {year: 2010}, {year: 2020}]
+     * sortBy([{year: 2010}, {year: 2020}, {year: 1910}], &year)
+     * @category jmespath
+     */
     sortBy: {
       _func: resolvedArgs => {
         const sortedArray = resolvedArgs[0].slice(0);
@@ -4978,6 +6269,13 @@ function functions(
         if ([TYPE_NUMBER, TYPE_STRING].indexOf(requiredType) < 0) {
           throw new Error('TypeError');
         }
+        // In order to get a stable sort out of an unstable
+        // sort algorithm, we decorate/sort/undecorate (DSU)
+        // by creating a new list of [index, element] pairs.
+        // In the cmp function, if the evaluated elements are
+        // equal, then the index will be used as the tiebreaker.
+        // After the decorated list has been sorted, it will be
+        // undecorated to extract the original elements.
         const decorated = [];
         for (let i = 0; i < sortedArray.length; i += 1) {
           decorated.push([i, sortedArray[i]]);
@@ -5002,8 +6300,12 @@ function functions(
           if (exprA < exprB) {
             return -1;
           }
+          // If they're equal compare the items by their
+          // order to maintain relative order of equal keys
+          // (i.e. to get a stable sort).
           return a[0] - b[0];
         });
+        // Undecorate: extract out the original list elements.
         for (let j = 0; j < decorated.length; j += 1) {
           [, sortedArray[j]] = decorated[j];
         }
@@ -5011,10 +6313,32 @@ function functions(
       },
       _signature: [{ types: [TYPE_ARRAY] }, { types: [TYPE_EXPREF] }],
     },
+
+    /**
+     * Returns true if the `subject` starts with the `prefix`, otherwise returns false.
+     * @param {string} subject subject in which the `prefix` is being searched for
+     * @param {string} prefix prefix to search in the subject
+     * @return {boolean}
+     * @function startsWith
+     * @example
+     * startsWith('jack is at home', 'jack') // returns true
+     * @category jmespath
+     */
     startsWith: {
       _func: resolvedArgs => valueOf(resolvedArgs[0]).startsWith(valueOf(resolvedArgs[1])),
       _signature: [{ types: [TYPE_STRING] }, { types: [TYPE_STRING] }],
     },
+
+    /**
+     * Returns the sum of the provided `collection` array argument.
+     * An empty array will produce a return value of 0.
+     * @param {number[]} collection array whose element's sum has to be computed
+     * @return {number}
+     * @function sum
+     * @example
+     * sum([1, 2, 3]) //returns 6
+     * @category jmespath
+     */
     sum: {
       _func: resolvedArgs => {
         let sum = 0;
@@ -5025,6 +6349,20 @@ function functions(
       },
       _signature: [{ types: [TYPE_ARRAY_NUMBER] }],
     },
+
+    /**
+     * converts the passed `arg` to an array. The conversion happens as per the following rules
+     * * array - Returns the passed in value.
+     * * number/string/object/boolean - Returns a one element array containing the argument.
+     * @param {any} arg
+     * @return {array}
+     * @function toArray
+     * @example
+     * toArray(1) // returns [1]
+     * @example
+     * toArray(null()) // returns [`null`]
+     * @category jmespath
+     */
     toArray: {
       _func: resolvedArgs => {
         if (getTypeName(resolvedArgs[0]) === TYPE_ARRAY) {
@@ -5032,8 +6370,31 @@ function functions(
         }
         return [resolvedArgs[0]];
       },
+
       _signature: [{ types: [TYPE_ANY] }],
     },
+
+    /**
+     * converts the passed arg to a number. The conversion happens as per the following rules
+     * * string - Returns the parsed number.
+     * * number - Returns the passed in value.
+     * * array - null
+     * * object - null
+     * * boolean - null
+     * * null - null
+     * @param {any} arg
+     * @return {number}
+     * @function toNumber
+     * @example
+     * toNumber(1) //returns 1
+     * @example
+     * toNumber('10') //returns 10
+     * @example
+     * toNumber({a: 1}) //returns null
+     * @example
+     * toNumber(true()) //returns null
+     * @category jmespath
+     */
     toNumber: {
       _func: resolvedArgs => {
         const typeName = getTypeName(resolvedArgs[0]);
@@ -5047,6 +6408,20 @@ function functions(
       },
       _signature: [{ types: [TYPE_ANY] }],
     },
+
+    /**
+     * converts the passed `arg` to a string. The conversion happens as per the following rules
+     * * string - Returns the passed in value.
+     * * number/array/object/boolean - The JSON encoded value of the object.
+     * @param {any} arg
+     * @return {string}
+     * @function toString
+     * @example
+     * toString(1) //returns '1'
+     * @example
+     * toString(true()) //returns 'true'
+     * @category jmespath
+     */
     toString: {
       _func: resolvedArgs => {
         if (getTypeName(resolvedArgs[0]) === TYPE_STRING) {
@@ -5054,8 +6429,30 @@ function functions(
         }
         return JSON.stringify(resolvedArgs[0]);
       },
+
       _signature: [{ types: [TYPE_ANY] }],
     },
+
+    /**
+     * Returns the JavaScript type of the given `subject` argument as a string value.
+     *
+     * The return value MUST be one of the following:
+     * * number
+     * * string
+     * * boolean
+     * * array
+     * * object
+     * * null
+     * @param {any} subject
+     * @return {string}
+     *
+     * @function type
+     * @example
+     * type(1) //returns 'number'
+     * @example
+     * type('') //returns 'string'
+     * @category jmespath
+     */
     type: {
       _func: resolvedArgs => ({
         [TYPE_NUMBER]: 'number',
@@ -5068,6 +6465,18 @@ function functions(
       }[getTypeName(resolvedArgs[0])]),
       _signature: [{ types: [TYPE_ANY] }],
     },
+
+    /**
+     * Returns the values of the provided object `obj`. Note that because JSON hashes are
+     * inherently unordered, the values associated with the provided object obj are
+     * inherently unordered.
+     * @param {object} obj
+     * @return {array}
+     * @function values
+     * @example
+     * values({a : 3, b : 4}) //returns [3, 4]
+     * @category jmespath
+     */
     values: {
       _func: resolvedArgs => {
         const arg = valueOf(resolvedArgs[0]);
@@ -5076,6 +6485,19 @@ function functions(
       },
       _signature: [{ types: [TYPE_ANY] }],
     },
+
+    /**
+     * Returns a convolved (zipped) array containing grouped arrays of values from
+     * the array arguments from index 0, 1, 2, etc.
+     * This function accepts a variable number of arguments.
+     * The length of the returned array is equal to the length of the shortest array.
+     * @param {...array} arrays array of arrays to zip together
+     * @return {array} An array of arrays with elements zipped together
+     * @function zip
+     * @example
+     * zip([1, 2, 3], [4, 5, 6]) //returns [[1, 4], [2, 5], [3, 6]]
+     * @category jmespath
+     */
     zip: {
       _func: args => {
         const count = args.reduce((min, current) => Math.min(min, current.length), args[0].length);
@@ -5094,13 +6516,17 @@ function functions(
   return functionMap;
 }
 
+/* eslint-disable max-classes-per-file */
+
+// Type constants used to define functions.
 const {
   TYPE_CLASS,
   TYPE_ANY,
 } = dataTypes;
+
 function getToNumber(stringToNumber, debug = []) {
   return value => {
-    const n = getValueOf(value);
+    const n = getValueOf(value); // in case it's an object that implements valueOf()
     if (n === null) return null;
     if (n instanceof Array) {
       debug.push('Converted array to zero');
@@ -5116,20 +6542,26 @@ function getToNumber(stringToNumber, debug = []) {
 }
 function toString(a) {
   if (a === null || a === undefined) return '';
+  // don't call a 'toString' method, since we could have a child named 'toString()'
   return a.toString();
 }
+
 const defaultStringToNumber = (str => {
   const n = +str;
   return Number.isNaN(n) ? 0 : n;
 });
+
 function isClass(obj) {
   if (obj === null) return false;
   if (Array.isArray(obj)) return false;
   return obj.constructor.name !== 'Object';
 }
+
 function matchClass(arg, expectedList) {
+  // checking isClass() generates a dependency -- so call it only if necessary
   return expectedList.includes(TYPE_CLASS) && isClass(arg);
 }
+
 class Runtime {
   constructor(debug, toNumber, customFunctions = {}) {
     this.strictDeepEqual = strictDeepEqual;
@@ -5144,16 +6576,25 @@ class Runtime {
       toString,
       debug,
     );
+
     Object.entries(
       openFormulaFunctions(getValueOf, toString, toNumber, debug),
     ).forEach(([fname, func]) => {
       this.functionTable[fname] = func;
     });
+
     Object.entries(customFunctions).forEach(([fname, func]) => {
       this.functionTable[fname] = func;
     });
   }
+
+  // eslint-disable-next-line class-methods-use-this
   _validateArgs(argName, args, signature, bResolved) {
+    // Validating the args requires validating
+    // the correct arity and the correct type of each arg.
+    // If the last argument is declared as variadic, then we need
+    // a minimum number of args to be required.  Otherwise it has to
+    // be an exact amount.
     if (signature.length === 0) {
       return;
     }
@@ -5172,31 +6613,39 @@ class Runtime {
       + `takes ${signature.length}${pluralized
       } but received ${args.length}`);
     }
+    // if the arguments are unresolved, there's no point in validating types
     if (!bResolved) return;
     let currentSpec;
     let actualType;
     const limit = Math.min(signature.length, args.length);
     for (let i = 0; i < limit; i += 1) {
       currentSpec = signature[i].types;
+      // Try to avoid checks that will introspect the object and generate dependencies
       if (!matchClass(args[i], currentSpec) && !currentSpec.includes(TYPE_ANY)) {
         actualType = getTypeNames(args[i]);
+        // eslint-disable-next-line no-param-reassign
         args[i] = matchType(actualType, currentSpec, args[i], argName, this.toNumber, toString);
       }
     }
   }
+
   callFunction(name, resolvedArgs, data, interpreter, bResolved = true) {
+    // this check will weed out 'valueOf', 'toString' etc
     if (!Object.prototype.hasOwnProperty.call(this.functionTable, name)) throw new Error(`Unknown function: ${name}()`);
+
     const functionEntry = this.functionTable[name];
     this._validateArgs(name, resolvedArgs, functionEntry._signature, bResolved);
     return functionEntry._func.call(this, resolvedArgs, data, interpreter);
   }
 }
+
 class Formula {
   constructor(debug, customFunctions, stringToNumberFn) {
     this.debug = debug;
     this.toNumber = getToNumber(stringToNumberFn || defaultStringToNumber, debug);
     this.runtime = new Runtime(debug, this.toNumber, customFunctions);
   }
+
   compile(stream, allowedGlobalNames = []) {
     let ast;
     try {
@@ -5208,7 +6657,11 @@ class Formula {
     }
     return ast;
   }
+
   search(node, data, globals = {}, language = 'en-US') {
+    // This needs to be improved.  Both the interpreter and runtime depend on
+    // each other.  The runtime needs the interpreter to support exprefs.
+    // There's likely a clean way to avoid the cyclic dependency.
     this.runtime.interpreter = new TreeInterpreter(
       this.runtime,
       globals,
@@ -5217,6 +6670,7 @@ class Formula {
       this.debug,
       language,
     );
+
     try {
       return this.runtime.interpreter.search(node, data);
     } catch (e) {
@@ -5226,7 +6680,33 @@ class Formula {
   }
 }
 
+/*
+Copyright 2021 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * Returns an instance of JSON JsonFormula Expression that can be executed later on with
+ * multiple instances of JSON Data. The instance of the class has a single search
+ * function that can be used to evaluate the expression on a json payload. The advantage
+ * of using this over {jsonJsonFormula} function is that it can be performant if a single expression
+ * has to be used for multiple json data instances.
+ */
 class JsonFormula {
+  /**
+   * @param customFunctions {*} custom functions needed by a hosting application.
+   * @param stringToNumber {function} A function that converts string values to numbers.
+   * Can be used to convert currencies/dates to numbers
+   * @param language
+   * @param debug {array} will be populated with any errors/warnings
+   */
   constructor(
     customFunctions = {},
     stringToNumber = null,
@@ -5237,10 +6717,25 @@ class JsonFormula {
     this.debug = debug;
     this.formula = new Formula(debug, customFunctions, stringToNumber);
   }
+
+  /**
+   * Evaluates the JsonFormula on a particular json payload and return the result
+   * @param json {object} the json data on which the expression needs to be evaluated
+   * @param globals {*} global objects that can be accessed via custom functions.
+   * @returns {*} the result of the expression being evaluated
+   */
   search(expression, json, globals = {}, language = 'en-US') {
     const ast = this.compile(expression, Object.keys(globals));
     return this.run(ast, json, language, globals);
   }
+
+  /**
+   * Execute a previously compiled expression against a json object and return the result
+   * @param ast {object} The abstract syntax tree returned from compile()
+   * @param json {object} the json data on which the expression needs to be evaluated
+   * @param globals {*} set of objects available in global scope
+   * @returns {*} the result of the expression being evaluated
+   */
   run(ast, json, language, globals) {
     return this.formula.search(
       ast,
@@ -5249,6 +6744,14 @@ class JsonFormula {
       language,
     );
   }
+
+  /*
+   * Creates a compiled expression that can be executed later on with some data.
+   * @param expression {string} the expression to evaluate
+   * @param allowedGlobalNames {string[]} A list of names of the global variables
+   * being used in the expression.
+   * @param debug {array} will be populated with any errors/warnings
+   */
   compile(expression, allowedGlobalNames = []) {
     this.debug.length = 0;
     return this.formula.compile(expression, allowedGlobalNames);
@@ -5301,8 +6804,7 @@ class RuleEngine {
 }
 
 const defaults = {
-    visible: true,
-    enabled: true
+    visible: true
 };
 class Fieldset extends Container {
     constructor(params, _options) {
@@ -5345,6 +6847,12 @@ class Fieldset extends Container {
     }
 }
 
+var __decorate$1 = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
 class InstanceManager extends Fieldset {
     get maxOccur() {
         return this._jsonModel.maxItems;
@@ -5362,22 +6870,13 @@ class InstanceManager extends Fieldset {
         return this.removeItem(action);
     }
 }
-__decorate([
+__decorate$1([
     dependencyTracked()
 ], InstanceManager.prototype, "maxOccur", null);
-__decorate([
+__decorate$1([
     dependencyTracked()
 ], InstanceManager.prototype, "minOccur", null);
 
-class ValidationError {
-    fieldName;
-    errorMessages;
-    constructor(fieldName = '', errorMessages = []) {
-        this.errorMessages = errorMessages;
-        this.fieldName = fieldName;
-    }
-}
-
 const dateRegex = /^(\d{4})-(\d{1,2})-(\d{1,2})$/;
 const days = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
 const daysInMonth = (leapYear, month) => {
@@ -5651,9 +7150,33 @@ const Constraints = {
     }
 };
 
+/*************************************************************************
+ * ADOBE CONFIDENTIAL
+ * ___________________
+ *
+ *  Copyright 2022 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  All information contained herein is, and remains
+ * the property of Adobe and its suppliers, if any. The intellectual
+ * and technical concepts contained herein are proprietary to Adobe
+ * and its suppliers and are protected by all applicable intellectual
+ * property laws, including trade secret and copyright laws.
+ * Dissemination of this information or reproduction of this material
+ * is strictly forbidden unless prior written permission is obtained
+ * from Adobe.
+ **************************************************************************/
+/**
+ * https://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
+ * Credit: https://git.corp.adobe.com/dc/dfl/blob/master/src/patterns/parseDateTimeSkeleton.js
+ * Created a separate library to be used elsewhere as well.
+ */
 const DATE_TIME_REGEX =
+    // eslint-disable-next-line max-len
     /(?:[Eec]{1,6}|G{1,5}|[Qq]{1,5}|(?:[yYur]+|U{1,5})|[ML]{1,5}|d{1,2}|D{1,3}|F{1}|[abB]{1,5}|[hkHK]{1,2}|w{1,2}|W{1}|m{1,2}|s{1,2}|[zZOvV]{1,5}|[zZOvVxX]{1,3}|S{1,3}|'(?:[^']|'')*')|[^a-zA-Z']+/g;
+
 const ShorthandStyles$1 = ["full", "long", "medium", "short"];
+
 function getSkeleton(skeleton, language) {
     if (ShorthandStyles$1.find(type => skeleton.includes(type))) {
         const parsed = parseDateStyle(skeleton, language);
@@ -5674,13 +7197,24 @@ function getSkeleton(skeleton, language) {
     }
     return skeleton;
 }
+
+/**
+ *
+ * @param skeleton shorthand style for the date concatenated with shorthand style of time. The
+ * Shorthand style for both date and time is one of ['full', 'long', 'medium', 'short'].
+ * @param language {string} language to parse the date shorthand style
+ * @returns {[*,string][]}
+ */
 function parseDateStyle(skeleton, language) {
     const options = {};
+    // the skeleton could have two keywords -- one for date, one for time
     const styles = skeleton.split(/\s/).filter(s => s.length);
     options.dateStyle = styles[0];
     if (styles.length > 1) options.timeStyle = styles[1];
+
     const testDate = new Date(2000, 2, 1, 2, 3, 4);
     const parts = new Intl.DateTimeFormat(language, options).formatToParts(testDate);
+    // oddly, the formatted month name can be different from the standalone month name
     const formattedMarch = parts.find(p => p.type === 'month').value;
     const longMarch = new Intl.DateTimeFormat(language, {month: 'long'}).formatToParts(testDate)[0].value;
     const shortMarch = new Intl.DateTimeFormat(language, {month: 'short'}).formatToParts(testDate)[0].value;
@@ -5704,6 +7238,11 @@ function parseDateStyle(skeleton, language) {
     });
     return result;
 }
+
+/**
+ * Parse Date time skeleton into Intl.DateTimeFormatOptions parts
+ * Ref: https://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
+ */
 function parseDateTimeSkeleton(skeleton, language) {
     if (ShorthandStyles$1.find(type => skeleton.includes(type))) {
         return parseDateStyle(skeleton, language);
@@ -5712,9 +7251,11 @@ function parseDateTimeSkeleton(skeleton, language) {
     skeleton.replace(DATE_TIME_REGEX, match => {
         const len = match.length;
         switch (match[0]) {
+            // Era
             case 'G':
                 result.push(['era', len === 4 ? 'long' : len === 5 ? 'narrow' : 'short', len]);
                 break;
+            // Year
             case 'y':
                 result.push(['year', len === 2 ? '2-digit' : 'numeric', len]);
                 break;
@@ -5725,13 +7266,16 @@ function parseDateTimeSkeleton(skeleton, language) {
                 throw new RangeError(
                     '`Y/u/U/r` (year) patterns are not supported, use `y` instead'
                 );
+            // Quarter
             case 'q':
             case 'Q':
                 throw new RangeError('`q/Q` (quarter) patterns are not supported');
+            // Month
             case 'M':
             case 'L':
                 result.push(['month', ['numeric', '2-digit', 'short', 'long', 'narrow'][len - 1], len]);
                 break;
+            // Week
             case 'w':
             case 'W':
                 throw new RangeError('`w/W` (week) patterns are not supported');
@@ -5744,6 +7288,7 @@ function parseDateTimeSkeleton(skeleton, language) {
                 throw new RangeError(
                     '`D/F/g` (day) patterns are not supported, use `d` instead'
                 );
+            // Weekday
             case 'E':
                 result.push(['weekday', ['short', 'short', 'short', 'long', 'narrow', 'narrow'][len - 1], len]);
                 break;
@@ -5759,14 +7304,16 @@ function parseDateTimeSkeleton(skeleton, language) {
                 }
                 result.push(['weekday', ['short', 'long', 'narrow', 'short'][len - 3], len]);
                 break;
-            case 'a':
+            // Period
+            case 'a': // AM, PM
                 result.push(['hour12', true, 1]);
                 break;
-            case 'b':
-            case 'B':
+            case 'b': // am, pm, noon, midnight
+            case 'B': // flexible day periods
                 throw new RangeError(
                     '`b/B` (period) patterns are not supported, use `a` instead'
                 );
+            // Hour
             case 'h':
                 result.push(['hourCycle', 'h12']);
                 result.push(['hour', ['numeric', '2-digit'][len - 1], len]);
@@ -5789,9 +7336,11 @@ function parseDateTimeSkeleton(skeleton, language) {
                 throw new RangeError(
                     '`j/J/C` (hour) patterns are not supported, use `h/H/K/k` instead'
                 );
+            // Minute
             case 'm':
                 result.push(['minute', ['numeric', '2-digit'][len - 1], len]);
                 break;
+            // Second
             case 's':
                 result.push(['second', ['numeric', '2-digit'][len - 1], len]);
                 break;
@@ -5802,19 +7351,23 @@ function parseDateTimeSkeleton(skeleton, language) {
                 throw new RangeError(
                     '`S/A` (millisecond) patterns are not supported, use `s` instead'
                 );
-            case 'O':
+            // Zone
+            case 'O': // timeZone GMT-8 or GMT-08:00
                 result.push(['timeZoneName', len < 4 ? 'shortOffset' : 'longOffset', len]);
                 result.push(['x-timeZoneName', len < 4 ? 'O' : 'OOOO', len]);
                 break;
-            case 'X':
-            case 'x':
-            case 'Z':
+            case 'X': // 1, 2, 3, 4: The ISO8601 varios formats
+            case 'x': // 1, 2, 3, 4: The ISO8601 varios formats
+            case 'Z': // 1..3, 4, 5: The ISO8601 varios formats
+                // Z, ZZ, ZZZ should produce -0800
+                // ZZZZ should produce GMT-08:00
+                // ZZZZZ should produce -8:00 or -07:52:58
                 result.push(['timeZoneName', 'longOffset', 1]);
                 result.push(['x-timeZoneName', match, 1]);
                 break;
-            case 'z':
-            case 'v':
-            case 'V':
+            case 'z': // 1..3, 4: specific non-location format
+            case 'v': // 1, 4: generic non-location format
+            case 'V': // 1, 2, 3, 4: time zone ID or city
                 throw new RangeError(
                     'z/v/V` (timeZone) patterns are not supported, use `X/x/Z/O` instead'
                 );
@@ -5829,6 +7382,29 @@ function parseDateTimeSkeleton(skeleton, language) {
     return result;
 }
 
+/*************************************************************************
+ * ADOBE CONFIDENTIAL
+ * ___________________
+ *
+ *  Copyright 2022 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  All information contained herein is, and remains
+ * the property of Adobe and its suppliers, if any. The intellectual
+ * and technical concepts contained herein are proprietary to Adobe
+ * and its suppliers and are protected by all applicable intellectual
+ * property laws, including trade secret and copyright laws.
+ * Dissemination of this information or reproduction of this material
+ * is strictly forbidden unless prior written permission is obtained
+ * from Adobe.
+ **************************************************************************/
+
+/**
+ * in some cases, DateTimeFormat doesn't respect the 'numeric' vs. '2-digit' setting
+ * for time values. The function corrects that
+ * @param formattedParts instance of Intl.DateTimeFormatPart[]
+ * @param parsed
+ */
 function fixDigits(formattedParts, parsed) {
     ['hour', 'minute', 'second'].forEach(type => {
         const defn = formattedParts.find(f => f.type === type);
@@ -5838,29 +7414,55 @@ function fixDigits(formattedParts, parsed) {
         if (fmt === 'numeric' && defn.value.length === 2 && defn.value.charAt(0) === '0') defn.value = defn.value.slice(1);
     });
 }
+
 function fixYear(formattedParts, parsed) {
+    // two digit years are handled differently in DateTimeFormat. 00 becomes 1900
+    // providing a two digit year 0010 gets formatted to 10 and when parsed becomes 1910
+    // Hence we need to pad the year with 0 as required by the skeleton and mentioned in
+    // unicode. https://www.unicode.org/reports/tr35/tr35-dates.html#dfst-year
     const defn = formattedParts.find(f => f.type === 'year');
     if (!defn) return;
+    // eslint-disable-next-line no-unused-vars
     const chars = parsed.find(pair => pair[0] === 'year')[2];
     while(defn.value.length < chars) {
         defn.value = `0${defn.value}`;
     }
 }
+
+/**
+ *
+ * @param dateValue {Date}
+ * @param language {string}
+ * @param skeleton {string}
+ * @param timeZone {string}
+ * @returns {T}
+ */
 function formatDateToParts(dateValue, language, skeleton, timeZone) {
+    // DateTimeFormat renames some of the options in its formatted output
+    //@ts-ignore
     const mappings = key => ({
         hour12: 'dayPeriod',
         fractionalSecondDigits: 'fractionalSecond',
     })[key] || key;
+
+    // produces an array of name/value pairs of skeleton parts
     const allParameters = parseDateTimeSkeleton(skeleton, language);
     allParameters.push(['timeZone', timeZone]);
+
     const parsed = allParameters.filter(p => !p[0].startsWith('x-'));
     const nonStandard = allParameters.filter(p => p[0].startsWith('x-'));
+    // reduce to a set of options that can be used to format
     const options = Object.fromEntries(parsed);
     delete options.literal;
+
     const df = new Intl.DateTimeFormat(language, options);
+    // formattedParts will have all the pieces we need for our date -- but not in the correct order
     const formattedParts = df.formatToParts(dateValue);
+
     fixDigits(formattedParts, allParameters);
     fixYear(formattedParts, parsed);
+    // iterate through the original parsed components and use its ordering and literals,
+    // and add  the formatted pieces
     return parsed.reduce((result, cur) => {
         if (cur[0] === 'literal') result.push(cur);
         else {
@@ -5870,25 +7472,37 @@ function formatDateToParts(dateValue, language, skeleton, timeZone) {
                 const category = tz[0];
                 if (category === 'Z') {
                     if (tz.length < 4) {
+                        // handle 'Z', 'ZZ', 'ZZZ' Time Zone: ISO8601 basic hms? / RFC 822
                         v.value = v.value.replace(/(GMT|:)/g, '');
                         if (v.value === '') v.value = '+0000';
                     } else if (tz.length === 5) {
+                        // 'ZZZZZ' Time Zone: ISO8601 extended hms?
                         if (v.value === 'GMT') v.value = 'Z';
                         else v.value = v.value.replace(/GMT/, '');
                     }
                 }
                 if (category === 'X' || category === 'x') {
                     if (tz.length === 1) {
+                        // 'X' ISO8601 basic hm?, with Z for 0
+                        // -08, +0530, Z
+                        // 'x' ISO8601 basic hm?, without Z for 0
                         v.value = v.value.replace(/(GMT|:(00)?)/g, '');
                     }
                     if (tz.length === 2) {
+                        // 'XX' ISO8601 basic hm, with Z
+                        // -0800, Z
+                        // 'xx' ISO8601 basic hm, without Z
                         v.value = v.value.replace(/(GMT|:)/g, '');
                     }
                     if (tz.length === 3) {
+                        // 'XXX' ISO8601 extended hm, with Z
+                        // -08:00, Z
+                        // 'xxx' ISO8601 extended hm, without Z
                         v.value = v.value.replace(/GMT/g, '');
                     }
                     if (category === 'X' && v.value === '') v.value = 'Z';
                 } else if (tz === 'O') {
+                    // eliminate 'GMT', leading and trailing zeros
                     v.value = v.value.replace(/GMT/g, '').replace(/0(\d+):/, '$1:').replace(/:00/, '');
                     if (v.value === '') v.value = '+0';
                 }
@@ -5898,12 +7512,18 @@ function formatDateToParts(dateValue, language, skeleton, timeZone) {
         return result;
     }, []);
 }
+
+/**
+ *
+ * @param dateValue {Date}
+ * @param language {string}
+ * @param skeleton {string}
+ * @param timeZone {string}
+ */
 function formatDate(dateValue, language, skeleton, timeZone) {
-    if (skeleton.startsWith('date|')) {
-        skeleton = skeleton.split('|')[1];
-    }
     if (ShorthandStyles$1.find(type => skeleton.includes(type))) {
         const options = {timeZone};
+        // the skeleton could have two keywords -- one for date, one for time
         const parts = skeleton.split(/\s/).filter(s => s.length);
         if (ShorthandStyles$1.indexOf(parts[0]) > -1) {
             options.dateStyle = parts[0];
@@ -5939,7 +7559,9 @@ const currencies = {
   'ru-RU': 'RUB',
   'tr-TR': 'TRY'
 };
+
 const locales = Object.keys(currencies);
+
 const getCurrency = function (locale) {
   if (locales.indexOf(locale) > -1) {
     return currencies[locale]
@@ -5953,7 +7575,8 @@ const getCurrency = function (locale) {
 };
 
 const NUMBER_REGEX =
-    /(?:[#]+|[@]+(#+)?|[0]+|[,]|[.]|[-]|[+]|[%]|[¤]{1,4}(?:\/([a-zA-Z]{3}))?|[;]|[K]{1,2}|E{1,2}[+]?|'(?:[^']|'')*')|[^a-zA-Z']+/g;
+    // eslint-disable-next-line max-len
+    /(?:[#]+|[@]+(?:#+)?|[0]+|[,]|[.]|[-]|[+]|[%]|[¤]{1,4}(?:\/([a-zA-Z]{3}))?|[;]|[K]{1,2}|E{1,2}[+]?|'(?:[^']|'')*')|[^a-zA-Z']+/g;
 const supportedUnits = ['acre', 'bit', 'byte', 'celsius', 'centimeter', 'day',
     'degree', 'fahrenheit', 'fluid-ounce', 'foot', 'gallon', 'gigabit',
     'gigabyte', 'gram', 'hectare', 'hour', 'inch', 'kilobit', 'kilobyte',
@@ -5961,6 +7584,8 @@ const supportedUnits = ['acre', 'bit', 'byte', 'celsius', 'centimeter', 'day',
     'mile-scandinavian', 'milliliter', 'millimeter', 'millisecond', 'minute', 'month',
     'ounce', 'percent', 'petabyte', 'pound', 'second', 'stone', 'terabit', 'terabyte', 'week', 'yard', 'year'].join('|');
 const ShorthandStyles = [/^currency(?:\/([a-zA-Z]{3}))?$/, /^decimal$/, /^integer$/,  /^percent$/, new RegExp(`^unit\/(${supportedUnits})$`)];
+
+
 function parseNumberSkeleton(skeleton, language) {
     const options = {};
     const order = [];
@@ -5989,7 +7614,6 @@ function parseNumberSkeleton(skeleton, language) {
                 break;
             case 4:
                 options.style = 'percent';
-                options.maximumFractionDigits = 2;
                 break;
             case 5:
                 options.style = "unit";
@@ -6006,7 +7630,7 @@ function parseNumberSkeleton(skeleton, language) {
     options.minimumIntegerDigits = 1;
     options.maximumFractionDigits = 0;
     options.minimumFractionDigits = 0;
-    skeleton.replace(NUMBER_REGEX, (match, maxSignificantDigits, currencySymbol, offset) => {
+    skeleton.replace(NUMBER_REGEX, (match, offset) => {
         const len = match.length;
         switch(match[0]) {
             case '#':
@@ -6019,10 +7643,10 @@ function parseNumberSkeleton(skeleton, language) {
                 if (options?.minimumSignificantDigits) {
                     throw "@ symbol should occur together"
                 }
-                const hashes = maxSignificantDigits || "";
-                order.push(['@', len - hashes.length]);
-                options.minimumSignificantDigits = len - hashes.length;
-                options.maximumSignificantDigits = len;
+                order.push(['@', len]);
+                options.minimumSignificantDigits = len;
+                const hashes = match.match(/#+/) || "";
+                options.maximumSignificantDigits = len + hashes.length;
                 order.push(['digit', hashes.length]);
                 break;
             case ',':
@@ -6047,9 +7671,6 @@ function parseNumberSkeleton(skeleton, language) {
                 }
                 if (options?.decimal === true) {
                     options.minimumFractionDigits = len;
-                    if (!options.maximumFractionDigits) {
-                        options.maximumFractionDigits = len;
-                    }
                 } else {
                     options.minimumIntegerDigits = len;
                 }
@@ -6073,20 +7694,18 @@ function parseNumberSkeleton(skeleton, language) {
             case '¤':
                 if (offset !== 0 && offset !== skeleton.length - 1) {
                     console.error("currency display should be either in the beginning or at the end");
-                } else {
-                    options.style = 'currency';
-                    options.currencyDisplay = ['symbol', 'code', 'name', 'narrowSymbol'][len - 1];
-                    options.currency = currencySymbol || getCurrency(language);
-                    order.push(['currency', len]);
                 }
+                options.style = 'currency';
+                options.currencyDisplay = ['symbol', 'code', 'name', 'narrowSymbol'][len -1];
+                options.currency = getCurrency(language);
+                order.push(['currency', len]);
                 break;
             case '%':
                 if (offset !== 0 && offset !== skeleton.length - 1) {
                     console.error("percent display should be either in the beginning or at the end");
-                } else {
-                    order.push(['%', 1]);
-                    options.style = 'percent';
                 }
+                order.push(['%', 1]);
+                options.style = 'percent';
                 break;
             case 'E':
                 order.push(['E', len]);
@@ -6103,9 +7722,6 @@ function parseNumberSkeleton(skeleton, language) {
 }
 
 function formatNumber(numberValue, language, skeletn) {
-    if (skeletn.startsWith('num|')) {
-        skeletn = skel.split('|')[1];
-    }
     if (!skeletn) return numberValue
     language = language || "en";
     const {options, order} = parseNumberSkeleton(skeletn, language);
@@ -6116,6 +7732,7 @@ const getCategory = function (skeleton) {
     const chkCategory = skeleton?.match(/^(?:(num|date)\|)?(.+)/);
     return [chkCategory?.[1], chkCategory?.[2]]
 };
+
 const format = function (value, locale, skeleton, timezone) {
     const [category, skelton] = getCategory(skeleton);
     switch (category) {
@@ -6131,6 +7748,12 @@ const format = function (value, locale, skeleton, timezone) {
     }
 };
 
+var __decorate = (undefined && undefined.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
 const validTypes = ['string', 'number', 'boolean', 'file', 'string[]', 'number[]', 'boolean[]', 'file[]', 'array', 'object'];
 class Field extends Scriptable {
     constructor(params, _options) {
@@ -6279,10 +7902,10 @@ class Field extends Scriptable {
         }
     }
     get editFormat() {
-        return this.withCategory(this._jsonModel.editFormat);
+        return this._jsonModel.editFormat;
     }
     get displayFormat() {
-        return this.withCategory(this._jsonModel.displayFormat);
+        return this._jsonModel.displayFormat;
     }
     get placeholder() {
         return this._jsonModel.placeholder;
@@ -6355,43 +7978,31 @@ class Field extends Scriptable {
         return this._jsonModel.value === undefined || this._jsonModel.value === null || this._jsonModel.value === '';
     }
     withCategory(df) {
-        if (df) {
-            const hasCategory = df?.match(/^(?:date|num)\|/);
-            if (hasCategory === null) {
-                if (this.format === 'date') {
-                    df = `date|${df}`;
-                }
-                else if (this.type === 'number') {
-                    df = `num|${df}`;
-                }
-                return df;
+        const hasCategory = df?.match(/^(?:date|num)\|/);
+        if (hasCategory == null) {
+            if (this.format === 'date') {
+                df = `date|${df}`;
+            }
+            else if (this.type === 'number') {
+                df = `num|${df}`;
             }
+            return df;
         }
         return df;
     }
     get editValue() {
-        const df = this.editFormat;
+        const df = this.withCategory(this.editFormat);
         if (df && this.isNotEmpty(this.value) && this.valid !== false) {
-            try {
-                return format(this.value, this.language, df);
-            }
-            catch (e) {
-                return this.value;
-            }
+            return format(this.value, this.language, df);
         }
         else {
             return this.value;
         }
     }
     get displayValue() {
-        const df = this.displayFormat;
+        const df = this.withCategory(this.displayFormat);
         if (df && this.isNotEmpty(this.value) && this.valid !== false) {
-            try {
-                return format(this.value, this.language, df);
-            }
-            catch (e) {
-                return this.value;
-            }
+            return format(this.value, this.language, df);
         }
         else {
             return this.value;
@@ -6531,7 +8142,7 @@ class Field extends Scriptable {
             const iv = this._jsonModel.minimum || this._jsonModel.default || 0;
             const fIVal = iv * factor;
             const qt = (fVal - fIVal) / fStep;
-            const valid = Math.abs(fVal - fIVal) % fStep < .001;
+            const valid = (fVal - fIVal) % fStep < .001;
             let next, prev;
             if (!valid) {
                 next = (Math.ceil(qt) * fStep + fIVal) / factor;
@@ -6734,8 +8345,6 @@ class Field extends Scriptable {
     getState() {
         return {
             ...super.getState(),
-            editFormat: this.editFormat,
-            displayFormat: this.displayFormat,
             editValue: this.editValue,
             displayValue: this.displayValue
         };