@openmrs/esm-form-engine-lib 2.1.0-pre.1362

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

@@ -0,0 +1,387 @@
+import { registerExpressionHelper } from '..';
+import { type FormField } from '../types';
+import { CommonExpressionHelpers } from './common-expression-helpers';
+import { checkReferenceToResolvedFragment, evaluateExpression, type ExpressionContext } from './expression-runner';
+
+export const testFields: Array<FormField> = [
+  {
+    label: 'Was the client linked to care and treatment in this facility?',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'radio',
+      concept: 'e8e8fe71-adbb-48e7-b531-589985094d30',
+      answers: [
+        {
+          concept: 'cf82933b-3f3f-45e7-a5ab-5d31aaee3da3',
+          label: 'Yes',
+        },
+        {
+          concept: '488b58ff-64f5-4f8a-8979-fa79940b1594',
+          label: 'No',
+        },
+      ],
+    },
+    id: 'linkedToCare',
+  },
+  {
+    label: 'What Identification Number was issued to the client?',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'text',
+      concept: '162576AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+    },
+    id: 'patientIdentificationNumber',
+  },
+  {
+    label: 'Which of the following prevention services was the client referred to?',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'checkbox',
+      concept: '5f394708-ca7d-4558-8d23-a73de181b02d',
+      answers: [
+        {
+          concept: '88cdde2b-753b-48ac-a51a-ae5e1ab24846',
+          label: 'Pre Exposure Prophylaxis (PEP)',
+        },
+        {
+          concept: '46da10c7-49e3-45e5-8e82-7c529d52a1a8',
+          label: 'STI Testing and Treatment',
+        },
+        {
+          concept: '1691AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+          label: 'Post-exposure prophylaxis',
+        },
+        {
+          concept: '162223AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+          label: 'Voluntary male circumcision clinic',
+        },
+      ],
+    },
+    id: 'referredToPreventionServices',
+  },
+  {
+    label: 'What were the HTS provider’s remarks?',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'textarea',
+      concept: '437d1e25-e7ab-481c-aabc-01f21c6cdef1',
+    },
+    id: 'htsProviderRemarks',
+  },
+  {
+    label: 'Body Temperature',
+    type: 'obs',
+    questionOptions: {
+      rendering: 'number',
+      concept: '537d1e25-e7av-481c-aabc-01f21c6cdefo',
+    },
+    id: 'bodyTemperature',
+  },
+];
+
+describe('Common expression runner - evaluateExpression', () => {
+  const context: ExpressionContext = { mode: 'enter', patient: {} };
+  const allFields = JSON.parse(JSON.stringify(testFields));
+  let valuesMap = {
+    linkedToCare: '',
+    patientIdentificationNumber: '',
+    htsProviderRemarks: '',
+    referredToPreventionServices: [],
+    bodyTemperature: 0,
+  };
+
+  afterEach(() => {
+    // teardown
+    valuesMap = {
+      linkedToCare: '',
+      patientIdentificationNumber: '',
+      htsProviderRemarks: '',
+      referredToPreventionServices: [],
+      bodyTemperature: 0,
+    };
+    allFields.forEach((field) => {
+      field.fieldDependents = undefined;
+    });
+  });
+
+  it('should evaluate basic boolean strings', () => {
+    // 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),
+    ).toBeFalsy();
+  });
+
+  it('should support two dimension expressions', () => {
+    // replay and verify
+    expect(
+      evaluateExpression(
+        "linkedToCare == '488b58ff-64f5-4f8a-8979-fa79940b1594'",
+        { value: allFields[1], type: 'field' },
+        allFields,
+        valuesMap,
+        context,
+      ),
+    ).toBeFalsy();
+    // provide some values
+    valuesMap['linkedToCare'] = '488b58ff-64f5-4f8a-8979-fa79940b1594';
+    // replay and verify
+    expect(
+      evaluateExpression(
+        "linkedToCare == '488b58ff-64f5-4f8a-8979-fa79940b1594'",
+        { value: allFields[1], type: 'field' },
+        allFields,
+        valuesMap,
+        context,
+      ),
+    ).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 isEmpty(value) runtime helper function', () => {
+    // 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();
+  });
+
+  it('should support includes(question, value) runtime helper function', () => {
+    // setup
+    valuesMap['referredToPreventionServices'] = [
+      '88cdde2b-753b-48ac-a51a-ae5e1ab24846',
+      '162223AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+    ];
+    // replay and verify
+    expect(
+      evaluateExpression(
+        "includes('referredToPreventionServices', '88cdde2b-753b-48ac-a51a-ae5e1ab24846') && !includes('referredToPreventionServices', '1691AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')",
+        { value: allFields[1], type: 'field' },
+        allFields,
+        valuesMap,
+        context,
+      ),
+    ).toBeTruthy();
+  });
+
+  it('should support session mode as a runtime', () => {
+    expect(
+      evaluateExpression(
+        "mode == 'enter' && isEmpty('htsProviderRemarks')",
+        { value: allFields[2], type: 'field' },
+        allFields,
+        valuesMap,
+        context,
+      ),
+    ).toBeTruthy();
+  });
+
+  it("should register dependency of the current node to it's determinant", () => {
+    // setup
+    const referredToPreventionServices = allFields[2];
+    const htsProviderRemarks = allFields[3];
+    // verify
+    expect(referredToPreventionServices.fieldDependents).toBeFalsy();
+    expect(htsProviderRemarks.fieldDependents).toBeFalsy();
+    // replay
+    expect(
+      evaluateExpression(
+        "!includes('referredToPreventionServices', '88cdde2b-753b-48ac-a51a-ae5e1ab24846') && isEmpty('htsProviderRemarks')",
+        { value: allFields[4], type: 'field' },
+        allFields,
+        valuesMap,
+        context,
+      ),
+    ).toBeTruthy();
+    expect(Array.from(referredToPreventionServices.fieldDependents)).toStrictEqual(['bodyTemperature']);
+    expect(Array.from(htsProviderRemarks.fieldDependents)).toStrictEqual(['bodyTemperature']);
+  });
+
+  it('should support registered custom helper functions', () => {
+    // setup
+    function customHelper(a, b) {
+      return a + b;
+    }
+    registerExpressionHelper('customAdd', customHelper);
+
+    // verify
+    const result = evaluateExpression(
+      'customAdd(2, 3)',
+      { value: allFields[1], type: 'field' },
+      allFields,
+      {},
+      context,
+    );
+    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);
+  });
+});
+
+describe('Common expression runner - validate helper functions', () => {
+  const allFields = JSON.parse(JSON.stringify(testFields));
+  const allFieldsKeys = allFields.map((f) => f.id);
+  let valuesMap = {
+    linkedToCare: '',
+    patientIdentificationNumber: '',
+    htsProviderRemarks: '',
+    referredToPreventionServices: [],
+    bodyTemperature: 0,
+  };
+
+  const users = [
+    { id: 1, name: 'Alice', age: 25 },
+    { id: 2, name: 'Bob', age: 30 },
+    { id: 3, name: 'Charlie', age: 35 },
+  ];
+
+  afterEach(() => {
+    // teardown
+    valuesMap = {
+      linkedToCare: '',
+      patientIdentificationNumber: '',
+      htsProviderRemarks: '',
+      referredToPreventionServices: [],
+      bodyTemperature: 0,
+    };
+    allFields.forEach((field) => {
+      field.fieldDependents = undefined;
+    });
+  });
+  const helper = new CommonExpressionHelpers(
+    { value: allFields[1], type: 'field' },
+    {},
+    allFields,
+    valuesMap,
+    allFieldsKeys,
+  );
+
+  it('should return true if value is empty, null or undefined', () => {
+    let val = '';
+
+    expect(helper.isEmpty(val)).toBe(true);
+
+    val = 'test';
+    expect(helper.isEmpty(val)).toBe(false);
+
+    val = null;
+    expect(helper.isEmpty(val)).toBe(true);
+
+    val = undefined;
+    expect(helper.isEmpty(val)).toBe(true);
+  });
+
+  it('should return true if array contains items', () => {
+    const arr = [1, 2, 3, 4];
+
+    let members = [1, 4];
+
+    let result = helper.arrayContains(arr, members);
+    expect(result).toBe(true);
+
+    members = [4, 7, 8, 9, 0, 6];
+    result = helper.arrayContains(arr, members);
+    expect(result).toBe(false);
+  });
+
+  it('should return true if array contains atleast one item', () => {
+    const arr = [1, 2, 3, 4];
+
+    let members = [1, 4, 7, 8, 9, 0, 6];
+
+    let result = helper.arrayContainsAny(arr, members);
+    expect(result).toBe(true);
+
+    members = [7, 8, 9, 0, 6];
+    result = helper.arrayContainsAny(arr, members);
+    expect(result).toBe(false);
+  });
+
+  it('should evaluate values against regular expressions(Regex)', () => {
+    const regex = '[A-Za-z0-9]+-123456';
+
+    let result = helper.doesNotMatchExpression(regex, 'RandomID');
+    expect(result).toBe(true);
+
+    result = helper.doesNotMatchExpression(regex, 'REC12345-123456');
+    expect(result).toBe(false);
+  });
+
+  it('returns an array of values for a given key', () => {
+    const ages = helper.extractRepeatingGroupValues('age', users);
+    expect(ages).toEqual([25, 30, 35]);
+  });
+
+  it('returns an empty array if the input array is empty', () => {
+    const emptyArray = [];
+    const values = helper.extractRepeatingGroupValues('someKey', emptyArray);
+    expect(values).toEqual([]);
+  });
+
+  it('returns a Date object', () => {
+    const result = helper.formatDate('2023-04-13', 'yyyy-MM-dd', '+0300');
+    expect(result instanceof Date).toBe(true);
+  });
+
+  it('uses default format and offset values when passed as null arguments', () => {
+    const result = helper.formatDate('2023-04-13T01:23:45.678Z', null, null);
+    expect(result.toISOString()).toEqual('2023-04-13T01:23:45.678Z');
+  });
+});

