@hedia/recommendation-screen 2.1.15 → 2.1.17-alpha

package/src/utils/Constants.js

@@ -1,24 +1,47 @@
 import { BolusCalculator } from "@hedia/types";
+/** Reusable color definition. */
 export const BACKGROUND_COLOUR_PURPLE = `rgba(27, 31, 72, 1)`;
+/** Reusable color definition. */
 export const BORDER_COLOUR_GREY = `rgba(74, 91, 134, 1)`;
+/** Reusable color definition. */
 export const BORDER_COLOUR_TEAL = `rgba(1, 255, 252, 0.8)`;
+/** The threshold above which hyperglycemia is considered to be severe in mmol/L */
 export const SEVERE_HYPERGLYCEMIA_START_MMOL = 15;
+/** The number of seconds in four hours. */
 export const FOUR_HOURS_SECONDS = 14400;
+/** The number of minutes in one hour. */
 export const ONE_HOUR_MINUTES = 60;
+/** Extra time before an activity starts or stops. */
 export const ACTIVITY_BUFFER_MINUTES = 10;
+/** The lower and upper limits for the amount of carbohydrates in grams. */
 export const CARBOHYDRATES_LIMTS = { min: 0, max: 300 };
+/** The lower and upper limits for the insulin dose in units. The upper limit is represented by the SAFETY_INSULIN_LIMIT constant while the lower limit is 0. */
 export const INSULIN_DOSE_LIMITS = { min: 0, max: BolusCalculator.Constants.SAFETY_INSULIN_LIMIT };
+/** The lower and upper limits for the age of boluses that gets taken into account for calculating insulin on board. */
 export const BOLUS_SECONDS_PASSED_LIMITS = { min: 0, max: FOUR_HOURS_SECONDS };
+/** The lower and upper limits for the duration of an activity in minutes. */
 export const ACTIVITY_DURATION_MINUTES_LIMITS = { min: 1, max: ONE_HOUR_MINUTES };
+/** The lower and upper limits of insulin sensitivity settings. */
 export const INSULIN_SENSITIVITY_MMOL_LIMITS = { min: 0.3, max: 10 };
+/** The lower and upper limits of insulin-to-carbs ratio settings. */
 export const INSULIN_TO_CARBS_RATIO_LIMITS = { min: 1, max: 50 };
+/** The lower and upper limits of the entered blood glucose level value in mmol/L. */
 export const CURRENT_BGL_MMOL_LIMITS = { min: 1.1, max: 33.3 };
+/** The conversion factor to multiply a blood glucose value with to go from mmol/L to mg/dL. */
 export const MMOLL_PER_MGDL_BGL = 0.0555;
+/** The conversion factor to multiply a blood glucose value with to go from mg/dL to mmol/L. */
 export const MGDL_PER_MMOLL_BGL = 1 / MMOLL_PER_MGDL_BGL;
+/** The lower and upper limits of the entered blood ketones value in mmol/L. */
 export const CURRENT_BKL_MMOL_LIMITS = { min: 0, max: 8 };
+/** The conversion factor to multiply a blood ketones value with to go from mmol/L to mg/dL. */
 export const MMOLL_PER_MGDL_BKL = 0.096;
+/** The conversion factor to multiply a blood ketones value with to go from mg/dL to mmol/L. */
 export const MGDL_PER_MMOLL_BKL = 1 / MMOLL_PER_MGDL_BKL;
+/** The lower and upper limits for a valid BGL target in mmol/L. */
 export const TARGET_BGL_MMOL_LIMITS = { min: 5, max: 13.9 };
+/** The lower and upper limits for a valid activity BGL target in mmol/L. */
 export const ACTIVITY_TARGET_BGL_MMOL_LIMITS = { min: 5, max: 13.9 };
+/** The lower and upper limits for how long the reminder notification timer may be. */
 export const REMINDER_HOURS_LIMITS = { min: 0, max: 6 };
+/** The lower and upper limits for activity reduction. */
 export const ACTIVITY_SETTINGS_INTERVAL_LIMITS = { min: 0, max: 1 };

