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

package/src/utils/error-utils.ts

@@ -0,0 +1,37 @@
+import { showToast } from '@openmrs/esm-framework';
+
+export function reportError(error: Error, title: string): void {
+  if (error) {
+    const errorMessage = extractErrorMessagesFromResponse(error).join(', ');
+    console.error(error);
+    showToast({
+      description: errorMessage,
+      title: title,
+      kind: 'error',
+      critical: true,
+    });
+  }
+}
+
+/**
+ * Extracts error messages from a given error response object.
+ * If fieldErrors are present, it extracts the error messages from each field.
+ * Otherwise, it returns the top-level error message.
+ *
+ * @param {object} errorObject - The error response object.
+ * @returns {string[]} An array of error messages.
+ */
+export function extractErrorMessagesFromResponse(errorObject) {
+  const fieldErrors = errorObject?.responseBody?.error?.fieldErrors;
+  const globalErrors = errorObject?.responseBody?.error?.globalErrors;
+
+  if ((!fieldErrors || Object.keys(fieldErrors).length === 0) && !globalErrors) {
+    return [errorObject?.responseBody?.error?.message ?? errorObject?.message];
+  }
+
+  if (globalErrors?.length) {
+    return globalErrors.flatMap((error) => error.message);
+  } else {
+    return Object.values(fieldErrors).flatMap((errors: Array<Error>) => errors.map((error) => error.message));
+  }
+}

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

@@ -0,0 +1,308 @@
+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);
+  });
+});

package/src/utils/expression-parser.ts

@@ -0,0 +1,158 @@
+import { type FormField } from '../types';
+import { ConceptFalse, ConceptTrue } from '../constants';
+import { registerDependency } from './common-expression-helpers';
+import { type FormNode } from './expression-runner';
+
+/**
+ * Parses a complex expression string into an array of tokens, ignoring operators found within quotes and within parentheses.
+ *
+ * @param expression The expression string to parse.
+ * @returns An array of tokens representing the individual elements of the expression.
+ */
+export function parseExpression(expression: string): string[] {
+  const tokens = [];
+  let currentToken = '';
+  let inQuote = false;
+  let openParensCount = 0;
+
+  for (let i = 0; i < expression.length; i++) {
+    const char = expression.charAt(i);
+
+    if (char === "'" || char === '"') {
+      if (inQuote) {
+        inQuote = false;
+      } else if (openParensCount === 0) {
+        inQuote = true;
+      }
+    }
+    if (inQuote) {
+      currentToken += char;
+    } else {
+      if (char === '(') {
+        openParensCount++;
+      } else if (char === ')') {
+        openParensCount--;
+      }
+      if (openParensCount === 0) {
+        if (char === ' ' || char === '\t' || char === '\n') {
+          if (currentToken.length > 0) {
+            tokens.push(currentToken);
+            currentToken = '';
+          }
+        } else {
+          currentToken += char;
+        }
+      } else {
+        currentToken += char;
+      }
+    }
+  }
+  if (currentToken.length > 0) {
+    tokens.push(currentToken);
+  }
+  return tokens;
+}
+
+/**
+ * Links field references within expression fragments to the actual field values
+ * @returns The expression with linked field references
+ */
+export function linkReferencedFieldValues(
+  fields: FormField[],
+  fieldValues: Record<string, any>,
+  tokens: string[],
+): string {
+  const processedTokens = [];
+  tokens.forEach((token) => {
+    if (hasParentheses(token)) {
+      let tokenWithUnresolvedArgs = token;
+      extractArgs(token).forEach((arg) => {
+        const referencedField = findReferencedFieldIfExists(arg, fields);
+        if (referencedField) {
+          tokenWithUnresolvedArgs = replaceFieldRefWithValuePath(
+            referencedField,
+            fieldValues[referencedField.id],
+            tokenWithUnresolvedArgs,
+          );
+        }
+      });
+      processedTokens.push(tokenWithUnresolvedArgs);
+    } else {
+      const referencedField = findReferencedFieldIfExists(token, fields);
+      if (referencedField) {
+        processedTokens.push(replaceFieldRefWithValuePath(referencedField, fieldValues[referencedField.id], token));
+      } else {
+        // push token as is
+        processedTokens.push(token);
+      }
+    }
+  });
+  return processedTokens.join(' ');
+}
+
+/**
+ * Extracts the arguments or parameters to a function within an arbitrary expression.
+ *
+ * @param {string} expression - The expression to extract arguments from.
+ * @returns {string[]} An array of the extracted arguments.
+ */
+export function extractArgs(expression: string): string[] {
+  const args = [];
+  // eslint-disable-next-line no-useless-escape
+  const regx = /(?:\w+|'(?:\\'|[^'\n])*')(?=[,\)]|\s*(?=\)))/g;
+  let match;
+  while ((match = regx.exec(expression))) {
+    args.push(match[0].replace(/\\'/g, "'").replace(/(^'|'$)/g, ''));
+  }
+  return args;
+}
+
+/**
+ * Checks if an expression contains opening and closing parentheses.
+ *
+ * @param {string} expression - The expression to check.
+ * @returns {boolean} `true` if the expression contains parentheses, otherwise `false`.
+ */
+export function hasParentheses(expression: string): boolean {
+  const re = /[()]/;
+  return re.test(expression);
+}
+
+export function replaceFieldRefWithValuePath(field: FormField, value: any, token: string): string {
+  if (token.includes(`useFieldValue('${field.id}')`)) {
+    return token;
+  }
+  // strip quotes
+  token = token.replace(new RegExp(`['"]${field.id}['"]`, 'g'), field.id);
+  if (field.questionOptions.rendering == 'toggle' && typeof value == 'boolean') {
+    // TODO: reference ConceptTrue and ConceptFalse through config patterns
+    return token.replace(field.id, `${value ? `'${ConceptTrue}'` : `'${ConceptFalse}'`}`);
+  }
+  return token.replace(field.id, `fieldValues.${field.id}`);
+}
+
+/**
+ * Finds and registers referenced fields in the expression
+ * @param fieldNode The field node
+ * @param tokens Expression tokens
+ * @param fields All fields
+ */
+export function findAndRegisterReferencedFields(fieldNode: FormNode, tokens: string[], fields: Array<FormField>): void {
+  tokens.forEach((token) => {
+    if (hasParentheses(token)) {
+      extractArgs(token).forEach((arg) => {
+        registerDependency(fieldNode, findReferencedFieldIfExists(arg, fields));
+      });
+    } else {
+      registerDependency(fieldNode, findReferencedFieldIfExists(token, fields));
+    }
+  });
+}
+
+function findReferencedFieldIfExists(fieldId: string, fields: FormField[]): FormField | undefined {
+  // check if field id has trailing quotes
+  if (/^'+|'+$/.test(fieldId)) {
+    fieldId = fieldId.replace(/^'|'$/g, '');
+  }
+  return fields.find((field) => field.id === fieldId);
+}