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

package/src/utils/forms-loader.test.ts

@@ -0,0 +1,323 @@
+import { type FormJsonFile, getForm, getFormByVersion, getLatestFormVersion, applyFormIntent } from './forms-loader';
+import formsRegistry from '__mocks__/packages/test-forms-registry';
+import {
+  htsHivtestResultingSchemaV2,
+  htsRetrospectiveResultingSchemaV2,
+  htsWildcardResultingSchemaV2,
+  testSchemaV2,
+} from '__mocks__/forms/rfe-forms/forms-loader.test.schema';
+
+const htsTestForms: FormJsonFile[] = [
+  {
+    version: '1.0',
+    semanticVersion: '1.0.0',
+    json: {
+      name: 'Test HTS POC',
+      pages: [],
+      processor: 'EncounterFormProcessor',
+      uuid: 'da24c540-cc83-43bc-978f-c1ef180a497f',
+      referencedForms: [],
+      encounterType: '79c1f50f-f77d-42e2-ad2a-d29304dde2fe',
+    },
+  },
+  {
+    version: '1.1',
+    semanticVersion: '1.1.0',
+    json: {
+      name: 'Test HTS POC',
+      pages: [],
+      processor: null,
+      uuid: 'da24c540-cc83-43bc-978f-c1ef180a497f',
+      referencedForms: [],
+      encounterType: '79c1f50f-f77d-42e2-ad2a-d29304dde2fe',
+    },
+  },
+  {
+    version: '2.0',
+    semanticVersion: '2.0.0',
+    json: {
+      name: 'Test HTS POC',
+      pages: [],
+      processor: null,
+      uuid: 'da24c540-cc83-43bc-978f-c1ef180a497f',
+      referencedForms: ['f23de883-ea70-45e5-bff7-eff334b28c4b'],
+      encounterType: '79c1f50f-f77d-42e2-ad2a-d29304dde2fe',
+    },
+  },
+];
+
+describe('Forms loader - getForm', () => {
+  it('should get latest form if no version was specified', () => {
+    // replay
+    const latestHTSForm = getForm('hiv', 'hts_poc', null, false, formsRegistry);
+    // verify
+    expect(latestHTSForm).toEqual({
+      name: 'Test HTS POC',
+      pages: [
+        {
+          label: 'Screening',
+          sections: [
+            {
+              label: 'Testing history',
+              isExpanded: 'true',
+              questions: [
+                {
+                  label: 'When was the HIV test conducted?',
+                  type: 'obs',
+                  questionOptions: {
+                    rendering: 'date',
+                    concept: '164400AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+                    weeksList: '',
+                  },
+                  required: 'true',
+                  unspecified: 'true',
+                  hide: {
+                    hideWhenExpression: 'false',
+                  },
+                  validators: [
+                    {
+                      type: 'date',
+                      allowFutureDates: 'false',
+                    },
+                    {
+                      type: 'js_expression',
+                      failsWhenExpression: "myValue < '1/1/1980' || myValue > today()",
+                    },
+                  ],
+                  behaviours: [
+                    {
+                      intent: 'HTS_RETROSPECTIVE',
+                      required: 'true',
+                      unspecified: 'true',
+                      hide: {
+                        hideWhenExpression: 'false',
+                      },
+                      validators: [
+                        {
+                          type: 'date',
+                          allowFutureDates: 'false',
+                        },
+                        {
+                          type: 'js_expression',
+                          failsWhenExpression: "myValue < '1/1/1980' || myValue > today()",
+                        },
+                      ],
+                    },
+                    {
+                      intent: 'HTS_HIVTEST',
+                      required: 'true',
+                    },
+                    {
+                      intent: '',
+                      required: 'false',
+                      hide: {
+                        hideWhenExpression: "hivTestConducted !== 'cf82933b-3f3f-45e7-a5ab-5d31aaee3da3'",
+                      },
+                      validators: [
+                        {
+                          type: 'date',
+                          allowFutureDates: 'false',
+                        },
+                        {
+                          type: 'js_expression',
+                          failsWhenExpression: "myValue < '1/1/1980' || myValue > today()",
+                        },
+                      ],
+                    },
+                  ],
+                  id: 'dateTestPerformed',
+                },
+              ],
+            },
+          ],
+        },
+      ],
+      availableIntents: ['HTS_RETROSPECTIVE', 'HTS_HIVTEST', '*'],
+      processor: 'EncounterFormProcessor',
+      uuid: 'da24c540-cc83-43bc-978f-c1ef180a497f',
+      referencedForms: [],
+      encounterType: '79c1f50f-f77d-42e2-ad2a-d29304dde2fe',
+    });
+  });
+
+  it('should get form with specified version', () => {
+    // replay
+    const htsFormV1_0 = getForm('hiv', 'hts_poc', '1.0', false, formsRegistry);
+    // verify
+    expect(htsFormV1_0).toEqual({
+      name: 'Test HTS POC',
+      pages: [],
+      processor: 'EncounterFormProcessor',
+      uuid: 'da24c540-cc83-43bc-978f-c1ef180a497f',
+      referencedForms: [],
+      encounterType: '79c1f50f-f77d-42e2-ad2a-d29304dde2fe',
+    });
+  });
+
+  it('should throw an error if specified version was not found while in strict mode', () => {
+    // replay
+    try {
+      getForm('hiv', 'hts_poc', '9.1', true, formsRegistry);
+      // fail test if this point is hit
+      fail('An error was expected to be called');
+    } catch (error) {
+      // verify
+      expect(error.message).toBe("Couldn't find form with version: 9.1");
+    }
+  });
+
+  it('should get lastet if required version was not found while in none strict mode', () => {
+    // replay
+    const latestForm = getForm('hiv', 'hts_poc', '9.1', false, formsRegistry);
+    // verify
+    expect(latestForm).toEqual({
+      name: 'Test HTS POC',
+      pages: [
+        {
+          label: 'Screening',
+          sections: [
+            {
+              label: 'Testing history',
+              isExpanded: 'true',
+              questions: [
+                {
+                  label: 'When was the HIV test conducted?',
+                  type: 'obs',
+                  questionOptions: {
+                    rendering: 'date',
+                    concept: '164400AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+                    weeksList: '',
+                  },
+                  required: 'true',
+                  unspecified: 'true',
+                  hide: {
+                    hideWhenExpression: 'false',
+                  },
+                  validators: [
+                    {
+                      type: 'date',
+                      allowFutureDates: 'false',
+                    },
+                    {
+                      type: 'js_expression',
+                      failsWhenExpression: "myValue < '1/1/1980' || myValue > today()",
+                    },
+                  ],
+                  behaviours: [
+                    {
+                      intent: 'HTS_RETROSPECTIVE',
+                      required: 'true',
+                      unspecified: 'true',
+                      hide: {
+                        hideWhenExpression: 'false',
+                      },
+                      validators: [
+                        {
+                          type: 'date',
+                          allowFutureDates: 'false',
+                        },
+                        {
+                          type: 'js_expression',
+                          failsWhenExpression: "myValue < '1/1/1980' || myValue > today()",
+                        },
+                      ],
+                    },
+                    {
+                      intent: 'HTS_HIVTEST',
+                      required: 'true',
+                    },
+                    {
+                      intent: '',
+                      required: 'false',
+                      hide: {
+                        hideWhenExpression: "hivTestConducted !== 'cf82933b-3f3f-45e7-a5ab-5d31aaee3da3'",
+                      },
+                      validators: [
+                        {
+                          type: 'date',
+                          allowFutureDates: 'false',
+                        },
+                        {
+                          type: 'js_expression',
+                          failsWhenExpression: "myValue < '1/1/1980' || myValue > today()",
+                        },
+                      ],
+                    },
+                  ],
+                  id: 'dateTestPerformed',
+                },
+              ],
+            },
+          ],
+        },
+      ],
+      availableIntents: ['HTS_RETROSPECTIVE', 'HTS_HIVTEST', '*'],
+      processor: 'EncounterFormProcessor',
+      uuid: 'da24c540-cc83-43bc-978f-c1ef180a497f',
+      referencedForms: [],
+      encounterType: '79c1f50f-f77d-42e2-ad2a-d29304dde2fe',
+    });
+  });
+});
+
+describe('Forms loader - getLatestFormVersion', () => {
+  it('should get latest form', () => {
+    // replay
+    const latest = getLatestFormVersion(htsTestForms);
+
+    // verify
+    expect(latest).toEqual({
+      version: '2.0',
+      semanticVersion: '2.0.0',
+      json: {
+        name: 'Test HTS POC',
+        pages: [],
+        processor: null,
+        uuid: 'da24c540-cc83-43bc-978f-c1ef180a497f',
+        referencedForms: ['f23de883-ea70-45e5-bff7-eff334b28c4b'],
+        encounterType: '79c1f50f-f77d-42e2-ad2a-d29304dde2fe',
+      },
+    });
+  });
+});
+
+describe('Forms loader - getFormByVersion', () => {
+  it('should get required form version', () => {
+    // replay
+    const htsFormV1_1 = getFormByVersion(htsTestForms, '1.1');
+
+    // verify
+    expect(htsFormV1_1).toEqual({
+      version: '1.1',
+      semanticVersion: '1.1.0',
+      json: {
+        name: 'Test HTS POC',
+        pages: [],
+        processor: null,
+        uuid: 'da24c540-cc83-43bc-978f-c1ef180a497f',
+        referencedForms: [],
+        encounterType: '79c1f50f-f77d-42e2-ad2a-d29304dde2fe',
+      },
+    });
+  });
+});
+
+xdescribe('Forms loader - applyFormIntent', () => {
+  it('should return correct fields for HTS_RETROSPECTIVE intent', () => {
+    let resultingSchema = applyFormIntent('HTS_RETROSPECTIVE', testSchemaV2);
+
+    expect(resultingSchema).toEqual(htsRetrospectiveResultingSchemaV2);
+  });
+
+  it('should return correct fields for HTS_HIVTEST intent', () => {
+    let resultingSchema = applyFormIntent('HTS_HIVTEST', testSchemaV2);
+
+    expect(resultingSchema).toEqual(htsHivtestResultingSchemaV2);
+  });
+
+  it('should return correct fields for * intent', () => {
+    let resultingSchema = applyFormIntent('*', testSchemaV2);
+
+    expect(resultingSchema).toEqual(htsWildcardResultingSchemaV2);
+  });
+});