package/src/utils/RecommendationError.d.ts

@@ -1,27 +1,56 @@
 import { RecommendationErrorEnum } from "../types/enum";
+/**
+ * Defines a set of human readable error messages.
+ * Each of them is defined as a function that returns the required translatable error message.
+ * The app should generally prevent the user from entering invalid values at the time of entry, so in almost all of these cases,
+ * the use of any of these errors indicate that something might have gone really wrong, and the user will be prevented
+ * from getting a recommendation until the problem is solved.
+ */
 export declare class RecommendationError extends Error {
     readonly type: RecommendationErrorEnum;
     constructor(message: string, type: RecommendationErrorEnum);
 }
+/** The given activity settings are corrupt. */
 export declare const ActivitySettingsError: () => RecommendationError;
+/** The duration of the given activity is invalid. */
 export declare const ActivityDurationError: () => RecommendationError;
+/** The start date of the given activity is invalid. */
 export declare const ActivityDateError: () => RecommendationError;
+/** The intensity of the given activity is invalid. */
 export declare const ActivityIntensityError: () => RecommendationError;
+/** Type of the given activity is invalid. */
 export declare const ActivityTypeError: () => RecommendationError;
+/** The user’s activity target BGL setting is invalid. */
 export declare const ActivityTargetBGLError: () => RecommendationError;
+/** More than 300 g carbohydrates entered. */
 export declare const CarbohydrateLimitError: () => RecommendationError;
+/** The user’s insulin sensitivity setting is outside of the valid range. */
 export declare const InsulinSensitivityError: () => RecommendationError;
+/** The user’s insulin-to-carbs ratio setting is outside of the valid range. */
 export declare const InsulinToCarbsRatioError: () => RecommendationError;
+/** The entered current blood glucose level is outside of the valid range. */
 export declare const CurrentBGLError: () => RecommendationError;
+/** The blood glucose level of the latest logbook entry from the last 6 hours is outside of the valid range. */
 export declare const LatestLogbook6HoursBGLError: () => RecommendationError;
+/** The entered current blood ketones concentration is outside of the valid range. */
 export declare const CurrentBKLError: () => RecommendationError;
+/** The user’s target BGL setting is outside of the valid range. */
 export declare const TargetBGLError: () => RecommendationError;
+/** At least one of the recent (within the previous 4 hours) logbook entries has an insulin amount that exceeds the safety insulin threshold. */
 export declare const BolusInsulinDoseError: () => RecommendationError;
+/** At least one entry from the list of recent logbook entries is older than 4 hours. */
 export declare const BolusInsulinSecondsPassedError: () => RecommendationError;
+/** The user’s recent boluses entries are not in the allowed format. */
 export declare const RecentBolusError: () => RecommendationError;
+/** The user’s setting for initial reminder time is outside of the valid range. */
 export declare const UserReminderError: () => RecommendationError;
+/** The user’s insulin injection method setting is invalid. */
 export declare const InjectionMethodError: () => RecommendationError;
+/**The user’s language setting is not supported by the bolus calculator or it is in the wrong format */
 export declare const LanguageError: () => RecommendationError;
+/** The user’s blood ketones unit setting is invalid. */
 export declare const BloodKetoneUnitError: () => RecommendationError;
+/** The user’s blood glucose level measuring unit setting is invalid. */
 export declare const BloodGlucoseUnitError: () => RecommendationError;
+/** The user has provided a blood ketone level but the blood ketone measuring  unit is not defined. */
 export declare const BloodKetonePropsError: () => RecommendationError;

package/src/utils/RecommendationError.js

@@ -3,31 +3,60 @@ import { t } from "@lingui/macro";
 import { i18n } from "../locale/i18nUtils";
 import { RecommendationErrorEnum } from "../types/enum";
 const SAFETY_INSULIN_LIMIT = BolusCalculator.Constants.SAFETY_INSULIN_LIMIT;
