@hedia/recommendation-screen 2.1.14 → 2.1.16

package/src/utils/Utils.js

@@ -2,7 +2,20 @@ import { BloodGlucoseUnit, BloodKetonesUnit, UserSettings } from "@hedia/types";
 import { MGDL_PER_MMOLL_BGL, MGDL_PER_MMOLL_BKL } from "./Constants";
 const InjectionMethod = UserSettings.Enums.InjectionMethod;
 const { PenHalf, PenWhole, Pump } = InjectionMethod;
+/** Helper functions used for displaying data to the user. */
 export class Utils {
+    /**
+     * Get the inverse of the precision to an insulin amount should be rounded based on the user’s injection method.
+     *
+     * Steps:
+     * 1. Use a switch statement to return the appropriate number depending on the value of the method argument:
+     * 	- If PenWhole, return 1.
+     * 	- If PenHalf, return 2.
+     * 	- If Pump, return 10.
+     * 	- Otherwise throw an exception.
+     * @param method The method by which the user injects insulin.
+     * @returns The inverse of the precision to which an insulin amount should be rounded based on the user’s injection method.
+     */
     static getRounding(method) {
         switch (method) {
             case PenWhole:
@@ -15,33 +28,112 @@ export class Utils {
                 throw Error(`Unsupported InjectionMethod: ${method}`);
         }
     }
+    /**
+     * Round an insulin amount to the precision that is dictated by the user’s injection method.
+     *
+     * Steps:
+     * 1. Get the inverse rounding precision by calling getRounding() with injectMethod as argument.
+     * 2. Return the rounded insulin amount calculated by the following operations:
+     *  	- Multiply the insulin value prop by the inverse rounding precision.
+     *  	- Round to the nearest whole number.
+     *  	- Divide by the inverse rounding precision and return the result.
+     * @param value The amount of insulin to be rounded.
+     * @param injectMethod The method by which the user injects insulin.
+     * @returns The rounded insulin amount.
+     */
     static roundValue(value, injectMethod) {
         const rounding = Utils.getRounding(injectMethod);
         return Math.round(value * rounding) / rounding;
     }
+    /**
+     * Determine whether a numerical value is in the given closed interval.
+     *
+     * Steps:
+     * 1. If value is null then return false. (Note that we only need to check explicitly for null comparing it
+     *    to a number returns true while comparing undefined to a number returns false).
+     * 2. Evaluate whether value >= the interval argument’s min property && value <= the interval argument’s max property and return the result.
+     * @param value The number that will be checked for membership of the interval.
+     * @param interval The interval to compare the value to.
+     * @returns Boolean value indicating whether the value is in the closed interval.
+     */
     static isInRange(value, interval) {
         if (value === null) {
             return false;
         }
         return value >= interval.min && value <= interval.max;
     }
+    /**
+     * Convert a blood glucose level value from mmol/L to mg/dL.
+     *
+     * Steps:
+     * 1. Return the result of rounding the product of multiplying value with MGDL_PER_MMOLL_BGL.
+     * @param value The blood glucose level value in mmol/L to be converted.
+     * @returns The blood glucose value in mg/dL that corresponds to the given value in mmol/L.
+     */
     static convertBGLToMGDL(value) {
         return Math.round(value * MGDL_PER_MMOLL_BGL);
     }
+    /**
+     * Depending on the blood glucose unit passed, returns the value as a string or returns a stringified call to the convertBGLToMGDL method.
+     *
+     * Steps:
+     * 1. Using a ternary operator on the unit argument return the passed value argument in case unit is a MMOL_L.
+     * 	  Otherwise, return a call to the convertBGLToMGDL method with the value passed as an argument.
+     * @param value The blood glucose level value in mmol/L to be converted.
+     * @param unit The blood glucose measurement unit.
+     * @returns The blood glucose value that will be displayed to the user.
+     */
     static displayedBGLValue(value, unit) {
-        return unit === BloodGlucoseUnit.MMOL_L ? `${value}` : `${Utils.convertBGLToMGDL(value)}`;
+        return unit === BloodGlucoseUnit.MMOL_L ? value.toFixed(1) : `${Utils.convertBGLToMGDL(value)}`;
     }
+    /**
+     * Convert a blood ketones concentration from mmol/L to mg/dL.
+     * Steps:
+     * 1. Return the result of rounding the product of multiplying value with MGDL_PER_MMOLL_BKL.
+     * @param value The blood ketones concentration in mmol/L to be converted.
+     * @returns The blood ketones concentration in mg/dL that corresponds to the given value in mmol/L.
+     */
     static convertBKLToMGDL(value) {
         return Math.round(value * MGDL_PER_MMOLL_BKL);
     }
+    /**
+     * Depending on the blood ketone unit passed, returns the value as a string or returns a call to the convertBKLToMGDL method.
+     *
+     * Steps:
+     * 1. Using a ternary operator on the unit argument return the passed value argument in case unit is a MMOL_L.
+     *    Otherwise, return a call to the convertBKLToMGDL method with the value passed as an argument.
+     * @param value The blood ketone level value in mmol/L to be converted.
+     * @param unit The blood ketone measurement unit.
+     * @returns The blood ketone value that will be displayed to the user.
+     */
     static displayedBKLValue(value, unit) {
-        return unit === BloodKetonesUnit.MMOL_L ? `${value}` : `${Utils.convertBKLToMGDL(value)}`;
+        return unit === BloodKetonesUnit.MMOL_L ? value.toFixed(1) : `${Utils.convertBKLToMGDL(value)}`;
     }
+    /**
+     * Returns the key of key/value object when passing the key value as argument.
+     *
+     * Steps:
+     * 1. Save all the values of the keys object into the values constant
+     * 2. From the array of keys, return the one at the index of the first occurence of the value in the values constant
+     * @param keys The keys of the T object.
+     * @param value The value for the requested key.
+     * @returns The key of the passed value.
+     */
     static getKeyFromValue(keys, value) {
         const values = Object.values(keys);
         return Object.keys(keys)[values.indexOf(value)];
     }
 }
+/**
+ * Format a measurement unit for displaying to the user. More concrete, it is used to display the litre symbol with uppercase "L".
+ *
+ * Steps:
+ * 1. Set unitWithoutLastLetter to be unit except for the last character.
+ * 2. Set lastLetterUppercase to be the last letter of unit converted to uppercase.
+ * 3. Return unitWithoutLastLetter concatenated with lastLetterUppercase.
+ * @param unit The measurement unit to format.
+ * @returns The measurement unit formatted for displaying to the user.
+ */
 Utils.formatUnit = (unit) => {
     const unitWithoutLastLetter = unit.substring(0, unit.length - 1);
     const lastLetterUppercase = unit.substring(unit.length - 1, unit.length).toUpperCase();

package/src/utils/Validations.d.ts

@@ -1,27 +1,250 @@
-import { Activity, BloodGlucoseUnit, BloodKetonesUnit, Languages, UserSettings } from "@hedia/types";
+/**
+ * The validations module contains functions for checking the integrity of every single value that is being passed in to the recommendation screen from the outside.
+ * If any of the individual integrity checks fails, then an exception will be thrown to indicate that the data that was passed in is untrustworthy
+ * and prevent a recommendation to be shown to the user based on the corrupted data.
+ * @module
+ */
+import { Activity, BloodGlucoseUnit, BloodKetonesUnit, BolusCalculator, Languages, Logbook, UserSettings } from "@hedia/types";
 import { IRecommendationProps } from "../RecommendationScreen";
-import { ActivitySettings, IActivityParams, IRecentBolus, logbookEntry } from "../types/types";
+/**
+ * Main function for validating all input properties for the insulin recommendation screen component.
+ * Throws an exception if any of the individual checks fail.
+ *
+ * Steps:
+ * 1.  Call checkCalculatorParams() with the calculatorParams property of the props as argument.
+ * 2.  Call checkBGLUnit() with the bloodGlucoseUnit property of the props as argument.
+ * 3.  Call checkBKProps() with the bloodKetoneUnit and currentBKL properties of the props as arguments.
+ * 4.  Call checkBKLUnit() with the bloodKetoneUnit property of the props as argument.
+ * 5.  Call checkBloodKetoneLevel() with the currentBKL property of the props as argument.
+ * 6.  Call checkInjectionMethod() with the injectionMethod property of the props as argument.
+ * 7.  Call checkUserReminder() with the userReminder property of the props as argument.
+ * 8.  Call checkLanguage() with the language property of the props as argument.
+ * 9.  Call checkLatestLogbook6Hours() with the latestLogbookFrom6Hours property of the props as argument.
+ * 10. If the activity property of the calculatorParams prop is truthy, and the activityDisplayProps prop is truthy:
+ * 	   call the checkActivityType method with the activityType property of the activityDisplayProps prop as the argument.
+ * @param props All the props that were passed in to the RecommendationScreen component.
+ */
 export declare function validateParams(props: IRecommendationProps): void;
+/**
+ * In case the users is providing a blood ketone current level, check if the blood ketone unit is defined.
+ *
+ * Steps:
+ * 1. If the currentBKL is not null and the bloodKetoneUnit is null throw an BloodKetonePropsError
+ * @param bloodKetoneUnit The user’s blood ketone unit.
+ * @param currentBKL The users’s current blood ketone level.
+ */
 export declare function checkBKProps(bloodKetoneUnit: BloodKetonesUnit | null, currentBKL: number | null): void;
+/**
+ * The user’s preferred language for using the app.
+ *
+ * Steps:
+ * 1. Search in the Languages enum values the language provided as an argument.
+ *    If language is not present in the  Languages enum values array, throw a LanguageError.
+ * @param language The user’s preferred language for using the app.
+ */
 export declare function checkLanguage(language: Languages): void;
-export declare function checkLatestLogbook6Hours(logbook: logbookEntry | null): void;
+/**
+ * Check if the latest logbook from the last 6 hours is valid.
+ *
+ * Steps:
+ * 1. If logbook is undefined, throw an LatestLogbook6HoursBGLError.
+ * 2. If logbook is not null and if the blood_glucose_millimolar property of the logbook object is not null,
+ *    check if the blood_glucose_millimolar is inside the allowed range for blood glucose level.
+ *    If it is not, throw LatestLogbook6HoursBGLError.
+ * @param logbook The user’s  latest logbook from the last 6 hours
+ */
+export declare function checkLatestLogbook6Hours(logbook: Logbook.Types.ILogbookEntry | null): void;
+/**
+ * Check if the injectionMethod parameter is valid.
+ *
+ * Steps:
+ * 1. Search in the InjectionMethod enum values the injectionMethod provided as an argument.
+ *    If injectionMethod is not present in the InjectionMethod enum values array, throw a InjectionMethodError.
+ * @param injectionMethod The user’s insulin injection method.
+ */
 export declare function checkInjectionMethod(injectionMethod: UserSettings.Enums.InjectionMethod): void;
+/**
+ * Check if the blood glucose unit parameter is valid.
+ * Steps:
+ * 1. Search in the BloodGlucoseUnit enum values the unit provided as an argument.
+ *    If unit is not present in the BloodGlucoseUnit enum values array, throw a BloodGlucoseUnitError.
+ * @param unit The user’s preferred blood glucose unit for using the app.
+ */
 export declare function checkBGLUnit(unit: BloodGlucoseUnit): void;
+/**
+ * Check if the blood ketones unit parameter is valid.
+ *
+ * Steps:
+ * 1. If the unit is not null, search in the BloodKetonesUnit enum values the unit provided as an argument.
+ *    If unit is not present in the BloodKetonesUnit enum values array, throw a BloodKetoneUnitError.
+ * @param unit The user’s preferred blood ketones unit for using the app.
+ * It can be null if the user did not choose a measurement unit at the moment of this validation.
+ */
 export declare function checkBKLUnit(unit: BloodKetonesUnit | null): void;
+/**
+ * Check if the users preferred default reminder duration is valid by verifying that it is within the allowed range.
+ *
+ * Steps:
+ * 1. Use isInRange() {@link Utils} to check if userReminder is in the interval [0; 6]. If it isn’t then throw an UserReminderError().
+ * @param userReminder The default reminder time in hours from the user’s settings
+ */
 export declare function checkUserReminder(userReminder: number): void;
-export declare function checkActivity(activity: IActivityParams | null): void;
-export declare function checkRecentBolus(recentBoluses: Array<IRecentBolus>): void;
-export declare function checkRecentBolusesInsulinDose(recentBoluses: Array<IRecentBolus>): void;
-export declare function checkRecentBolusesSecondsPassed(recentBoluses: Array<IRecentBolus>): void;
+/**
+ * Check validity of the values that are used as input for the actual insulin recommendation calculation.
+ *
+ * Steps:
+ * 1. Call checkActivity() with the activity property of the calculatorParams as argument.
+ * 2. Call checkCarbohydrates() with the carbohydrates property of the calculatorParams as argument.
+ * 3. Call checkCurrentBGL() with the currentBGL property of the calculatorParams as argument.
+ * 4. Call checkTargetBGL() with the targetBGL property of the calculatorParams as argument.
+ * 5. Call checkInsulinToCarbRatio() with the carbohydrateRatio property of the calculatorParams as argument.
+ * 6. Call checkInsulinSensitivity() with the insulinSensitivity property of the calculatorParams as argument.
+ * 7. Call checkRecentBolus() with the recentBoluses property of the calculatorParams as argument.
+ * 8. Call checkRecentBolusesInsulinDose() with the recentBoluses property of the calculatorParams as argument.
+ * 9. Call checkRecentBolusesSecondsPassed() with the recentBoluses property of the calculatorParams as argument.
+ * @param calculatorParams The inputs for calculation to be checked
+ */
+export declare function checkCalculatorParams(calculatorParams: BolusCalculator.Types.IRecommendationParams): void;
+/**
+ * Check the validity of the values inputted for physical activity
+ *
+ * Steps:
+ * 1. If the activity argument is truthy do the following:
+ * - Call checkActivityDate() with the activity as argument
+ * - Call checkActivityDuration() with the activityDuration property of the activity as argument
+ * - Call checkActivityIntensity() with the activityIntensity property of the activity as argument
+ * - Call checkActivitySettings() with the activitySettings property of the activity as argument
+ * - Call checkActivityTargetBGL() with the activitySettings.target property of the activity as argument
+ * @param activity  The activity that is associated with the calculation, or null if no activity was entered
+ */
+export declare function checkActivity(activity: BolusCalculator.Types.IActivityParams | null): void;
+/**
+ * Check if the recentBoluses is in the right format.
+ *
+ * Steps:
+ * 1. If recentBoluses is null or undefined throw a RecentBolusError.
+ * @param recentBoluses List of all known bolus injections from the past 4 hours including insulin amount and how many seconds has passed since the injection.
+ */
+export declare function checkRecentBolus(recentBoluses: Array<BolusCalculator.Types.IRecentBolus>): void;
+/**
+ * Check if the insulin dose in each of the given recent insulin injections is valid by verifying that they are within the allowed range.
+ *
+ * Steps
+ * 1. If recentBoluses isn’t null, for each bolus element in recentBoluses
+ * 	  use isInRange() to check if the insulinDose parameter of the bolus element is in the interval [0; 50].
+ * 	  If it isn’t then throw an BolusInsulinDoseError().
+ * @param recentBoluses List of all known bolus injections from the past 4 hours including insulin amount and how many seconds has passed since the injection.
+ */
+export declare function checkRecentBolusesInsulinDose(recentBoluses: Array<BolusCalculator.Types.IRecentBolus>): void;
+/**
+ * Check if the amount of time since each recent insulin injection is valid by verifying that they are within the allowed range.
+ *
+ * Steps:
+ * 1. If recentBoluses isn’t null, for each bolus element in recentBoluses
+ *    use isInRange() to check if the secondsPassed parameter of the bolus element is in the interval [0; 1440].
+ *    If it isn’t then throw an BolusInsulinSecondsPassedError().
+ * @param recentBoluses List of all known bolus injections from the past 4 hours including insulin amount and how many seconds has passed since the injection.
+ */
+export declare function checkRecentBolusesSecondsPassed(recentBoluses: Array<BolusCalculator.Types.IRecentBolus>): void;
+/**
+ * Check if the duration of an entered activity is valid by verifying that it is within the allowed range.
+ *
+ * Steps:
+ * 1. Use isInRange() to check if activityDuration is in the interval [0; 60]. If it isn’t then throw an ActivityDurationError().
+ * @param activityDuration The duration of an entered physical activity in minutes.
+ */
 export declare function checkActivityDuration(activityDuration: number): void;
+/**
+ * Check if the activity intensity parameter is valid.
+ *
+ * Steps:
+ * 1. Search in the {@link ActivityIntensity} enum values the activityIntensity provided as an argument.
+ *    If activityIntensity is not present in the ActivityIntensity enum values array, throw an ActivityIntensityError.
+ * @param activityIntensity The intensity of the entered activity.
+ */
 export declare function checkActivityIntensity(activityIntensity: Activity.Enums.ActivityIntensity): void;
+/**
+ * Check if the activity type parameter is valid.
+ *
+ * Steps:
+ * 1. Search in the {@link ActivityEnum} enum values the activityType provided as an argument.
+ *    If activityType is not present in the ActivityEnum enum values array, throw an ActivityTypeError.
+ * @param activityType The type of the entered activity.
+ */
 export declare function checkActivityType(activityType: Activity.Enums.ActivityEnum | null): void;
-export declare function checkActivityDate(activity: IActivityParams): void;
-export declare function checkActivitySettings(activitySettings: ActivitySettings): void;
+/**
+ * Verify that the ending time of the given activity has not been passed by more than 4 hours and 10 minutes.
+ *
+ * Steps:
+ * 1. Use the moment library to create an object that represents the start time of the activity by loading from the activityDate property of the activity argument.
+ *    Add to the object the duration of the activity plus 4 hours and 10 minutes and save the resulting date as maximumDate.
+ * 2. Check if the current time is after maximumDate throw an ActivityDateError().
+ * @param activity The activity for which we want to check the date
+ */
+export declare function checkActivityDate(activity: BolusCalculator.Types.IActivityParams): void;
+/**
+ * Steps:
+ * 1. Iterate over all combinations of activity intensities and activity duration intervals and for each one:
+ * 	- If the current intensity is hard and the duration is long (fromFortysix) then check that the value from activitySettings
+ * for the current combination of activity intensity is either null or in the interval [0; 1]
+ * 	- If the current intensity isn’t hard or the duration isn’t long then use isInRange() to check that the value from activitySettings
+ * for the current combination of activity intensity is in the interval [0; 1].
+ * @param activitySettings The user’s settings for doing physical activity
+ */
+export declare function checkActivitySettings(activitySettings: Activity.Types.ActivitySettings): void;
+/**
+ * Check if the target blood glucose level for doing exercise is valid by verifying that it is within the allowed range.
+ *
+ * Steps:
+ * 1. Use isInRange() to check if activitySettingsTargetBGL is in the interval [5.0; 13.9]. If it isn’t then throw an ActivityTargetBGLError().
+ * @param activitySettingsTargetBGL The target blood glucose level for doing exercise in mmol/L from the user’s settings.
+ */
 export declare function checkActivityTargetBGL(activitySettingsTargetBGL: number): void;
+/**
+ * Check if the current blood glucose level is valid by verifying that it is either null or within the allowed range.
+ * Steps:
+ * 1. If currentBGL is not null then use isInRange() to check if currentBGL is in the interval [1.1; 33.3].
+ *    If it isn’t then throw a CurrentBGLError().
+ * @param currentBGL The current blood glucose level in mmol/L entered by the user, or null to indicate that the value is unknown because it wasn’t given.
+ */
 export declare function checkCurrentBGL(currentBGL: number | null): void;
+/**
+ * Check if the target blood glucose level is valid by verifying that it is within the allowed range.
+ *
+ * Steps:
+ * 1. Use isInRange() to check if targetBGL is in the interval [5.0; 13.9]. If it isn’t then throw a TargetBGLError().
+ * @param targetBGL The target blood glucose level in mmol/L extracted from the user’s settings depending on the time of day.
+ */
 export declare function checkTargetBGL(targetBGL: number): void;
+/**
+ * Check if the current blood ketones concentration is valid by verifying that it is either null or within the allowed range.
+ *
+ * Steps:
+ * 1. If currentBKL is not null then use isInRange() to check if currentBGL is in the interval [0.0; 8.0]. If it isn’t then throw a CurrentBKLError().
+ * @param currentBKL The current blood ketones concentration in mmol/L entered by the user, or null to indicate that the value is unknown because it wasn’t given.
+ */
 export declare function checkBloodKetoneLevel(currentBKL: number | null): void;
+/**
+ * Check if the insulin sensitivity is valid by verifying that it is within the allowed range.
+ *
+ * Steps:
+ * 1. Use isInRange() to check if insulinSensitivity is in the interval [0.3; 10]. If it isn’t then throw an InsulinSensitivityError().
+ * @param insulinSensitivity The insulin sensitivity in (mmol/L)/IU extracted from the user’s settings depending on the time of day.
+ */
 export declare function checkInsulinSensitivity(insulinSensitivity: number): void;
+/**
+ * Check if the insulin-to-carbs ratio is valid by verifying that it is within the allowed range.
+ *
+ * Steps:
+ * 1. Use isInRange() to check if insulinToCarbRatio is in the interval [1; 50]. If it isn’t then throw an InsulinToCarbsRatioError().
+ * @param insulinToCarbRatio The insulin-to-carbs ratio in g/IU extracted from the user’s settings depending on the time of day.
+ */
 export declare function checkInsulinToCarbRatio(insulinToCarbRatio: number): void;
+/**
+ * Check if the entered amount of carbohydrates is valid by verifying that it is within the allowed range.
+ *
+ * Steps:
+ * 1. Use isInRange() to check if carbohydrates is in the interval [0; 300]. If it isn’t then throw a CarbohydrateLimitError().
+ * @param carbohydrates The amount of carbohydrates that the user is eating in grams.
+ */
 export declare function checkCarbohydrates(carbohydrates: number): void;