@openmrs/esm-form-engine-lib 2.1.0-pre.1510 → 2.1.0-pre.1511

package/src/utils/expression-runner.test.ts

@@ -1,7 +1,6 @@
 import { registerExpressionHelper } from '..';
 import { type FormField } from '../types';
-import { CommonExpressionHelpers } from './common-expression-helpers';
-import { checkReferenceToResolvedFragment, evaluateExpression, type ExpressionContext } from './expression-runner';
+import { evaluateAsyncExpression, evaluateExpression, type ExpressionContext } from './expression-runner';
 
 export const testFields: Array<FormField> = [
   {
@@ -79,7 +78,100 @@ export const testFields: Array<FormField> = [
   },
 ];
 
-describe('Common expression runner - evaluateExpression', () => {
+export const fields: Array<FormField> = [
+  {
+    label: 'No Interest',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'radio',
+      concept: 'no_interest_concept',
+      answers: [],
+    },
+    id: 'no_interest',
+  },
+  {
+    label: 'Depressed',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'radio',
+      concept: 'depressed_concept',
+      answers: [],
+    },
+    id: 'depressed',
+  },
+  {
+    label: 'Bad Sleep',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'radio',
+      concept: 'bad_sleep_concept',
+      answers: [],
+    },
+    id: 'bad_sleep',
+  },
+  {
+    label: 'Feeling Tired',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'radio',
+      concept: 'feeling_tired_concept',
+      answers: [],
+    },
+    id: 'feeling_tired',
+  },
+  {
+    label: 'Poor Appetite',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'radio',
+      concept: 'poor_appetite_concept',
+      answers: [],
+    },
+    id: 'poor_appetite',
+  },
+  {
+    label: 'Troubled',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'radio',
+      concept: 'troubled_concept',
+      answers: [],
+    },
+    id: 'troubled',
+  },
+  {
+    label: 'Feeling Bad',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'radio',
+      concept: 'feeling_bad_concept',
+      answers: [],
+    },
+    id: 'feeling_bad',
+  },
+  {
+    label: 'Speaking Slowly',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'radio',
+      concept: 'speaking_slowly_concept',
+      answers: [],
+    },
+    id: 'speaking_slowly',
+  },
+  {
+    label: 'Better Off Dead',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'radio',
+      concept: 'better_dead_concept',
+      answers: [],
+    },
+    id: 'better_dead',
+  },
+];
+
+describe('Expression runner', () => {
   const context: ExpressionContext = { mode: 'enter', patient: {} };
   const allFields = JSON.parse(JSON.stringify(testFields));
   let valuesMap = {
@@ -88,6 +180,15 @@ describe('Common expression runner - evaluateExpression', () => {
     htsProviderRemarks: '',
     referredToPreventionServices: [],
     bodyTemperature: 0,
+    no_interest: '',
+    depressed: '',
+    bad_sleep: '',
+    feeling_tired: '',
+    poor_appetite: '',
+    troubled: '',
+    feeling_bad: '',
+    speaking_slowly: '',
+    better_dead: '',
   };
 
   afterEach(() => {
@@ -98,24 +199,37 @@ describe('Common expression runner - evaluateExpression', () => {
       htsProviderRemarks: '',
       referredToPreventionServices: [],
       bodyTemperature: 0,
+      no_interest: '',
+      depressed: '',
+      bad_sleep: '',
+      feeling_tired: '',
+      poor_appetite: '',
+      troubled: '',
+      feeling_bad: '',
+      speaking_slowly: '',
+      better_dead: '',
     };
     allFields.forEach((field) => {
       field.fieldDependents = undefined;
     });
   });
 
-  it('should evaluate basic boolean strings', () => {
+  it('should support unary expressions', () => {
     // replay and verify
     expect(
       evaluateExpression('true', { value: allFields[0], type: 'field' }, allFields, valuesMap, context),
     ).toBeTruthy();
     // replay and verify
     expect(
-      evaluateExpression('false', { value: allFields[0], type: 'field' }, allFields, valuesMap, context),
+      evaluateExpression('!true', { value: allFields[0], type: 'field' }, allFields, valuesMap, context),
     ).toBeFalsy();
+    // replay and verify
+    expect(
+      evaluateExpression('!false', { value: allFields[0], type: 'field' }, allFields, valuesMap, context),
+    ).toBeTruthy();
   });
 
-  it('should support two dimension expressions', () => {
+  it('should support binary expressions', () => {
     // replay and verify
     expect(
       evaluateExpression(
@@ -140,46 +254,42 @@ describe('Common expression runner - evaluateExpression', () => {
     ).toBeTruthy();
   });
 
-  it('should support multiple dimession expressions', () => {
-    // replay and verify
-    expect(
-      evaluateExpression(
-        "linkedToCare == 'cf82933b-3f3f-45e7-a5ab-5d31aaee3da3' && htsProviderRemarks !== '' && bodyTemperature >= 39",
-        { value: allFields[1], type: 'field' },
-        allFields,
-        valuesMap,
-        context,
-      ),
-    ).toBeFalsy();
-    // provide some values
-    valuesMap['linkedToCare'] = 'cf82933b-3f3f-45e7-a5ab-5d31aaee3da3';
-    valuesMap['htsProviderRemarks'] = 'Some test remarks...';
-    valuesMap['bodyTemperature'] = 40;
-    // replay and verify
-    expect(
-      evaluateExpression(
-        "linkedToCare == 'cf82933b-3f3f-45e7-a5ab-5d31aaee3da3' && htsProviderRemarks !== '' && bodyTemperature >= 39",
-        { value: allFields[1], type: 'field' },
-        allFields,
-        valuesMap,
-        context,
-      ),
-    ).toBeTruthy();
+  it('should support complex expressions', () => {
+    // setup
+    valuesMap.bad_sleep = 'a53f32bc-6904-4692-8a4c-fb7403cf0306';
+    valuesMap.better_dead = '296b39ec-06c5-4310-8f30-d2c9f083fb71';
+    valuesMap.depressed = '5eb5852d-3d29-41f9-b2ff-d194e062003d';
+    valuesMap.feeling_bad = '349260db-8e0f-4c06-be92-5120b3708d1e';
+    valuesMap.feeling_tired = '0ea1378d-04eb-4e7e-908b-26d8c27d37e1';
+    valuesMap.troubled = '57766c65-6548-486b-9dad-0fedf531ed7d';
+
+    const expression =
+      "(no_interest === 'b631d160-8d40-4cf7-92cd-67f628c889e8' ? 1 : isEmpty(no_interest) ? 2 : no_interest === '8ff1f85c-4f04-4f5b-936a-5aa9320cb66e' ? 3 : 0) + (depressed === 'b631d160-8d40-4cf7-92cd-67f628c889e8' ? 1 : depressed === '5eb5852d-3d29-41f9-b2ff-d194e062003d' ? 2 :  depressed==='8ff1f85c-4f04-4f5b-936a-5aa9320cb66e' ? 3 : 0) + (bad_sleep === 'a53f32bc-6904-4692-8a4c-fb7403cf0306' ? 1 : bad_sleep === '234259ec-5368-4488-8482-4f261cc76714' ? 2 : bad_sleep === '8ff1f85c-4f04-4f5b-936a-5aa9320cb66e' ? 3 : 0) + (feeling_tired === 'b631d160-8d40-4cf7-92cd-67f628c889e8' ? 1 : feeling_tired === '234259ec-5368-4488-8482-4f261cc76714' ? 2 : feeling_tired === '0ea1378d-04eb-4e7e-908b-26d8c27d37e1' ? 3 : 0) +(poor_appetite === 'b631d160-8d40-4cf7-92cd-67f628c889e8' ? 1 : poor_appetite === '234259ec-5368-4488-8482-4f261cc76714' ? 2 : poor_appetite === '8ff1f85c-4f04-4f5b-936a-5aa9320cb66e' ? 3 : 0) + (troubled === '57766c65-6548-486b-9dad-0fedf531ed7d' ? 1 : troubled === '234259ec-5368-4488-8482-4f261cc76714' ? 2 : troubled === '8ff1f85c-4f04-4f5b-936a-5aa9320cb66e' ? 3 : 0) + (feeling_bad === 'b631d160-8d40-4cf7-92cd-67f628c889e8' ? 1 : feeling_bad === '234259ec-5368-4488-8482-4f261cc76714' ? 2 : feeling_bad === '349260db-8e0f-4c06-be92-5120b3708d1e' ? 3 : 0) + (speaking_slowly === 'b631d160-8d40-4cf7-92cd-67f628c889e8' ? 1 : speaking_slowly === '234259ec-5368-4488-8482-4f261cc76714' ? 2 : speaking_slowly === '8ff1f85c-4f04-4f5b-936a-5aa9320cb66e' ? 3 : 0) + (better_dead === 'b631d160-8d40-4cf7-92cd-67f628c889e8' ? 1 : better_dead === '296b39ec-06c5-4310-8f30-d2c9f083fb71' ? 2 : better_dead === '8ff1f85c-4f04-4f5b-936a-5aa9320cb66e' ? 3 : 0)";
+
+    expect(evaluateExpression(expression, { value: allFields[9], type: 'field' }, allFields, valuesMap, context)).toBe(
+      14,
+    );
   });
 
-  it('should support isEmpty(value) runtime helper function', () => {
+  it('should support async expressions', async () => {
     // setup
-    valuesMap['linkedToCare'] = 'cf82933b-3f3f-45e7-a5ab-5d31aaee3da3';
-    // replay and verify
-    expect(
-      evaluateExpression(
-        "!isEmpty('linkedToCare') && isEmpty('htsProviderRemarks')",
-        { value: allFields[1], type: 'field' },
-        allFields,
-        valuesMap,
-        context,
-      ),
-    ).toBeTruthy();
+    valuesMap.bad_sleep = 'a53f32bc-6904-4692-8a4c-fb7403cf0306';
+    registerExpressionHelper('getAsyncValue', () => {
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          resolve(18);
+        }, 10);
+      });
+    });
+
+    const result = await evaluateAsyncExpression(
+      'getAsyncValue().then(value => !isEmpty(bad_sleep) ? value + 3 : value)',
+      { value: allFields[9], type: 'field' },
+      allFields,
+      valuesMap,
+      context,
+    );
+    expect(result).toBe(21);
   });
 
   it('should support includes(question, value) runtime helper function', () => {
@@ -191,7 +301,7 @@ describe('Common expression runner - evaluateExpression', () => {
     // replay and verify
     expect(
       evaluateExpression(
-        "includes('referredToPreventionServices', '88cdde2b-753b-48ac-a51a-ae5e1ab24846') && !includes('referredToPreventionServices', '1691AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')",
+        "includes(referredToPreventionServices, '88cdde2b-753b-48ac-a51a-ae5e1ab24846') && !includes(referredToPreventionServices, '1691AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')",
         { value: allFields[1], type: 'field' },
         allFields,
         valuesMap,
@@ -203,7 +313,7 @@ describe('Common expression runner - evaluateExpression', () => {
   it('should support session mode as a runtime', () => {
     expect(
       evaluateExpression(
-        "mode == 'enter' && isEmpty('htsProviderRemarks')",
+        "mode == 'enter' && isEmpty(htsProviderRemarks)",
         { value: allFields[2], type: 'field' },
         allFields,
         valuesMap,
@@ -222,7 +332,7 @@ describe('Common expression runner - evaluateExpression', () => {
     // replay
     expect(
       evaluateExpression(
-        "!includes('referredToPreventionServices', '88cdde2b-753b-48ac-a51a-ae5e1ab24846') && isEmpty('htsProviderRemarks')",
+        "!includes(referredToPreventionServices, '88cdde2b-753b-48ac-a51a-ae5e1ab24846') && isEmpty(htsProviderRemarks)",
         { value: allFields[4], type: 'field' },
         allFields,
         valuesMap,
@@ -251,26 +361,3 @@ describe('Common expression runner - evaluateExpression', () => {
     expect(result).toEqual(5);
   });
 });
-
-describe('Common expression runner - checkReferenceToResolvedFragment', () => {
-  it('should extract resolved fragment and chained reference when given a valid input', () => {
-    const token = 'resolve(api.fetchSomeValue("arg1", "arg2")).someOtherRef';
-    const expected = ['resolve(api.fetchSomeValue("arg1", "arg2"))', '.someOtherRef'];
-    const result = checkReferenceToResolvedFragment(token);
-    expect(result).toEqual(expected);
-  });
-
-  it('should extract only resolved fragment when there is no chained reference', () => {
-    const token = 'resolve(AnotherFragment)';
-    const expected = ['resolve(AnotherFragment)', ''];
-    const result = checkReferenceToResolvedFragment(token);
-    expect(result).toEqual(expected);
-  });
-
-  it('should return an empty string for the resolved fragment and chained reference when given an invalid input', () => {
-    const token = 'invalidToken';
-    const expected = ['', ''];
-    const result = checkReferenceToResolvedFragment(token);
-    expect(result).toEqual(expected);
-  });
-});

package/src/utils/expression-runner.ts

@@ -1,10 +1,17 @@
 import { getRegisteredExpressionHelpers } from '../registry/registry';
 import { isEmpty } from 'lodash-es';
 import { type OpenmrsEncounter, type FormField, type FormPage, type FormSection } from '../types';
-import { CommonExpressionHelpers } from './common-expression-helpers';
-import { findAndRegisterReferencedFields, linkReferencedFieldValues, parseExpression } from './expression-parser';
+import { CommonExpressionHelpers, registerDependency, simpleHash } from './common-expression-helpers';
 import { HistoricalDataSourceService } from '../datasources/historical-data-source';
-import { type Visit } from '@openmrs/esm-framework';
+import {
+  compile,
+  type DefaultEvaluateReturnType,
+  evaluateAsType,
+  evaluateAsTypeAsync,
+  extractVariableNames,
+  type VariablesMap,
+  type Visit,
+} from '@openmrs/esm-framework';
 
 export interface FormNode {
   value: FormPage | FormSection | FormField;
@@ -19,7 +26,21 @@ export interface ExpressionContext {
   visit?: Visit;
 }
 
-export const HD = new HistoricalDataSourceService();
+export type EvaluateReturnType = DefaultEvaluateReturnType | Record<string, any>;
+
+export const astCache = new Map();
+
+function typePredicate(result: unknown): result is EvaluateReturnType {
+  return (
+    typeof result === 'string' ||
+    typeof result === 'number' ||
+    typeof result === 'boolean' ||
+    typeof result === 'undefined' ||
+    typeof result === 'object' || // Support for arbitrary objects
+    result === null ||
+    result === undefined
+  );
+}
 
 export function evaluateExpression(
   expression: string,
@@ -31,54 +52,12 @@ export function evaluateExpression(
   if (!expression?.trim()) {
     return null;
   }
-
-  const allFieldsKeys = fields.map((f) => f.id);
-  const parts = parseExpression(expression.trim());
-  // register dependencies
-  findAndRegisterReferencedFields(node, parts, fields);
-  // setup function scope
-  let { myValue, patient } = context;
-  const { sex, age } = patient && 'sex' in patient && 'age' in patient ? patient : { sex: undefined, age: undefined };
-
-  if (node.type === 'field' && myValue === undefined && node.value) {
-    myValue = fieldValues[node.value['id']];
-  }
-
-  const HD = new HistoricalDataSourceService();
-
-  HD.putObject('prevEnc', {
-    value: context.previousEncounter || { obs: [] },
-    getValue(concept) {
-      return this.value.obs.find((obs) => obs.concept.uuid == concept);
-    },
-  });
-
-  const visitType = context.visit?.visitType || { uuid: '' };
-  const visitTypeUuid = visitType.uuid ?? '';
-
-  const _ = {
-    isEmpty,
-  };
-
-  const expressionContext = {
-    ...new CommonExpressionHelpers(node, patient, fields, fieldValues, allFieldsKeys),
-    ...getRegisteredExpressionHelpers(),
-    ...context,
-    fieldValues,
-    patient,
-    myValue,
-    sex,
-    age,
-    HD,
-    visitType,
-    visitTypeUuid,
-    _,
-  };
-
-  expression = linkReferencedFieldValues(fields, fieldValues, parts);
+  const compiledExpression = getExpressionAst(expression);
+  // track dependencies
+  trackFieldDependencies(compiledExpression, node, fields);
 
   try {
-    return evaluate(expression, expressionContext);
+    return evaluateAsType(compiledExpression, getEvaluationContext(node, fields, fieldValues, context), typePredicate);
   } catch (error) {
     console.error(`Error: ${error} \n\n failing expression: ${expression}`);
   }
@@ -95,25 +74,35 @@ export async function evaluateAsyncExpression(
   if (!expression?.trim()) {
     return null;
   }
+  const compiledExpression = getExpressionAst(expression);
+  // track dependencies
+  trackFieldDependencies(compiledExpression, node, fields);
+  try {
+    return evaluateAsTypeAsync(
+      compiledExpression,
+      getEvaluationContext(node, fields, fieldValues, context),
+      typePredicate,
+    );
+  } catch (error) {
+    console.error(`Error: ${error} \n\n failing expression: ${expression}`);
+  }
+  return null;
+}
 
-  const allFieldsKeys = fields.map((f) => f.id);
-  let parts = parseExpression(expression.trim());
-
-  const visitType = context.visit?.visitType || { uuid: '' };
-  const visitTypeUuid = visitType.uuid ?? '';
-
-  // register dependencies
-  findAndRegisterReferencedFields(node, parts, fields);
-
-  // setup function scope
+function getEvaluationContext(
+  node: FormNode,
+  formFields: FormField[],
+  fieldValues: Record<string, any>,
+  context: ExpressionContext,
+): VariablesMap {
   let { myValue, patient } = context;
-  const { sex, age } = patient && 'sex' in patient && 'age' in patient ? patient : { sex: undefined, age: undefined };
-  if (node.type === 'field' && myValue === undefined) {
+  const { sex, age } = patient ?? {};
+
+  if (node.type === 'field' && myValue === undefined && node.value) {
     myValue = fieldValues[node.value['id']];
   }
 
   const HD = new HistoricalDataSourceService();
-
   HD.putObject('prevEnc', {
     value: context.previousEncounter || { obs: [] },
     getValue(concept) {
@@ -121,99 +110,60 @@ export async function evaluateAsyncExpression(
     },
   });
 
+  const visitType = context.visit?.visitType || { uuid: '' };
+  const visitTypeUuid = visitType.uuid ?? '';
+
   const _ = {
     isEmpty,
   };
 
-  const expressionContext = {
-    ...new CommonExpressionHelpers(node, patient, fields, fieldValues, allFieldsKeys),
+  return {
+    ...new CommonExpressionHelpers(node, patient, formFields, fieldValues),
     ...getRegisteredExpressionHelpers(),
     ...context,
-    fieldValues,
+    ...fieldValues,
     patient,
     myValue,
     sex,
     age,
-    temporaryObjectsMap: {},
     HD,
     visitType,
     visitTypeUuid,
     _,
   };
-
-  expression = linkReferencedFieldValues(fields, fieldValues, parts);
-
-  // parts with resolve-able field references
-  parts = parseExpression(expression);
-  const lazyFragments = [];
-  parts.forEach((part, index) => {
-    if (index % 2 == 0) {
-      if (part.startsWith('resolve(')) {
-        const [refinedSubExpression] = checkReferenceToResolvedFragment(part);
-        lazyFragments.push({ expression: refinedSubExpression, index });
-      }
-    }
-  });
-
-  const temporaryObjectsMap = {};
-  // resolve lazy fragments
-  const fragments = await Promise.all(lazyFragments.map(({ expression }) => evaluate(expression, expressionContext)));
-  lazyFragments.forEach((fragment, index) => {
-    if (typeof fragments[index] == 'object') {
-      const objectKey = `obj_${index}`;
-      temporaryObjectsMap[objectKey] = fragments[index];
-      expression = expression.replace(fragment.expression, `temporaryObjectsMap.${objectKey}`);
-    } else {
-      expression = expression.replace(
-        fragment.expression,
-        typeof fragments[index] == 'string' ? `'${fragments[index]}'` : fragments[index],
-      );
-    }
-  });
-
-  expressionContext.temporaryObjectsMap = temporaryObjectsMap;
-
-  try {
-    return evaluate(expression, expressionContext);
-  } catch (error) {
-    console.error(`Error: ${error} \n\n failing expression: ${expression}`);
-  }
-  return null;
 }
 
 /**
- * Checks if the given token contains a reference to a resolved fragment
- * and returns the fragment and the remaining chained reference.
- * @param token - The token to check.
- * @returns An array containing the resolved fragment and the remaining chained reference.
+ * Compiles an expression into an abstract syntax tree (AST) and caches the result.
+ * @param expression - The expression to compile.
+ * @returns The abstract syntax tree (AST) of the compiled expression.
  */
-export function checkReferenceToResolvedFragment(token: string) {
-  // Match the substring that starts with the keyword "resolve" and continues until
-  // the closing parenthesis of the inner function call.
-  const match = token.match(/resolve\((.*)\)/) || [];
-  const chainedRef = match.length ? token.substring(token.indexOf(match[0]) + match[0].length) : '';
-  return [match[0] || '', chainedRef];
+function getExpressionAst(expression: string): ReturnType<typeof compile> {
+  const hash = simpleHash(expression);
+  if (astCache.has(hash)) {
+    return astCache.get(hash);
+  }
+  const ast = compile(expression);
+  astCache.set(hash, ast);
+  return ast;
 }
 
 /**
- * A slightly safer version of the built-in eval()
- *
- * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval
- *
- * ```js
- * evaluate("myNum + 2", { myNum: 5 }); // 7
- * ```
- *
- * Note that references to variables not included in the `expressionContext` will result at
- * `undefined` during evaluation.
- *
- * @param expression A JS expression to execute
- * @param expressionContext A JS object consisting of the names to make available in the scope
- *   the expression is executed in.
+ * Extracts all referenced fields in the expression and registers them as dependencies.
+ * @param expression - The expression to track dependencies for.
+ * @param fieldNode - The node representing the field.
+ * @param allFields - The list of all fields in the form.
  */
-function evaluate(expression: string, expressionContext?: Record<string, any>) {
-  return Function(...Object.keys(expressionContext), `"use strict"; return (${expression})`).call(
-    undefined,
-    ...Object.values(expressionContext),
-  );
+export function trackFieldDependencies(
+  expression: ReturnType<typeof compile>,
+  fieldNode: FormNode,
+  allFields: FormField[],
+) {
+  const variables = extractVariableNames(expression);
+  for (const variable of variables) {
+    const field = allFields.find((field) => field.id === variable);
+    if (field) {
+      registerDependency(fieldNode, field);
+    }
+  }
 }