package/src/utils/forms-loader.ts

@@ -0,0 +1,306 @@
+import * as semver from 'semver';
+import { type FormField } from '../types';
+
+let baseRegistry = {};
+export interface FormJsonFile {
+  version: string;
+  semanticVersion?: string;
+  json: any;
+}
+
+/**
+ * This is a form behaviour property applied on `page` or `section` or `question`
+ */
+interface BehaviourProperty {
+  name: string;
+  type: 'field' | 'section' | 'page' | 'all';
+  value: string;
+}
+
+/**
+ * Convinience function for loading form(s) associated to a given package or form version.
+ *
+ * @param packageName The package associated with the form
+ * @param formNamespace The form namespace
+ * @param version The form version
+ * @param isStrict If `true`, throws error if specified form version wasn't found
+ * @param formsRegistry Form registry. (This was added for testing purposes)
+ * @returns The form json
+ */
+export function getForm(
+  packageName: string,
+  formNamespace: string,
+  version?: string,
+  isStrict?: boolean,
+  formsRegistry?: any,
+) {
+  const forms = lookupForms(packageName, formNamespace, formsRegistry);
+  let form = null;
+  if (version) {
+    form = getFormByVersion(forms, version, isStrict);
+  }
+  if (!form) {
+    form = getLatestFormVersion(forms);
+  }
+  return loadSubforms(form.json);
+}
+
+export function loadSubforms(parentForm) {
+  parentForm.pages = parentForm.pages || [];
+  parentForm.pages.forEach((page) => {
+    if (page.isSubform && page.subform?.name && page.subform.package) {
+      try {
+        const subform = getForm(page.subform.package, page.subform.name);
+        if (!subform) {
+          console.error(`Form with name "${page.subform.package}/${page.subform.name}" was not found in registry.`);
+        }
+        page.subform.form = subform;
+      } catch (error) {
+        console.error(error);
+      }
+    }
+  });
+  return parentForm;
+}
+
+export function getLatestFormVersion(forms: FormJsonFile[]) {
+  if (forms.length == 1) {
+    return forms[0];
+  }
+  const candidates = forms.map((f) => f.semanticVersion);
+  const latest = candidates.sort(formsVersionComparator)[candidates.length - 1];
+  return forms.find((f) => f.semanticVersion == latest);
+}
+
+export function getFormByVersion(forms: FormJsonFile[], requiredVersion: string, isStrict?: boolean) {
+  for (let form of forms) {
+    if (semver.satisfies(form.semanticVersion, requiredVersion)) {
+      return form;
+    }
+  }
+  if (isStrict) {
+    throw new Error(`Couldn't find form with version: ${requiredVersion}`);
+  } else {
+    return null;
+  }
+}
+
+export function lookupForms(packageName, formNamespace, formsRegistry) {
+  const pkg = formsRegistry ? formsRegistry[packageName] : baseRegistry[packageName];
+  if (!pkg) {
+    throw Error(`Package with name ${packageName} was not found in registry`);
+  }
+  if (!pkg[formNamespace]) {
+    throw new Error(`Form namespace '${formNamespace}' was not found in forms registry`);
+  }
+  return Object.keys(pkg[formNamespace]).map((formVersion) => {
+    return {
+      version: formVersion,
+      semanticVersion: semver.coerce(formVersion).version,
+      json: pkg[formNamespace][formVersion],
+    };
+  });
+}
+
+/**
+ * Function parses JSON form input and filters validation behaviours according to a given intent
+ *
+ * @param {string} intent The specified intent
+ * @param {object} originalJson The original JSON form schema object
+ * @param parentOverrides An array of behaviour overrides from parent form to be applied to a subform
+ * @returns {object} The form json
+ */
+export function applyFormIntent(intent, originalJson, parentOverrides?: Array<BehaviourProperty>) {
+  if (!intent) {
+    return originalJson;
+  }
+  const jsonBuffer = JSON.parse(JSON.stringify(originalJson));
+  // Set the default page based on the current intent
+  jsonBuffer.defaultPage = jsonBuffer.availableIntents?.find(
+    (candidate) => candidate.intent === (intent?.intent || intent),
+  )?.defaultPage;
+
+  // filter form-level markdown behaviour
+  if (jsonBuffer.markdown) {
+    updateMarkdownRequiredBehaviour(jsonBuffer.markdown, intent);
+  }
+
+  // Before starting traversal, ensure nodes exist, at least as empty-arrays
+  jsonBuffer.pages = jsonBuffer.pages || [];
+
+  // Traverse the property tree with items of interest for validation
+  jsonBuffer.pages.forEach((page) => {
+    if (page.isSubform && page.subform?.form) {
+      const behaviourOverrides = [];
+      const targetBehaviour = page.subform.behaviours?.find(
+        (behaviour) => behaviour.intent == intent?.intent || intent,
+      );
+      if (targetBehaviour?.readonly !== undefined || targetBehaviour?.readonly != null) {
+        behaviourOverrides.push({ name: 'readonly', type: 'field', value: targetBehaviour?.readonly });
+      }
+
+      page.subform.form = applyFormIntent(
+        targetBehaviour?.subform_intent || '*',
+        page.subform?.form,
+        behaviourOverrides,
+      );
+    }
+    // TODO: Apply parentOverrides to pages if applicable
+    const pageBehaviour = page.behaviours?.find((behaviour) => behaviour.intent === (intent?.intent || intent));
+    if (pageBehaviour) {
+      page.hide = pageBehaviour?.hide;
+      page.readonly = pageBehaviour?.readonly;
+    } else {
+      const fallBackBehaviour = page.behaviours?.find((behaviour) => behaviour.intent === '*');
+      page.hide = fallBackBehaviour?.hide;
+      page.readonly = fallBackBehaviour?.readonly;
+    }
+
+    // filter page-level markdown behaviour
+    if (page.markdown) {
+      updateMarkdownRequiredBehaviour(page.markdown, intent);
+    }
+    // Before starting traversal, ensure nodes exist, at least as empty-arrays
+    page.sections = page.sections || [];
+
+    page.sections.forEach((section) => {
+      // TODO: Apply parentOverrides to sections if applicable
+      const secBehaviour = section.behaviours?.find((behaviour) => behaviour.intent === intent?.intent || intent);
+      if (secBehaviour) {
+        section.hide = secBehaviour?.hide;
+      } else {
+        const fallBackBehaviour = section.behaviours?.find((behaviour) => behaviour.intent === '*');
+        section.hide = fallBackBehaviour?.hide ?? section.hide;
+      }
+
+      // filter section-level markdown behaviour
+      if (section.markdown) {
+        updateMarkdownRequiredBehaviour(section.markdown, intent);
+      }
+
+      // Before starting traversal, ensure nodes exist, at least as empty-arrays
+      section.questions = section.questions || [];
+
+      section.questions.forEach((question: FormField) => {
+        if (question['behaviours']) {
+          updateQuestionRequiredBehaviour(question, intent?.intent || intent);
+          parentOverrides
+            ?.filter((override) => override.type == 'all' || override.type == 'field')
+            ?.forEach((override) => {
+              question[override.name] = override.value;
+            });
+        }
+
+        if (question.questions && question.questions.length) {
+          question.questions.forEach((childQuestion) => {
+            updateQuestionRequiredBehaviour(childQuestion, intent?.intent || intent);
+
+            parentOverrides
+              ?.filter((override) => override.type == 'all' || override.type == 'field')
+              ?.forEach((override) => {
+                childQuestion[override.name] = override.value;
+              });
+          });
+        }
+      });
+    });
+  });
+  return jsonBuffer;
+}
+
+// Helpers
+
+function updateQuestionRequiredBehaviour(question, intent: string) {
+  const requiredIntentBehaviour = question.behaviours?.find((behaviour) => behaviour.intent === intent);
+
+  const defaultIntentBehaviour = question.behaviours?.find((bevahiour) => bevahiour.intent === '*');
+  // If both required and default intents exist, combine them and update to question
+  if (requiredIntentBehaviour || defaultIntentBehaviour) {
+    // Remove the intent name props from each object
+    delete requiredIntentBehaviour?.intent;
+    delete defaultIntentBehaviour?.intent;
+
+    // Combine required and default intents following the rules:
+    // 1. The default intent is applied to all other intents
+    // 2. Intent-specific behaviour overrides default behaviour
+    const combinedBehaviours = Object.assign(defaultIntentBehaviour || {}, requiredIntentBehaviour || {});
+    const defaultValue = combinedBehaviours.defaultValue;
+    if (defaultValue != undefined) {
+      // add the default value under the question options
+      question.questionOptions.defaultValue = defaultValue;
+      // delete it so that it's not added at the root level of the question
+      delete combinedBehaviours.defaultValue;
+    }
+    // Add the combinedBehaviours data to initial question
+    question = Object.assign(question, combinedBehaviours);
+    // Remove behaviours list
+    delete question.behaviours;
+  }
+}
+
+function updateMarkdownRequiredBehaviour(markdown, intent) {
+  const requiredIntentBehaviour = markdown.behaviours?.find((behaviour) => behaviour.intent === intent);
+  const defaultIntentBehaviour = markdown.behaviours?.find((behaviour) => behaviour.intent === '*');
+
+  if (requiredIntentBehaviour && defaultIntentBehaviour) {
+    delete requiredIntentBehaviour.intent;
+    delete defaultIntentBehaviour.intent;
+    const combinedBehaviours = Object.assign(defaultIntentBehaviour, requiredIntentBehaviour);
+
+    markdown = Object.assign(markdown, combinedBehaviours);
+    delete markdown.behaviours;
+  } else if (!requiredIntentBehaviour && defaultIntentBehaviour) {
+    delete defaultIntentBehaviour.intent;
+
+    markdown = Object.assign(markdown, defaultIntentBehaviour);
+    delete markdown.behaviours;
+  }
+}
+
+export function updateExcludeIntentBehaviour(excludedIntents: Array<string>, originalJson) {
+  originalJson.availableIntents = originalJson.availableIntents.filter(
+    (intent) => !excludedIntents.includes(intent?.intent || intent),
+  );
+  return originalJson;
+}
+
+export function addToBaseFormsRegistry(customRegistry: Record<string, any>) {
+  baseRegistry = { ...baseRegistry, ...customRegistry };
+}
+
+function isPositiveInteger(x) {
+  return /^\d+$/.test(x);
+}
+
+function formsVersionComparator(v1, v2) {
+  let v1parts = v1.split('.');
+  let v2parts = v2.split('.');
+  // First, validate both numbers are true version numbers
+  function validateParts(parts) {
+    for (let i = 0; i < parts.length; ++i) {
+      if (!isPositiveInteger(parts[i])) {
+        return false;
+      }
+    }
+    return true;
+  }
+  if (!validateParts(v1parts) || !validateParts(v2parts)) {
+    return NaN;
+  }
+  for (let i = 0; i < v1parts.length; ++i) {
+    if (v2parts.length === i) {
+      return 1;
+    }
+    if (v1parts[i] === v2parts[i]) {
+      continue;
+    }
+    if (v1parts[i] > v2parts[i]) {
+      return 1;
+    }
+    return -1;
+  }
+  if (v1parts.length != v2parts.length) {
+    return -1;
+  }
+  return 0;
+}

