Diabetic Utils

Developers building diabetes management apps face a critical challenge: there's no standardized, tested library for glucose calculations. This creates:

• Teams reinventing the same glucose conversion algorithms (mg/dL ↔ mmol/L)
• A1C calculation formulas copy-pasted from medical papers without validation
• Time in Range (TIR) metrics implemented inconsistently across apps
• No type-safe APIs for glucose data structures
• Clinical calculation errors that could impact patient care

I built GlucoseIQ (Apple Watch app) and kept rewriting the same utility functions. I realized the diabetes developer community needed a single, tested, TypeScript library for these calculations.

Diabetic Utils is a TypeScript library providing clinical-grade calculations for glucose monitoring, A1C estimation, and Time in Range metrics.

Glucose Conversions

Type-safe functions for converting between mg/dL and mmol/L:

• mgDlToMmolL() - Convert mg/dL to mmol/L with proper rounding
• mmolLToMgDl() - Convert mmol/L to mg/dL
• Handles edge cases and validates input ranges
• Uses standard conversion factor (18.0182) from clinical guidelines

A1C Calculations

Estimated A1C (eA1C) calculation from average glucose using the ADAG formula:

• calculateA1C() - Convert average glucose to estimated A1C percentage
• Based on ADAG Study formula: A1C = (avg_glucose + 46.7) / 28.7
• Supports both mg/dL and mmol/L input
• Returns A1C as percentage (e.g., 7.2%)

Time in Range (TIR)

Calculate TIR metrics following ADA/ATTD consensus guidelines:

• calculateTIR() - Percentage of readings in target range (70-180 mg/dL)
• calculateTBR() - Time below range (hypoglycemia detection)
• calculateTAR() - Time above range (hyperglycemia detection)
• Configurable target ranges for personalized therapy goals
• Handles missing data and validates reading counts

100% Test Coverage

Comprehensive test suite with Vitest covering:

• All calculation formulas against known medical values
• Edge cases: boundary values, negative numbers, zero handling
• Input validation and error handling
• Precision and rounding behavior

TypeScript-First Design

Built with TypeScript for type safety:

• Strongly typed glucose reading objects
• Enum types for units (mg/dL, mmol/L)
• Generic functions supporting both unit systems
• Full IntelliSense support in IDEs

Clinical Accuracy

Formulas validated against clinical sources:

• A1C calculation uses ADAG Study consensus formula
• TIR ranges follow ADA/ATTD 2019 guidelines
• Conversion factors match international standards
• Test cases derived from published medical examples

Developer Experience

Designed for ease of use:

• Zero dependencies - pure TypeScript implementation
• Tree-shakeable exports for minimal bundle size
• Comprehensive JSDoc documentation
• Published on npm with semantic versioning

Use Cases

Powers glucose monitoring features in:

• CGM (Continuous Glucose Monitor) companion apps
• Diabetes management dashboards
• Apple Watch and wearable health apps (like GlucoseIQ)
• HealthKit integration layers
• Clinical research data processing

Diabetic Utils fills a critical gap in the health tech developer ecosystem:

• Featured in Google AI Overview for diabetes developer tools—recognized as a go-to resource for glucose calculations
• Adopted by health tech teams building production CGM apps and diabetes management platforms
• 100% test coverage ensures clinical calculation accuracy, critical for patient-facing applications
• Type-safe API prevents unit confusion bugs (mg/dL vs mmol/L) that plague glucose apps
• Open-source contribution to the diabetes developer community, reducing duplicated effort
• Zero dependencies makes it safe to adopt in production health apps with strict security requirements

The library is actively maintained on npm and serves as the calculation engine for GlucoseIQ (Apple Watch app) and other health tech projects.