+/**
+ * Defines a set of human readable error messages.
+ * Each of them is defined as a function that returns the required translatable error message.
+ * The app should generally prevent the user from entering invalid values at the time of entry, so in almost all of these cases,
+ * the use of any of these errors indicate that something might have gone really wrong, and the user will be prevented
+ * from getting a recommendation until the problem is solved.
+ */
 export class RecommendationError extends Error {
     constructor(message, type) {
         super(message);
         this.type = type;
     }
 }
+/** The given activity settings are corrupt. */
 export const ActivitySettingsError = () => new RecommendationError(i18n._(t `Error. Please verify that your activity settings are set up correctly.`), RecommendationErrorEnum.ActivitySettings);
+/** The duration of the given activity is invalid. */
 export const ActivityDurationError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator only supports activities with a duration of maximum 60 minutes.`), RecommendationErrorEnum.ActivityDuration);
+/** The start date of the given activity is invalid. */
 export const ActivityDateError = () => new RecommendationError(i18n._(t `Hedia Calculator does not support activities that finished more than 4 hours ago.`), RecommendationErrorEnum.ActivityDate);
+/** The intensity of the given activity is invalid. */
 export const ActivityIntensityError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support your activity intensity value`), RecommendationErrorEnum.ActivityIntensity);
+/** Type of the given activity is invalid. */
 export const ActivityTypeError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support your activity type value`), RecommendationErrorEnum.ActivityType);
+/** The user’s activity target BGL setting is invalid. */
 export const ActivityTargetBGLError = () => new RecommendationError(i18n._(t `Error. Please verify that your activity target blood glucose value is correct.`), RecommendationErrorEnum.ActivityTargetBGL);
+/** More than 300 g carbohydrates entered. */
 export const CarbohydrateLimitError = () => new RecommendationError(i18n._(t `Hedia Calculator does not support insulin recommendations with more than 300 grams of carbohydrates present.`), RecommendationErrorEnum.CarbohydrateLimit);
+/** The user’s insulin sensitivity setting is outside of the valid range. */
 export const InsulinSensitivityError = () => new RecommendationError(i18n._(t `Error. Please verify that your insulin sensitivity value is correct.`), RecommendationErrorEnum.InsulinSensitivity);
+/** The user’s insulin-to-carbs ratio setting is outside of the valid range. */
 export const InsulinToCarbsRatioError = () => new RecommendationError(i18n._(t `Error. Please verify that your insulin to carb ratio value is correct.`), RecommendationErrorEnum.InsulinToCarbsRatio);
+/** The entered current blood glucose level is outside of the valid range. */
 export const CurrentBGLError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support your current blood glucose level.`), RecommendationErrorEnum.CurrentBGL);
+/** The blood glucose level of the latest logbook entry from the last 6 hours is outside of the valid range. */
 export const LatestLogbook6HoursBGLError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support the blood glucose level of your latest logbook entry from the last 6 hours.`), RecommendationErrorEnum.LatestLogbook6HoursBGL);
+/** The entered current blood ketones concentration is outside of the valid range. */
 export const CurrentBKLError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support your current blood ketone level.`), RecommendationErrorEnum.CurrentBKL);
+/** The user’s target BGL setting is outside of the valid range. */
 export const TargetBGLError = () => new RecommendationError(i18n._(t `Error. Please verify that your target blood glucose value is correct.`), RecommendationErrorEnum.TargetBGL);
+/** At least one of the recent (within the previous 4 hours) logbook entries has an insulin amount that exceeds the safety insulin threshold. */
 export const BolusInsulinDoseError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support an insulin dose greater than ${SAFETY_INSULIN_LIMIT} units`), RecommendationErrorEnum.BolusInsulinDose);
+/** At least one entry from the list of recent logbook entries is older than 4 hours. */
 export const BolusInsulinSecondsPassedError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support insulin recommendations with boluses older than 4 hours`), RecommendationErrorEnum.BolusInsulinSecondsPassed);