package/src/utils/post-submission-action-helper.ts

@@ -0,0 +1,71 @@
+export function evaluatePostSubmissionExpression(expression: string, encounters: any[]): boolean {
+  const encounter = encounters[0];
+  const regx = /(?:\w+|'(?:\\'|[^'\n])*')/g;
+  let match;
+  const fieldIds = new Set<string>();
+  try {
+    while ((match = regx.exec(expression))) {
+      const value = match[0].replace(/\\'/g, "'"); // Replace escaped single quotes
+
+      const isBoolean = /^(true|false)$/i.test(value);
+      const isNumber = /^-?\d+$/.test(value);
+      const isFloat = /^-?\d+\.\d+$/.test(value);
+
+      if (
+        !(value.startsWith("'") && value.endsWith("'")) &&
+        typeof value === 'string' &&
+        !isBoolean &&
+        !isNumber &&
+        !isFloat
+      ) {
+        fieldIds.add(value);
+      }
+    }
+
+    let fieldToValueMap = {};
+    let replacedExpression;
+    if (fieldIds.size) {
+      fieldToValueMap = getFieldValues(fieldIds, encounter);
+    }
+
+    if (Object.keys(fieldToValueMap).length) {
+      replacedExpression = expression.replace(/(\w+)/g, (match) => {
+        return Object.prototype.hasOwnProperty.call(fieldToValueMap, match) ? fieldToValueMap[match] : match;
+      });
+    } else {
+      replacedExpression = expression;
+    }
+
+    return eval(replacedExpression);
+  } catch (error) {
+    throw new Error('Error evaluating expression');
+  }
+}
+
+function getFieldValues(fieldIds: Set<string>, encounter: any): Record<string, any> {
+  const result: Record<string, any> = {};
+  fieldIds.forEach((fieldId) => {
+    let value = encounter.obs?.find((item) => item.formFieldPath.includes(fieldId))?.value;
+    if (typeof value === 'object') {
+      value = value.uuid;
+    }
+    if (value) {
+      value = formatValue(value);
+    }
+    result[fieldId] = value;
+  });
+
+  return result;
+}
+
+//This function wraps string values in single quotes which Javascript will evaluate
+function formatValue(value: any): any {
+  if (typeof value === 'string') {
+    if (value.length >= 2 && value[0] === "'" && value[value.length - 1] === "'") {
+      return value;
+    } else {
+      return `'${value}'`;
+    }
+  }
+  return value;
+}