@olaboot/esm-form-engine-lib 4.1.0

package/dist/utils/common-expression-helpers.d.ts

@@ -0,0 +1,261 @@
+import dayjs from 'dayjs';
+import { type FormField } from '../types';
+import { type FormNode } from './expression-runner';
+import { isEmpty as isValueEmpty } from '../validators/form-validator';
+import * as apiFunctions from '../api';
+export declare class CommonExpressionHelpers {
+    node: FormNode;
+    patient: any;
+    allFields: FormField[];
+    allFieldValues: Record<string, any>;
+    api: typeof apiFunctions;
+    isEmpty: typeof isValueEmpty;
+    dayjs: typeof dayjs;
+    constructor(node: FormNode, patient: any, allFields: FormField[], allFieldValues: Record<string, any>);
+    /**
+     * Shared helper for Z-score calculations. Finds the standard deviation (SD) value
+     * by comparing a measurement against WHO growth reference data.
+     * @param refSectionObject - Reference data object with SD columns (e.g., '-3SD', '-2SD', etc.)
+     * @param measurementValue - The patient's measurement to compare against reference values
+     * @returns The SD score as a string (e.g., '-2', '0', '1') or null if no reference data
+     */
+    private calculateZScoreFromRef;
+    /**
+     * Returns the current date and time.
+     * @returns A new Date object representing the current moment
+     */
+    today: () => Date;
+    /**
+     * Checks if a collection contains a specific value.
+     * @param collection - The array to search in
+     * @param value - The value to search for
+     * @returns true if the collection contains the value, false otherwise
+     */
+    includes: <T = any>(collection: T[], value: T) => boolean;
+    /**
+     * Checks if the left date is before the right date.
+     * @param left - The date to check
+     * @param right - The date to compare against (can be a Date object or string)
+     * @param format - Optional format string for parsing right date (defaults to 'YYYY-MM-DD')
+     * @returns true if left is before right
+     */
+    isDateBefore: (left: Date, right: string | Date, format?: string) => boolean;
+    /**
+     * Checks if selectedDate is on or after baseDate plus a duration offset.
+     * @param selectedDate - The date to check
+     * @param baseDate - The base date to add the duration to
+     * @param duration - The number of time units to add to baseDate
+     * @param timePeriod - The time unit: 'days', 'weeks', 'months', or 'years'
+     * @returns true if selectedDate >= (baseDate + duration)
+     */
+    isDateAfter: (selectedDate: Date, baseDate: Date, duration: number, timePeriod: "days" | "weeks" | "months" | "years") => boolean;
+    /**
+     * Adds weeks to a date without mutating the original.
+     * @param date - The starting date
+     * @param weeks - Number of weeks to add
+     * @returns A new Date object with the weeks added
+     */
+    addWeeksToDate: (date: Date, weeks: number) => Date;
+    /**
+     * Adds days to a date without mutating the original.
+     * @param date - The starting date
+     * @param days - Number of days to add
+     * @returns A new Date object with the days added
+     */
+    addDaysToDate: (date: Date, days: number) => Date;
+    /**
+     * Simple date comparison - checks if left date is strictly after right date.
+     * Mirrors the API of isDateBefore for consistency.
+     * @param left - The date to check
+     * @param right - The date to compare against (string or Date)
+     * @param format - Optional format string for parsing right date (defaults to 'YYYY-MM-DD')
+     * @returns true if left is after right
+     */
+    isDateAfterSimple: (left: Date, right: string | Date, format?: string) => boolean;
+    /**
+     * Retrieves the current value of another form field and registers a dependency.
+     * When the referenced field changes, expressions using this helper will be re-evaluated.
+     * @param questionId - The ID of the field to get the value from
+     * @returns The field's current value, or null if not found/set
+     */
+    useFieldValue: (questionId: string) => any;
+    /**
+     * Tests if a value does NOT match a regular expression pattern.
+     * Returns true for empty/null/undefined values (treated as non-matching).
+     * @param regexString - The regular expression pattern to test against
+     * @param val - The value to test
+     * @returns true if the value does not match the pattern or is empty/null/undefined
+     */
+    doesNotMatchExpression: (regexString: string, val: string | null | undefined) => boolean;
+    /**
+     * Calculates Body Mass Index (BMI) from height and weight.
+     * Formula: weight (kg) / height (m)²
+     * @param height - Height in centimeters
+     * @param weight - Weight in kilograms
+     * @returns BMI rounded to 1 decimal place, or null if inputs are missing
+     */
+    calcBMI: (height: number, weight: number) => number;
+    /**
+     * Calculates the Expected Date of Delivery (EDD) from the last menstrual period.
+     * Uses Naegele's rule: LMP + 280 days (40 weeks).
+     * @param lmp - Last menstrual period date
+     * @returns Expected delivery date, or null if lmp is not provided
+     */
+    calcEDD: (lmp: Date) => Date | null;
+    /**
+     * Calculates the number of complete months a patient has been on ART.
+     * @param artStartDate - The date when ART treatment started
+     * @returns Number of months on ART, 0 if less than 30 days, or null if no start date
+     * @throws Error if artStartDate is not a valid Date object
+     */
+    calcMonthsOnART: (artStartDate: Date) => number;
+    /**
+     * Determines viral load suppression status based on the viral load count.
+     *
+     * WARNING: This function returns hardcoded concept UUIDs that are specific to certain
+     * OpenMRS implementations. These UUIDs may not exist or may differ in your system.
+     * Consider using form-level configuration or concept mappings instead.
+     *
+     * @param viralLoadCount - The viral load count (copies/mL)
+     * @returns Concept UUID based on suppression threshold (>50 copies/mL), or null if no count
+     * @deprecated Consider implementing viral load status logic in form expressions with
+     *             configurable concept UUIDs instead of using this hardcoded helper.
+     */
+    calcViralLoadStatus: (viralLoadCount: number) => string;
+    /**
+     * Calculates the next clinic visit date based on ARV dispensing duration.
+     * @param followupDate - The current follow-up/encounter date
+     * @param arvDispensedInDays - Number of days of ARV medication dispensed
+     * @returns The next visit date (followupDate + arvDispensedInDays), or null if inputs are missing
+     */
+    calcNextVisitDate: (followupDate: Date, arvDispensedInDays: number) => Date | null;
+    /**
+     * Calculates the treatment end date for patients on ART.
+     * Adds a 30-day grace period plus the ARV dispensing duration.
+     *
+     * WARNING: This function checks against a hardcoded concept UUID (160429AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA)
+     * for 'Currently in Treatment' status. This UUID may not exist or may differ in your system.
+     * Consider implementing this logic in form expressions with configurable concept references instead.
+     *
+     * @param followupDate - The current follow-up/encounter date
+     * @param arvDispensedInDays - Number of days of ARV medication dispensed
+     * @param patientStatus - The patient's treatment status UUID (must match hardcoded UUID)
+     * @returns Treatment end date (followupDate + 30 + arvDispensedInDays), or null if conditions not met
+     * @deprecated Consider implementing treatment end date logic in form expressions with
+     *             configurable concept UUIDs instead of using this hardcoded helper.
+     */
+    calcTreatmentEndDate: (followupDate: Date, arvDispensedInDays: number, patientStatus: string) => Date | null;
+    /**
+     * Calculates the patient's age in years based on a reference date.
+     * Note: Uses year-only calculation (ignores month/day), so a patient born in December 1990
+     * will be considered 31 years old on January 1, 2021.
+     * @param dateValue - The reference date to calculate age at (defaults to today if not provided)
+     * @returns Age in years (year difference only, not precise age)
+     */
+    calcAgeBasedOnDate: (dateValue?: ConstructorParameters<typeof Date>[0] | null) => number;
+    /**
+     * Calculates Body Surface Area (BSA) using the Mosteller formula.
+     * Formula: √((height × weight) / 3600)
+     * @param height - Height in centimeters
+     * @param weight - Weight in kilograms
+     * @returns BSA in m² rounded to 2 decimal places, or null if inputs are missing
+     */
+    calcBSA: (height: number, weight: number) => number | null;
+    /**
+     * Checks if an array contains ALL of the specified members.
+     * @param array - The array to search in
+     * @param members - A single value or array of values that must all be present
+     * @returns true if array contains all members, false otherwise.
+     *          Returns true for empty members array. Returns false for null/non-array input.
+     */
+    arrayContains: <T = any>(array: T[], members: T[] | T) => boolean;
+    /**
+     * Checks if an array contains ANY of the specified members.
+     * @param array - The array to search in
+     * @param members - An array of values where at least one must be present
+     * @returns true if array contains at least one member, false otherwise.
+     *          Returns true for empty members array. Returns false for null/non-array input.
+     */
+    arrayContainsAny: <T = any>(array: T[], members: T[]) => boolean;
+    /**
+     * Parses a date string into a Date object using OpenMRS framework parsing.
+     * @param dateString - The date string to parse
+     * @returns A Date object
+     */
+    parseDate: (dateString: string) => Date;
+    /**
+     * Formats a date value into a string.
+     * @param value - The date to format (Date object or value that can be converted to Date)
+     * @param format - Optional dayjs format string (e.g., 'YYYY-MM-DD', 'DD/MM/YYYY').
+     *                 If not provided, uses OpenMRS default locale format.
+     * @returns Formatted date string
+     * @throws Error if the value cannot be converted to a valid date
+     */
+    formatDate: (value: ConstructorParameters<typeof Date>[0], format?: string) => string;
+    /**
+     * Extracts values for a specific key from an array of objects (typically repeating group data).
+     * @param key - The property key to extract from each object
+     * @param array - Array of objects to extract values from
+     * @returns Array of values for the specified key
+     */
+    extractRepeatingGroupValues: (key: string | number | symbol, array: Record<string | number | symbol, unknown>[]) => unknown[];
+    /**
+     * Calculates the gravida (total number of pregnancies) based on term pregnancies and abortions/miscarriages.
+     * @param parityTerm - The number of term pregnancies (can be number or numeric string)
+     * @param parityAbortion - The number of abortions including miscarriages (can be number or numeric string)
+     * @returns The total number of pregnancies (gravida)
+     * @throws Error if either input is not a valid number
+     */
+    calcGravida: (parityTerm: number | string, parityAbortion: number | string) => number;
+    /**
+     * Calculates the Weight-for-Height Z-score for pediatric patients using WHO growth standards.
+     * Used to assess acute malnutrition (wasting).
+     * @param height - Patient's height/length in centimeters (valid range: 45-110 cm)
+     * @param weight - Patient's weight in kilograms
+     * @returns Z-score as a string (e.g., '-2', '0', '1'), '-4' if out of range, or null if inputs missing
+     */
+    calcWeightForHeightZscore: (height: number, weight: number) => string | null;
+    /**
+     * Calculates the BMI-for-Age Z-score for pediatric patients using WHO growth standards.
+     * Used to assess both undernutrition and overweight/obesity.
+     * @param height - Patient's height in centimeters
+     * @param weight - Patient's weight in kilograms
+     * @returns Z-score as a string (e.g., '-2', '0', '1'), or null if inputs missing
+     */
+    calcBMIForAgeZscore: (height: number, weight: number) => string | null;
+    /**
+     * Calculates the Height-for-Age Z-score for pediatric patients using WHO growth standards.
+     * Used to assess chronic malnutrition (stunting).
+     * @param height - Patient's height/length in centimeters
+     * @param _weight - Unused parameter kept for backward compatibility
+     * @returns Z-score as a string (e.g., '-2', '0', '1'), or null if height is missing
+     */
+    calcHeightForAgeZscore: (height: number, _weight?: number) => string | null;
+    /**
+     * Calculates the time difference between an observation date and today.
+     * @param obsDate - The observation/reference date to compare against today
+     * @param timeFrame - The unit of time: 'd' (days), 'w' (weeks), 'm' (months), or 'y' (years)
+     * @returns The absolute time difference as a number, or 0 if obsDate is not provided
+     */
+    calcTimeDifference: (obsDate: Date | dayjs.Dayjs, timeFrame: "d" | "w" | "m" | "y") => number;
+    /**
+     * Resolves a Promise and returns its value. Used to await async operations in form expressions.
+     * @param lazy - A Promise to resolve
+     * @returns A Promise that resolves to the value of the input Promise
+     */
+    resolve: (lazy: Promise<unknown>) => Promise<unknown>;
+}
+/**
+ * Simple hash function to generate a unique identifier for a string.
+ * @param str - The string to hash.
+ * @returns A unique identifier for the string.
+ */
+export declare function simpleHash(str: string): number;
+/**
+ * Registers a dependency relationship between a form node and a field.
+ * When the determinant field's value changes, the dependent node will be re-evaluated.
+ * @param node - The dependent node (page, section, or field) that depends on the determinant
+ * @param determinant - The field that the node depends on
+ */
+export declare function registerDependency(node: FormNode, determinant: FormField): void;
+//# sourceMappingURL=common-expression-helpers.d.ts.map

package/dist/utils/common-expression-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common-expression-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/common-expression-helpers.ts"],"names":[],"mappings":"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"}