+/** The user’s recent boluses entries are not in the allowed format. */
 export const RecentBolusError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator could not find your recent boluses`), RecommendationErrorEnum.RecentBolus);
+/** The user’s setting for initial reminder time is outside of the valid range. */
 export const UserReminderError = () => new RecommendationError(i18n._(t `Error. Please verify your notifications settings.`), RecommendationErrorEnum.UserReminder);
+/** The user’s insulin injection method setting is invalid. */
 export const InjectionMethodError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support your injection method.`), RecommendationErrorEnum.InjectionMethod);
+/**The user’s language setting is not supported by the bolus calculator or it is in the wrong format */
 export const LanguageError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support your current language.`), RecommendationErrorEnum.Language);
+/** The user’s blood ketones unit setting is invalid. */
 export const BloodKetoneUnitError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support your current blood ketone unit.`), RecommendationErrorEnum.BloodKetoneUnit);
+/** The user’s blood glucose level measuring unit setting is invalid. */
 export const BloodGlucoseUnitError = () => new RecommendationError(i18n._(t `Error. Hedia Calculator does not support your current blood glucose unit.`), RecommendationErrorEnum.BloodGlucoseUnit);
+/** The user has provided a blood ketone level but the blood ketone measuring  unit is not defined. */
 export const BloodKetonePropsError = () => new RecommendationError(i18n._(t `Error. Your blood ketone settings are invalid.`), RecommendationErrorEnum.BloodKetoneProps);

package/src/utils/RecommendationUtils.d.ts

@@ -1,8 +1,100 @@
+/**
+ * Helper functions for processing and categorising user inputs for determining which warnings and messages to display.
+ * @module
+ */
+import { BolusCalculator, Logbook } from "@hedia/types";
 import { BgLevel } from "../types/enum";