package/src/utils/expression-runner.ts

@@ -0,0 +1,219 @@
+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 { HistoricalDataSourceService } from '../datasources/historical-data-source';
+import { type Visit } from '@openmrs/esm-framework';
+
+export interface FormNode {
+  value: FormPage | FormSection | FormField;
+  type: 'field' | 'page' | 'section';
+}
+
+export interface ExpressionContext {
+  mode: 'enter' | 'edit' | 'view' | 'embedded-view';
+  myValue?: any;
+  patient: any;
+  previousEncounter?: OpenmrsEncounter;
+  visit?: Visit;
+}
+
+export const HD = new HistoricalDataSourceService();
+
+export function evaluateExpression(
+  expression: string,
+  node: FormNode,
+  fields: Array<FormField>,
+  fieldValues: Record<string, any>,
+  context: ExpressionContext,
+): any {
+  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);
+
+  try {
+    return evaluate(expression, expressionContext);
+  } catch (error) {
+    console.error(`Error: ${error} \n\n failing expression: ${expression}`);
+  }
+  return null;
+}
+
+export async function evaluateAsyncExpression(
+  expression: string,
+  node: FormNode,
+  fields: Array<FormField>,
+  fieldValues: Record<string, any>,
+  context: ExpressionContext,
+): Promise<any> {
+  if (!expression?.trim()) {
+    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
+  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) {
+    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 _ = {
+    isEmpty,
+  };
+
+  const expressionContext = {
+    ...new CommonExpressionHelpers(node, patient, fields, fieldValues, allFieldsKeys),
+    ...getRegisteredExpressionHelpers(),
+    ...context,
+    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.
+ */
+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];
+}
+
+/**
+ * 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.
+ */
+function evaluate(expression: string, expressionContext?: Record<string, any>) {
+  return Function(...Object.keys(expressionContext), `"use strict"; return (${expression})`).call(
+    undefined,
+    ...Object.values(expressionContext),
+  );
+}