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

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);
+    }
+  }
 }

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

@@ -1,308 +0,0 @@
-import { type FormField } from '../types';
-import { ConceptFalse } from '../constants';
-import {
-  extractArgs,
-  findAndRegisterReferencedFields,
-  hasParentheses,
-  linkReferencedFieldValues,
-  parseExpression,
-  replaceFieldRefWithValuePath,
-} from './expression-parser';
-import { testFields } from './expression-runner.test';
-
-describe('Expression parsing', () => {
-  it('should split expression 1 into parts correctly', () => {
-    const input =
-      "isDateBefore(myValue, '1980-01-01') || myValue < useFieldValue('initiationDate', null) && getOtherValue('arg1', 'arg2')";
-    const expectedOutput = [
-      "isDateBefore(myValue, '1980-01-01')",
-      '||',
-      'myValue',
-      '<',
-      "useFieldValue('initiationDate', null)",
-      '&&',
-      "getOtherValue('arg1', 'arg2')",
-    ];
-
-    expect(parseExpression(input)).toEqual(expectedOutput);
-  });
-
-  it('should split expression 2 into parts correctly', () => {
-    const input = "isDateBefore(myValue, '1980-01-01') || myValue < useFieldValue('initiationDate', null)";
-    const expectedOutput = [
-      "isDateBefore(myValue, '1980-01-01')",
-      '||',
-      'myValue',
-      '<',
-      "useFieldValue('initiationDate', null)",
-    ];
-
-    expect(parseExpression(input)).toEqual(expectedOutput);
-  });
-
-  it('should split expression 3 into parts correctly', () => {
-    const input =
-      "isDateBefore(myValue, '1980-01-01') != myValue && useFieldValue('initiationDate', null) && getOtherValue('Some string', 'Some other string')";
-    const expectedOutput = [
-      "isDateBefore(myValue, '1980-01-01')",
-      '!=',
-      'myValue',
-      '&&',
-      "useFieldValue('initiationDate', null)",
-      '&&',
-      "getOtherValue('Some string', 'Some other string')",
-    ];
-
-    expect(parseExpression(input)).toEqual(expectedOutput);
-  });
-
-  it('should split expression 4 into parts correctly', () => {
-    const input = "getValue('some id') ? 'was truthy' : 'was false'";
-    const expectedOutput = ["getValue('some id')", '?', "'was truthy'", ':', "'was false'"];
-
-    expect(parseExpression(input)).toEqual(expectedOutput);
-  });
-});
-
-describe('replaceFieldRefWithValuePath', () => {
-  const field1: FormField = {
-    label: 'Visit Count',
-    type: 'obs',
-    questionOptions: {
-      rendering: 'number',
-      concept: '162576AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
-      answers: [],
-    },
-    id: 'htsVisitCount',
-  };
-
-  const field2: FormField = {
-    label: 'Notes',
-    type: 'obs',
-    questionOptions: {
-      rendering: 'text',
-      concept: '162576AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
-      answers: [],
-    },
-    id: 'notes',
-  };
-
-  const field3: FormField = {
-    label: 'Was HIV tested?',
-    type: 'obs',
-    questionOptions: {
-      rendering: 'toggle',
-      concept: '162576AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
-      answers: [],
-    },
-    id: 'wasHivTested',
-  };
-
-  it("should replace 'htsVisitCount' with value path", () => {
-    // setup
-    const token = "isEmpty('htsVisitCount')";
-    // replay
-    const result = replaceFieldRefWithValuePath(field1, 10, token);
-    // verify
-    expect(result).toEqual('isEmpty(fieldValues.htsVisitCount)');
-  });
-
-  it('should replace "notes" with value path', () => {
-    // setup
-    const token = 'api.getValue(notes)';
-    // replay
-    const result = replaceFieldRefWithValuePath(field2, 'Some notes', token);
-    // verify
-    expect(result).toEqual('api.getValue(fieldValues.notes)');
-  });
-
-  it('should replace "wasHivTested" with the system encoded boolean value for toggle rendering types', () => {
-    const token = "isEmpty('wasHivTested')";
-    const result = replaceFieldRefWithValuePath(field3, false, token);
-    expect(result).toEqual(`isEmpty('${ConceptFalse}')`);
-  });
-});
-
-describe('linkReferencedFieldValues', () => {
-  const field1: FormField = {
-    label: 'Visit Count',
-    type: 'obs',
-    questionOptions: {
-      rendering: 'number',
-      concept: '162576AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
-      answers: [],
-    },
-    id: 'htsVisitCount',
-  };
-
-  const field2: FormField = {
-    label: 'Notes',
-    type: 'obs',
-    questionOptions: {
-      rendering: 'text',
-      concept: '162576AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
-      answers: [],
-    },
-    id: 'notes',
-  };
-
-  const field3: FormField = {
-    label: 'Was HIV tested?',
-    type: 'obs',
-    questionOptions: {
-      rendering: 'toggle',
-      concept: '162576AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
-      answers: [],
-    },
-    id: 'wasHivTested',
-  };
-
-  const valuesMap = {
-    htsVisitCount: 10,
-    notes: 'Some notes',
-    wasHivTested: false,
-  };
-
-  it("should replace 'htsVisitCount' with value path", () => {
-    // setup
-    const expression = "htsVisitCount && helpFn1(htsVisitCount) && helpFn2('htsVisitCount')";
-    // replay
-    const result = linkReferencedFieldValues([field1], valuesMap, parseExpression(expression));
-    // verify
-    expect(result).toEqual(
-      'fieldValues.htsVisitCount && helpFn1(fieldValues.htsVisitCount) && helpFn2(fieldValues.htsVisitCount)',
-    );
-  });
-
-  it('should support complex expressions', () => {
-    // setup
-    const expression =
-      'htsVisitCount > 2 ? resolve(api.getByConcept(wasHivTested)) : resolve(api.call2ndApi(wasHivTested, htsVisitCount))';
-    // replay
-    const result = linkReferencedFieldValues([field1, field2, field3], valuesMap, parseExpression(expression));
-    // verify
-    expect(result).toEqual(
-      `fieldValues.htsVisitCount > 2 ? resolve(api.getByConcept('${ConceptFalse}')) : resolve(api.call2ndApi('${ConceptFalse}', fieldValues.htsVisitCount))`,
-    );
-  });
-
-  it('should ignore ref to useFieldValue', () => {
-    // setup
-    const expression =
-      "htsVisitCount > 2 ? resolve(api.getByConcept(useFieldValue('wasHivTested'))) : resolve(api.call2ndApi(wasHivTested, useFieldValue('htsVisitCount')))";
-    // replay
-    const result = linkReferencedFieldValues([field1, field2, field3], valuesMap, parseExpression(expression));
-    // verify
-    expect(result).toEqual(
-      `fieldValues.htsVisitCount > 2 ? resolve(api.getByConcept(useFieldValue('wasHivTested'))) : resolve(api.call2ndApi('${ConceptFalse}', useFieldValue('htsVisitCount')))`,
-    );
-  });
-});
-
-describe('findAndRegisterReferencedFields', () => {
-  it('should register field dependents', () => {
-    // setup
-    const expression = "linkedToCare == 'cf82933b-3f3f-45e7-a5ab-5d31aaee3da3' && !isEmpty(htsProviderRemarks)";
-    const patientIdentificationNumberField = testFields.find((f) => f.id === 'patientIdentificationNumber');
-
-    // replay
-    findAndRegisterReferencedFields(
-      { value: patientIdentificationNumberField, type: 'field' },
-      parseExpression(expression),
-      testFields,
-    );
-
-    // verify
-    const linkedToCare = testFields.find((f) => f.id === 'linkedToCare');
-    const htsProviderRemarks = testFields.find((f) => f.id === 'htsProviderRemarks');
-    expect(linkedToCare.fieldDependents).toStrictEqual(new Set(['patientIdentificationNumber']));
-    expect(htsProviderRemarks.fieldDependents).toStrictEqual(new Set(['patientIdentificationNumber']));
-  });
-});
-
-describe('extractArgs', () => {
-  it('should extract single argument correctly', () => {
-    const expression = "('arg1')";
-    const expectedOutput = ['arg1'];
-    expect(extractArgs(expression)).toEqual(expectedOutput);
-  });
-
-  it('should extract multiple arguments correctly', () => {
-    const expression = "('arg1', 'arg2', 'arg3')";
-    const expectedOutput = ['arg1', 'arg2', 'arg3'];
-    expect(extractArgs(expression)).toEqual(expectedOutput);
-  });
-
-  it('should handle arguments with spaces correctly', () => {
-    const expression = "('arg with spaces', 'another arg')";
-    const expectedOutput = ['arg with spaces', 'another arg'];
-    expect(extractArgs(expression)).toEqual(expectedOutput);
-  });
-
-  it('should handle arguments with special characters correctly', () => {
-    const expression = "('arg!@#$', 'another$%^&arg')";
-    const expectedOutput = ['arg!@#$', 'another$%^&arg'];
-    expect(extractArgs(expression)).toEqual(expectedOutput);
-  });
-
-  it('should handle no arguments correctly', () => {
-    const expression = '()';
-    const expectedOutput = [];
-    expect(extractArgs(expression)).toEqual(expectedOutput);
-  });
-
-  it('should handle arguments with escaped quotes correctly', () => {
-    const expression = "('arg\\'with\\'escaped\\'quotes', 'another\\'arg')";
-    const expectedOutput = ["arg'with'escaped'quotes", "another'arg"];
-    expect(extractArgs(expression)).toEqual(expectedOutput);
-  });
-
-  it('should handle complex expressions with various argument types', () => {
-    const expression = "('string', 123, true, 'another string')";
-    const expectedOutput = ['string', '123', 'true', 'another string'];
-    expect(extractArgs(expression)).toEqual(expectedOutput);
-  });
-
-  it('should handle arguments with no quotes correctly', () => {
-    const expression = '(arg1, arg2)';
-    const expectedOutput = ['arg1', 'arg2'];
-    expect(extractArgs(expression)).toEqual(expectedOutput);
-  });
-});
-
-describe('hasParentheses', () => {
-  it('should return true for expression with single set of parentheses', () => {
-    const expression = 'myFunction(arg1, arg2)';
-    expect(hasParentheses(expression)).toBe(true);
-  });
-
-  it('should return true for expression with multiple sets of parentheses', () => {
-    const expression = '(arg1 && (arg2 || arg3))';
-    expect(hasParentheses(expression)).toBe(true);
-  });
-
-  it('should return true for expression with nested parentheses', () => {
-    const expression = 'outerFunction(innerFunction(arg1, arg2))';
-    expect(hasParentheses(expression)).toBe(true);
-  });
-
-  it('should return false for expression without parentheses', () => {
-    const expression = 'arg1 && arg2 || arg3';
-    expect(hasParentheses(expression)).toBe(false);
-  });
-
-  it('should return true for expression with parentheses inside quotes', () => {
-    const expression = "myFunction('arg(with)parentheses')";
-    expect(hasParentheses(expression)).toBe(true);
-  });
-
-  it('should return true for expression with mixed characters and parentheses', () => {
-    const expression = 'a + b * (c - d)';
-    expect(hasParentheses(expression)).toBe(true);
-  });
-
-  it('should return true for complex expression with multiple types of parentheses', () => {
-    const expression = 'func1(arg1, (func2(arg2) && func3(arg3)))';
-    expect(hasParentheses(expression)).toBe(true);
-  });
-});