-import { IActivityParams, logbookEntry } from "../types/types";
-export declare function getBGLevel(currentBGL: number | null, latestLogbookFrom6Hours: logbookEntry | null): BgLevel;
-export declare function getReminder(bgLevel: BgLevel, carbohydrates: number, userReminder: number, activity: IActivityParams | null): number;
-export declare function getAttentionMessage(bgLevel: BgLevel, activity: IActivityParams | null): string | null;
-export declare function isSevereHyperglycemia(logbook?: logbookEntry | null): boolean;
-export declare function isActivityWithin15Minutes(activity: IActivityParams | null): boolean;
+/**
+ * Determine the category of the blood glucose level based on the numerical value of the BGL itself and potentially the most recent previously entered BGL.
+ *
+ * Steps:
+ * 1. If currentBGL is null return BgLevel.BGLevelNotProvided.
+ * 2. If currentBGL is in the interval [1.1; 2] return BgLevel.SevereHypoglycemia.
+ * 3. If currentBGL is in the interval ]2; 3.5] return BgLevel.Hypoglycemia.
+ * 4. If currentBGL is in the interval ]3.5; 4] return BgLevel.MildHypoglycemia.
+ * 5. If currentBGL is in the interval ]4; 5[ return BgLevel.NormoglycemiaUnder5MMOL.
+ * 6. If currentBGL is in the interval [5; 7] return BgLevel.Normoglycemia.
+ * 7. If currentBGL is in the interval ]7; 15[ return BgLevel.MildHyperglycemia.
+ * 8. If currentBGL is in the interval ]15; 33.3] and calling isSevereHyperglycemia() with latestLogbookFrom6Hours returns true then return BgLevel.SevereHyperglycemia.
+ * 9. If currentBGL is in the interval [15; 33.3] return BgLevel.Hyperglycemia.
+ * @param currentBGL The blood glucose level entered by the user or null if they didn’t enter it.
+ * @param latestLogbookFrom6Hours The latest saved logbook entry if one was logged within the last 6 hours. Otherwise null.
+ * @returns Indication of the category that the blood glucose level belongs to {@link BgLevel}.
+ */
+export declare function getBGLevel(currentBGL: number | null, latestLogbookFrom6Hours: Logbook.Types.ILogbookEntry | null): BgLevel;
+/**
+ * Calculate the initial value for the calibration reminder time slider.
+ *
+ * Steps:
+ * 1. Set reminder to be the user’s preferred reminder time if it is defined or to the default reminder time of 1.5 (hours) otherwise.
+ * 2. Use a switch statement on {@link BgLevel} to determine the appropriate reminder value to return:
+ * 	- If it is SevereHypoglycemia, Hypoglycemia, or MildHypoglycemia then return Reminder15Minutes.
+ * 	- If it is NormoglycemiaUnder5MMOL, Normoglycemia, MildHyperglycemia, or BGLevelNotProvided then return the value of reminder
+ *    if the user entered carbohydrates or an activity, or ReminderOff otherwise.
+ * 	- If it is Hyperglycemia, or SevereHyperglycemia then return Reminder15Minutes if isActivityWithin15Minutes() given the activity
+ *    is true and return Reminder60Minutes otherwise.
+ * 	- If none of the above conditions were triggered, throw a CurrentBGLError().
+ * @param bgLevel The severity category that the user’s current BGL belongs to.
+ * @param carbohydrates The amount of carbohydrates that the user is ingesting.
+ * @param userReminder The user’s preferred initial reminder time interval in hours.
+ * @param activity The activity that the user entered.
+ * @returns The initial value of the remeasurement reminder timer slider in hours {@link RecommendationReminders}.
+ */
+export declare function getReminder(bgLevel: BgLevel, carbohydrates: number, userReminder: number, activity: BolusCalculator.Types.IActivityParams | null): number;
+/**
+ * Get the attention message that fits with the user’s entered blood glucose level and activity.
+ *
+ * Steps:
+ * 1. Use at switch statement on bgLevel to determine the appropriate action to take:
+ * 	- If it is BGLevelNotProvided, Normoglycemia, or MildHyperglycemia then return null.
+ * 	- If it is NormoglycemiaUnder5MMOL then do the following:
+ * 		- If an activity is going to start within 15 minuts as determined by isActivityWithin15Minutes() then return AttentionMessage.NormoglycemiaActivityUnder5MMOL().
+ *        Otherwise return null.
+ * 	- If it is SevereHypoglycemia, Hypoglycemia, or MildHypoglycemia then do the following:
+ * 		- If an activity is going to start within 15 minuts as determined by isActivityWithin15Minutes() then
+ *        return the AttentionMessage that corresponds to the bgLevel and append a message about postponing the activity using addPostponeActivityMessage().
+ *        Otherwise return the AttentionMessage that corresponds to the {@link BgLevel} without further modification.
+ * 	- If it is Hyperglycemia then do the following:
+ * 		- If an activity is going to start within 15 minuts as determined by isActivityWithin15Minutes() then return AttentionMessage.HyperglycemiaActivity().
+ *        Otherwise return null.
+ * 	- If it is SevereHyperglycemia then do the following:
+ * 		- If an activity is going to start within 15 minuts as determined by isActivityWithin15Minutes() then return AttentionMessage.SevereHyperglycemiaActivity().
+ *        Otherwise return AttentionMessage.SevereHyperglycemia().
+ * 	- If none of the above conditions were triggered, throw a CurrentBGLError() {@link RecommendationError}.
+ * @param bgLevel  The category of the user’s blood glucose level.
+ * @param activity The activity that the user entered
+ * @returns The appropriate attention message {@link AttentionMessage} to display to the user or null if there is no message to be displayed.
+ */
+export declare function getAttentionMessage(bgLevel: BgLevel, activity: BolusCalculator.Types.IActivityParams | null): string | null;
+/**
+ * Determine based on on the previously measured BGL if the hyperglycemia should be categorized as severe.
+ *
+ * Steps:
+ * 1. If the logbook is not null or undefined, return the result of comparing if the blood_glucose_millimolar property of latestLogbookFrom6Hours
+ *    is strictly larger than the threshold for severe hyperglycemia (15) {@link Constants}.
+ * @param logbook The latest previous logbook entry - if any - from the past 6 hours.
+ * @returns True if the BGL from the previous logbook entry is above the threshold for severe hyperglycemia. False otherwise.
+ */
+export declare function isSevereHyperglycemia(logbook?: Logbook.Types.ILogbookEntry | null): boolean;
+/**
+ * Determine whether an activity is either ongoing or is starting within 15 minutes from now.
+ *
+ * Steps:
+ * 1. Extract the duration from the activity.
+ * 2. Check if the start date of the activity was between duration minutes in the past or 15 minutes in the future and return the result.
+ * @param activity The activity whose start time should be checked.
+ * @returns Indication of whether the activity is ongoing or imminent.
+ */
+export declare function isActivityWithin15Minutes(activity: BolusCalculator.Types.IActivityParams | null): boolean;
+/**
+ * The appropriate message for informing the user if the insulin recommendation was limited.
+ *
+ * Steps:
+ * 1. Set message to the return value of RecommendationWasLimitedActivity() if activityReduction is truthy or to the return value of RecommendationWasLimited() otherwise.
+ * 2. Return message if wasLimited is true or undefined otherwise.
+ * @param wasLimited Indicator of whether or not the user’s insulin recommendation was limited.
+ * @param activityReduction The fraction by which the insulin recommendation and the safety insulin limit has been reduced due to physical activity.
+ * @returns Callable that returns the appropriate message {@link Messages} for informing the user about the limitation.
+ * If no limitation message should be displayed to the user then null is returned.
+ */
 export declare function getLimitationMessage(wasLimited: boolean, activityReduction: number | null): string | null;

