diabetic-utils
Version:
Zero-bloat TypeScript utilities for diabetes data: glucose, A1C, conversions, time-in-range, and more.
640 lines (628 loc) • 28.6 kB
TypeScript
/**
* Formats a clinical A1C value as a percent string (e.g., "7.2%").
* Used for clinical reporting and display.
* @param val - A1C value (percentage)
* @returns A1C as string with percent sign
*/
declare function formatA1C(val: number): string;
/**
* Validates a clinical A1C value (percentage).
* Ensures value is within physiologically plausible range for clinical analytics.
* @param value - Candidate A1C value
* @returns True if value is a valid A1C percentage
*/
declare function isValidA1C(value: unknown): boolean;
/**
* Returns the clinical category for an A1C value (normal, prediabetes, diabetes, or invalid).
* Uses ADA thresholds by default, but allows custom cutoffs for research or population-specific use.
* @param a1c - A1C value (percentage)
* @returns 'normal' | 'prediabetes' | 'diabetes' | 'invalid'
*/
/**
* Returns the clinical category for an A1C value (normal, prediabetes, diabetes, or invalid).
* Uses ADA thresholds by default, but allows custom cutoffs for research or population-specific use.
* @param a1c - A1C value (percentage)
* @param thresholds - Optional custom thresholds: { normalMax?: number; prediabetesMax?: number }
* @returns 'normal' | 'prediabetes' | 'diabetes' | 'invalid'
*/
declare function getA1CCategory(a1c: number, thresholds?: {
normalMax?: number;
prediabetesMax?: number;
}): 'normal' | 'prediabetes' | 'diabetes' | 'invalid';
/**
* Checks if an A1C value is within a target range.
* @param a1c - A1C value
* @param target - [min, max] range (default: [6.5, 7.0])
* @param thresholds - Optional custom thresholds: { min?: number; max?: number }
* @returns True if in target range
*/
declare function isA1CInTarget(a1c: number, target?: [number, number], thresholds?: {
min?: number;
max?: number;
}): boolean;
/**
* Calculates the change (delta) between two A1C values.
* @param current - Current A1C
* @param previous - Previous A1C
* @returns Delta (current - previous)
* @throws If either value is invalid
*/
declare function a1cDelta(current: number, previous: number): number;
/**
* Determines the trend of A1C values over time.
* @param readings - Array of A1C values (chronological order)
* @returns 'increasing' | 'decreasing' | 'stable' | 'insufficient data'
*/
declare function a1cTrend(readings: number[]): 'increasing' | 'decreasing' | 'stable' | 'insufficient data';
/**
* Calculates HOMA-IR (Homeostatic Model Assessment for Insulin Resistance) from fasting glucose and insulin.
*
* Formula: HOMA-IR = (fasting glucose [mg/dL] × fasting insulin [µIU/mL]) / 405
*
* Used for estimating insulin resistance in clinical analytics and research. Not a diagnostic tool—interpret with clinical context.
*
* @param glucose - Fasting glucose value in mg/dL. Must be a positive finite number.
* @param insulin - Fasting insulin value in µIU/mL. Must be a positive finite number.
* @returns Object with numeric HOMA-IR value and clinical interpretation label.
* @throws {Error} If glucose or insulin are invalid (non-finite, zero, or negative).
* @see https://pubmed.ncbi.nlm.nih.gov/3899825/ (Original HOMA-IR publication)
* @see https://diabetesjournals.org/care/article/26/1/118/22567/Prevalence-and-Concomitants-of-Glucose-Intolerance (ADA: Glucose Intolerance and HOMA-IR context)
*/
declare function calculateHOMAIR(glucose: number, insulin: number): {
value: number;
interpretation: string;
};
/**
* Checks clinical consistency among A1C, fasting glucose, and fasting insulin markers.
*
* Returns:
* - Estimated average glucose (mg/dL), calculated per CDC formula
* - HOMA-IR result (value and interpretation)
* - Flags for potential inconsistencies
* - Educational recommendation and disclaimer
*
* Used for high-level clinical insight and trend alignment, not for diagnosis.
*
* @param a1c - A1C value (percentage). Must be a positive finite number.
* @param glucose - Fasting glucose value in mg/dL. Must be a positive finite number.
* @param insulin - Fasting insulin value in µIU/mL. Must be a positive finite number.
* @returns Object with estimated average glucose (mg/dL), HOMA-IR result object, flags array, recommendation string, and disclaimer.
* @throws {Error} If any input value is invalid (non-finite, zero, or negative).
* @see https://www.cdc.gov/diabetes/diabetes-testing/prediabetes-a1c-test.html (CDC: eAG formula)
*/
declare function checkGlycemicAlignment(a1c: number, glucose: number, insulin: number): {
estimatedAverageGlucose: number;
homaIR: {
value: number;
interpretation: string;
};
flags: string[];
recommendation: string;
disclaimer: string;
};
/**
* Denominator constant for HOMA-IR calculation.
* HOMA-IR = (glucose [mg/dL] × insulin [µIU/mL]) / HOMA_IR_DENOMINATOR
* @see https://www.ncbi.nlm.nih.gov/books/NBK279396/
*/
declare const HOMA_IR_DENOMINATOR = 405;
/**
* Interpretation cutoffs for HOMA-IR (insulin resistance assessment).
* These are general clinical categories, not diagnostic.
*/
declare const HOMA_IR_CUTOFFS: {
VERY_SENSITIVE: number;
NORMAL: number;
EARLY_RESISTANCE: number;
};
/**
* Clinical hypoglycemia threshold (mg/dL).
* Used for detecting low glucose events in analytics and reporting.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-level-ranges.html
*/
declare const HYPO_THRESHOLD_MGDL = 70;
/**
* Clinical hyperglycemia threshold (mg/dL).
* Used for detecting high glucose events in clinical analytics.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-level-ranges.html
*/
declare const HYPER_THRESHOLD_MGDL = 180;
/**
* Clinical hypoglycemia threshold (mmol/L).
* Used for low glucose detection in international/metric contexts.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-level-ranges.html
*/
declare const HYPO_THRESHOLD_MMOLL = 3.9;
/**
* Clinical hyperglycemia threshold (mmol/L).
* Used for high glucose detection in international/metric contexts.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-level-ranges.html
*/
declare const HYPER_THRESHOLD_MMOLL = 10;
/**
* Clinical multiplier for converting A1C to estimated average glucose (eAG).
* Used in eAG calculation per CDC/ADA guidelines.
* @see https://www.cdc.gov/diabetes/managing/managing-blood-sugar/a1c.html
*/
declare const A1C_TO_EAG_MULTIPLIER = 28.7;
/**
* Clinical constant for converting A1C to estimated average glucose (eAG).
* Used in eAG calculation per CDC/ADA guidelines.
* @see https://www.cdc.gov/diabetes/managing/managing-blood-sugar/a1c.html
*/
declare const A1C_TO_EAG_CONSTANT = 46.7;
/**
* Clinical conversion factor between mg/dL and mmol/L.
* Used for unit conversion in all clinical analytics.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
declare const MGDL_MMOLL_CONVERSION = 18.0182;
/**
* Clinical string literal for mg/dL glucose unit.
* Used for clinical data interoperability and formatting.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
declare const MG_DL: "mg/dL";
/**
* String literal for mmol/L unit.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
declare const MMOL_L: "mmol/L";
/**
* Color codes for glucose zones.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-level-ranges.html
*/
declare const GLUCOSE_COLOR_LOW = "#D32F2F";
declare const GLUCOSE_COLOR_NORMAL = "#388E3C";
declare const GLUCOSE_COLOR_NORMAL_UP = "#4CAF50";
declare const GLUCOSE_COLOR_NORMAL_DOWN = "#2E7D32";
declare const GLUCOSE_COLOR_ELEVATED = "#FBC02D";
declare const GLUCOSE_COLOR_HIGH = "#F57C00";
/**
* Glucose zone color mapping for different statuses and trends.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-level-ranges.html
*/
declare const GLUCOSE_ZONE_COLORS: {
LOW: string;
NORMAL: string;
ELEVATED: string;
HIGH: string;
NORMAL_UP: string;
NORMAL_DOWN: string;
};
/**
* Unicode arrows for glucose trend indication.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-level-ranges.html
*/
declare const TREND_ARROWS: {
STEADY: string;
RISING: string;
FALLING: string;
RAPIDRISE: string;
RAPIDFALL: string;
};
/**
* Supported clinical glucose units.
* Used for all clinical analytics and conversions.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
type GlucoseUnit = typeof MG_DL | typeof MMOL_L;
/**
* List of allowed clinical glucose units.
* Used for input validation and unit conversion.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
declare const AllowedGlucoseUnits: GlucoseUnit[];
/**
* Single clinical glucose reading.
* Includes value, unit, and ISO 8601 timestamp for clinical analytics.
* @see https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7445493/
*/
interface GlucoseReading {
readonly value: number;
readonly unit: GlucoseUnit;
readonly timestamp: string;
}
/**
* Result object for clinical Time-in-Range (TIR) analytics.
* Percentages for in-range, below-range, and above-range readings.
* @see https://care.diabetesjournals.org/content/42/8/1593
*/
interface TIRResult {
inRange: number;
belowRange: number;
aboveRange: number;
}
/**
* Options for clinical GMI (Glucose Management Indicator) estimation.
* Used to standardize GMI calculation input.
* @see https://diatribe.org/glucose-management-indicator-gmi
*/
interface EstimateGMIOptions {
value: number;
unit: GlucoseUnit;
}
/**
* Options for clinical Time-in-Range (TIR) analytics.
*/
interface TIROptions {
readings: GlucoseReading[];
unit: GlucoseUnit;
range: [number, number];
}
/**
* Single clinical A1C reading (value and ISO date).
*/
interface A1CReading {
value: number;
date: string;
}
/**
* Options for clinical glucose statistics analytics.
* Controls which metrics are calculated and reported.
*/
interface GlucoseStatsOptions {
readings: GlucoseReading[];
unit: GlucoseUnit;
range: [number, number];
gmi?: boolean;
a1c?: boolean;
tir?: boolean;
tirRange?: [number, number];
tirPercent?: boolean;
tirPercentBelow?: boolean;
tirPercentAbove?: boolean;
tirPercentInRange?: boolean;
tirPercentBelowRounded?: boolean;
tirPercentAboveRounded?: boolean;
tirPercentInRangeRounded?: boolean;
}
/**
* Converts clinical average glucose (mg/dL) to estimated A1C (percentage).
* Used for clinical analytics and patient reporting.
* @param avgMgDl - Average glucose in mg/dL
* @returns Estimated A1C value (percentage)
* @see https://www.cdc.gov/diabetes/managing/managing-blood-sugar/a1c.html
*/
declare function estimateA1CFromAvgGlucose(avgMgDl: number): number;
/**
* Converts clinical A1C value (percentage) to estimated average glucose (mg/dL).
* Used for clinical analytics and patient reporting.
* @param a1c - A1C value (percentage)
* @returns Estimated average glucose in mg/dL
* @see https://www.cdc.gov/diabetes/managing/managing-blood-sugar/a1c.html
*/
declare function estimateAvgGlucoseFromA1C(a1c: number): number;
/**
* Estimates eAG (estimated average glucose, mg/dL) from clinical A1C value.
* Throws if input is negative. Used for clinical and research reporting.
* @param a1c - A1C value (percentage)
* @returns Estimated average glucose (mg/dL)
* @throws {Error} If a1c is negative
* @see https://www.cdc.gov/diabetes/managing/managing-blood-sugar/a1c.html
*/
declare function estimateEAG(a1c: number): number;
/**
* Estimates A1C from average glucose.
* @param avgGlucose - Average glucose value
* @param unit - Glucose unit (mg/dL or mmol/L)
* @returns Estimated A1C
* @see https://www.cdc.gov/diabetes/managing/managing-blood-sugar/a1c.html
*/
declare function estimateA1CFromAverage(avgGlucose: number, unit?: GlucoseUnit): number;
/**
* Converts A1C to Glucose Management Indicator (GMI).
* @param a1c - A1C value
* @returns GMI value
* @see https://diatribe.org/glucose-management-indicator-gmi
*/
declare function a1cToGMI(a1c: number): number;
/**
* Estimate Glucose Management Indicator (GMI) from average glucose.
* @param valueOrOptions - Glucose value, string, or options object
* @param unit - Glucose unit (if value is a number)
* @returns GMI value
* @throws {Error} If unit is required but not provided when input is a number.
* @throws {Error} If the glucose unit is unsupported.
* @throws {Error} If the glucose value is not a positive number.
* @see https://diatribe.org/glucose-management-indicator-gmi
*/
declare function estimateGMI(valueOrOptions: number | string | EstimateGMIOptions, unit?: GlucoseUnit): number;
/**
* Converts clinical glucose value from mg/dL to mmol/L.
* Used for international interoperability and reporting.
* @param val - Glucose value in mg/dL
* @returns Value in mmol/L
* @throws {Error} If val is not a finite number or is negative/zero
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
declare function mgDlToMmolL(val: number): number;
/**
* Converts clinical glucose value from mmol/L to mg/dL.
* Used for international interoperability and reporting.
* @param val - Glucose value in mmol/L
* @returns Value in mg/dL
* @throws {Error} If val is not a finite number or is negative/zero
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
declare function mmolLToMgDl(val: number): number;
/**
* Converts clinical glucose value between mg/dL and mmol/L.
* Used for clinical interoperability and analytics.
* @param value - Glucose value (number)
* @param unit - Current glucose unit ('mg/dL' or 'mmol/L')
* @returns Object with converted value and new unit
* @throws {Error} If value is not a finite number or is negative/zero
* @throws {Error} If unit is not a supported glucose unit
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
declare function convertGlucoseUnit({ value, unit, }: {
value: number;
unit: GlucoseUnit;
}): {
value: number;
unit: GlucoseUnit;
};
/**
* Formats a clinical glucose value with unit and optional rounding.
* Used for clinical reporting, charting, and data export.
* @param val - Glucose value (number)
* @param unit - Glucose unit ('mg/dL' or 'mmol/L')
* @param options - Formatting options: { digits?: number; suffix?: boolean } (default: { digits: 0, suffix: true })
* @returns Formatted glucose string (e.g., '5.5 mmol/L', '120 mg/dL')
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
declare function formatGlucose(val: number, unit: GlucoseUnit, options?: {
digits?: number;
suffix?: boolean;
}): string;
/**
* Formats a value as a clinical percentage string (e.g., '85.0%').
* Used for reporting TIR, CV, and other clinical metrics.
* @param val - Value to format (fraction or percent)
* @param digits - Number of decimal places (default: 1)
* @returns Formatted percentage string (e.g., '85.0%')
*/
declare function formatPercentage(val: number, digits?: number): string;
/**
* Formats a UTC ISO 8601 timestamp to a local-readable date/time string.
* Used for clinical charting, logs, and reports. Supports optional IANA time zone.
* @param iso - ISO 8601 timestamp string (e.g., '2024-03-20T10:00:00Z')
* @param timeZone - Optional IANA time zone (e.g., 'America/New_York')
* @returns Localized date/time string (e.g., 'Mar 20, 2024, 06:00 AM')
* @throws {RangeError} If the ISO string is invalid or cannot be parsed
*/
declare function formatDate(iso: string, timeZone?: string): string;
/**
* Checks if a glucose value is clinically hypoglycemic for the given unit.
* Used for detecting low glucose events in clinical analytics and reporting.
* @param val - Glucose value (number)
* @param unit - Glucose unit ('mg/dL' or 'mmol/L'), default: 'mg/dL'
* @param thresholds - Optional custom thresholds ({ mgdl?: number; mmoll?: number })
* @returns True if value is below clinical hypoglycemia threshold
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-level-ranges.html
*/
declare function isHypo(val: number, unit?: GlucoseUnit, thresholds?: {
mgdl?: number;
mmoll?: number;
}): boolean;
/**
* Checks if a glucose value is clinically hyperglycemic for the given unit.
* Used for detecting high glucose events in clinical analytics and reporting.
* @param val - Glucose value (number)
* @param unit - Glucose unit ('mg/dL' or 'mmol/L'), default: 'mg/dL'
* @param thresholds - Optional custom thresholds ({ mgdl?: number; mmoll?: number })
* @returns True if value is above clinical hyperglycemia threshold
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-level-ranges.html
*/
declare function isHyper(val: number, unit?: GlucoseUnit, thresholds?: {
mgdl?: number;
mmoll?: number;
}): boolean;
/**
* Returns a clinical glucose status label ('low', 'normal', or 'high') based on thresholds for the given unit.
* Used for clinical charting, alerts, and reporting.
* @param val - Glucose value (number)
* @param unit - Glucose unit ('mg/dL' or 'mmol/L'), default: 'mg/dL'
* @param thresholds - Optional custom thresholds for hypo/hyper ({ hypo?: { mgdl?: number; mmoll?: number }, hyper?: { mgdl?: number; mmoll?: number } })
* @returns 'low', 'normal', or 'high' based on clinical thresholds
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-level-ranges.html
*/
declare function getGlucoseLabel(val: number, unit?: GlucoseUnit, thresholds?: {
hypo?: {
mgdl?: number;
mmoll?: number;
};
hyper?: {
mgdl?: number;
mmoll?: number;
};
}): 'low' | 'normal' | 'high';
/**
* Parses a clinical glucose string (e.g., "100 mg/dL", "5.5 mmol/L") into value and unit.
* Used for robust input validation and clinical data ingestion.
* @param input - String in the format "value unit" (e.g., "100 mg/dL")
* @returns Object with numeric value and validated unit
* @throws {Error} If input string is invalid or not in expected format
* @example
* parseGlucoseString("100 mg/dL") // { value: 100, unit: "mg/dL" }
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
declare function parseGlucoseString(input: string): {
value: number;
unit: GlucoseUnit;
};
/**
* Validates a clinical glucose value and unit.
* Ensures value is a positive finite number and unit is supported for analytics.
* @param value - Glucose value to validate
* @param unit - Glucose unit to validate
* @returns True if value and unit are clinically valid
*/
declare function isValidGlucoseValue(value: unknown, unit: unknown): boolean;
/**
* Clinical type guard for EstimateGMIOptions.
* Validates that the input matches the required shape for GMI estimation options (numeric value, string unit).
* Useful for ensuring safe handling of clinical glucose data and interoperability with analytics functions.
* @param input - Candidate value to validate.
* @returns True if input is a valid EstimateGMIOptions object.
*/
declare function isEstimateGMIOptions(input: unknown): input is EstimateGMIOptions;
/**
* Validates a clinical glucose string (e.g., "100 mg/dL", "5.5 mmol/L").
* Ensures the string is in a recognized clinical format for glucose values, supporting safe parsing and conversion.
* @param input - Value to check as a clinical glucose string.
* @returns True if input is a valid glucose string for clinical use.
* @see https://www.diabetes.co.uk/diabetes_care/blood-sugar-conversion.html
*/
declare function isValidGlucoseString(input: unknown): input is string;
/**
* Calculates clinical Time in Range (TIR) metrics for glucose readings.
* Returns the percentage of readings in, below, and above the specified clinical target range.
* @param readings - Array of glucose readings to analyze
* @param target - Object specifying the target range ({ min, max })
* @returns Object with in-range, below-range, and above-range percentages
* @see https://care.diabetesjournals.org/content/42/8/1593
*/
declare function calculateTIR(readings: GlucoseReading[], target: {
min: number;
max: number;
}): TIRResult;
/**
* Generates a clinical summary string from a TIRResult object.
* Used for reporting and visualization of TIR analytics.
* @param result - TIR result breakdown to summarize
* @returns String summarizing in-range, below-range, and above-range percentages (e.g., 'In Range: 70%, Below: 10%, Above: 20%')
*/
declare function getTIRSummary(result: TIRResult): string;
/**
* Groups glucose readings by date (YYYY-MM-DD).
* @param readings - Array of glucose readings to group.
* @returns An object mapping each date string to an array of readings for that day.
*/
declare function groupByDay(readings: GlucoseReading[]): Record<string, GlucoseReading[]>;
/**
* Calculates the percentage of glucose readings within a specified numeric range.
* Used for clinical TIR analytics and custom range assessments.
* @param readings - Array of glucose values (numbers) to analyze
* @param lower - Lower bound of the target range (inclusive)
* @param upper - Upper bound of the target range (inclusive)
* @returns Percentage of readings within the specified range (0-100)
*/
declare function calculateTimeInRange(readings: number[], lower: number, upper: number): number;
/**
* Calculates clinical-grade Mean Amplitude of Glycemic Excursions (MAGE).
* Implements gold-standard Service FJ et al. (1970) methodology with modern optimizations and clinical validation.
* @param readings - Array of glucose values (mg/dL or mmol/L)
* @param options - Configuration options for MAGE calculation
* @returns MAGE value, or NaN if insufficient data or no valid excursions
* @see https://pubmed.ncbi.nlm.nih.gov/5469118/ (Service FJ, et al. 1970)
* @see https://journals.sagepub.com/doi/10.1177/19322968211061165 (Fernandes NJ, et al. 2022)
* @see https://care.diabetesjournals.org/content/42/8/1593 (ADA 2019)
* @example
* // Basic usage
* glucoseMAGE([100, 120, 80, 160, 90, 140, 70, 180])
* // Advanced usage
* glucoseMAGE(readings, { shortWindow: 5, longWindow: 32, direction: 'auto' })
* @remarks
* - Minimum 24 data points recommended (1 day of hourly readings)
* - Best suited for continuous glucose monitoring (CGM) data
* - Not recommended for sparse or irregular measurements
* - Uses dual moving averages, three-point excursion definition, and prevents double-counting for clinical accuracy.
*/
declare function glucoseMAGE$1(readings: number[], options?: MAGEOptions): number;
/**
* Configuration options for clinical-grade MAGE calculation.
* @property shortWindow - Short moving average window (default: 5)
* @property longWindow - Long moving average window (default: 32)
* @property direction - Excursion direction: 'auto', 'ascending', or 'descending'
*/
interface MAGEOptions {
/** Short moving average window size (default: 5, validated optimal range: 1-7) */
shortWindow?: number;
/** Long moving average window size (default: 32, validated optimal range: 16-38) */
longWindow?: number;
/**
* Direction of excursions to count:
* - 'auto': Use first excursion type that exceeds SD threshold (Service 1970 default)
* - 'ascending': Count only ascending excursions (MAGE+)
* - 'descending': Count only descending excursions (MAGE-)
*/
direction?: 'auto' | 'ascending' | 'descending';
}
/**
* Calculates the unbiased sample standard deviation (SD) of glucose values.
* Uses n-1 in the denominator (sample SD), as recommended in clinical research and guidelines.
*
* @param readings Array of glucose values (numbers)
* @returns Standard deviation, or NaN if fewer than 2 values
* @throws {TypeError} If readings is not an array
* @see {@link https://care.diabetesjournals.org/content/42/8/1593 ADA 2019: Glycemic Targets}
* @see {@link https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7445493/ ISPAD 2019}
* @example
* ```ts
* glucoseStandardDeviation([100, 120, 140]) // 20
* glucoseStandardDeviation([]) // NaN
* ```
* @remarks
* - If readings contains <2 values, returns NaN (not enough data for SD).
* - Handles NaN/Infinity values by propagating them in the result.
*/
declare function glucoseStandardDeviation(readings: number[]): number;
/**
* Calculates the coefficient of variation (CV) for glucose values.
* CV = (SD / mean) × 100. Used to assess glycemic variability.
*
* @param readings Array of glucose values (numbers)
* @returns Coefficient of variation as a percentage, or NaN if <2 values or mean is 0
* @throws {TypeError} If readings is not an array
* @see {@link https://care.diabetesjournals.org/content/42/8/1593 ADA 2019: Glycemic Targets}
* @example
* ```ts
* glucoseCoefficientOfVariation([100, 120, 140]) // 18.26
* glucoseCoefficientOfVariation([100]) // NaN
* glucoseCoefficientOfVariation([]) // NaN
* ```
* @remarks
* - If readings contains <2 values or mean is 0, returns NaN.
* - Handles NaN/Infinity values by propagating them in the result.
*/
declare function glucoseCoefficientOfVariation(readings: number[]): number;
/**
* Calculates specified percentiles from an array of glucose values using the nearest-rank method.
* Used for clinical analytics and glucose variability assessment.
* @param readings - Array of glucose values (numbers)
* @param percentiles - Array of percentiles to calculate (e.g., [10, 25, 50, 75, 90])
* @returns Object mapping percentile to value, or {} if input is empty
* @throws {TypeError} If readings or percentiles is not an array
* @see https://en.wikipedia.org/wiki/Percentile
* @see https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7445493/ (ISPAD 2019)
* @example
* glucosePercentiles([100, 120, 140, 160, 180], [10, 50, 90]) // { 10: 100, 50: 140, 90: 180 }
* glucosePercentiles([], [10, 50, 90]) // {}
* @remarks
* - Returns the value at the nearest-rank for each percentile.
* - If readings is empty, returns an empty object.
* - Percentiles outside [0, 100] are ignored.
*/
declare function glucosePercentiles(readings: number[], percentiles: number[]): Record<number, number>;
/**
* Calculates Mean Amplitude of Glycemic Excursions (MAGE) for glucose values.
* Implements gold-standard Service FJ et al. (1970) clinical methodology, validated to 1.4% median error vs manual calculations.
* @param readings - Array of glucose values (mg/dL or mmol/L)
* @param options - Optional configuration for MAGE calculation
* @returns MAGE value, or NaN if insufficient data or no valid excursions
* @see https://pubmed.ncbi.nlm.nih.gov/5469118/ (Service FJ, et al. 1970)
* @see https://journals.sagepub.com/doi/10.1177/19322968211061165 (Fernandes NJ, et al. 2022)
* @see https://care.diabetesjournals.org/content/42/8/1593 (ADA 2019)
* @example
* glucoseMAGE([100, 120, 80, 160, 90, 140, 70, 180])
* glucoseMAGE(readings, { direction: 'ascending', shortWindow: 5, longWindow: 32 })
* @remarks
* - Minimum 24 data points recommended (1 day of hourly readings)
* - Best suited for continuous glucose monitoring (CGM) data
* - Not recommended for sparse or irregular measurements
* - Uses dual moving averages, three-point excursion definition, and prevents double-counting for clinical accuracy.
*/
declare function glucoseMAGE(readings: number[], options?: MAGEOptions): number;
export { type A1CReading, A1C_TO_EAG_CONSTANT, A1C_TO_EAG_MULTIPLIER, AllowedGlucoseUnits, type EstimateGMIOptions, GLUCOSE_COLOR_ELEVATED, GLUCOSE_COLOR_HIGH, GLUCOSE_COLOR_LOW, GLUCOSE_COLOR_NORMAL, GLUCOSE_COLOR_NORMAL_DOWN, GLUCOSE_COLOR_NORMAL_UP, GLUCOSE_ZONE_COLORS, type GlucoseReading, type GlucoseStatsOptions, type GlucoseUnit, HOMA_IR_CUTOFFS, HOMA_IR_DENOMINATOR, HYPER_THRESHOLD_MGDL, HYPER_THRESHOLD_MMOLL, HYPO_THRESHOLD_MGDL, HYPO_THRESHOLD_MMOLL, type MAGEOptions, MGDL_MMOLL_CONVERSION, MG_DL, MMOL_L, type TIROptions, type TIRResult, TREND_ARROWS, a1cDelta, a1cToGMI, a1cTrend, calculateHOMAIR, calculateTIR, calculateTimeInRange, checkGlycemicAlignment, glucoseMAGE$1 as clinicalMAGE, convertGlucoseUnit, estimateA1CFromAverage, estimateA1CFromAvgGlucose, estimateAvgGlucoseFromA1C, estimateEAG, estimateGMI, formatA1C, formatDate, formatGlucose, formatPercentage, getA1CCategory, getGlucoseLabel, getTIRSummary, glucoseCoefficientOfVariation, glucoseMAGE, glucosePercentiles, glucoseStandardDeviation, groupByDay, isA1CInTarget, isEstimateGMIOptions, isHyper, isHypo, isValidA1C, isValidGlucoseString, isValidGlucoseValue, mgDlToMmolL, mmolLToMgDl, parseGlucoseString };