@hedia/recommendation-screen 2.1.15 → 2.1.16

package/src/utils/Validations.js

@@ -1,10 +1,34 @@
-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, Languages, UserSettings, } from "@hedia/types";
 import moment from "moment";
 import { ACTIVITY_BUFFER_MINUTES, ACTIVITY_DURATION_MINUTES_LIMITS, ACTIVITY_SETTINGS_INTERVAL_LIMITS, ACTIVITY_TARGET_BGL_MMOL_LIMITS, BOLUS_SECONDS_PASSED_LIMITS, CARBOHYDRATES_LIMTS, CURRENT_BGL_MMOL_LIMITS, CURRENT_BKL_MMOL_LIMITS, INSULIN_DOSE_LIMITS, INSULIN_SENSITIVITY_MMOL_LIMITS, INSULIN_TO_CARBS_RATIO_LIMITS, ONE_HOUR_MINUTES, REMINDER_HOURS_LIMITS, TARGET_BGL_MMOL_LIMITS, } from "./Constants";
 import { ActivityDateError, ActivityDurationError, ActivityIntensityError, ActivitySettingsError, ActivityTargetBGLError, ActivityTypeError, BloodGlucoseUnitError, BloodKetonePropsError, BloodKetoneUnitError, BolusInsulinDoseError, BolusInsulinSecondsPassedError, CarbohydrateLimitError, CurrentBGLError, CurrentBKLError, InjectionMethodError, InsulinSensitivityError, InsulinToCarbsRatioError, LanguageError, LatestLogbook6HoursBGLError, RecentBolusError, TargetBGLError, UserReminderError, } from "./RecommendationError";
 import { Utils } from "./Utils";
 const { hard } = Activity.Enums.ActivityIntensity;
 const { fromFortysix } = Activity.Enums.ActivityReductionIntervals;