package/src/utils/RecommendationUtils.js

@@ -1,9 +1,30 @@
+/**
+ * Helper functions for processing and categorising user inputs for determining which warnings and messages to display.
+ * @module
+ */
 import moment from "moment";
 import { BgLevel, RecommendationReminders } from "../types/enum";
 import { addPostponeActivityMessageUnder5MMOL, AttentionMessage, Messages } from "./AttentionMessages";
 import { SEVERE_HYPERGLYCEMIA_START_MMOL } from "./Constants";
 import { CurrentBGLError } from "./RecommendationError";
 import { Utils } from "./Utils";
+/**
+ * Determine the category of the blood glucose level based on the numerical value of the BGL itself and potentially the most recent previously entered BGL.
+ *
+ * Steps:
+ * 1. If currentBGL is null return BgLevel.BGLevelNotProvided.
+ * 2. If currentBGL is in the interval [1.1; 2] return BgLevel.SevereHypoglycemia.
+ * 3. If currentBGL is in the interval ]2; 3.5] return BgLevel.Hypoglycemia.
+ * 4. If currentBGL is in the interval ]3.5; 4] return BgLevel.MildHypoglycemia.
+ * 5. If currentBGL is in the interval ]4; 5[ return BgLevel.NormoglycemiaUnder5MMOL.
+ * 6. If currentBGL is in the interval [5; 7] return BgLevel.Normoglycemia.
+ * 7. If currentBGL is in the interval ]7; 15[ return BgLevel.MildHyperglycemia.
+ * 8. If currentBGL is in the interval ]15; 33.3] and calling isSevereHyperglycemia() with latestLogbookFrom6Hours returns true then return BgLevel.SevereHyperglycemia.
+ * 9. If currentBGL is in the interval [15; 33.3] return BgLevel.Hyperglycemia.
+ * @param currentBGL The blood glucose level entered by the user or null if they didn’t enter it.
+ * @param latestLogbookFrom6Hours The latest saved logbook entry if one was logged within the last 6 hours. Otherwise null.
+ * @returns Indication of the category that the blood glucose level belongs to {@link BgLevel}.
+ */
 export function getBGLevel(currentBGL, latestLogbookFrom6Hours) {
     if (currentBGL === null) {
         return BgLevel.BGLevelNotProvided;
@@ -36,6 +57,24 @@ export function getBGLevel(currentBGL, latestLogbookFrom6Hours) {
     }
     return BgLevel.UnsupportedBGLevel;
 }
+/**
+ * Calculate the initial value for the calibration reminder time slider.
+ *
+ * Steps:
+ * 1. Set reminder to be the user’s preferred reminder time if it is defined or to the default reminder time of 1.5 (hours) otherwise.
+ * 2. Use a switch statement on {@link BgLevel} to determine the appropriate reminder value to return:
+ * 	- If it is SevereHypoglycemia, Hypoglycemia, or MildHypoglycemia then return Reminder15Minutes.
+ * 	- If it is NormoglycemiaUnder5MMOL, Normoglycemia, MildHyperglycemia, or BGLevelNotProvided then return the value of reminder
+ *    if the user entered carbohydrates or an activity, or ReminderOff otherwise.
+ * 	- If it is Hyperglycemia, or SevereHyperglycemia then return Reminder15Minutes if isActivityWithin15Minutes() given the activity
+ *    is true and return Reminder60Minutes otherwise.
+ * 	- If none of the above conditions were triggered, throw a CurrentBGLError().
+ * @param bgLevel The severity category that the user’s current BGL belongs to.
+ * @param carbohydrates The amount of carbohydrates that the user is ingesting.
+ * @param userReminder The user’s preferred initial reminder time interval in hours.
+ * @param activity The activity that the user entered.
+ * @returns The initial value of the remeasurement reminder timer slider in hours {@link RecommendationReminders}.
+ */
 export function getReminder(bgLevel, carbohydrates, userReminder, activity) {
     const reminder = userReminder === undefined ? RecommendationReminders.HediaReminderDefault : userReminder;
     switch (bgLevel) {
@@ -57,6 +96,30 @@ export function getReminder(bgLevel, carbohydrates, userReminder, activity) {
             throw CurrentBGLError();
     }
 }
+/**
+ * Get the attention message that fits with the user’s entered blood glucose level and activity.
+ *
+ * Steps:
+ * 1. Use at switch statement on bgLevel to determine the appropriate action to take:
+ * 	- If it is BGLevelNotProvided, Normoglycemia, or MildHyperglycemia then return null.
+ * 	- If it is NormoglycemiaUnder5MMOL then do the following:
+ * 		- If an activity is going to start within 15 minuts as determined by isActivityWithin15Minutes() then return AttentionMessage.NormoglycemiaActivityUnder5MMOL().
+ *        Otherwise return null.
+ * 	- If it is SevereHypoglycemia, Hypoglycemia, or MildHypoglycemia then do the following:
+ * 		- If an activity is going to start within 15 minuts as determined by isActivityWithin15Minutes() then
+ *        return the AttentionMessage that corresponds to the bgLevel and append a message about postponing the activity using addPostponeActivityMessage().
+ *        Otherwise return the AttentionMessage that corresponds to the {@link BgLevel} without further modification.
+ * 	- If it is Hyperglycemia then do the following:
+ * 		- If an activity is going to start within 15 minuts as determined by isActivityWithin15Minutes() then return AttentionMessage.HyperglycemiaActivity().
+ *        Otherwise return null.
+ * 	- If it is SevereHyperglycemia then do the following:
+ * 		- If an activity is going to start within 15 minuts as determined by isActivityWithin15Minutes() then return AttentionMessage.SevereHyperglycemiaActivity().
+ *        Otherwise return AttentionMessage.SevereHyperglycemia().
+ * 	- If none of the above conditions were triggered, throw a CurrentBGLError() {@link RecommendationError}.
+ * @param bgLevel  The category of the user’s blood glucose level.
+ * @param activity The activity that the user entered
+ * @returns The appropriate attention message {@link AttentionMessage} to display to the user or null if there is no message to be displayed.
+ */
 export function getAttentionMessage(bgLevel, activity) {
     const key = Utils.getKeyFromValue(BgLevel, bgLevel);
     const isAttentionMessageNull = AttentionMessage[key] === null;
@@ -84,6 +147,15 @@ export function getAttentionMessage(bgLevel, activity) {
             throw CurrentBGLError();
     }
 }
+/**
+ * Determine based on on the previously measured BGL if the hyperglycemia should be categorized as severe.
+ *
+ * Steps:
+ * 1. If the logbook is not null or undefined, return the result of comparing if the blood_glucose_millimolar property of latestLogbookFrom6Hours
+ *    is strictly larger than the threshold for severe hyperglycemia (15) {@link Constants}.
+ * @param logbook The latest previous logbook entry - if any - from the past 6 hours.
+ * @returns True if the BGL from the previous logbook entry is above the threshold for severe hyperglycemia. False otherwise.
+ */
 export function isSevereHyperglycemia(logbook) {
     if (logbook !== null && logbook !== undefined) {
         const { blood_glucose_millimolar } = logbook;
@@ -93,12 +165,32 @@ export function isSevereHyperglycemia(logbook) {
     }
     return false;
 }
+/**
+ * Determine whether an activity is either ongoing or is starting within 15 minutes from now.
+ *
+ * Steps:
+ * 1. Extract the duration from the activity.
+ * 2. Check if the start date of the activity was between duration minutes in the past or 15 minutes in the future and return the result.
+ * @param activity The activity whose start time should be checked.
+ * @returns Indication of whether the activity is ongoing or imminent.
+ */
 export function isActivityWithin15Minutes(activity) {
     const minutes = activity?.activityDuration;
     return moment
         .utc(activity?.activityDate)
         .isBetween(moment.utc().subtract(minutes, `minutes`), moment.utc().add(15, `minutes`));
 }
+/**
+ * The appropriate message for informing the user if the insulin recommendation was limited.
+ *
+ * Steps:
+ * 1. Set message to the return value of RecommendationWasLimitedActivity() if activityReduction is truthy or to the return value of RecommendationWasLimited() otherwise.
+ * 2. Return message if wasLimited is true or undefined otherwise.
+ * @param wasLimited Indicator of whether or not the user’s insulin recommendation was limited.
+ * @param activityReduction The fraction by which the insulin recommendation and the safety insulin limit has been reduced due to physical activity.
+ * @returns Callable that returns the appropriate message {@link Messages} for informing the user about the limitation.
+ * If no limitation message should be displayed to the user then null is returned.
+ */
 export function getLimitationMessage(wasLimited, activityReduction) {
     const message = activityReduction
         ? Messages.RecommendationWasLimitedActivity(activityReduction)

package/src/utils/Translations.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Used for storing Record type objects that contains translations about certain settings that needs to be presented to the user.
+ * @module
+ */
 import { Activity } from "@hedia/types";
+/**
+ * Object used for storing the translations of a physical activity intensity in order to be presented to the user
+ */
 export declare const ActivityIntensityTranslations: Record<Activity.Enums.ActivityIntensity, () => string>;

package/src/utils/Translations.js

@@ -1,5 +1,12 @@
+/**
+ * Used for storing Record type objects that contains translations about certain settings that needs to be presented to the user.
+ * @module
+ */
 import { t } from "@lingui/macro";
 import { i18n } from "../locale/i18nUtils";
+/**
+ * Object used for storing the translations of a physical activity intensity in order to be presented to the user
+ */
 export const ActivityIntensityTranslations = {
     light: () => i18n._(t `Light`),
     moderate: () => i18n._(t `Moderate`),

package/src/utils/Utils.d.ts

@@ -1,13 +1,105 @@
 import { BloodGlucoseUnit, BloodKetonesUnit, UserSettings } from "@hedia/types";
 import { IInterval } from "../types/types";
+/** Helper functions used for displaying data to the user. */
 export declare 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: UserSettings.Enums.InjectionMethod): number;
+    /**
+     * 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: number, injectMethod: UserSettings.Enums.InjectionMethod): number;
+    /**
+     * 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: number | null, interval: IInterval): boolean;
+    /**
+     * 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: number): number;
+    /**
+     * 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: number, unit: BloodGlucoseUnit): string;
+    /**
+     * 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: number): number;
+    /**
+     * 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: number, unit: BloodKetonesUnit): string;
+    /**
+     * 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.
+     */
     static formatUnit: (unit: BloodGlucoseUnit | BloodKetonesUnit) => string;
+    /**
+     * 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<T>(keys: T, value: T[keyof T]): keyof T;
 }