+/**
+ * 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 function validateParams(props) {
     checkCalculatorParams(props.calculatorParams);
     checkBGLUnit(props.bloodGlucoseUnit);
@@ -19,16 +43,42 @@ export function validateParams(props) {
         checkActivityType(props.activityDisplayProps.activityType);
     }
 }
+/**
+ * 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 function checkBKProps(bloodKetoneUnit, currentBKL) {
     if (currentBKL !== null && bloodKetoneUnit === null) {
         throw BloodKetonePropsError();
     }
 }
+/**
+ * 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 function checkLanguage(language) {
     if (!Object.values(Languages).includes(language)) {
         throw LanguageError();
     }
 }
+/**
+ * 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 function checkLatestLogbook6Hours(logbook) {
     if (logbook === undefined) {
         throw LatestLogbook6HoursBGLError();
@@ -39,18 +89,42 @@ export function checkLatestLogbook6Hours(logbook) {
         }
     }
 }
+/**
+ * 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 function checkInjectionMethod(injectionMethod) {
     const check = Object.values(UserSettings.Enums.InjectionMethod).some((method) => method === injectionMethod);
     if (!check) {
         throw InjectionMethodError();
     }
 }
+/**
+ * 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 function checkBGLUnit(unit) {
     const check = Object.values(BloodGlucoseUnit).some((enumUnit) => enumUnit === unit);
     if (!check) {
         throw BloodGlucoseUnitError();
     }
 }
+/**
+ * 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 function checkBKLUnit(unit) {
     if (unit !== null) {
         const check = Object.values(BloodKetonesUnit).some((enumUnit) => enumUnit === unit);
@@ -59,12 +133,34 @@ export function checkBKLUnit(unit) {
         }
     }
 }
+/**
+ * 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 function checkUserReminder(userReminder) {
     if (!Utils.isInRange(userReminder, REMINDER_HOURS_LIMITS)) {
         throw UserReminderError();
     }
 }
-function checkCalculatorParams(calculatorParams) {
+/**
+ * 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 function checkCalculatorParams(calculatorParams) {
     checkActivity(calculatorParams.activity);
     checkCarbohydrates(calculatorParams.carbohydrates);
     checkCurrentBGL(calculatorParams.currentBGL);
@@ -75,6 +171,18 @@ function checkCalculatorParams(calculatorParams) {
     checkRecentBolusesInsulinDose(calculatorParams.recentBoluses);
     checkRecentBolusesSecondsPassed(calculatorParams.recentBoluses);
 }
+/**
+ * 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 function checkActivity(activity) {
     if (activity) {
         checkActivityDate(activity);
@@ -84,11 +192,27 @@ export function checkActivity(activity) {
         checkActivityTargetBGL(activity.activitySettings.target);
     }
 }
+/**
+ * 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 function checkRecentBolus(recentBoluses) {
     if (recentBoluses === null || recentBoluses === undefined) {
         throw RecentBolusError();
     }
 }
+/**
+ * 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 function checkRecentBolusesInsulinDose(recentBoluses) {
     recentBoluses.forEach((bolus) => {
         if (!Utils.isInRange(bolus.insulinDose, INSULIN_DOSE_LIMITS)) {
@@ -96,6 +220,15 @@ export function checkRecentBolusesInsulinDose(recentBoluses) {
         }
     });
 }
+/**
+ * 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 function checkRecentBolusesSecondsPassed(recentBoluses) {
     recentBoluses.forEach((bolus) => {
         if (!Utils.isInRange(bolus.secondsPassed, BOLUS_SECONDS_PASSED_LIMITS)) {
@@ -103,23 +236,55 @@ export function checkRecentBolusesSecondsPassed(recentBoluses) {
         }
     });
 }
+/**
+ * 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 function checkActivityDuration(activityDuration) {
     if (!Utils.isInRange(activityDuration, ACTIVITY_DURATION_MINUTES_LIMITS)) {
         throw ActivityDurationError();
     }
 }
+/**
+ * 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 function checkActivityIntensity(activityIntensity) {
     const check = Object.values(Activity.Enums.ActivityIntensity).some((method) => method === activityIntensity?.toLowerCase());
     if (!check) {
         throw ActivityIntensityError();
     }
 }
+/**
+ * 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 function checkActivityType(activityType) {
     const check = Object.values(Activity.Enums.ActivityEnum).some((method) => method === activityType);
     if (!check) {
         throw ActivityTypeError();
     }
 }
+/**
+ * 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 function checkActivityDate(activity) {
     const maximumDate = moment
         .utc(activity.activityDate)
@@ -128,6 +293,15 @@ export function checkActivityDate(activity) {
         throw ActivityDateError();
     }
 }
+/**
+ * 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 function checkActivitySettings(activitySettings) {
     for (const intensity of Object.keys(activitySettings)) {
         const reductionIntervals = activitySettings[intensity];
@@ -145,11 +319,25 @@ export function checkActivitySettings(activitySettings) {
         }
     }
 }
+/**
+ * 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 function checkActivityTargetBGL(activitySettingsTargetBGL) {
     if (!Utils.isInRange(activitySettingsTargetBGL, ACTIVITY_TARGET_BGL_MMOL_LIMITS)) {
         throw ActivityTargetBGLError();
     }
 }
+/**
+ * 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 function checkCurrentBGL(currentBGL) {
     if (currentBGL !== null) {
         if (!Utils.isInRange(currentBGL, CURRENT_BGL_MMOL_LIMITS)) {
@@ -157,11 +345,25 @@ export function checkCurrentBGL(currentBGL) {
         }
     }
 }
+/**
+ * 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 function checkTargetBGL(targetBGL) {
     if (!Utils.isInRange(targetBGL, TARGET_BGL_MMOL_LIMITS)) {
         throw TargetBGLError();
     }
 }
+/**
+ * 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 function checkBloodKetoneLevel(currentBKL) {
     if (currentBKL !== null) {
         if (!Utils.isInRange(currentBKL, CURRENT_BKL_MMOL_LIMITS)) {
@@ -169,16 +371,37 @@ export function checkBloodKetoneLevel(currentBKL) {
         }
     }
 }
+/**
+ * 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 function checkInsulinSensitivity(insulinSensitivity) {
     if (!Utils.isInRange(insulinSensitivity, INSULIN_SENSITIVITY_MMOL_LIMITS)) {
         throw InsulinSensitivityError();
     }
 }
+/**
+ * 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 function checkInsulinToCarbRatio(insulinToCarbRatio) {
     if (!Utils.isInRange(insulinToCarbRatio, INSULIN_TO_CARBS_RATIO_LIMITS)) {
         throw InsulinToCarbsRatioError();
     }
 }
+/**
+ * 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 function checkCarbohydrates(carbohydrates) {
     if (!Utils.isInRange(carbohydrates, CARBOHYDRATES_LIMTS)) {
         throw CarbohydrateLimitError();

package/typedoc.json

@@ -0,0 +1,13 @@
+{
+	"entryPoints": [
+        "./src/RecommendationScreen.tsx", 
+        "./src/components/", 
+        "./src/locale/i18nUtils.ts",
+        "./src/utils/", 
+        "./src/types/",
+        "./node_modules/@hedia/types/dist/index.d.ts"
+    ],
+    "includes": "./node_modules/@hedia/types/dist/",
+    "excludeInternal": true,
+    "includeVersion": true
+}