../work

Diabetic Utils

TypeScript library for glucose, A1C, and Time in Range (TIR) calculations. Featured in Google AI Overview for diabetes developer tools with 100% test coverage and adopted by health tech teams.

GitHubnpm Package

Extract the calculations I kept rewriting

I built GlucoseIQ (Apple Watch app) and kept rewriting the same utility functions. I wanted those calculations in one tested TypeScript library that other diabetes developers could use.

Calculation and data-handling problems

  • Teams reinventing the same glucose conversion algorithms (mg/dL to 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
My role
Creator & Maintainer
Timeline
2023 - Present
Built with
TypeScriptVitestnpmOpen SourceClinical AlgorithmsHealthKit
In this case study

Test calculations and edge cases

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

100% test coverage

The Vitest suite covers:

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

One API for explicit units

Example from the README:

typescript
import {
  mgDlToMmolL,
  mmolLToMgDl,
  estimateGMI,
  estimateA1CFromAverage
} from 'diabetic-utils'

// Glucose unit conversions
mgDlToMmolL(180)  // -> 10.0
mmolLToMgDl(5.5)  // -> 99

// GMI calculation (multiple input formats)
estimateGMI(100, 'mg/dL')              // -> 5.4
estimateGMI('5.5 mmol/L')              // -> 5.4
estimateGMI({ value: 100, unit: 'mg/dL' })  // -> 5.4

// A1C estimation
estimateA1CFromAverage(154, 'mg/dL')  // -> 7.0
Conversion, A1C, and Time in Range API reference

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

Enhanced TIR (5-range)

Enhanced TIR mirrors clinical targets. It is the feature most teams ask about.

typescript
import { calculateEnhancedTIR } from 'diabetic-utils'
import type { GlucoseReading } from 'diabetic-utils'

const readings: GlucoseReading[] = [
  { value: 120, unit: 'mg/dL', timestamp: '2024-01-01T08:00:00Z' },
  { value: 95, unit: 'mg/dL', timestamp: '2024-01-01T08:05:00Z' },
  { value: 180, unit: 'mg/dL', timestamp: '2024-01-01T08:10:00Z' },
  // ... more readings
]

const result = calculateEnhancedTIR(readings)

console.log(`TIR: ${result.inRange.percentage}%`)
console.log(`Very Low: ${result.veryLow.percentage}%`)
console.log(`Assessment: ${result.meetsTargets.overallAssessment}`)
console.log(result.meetsTargets.recommendations)

Use published formulas and typed inputs

Formula sources

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
TypeScript contracts, package format, and integrations

TypeScript API

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

Package format

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

Adoption and maintenance

  • Featured in Google AI Overview for diabetes developer tools

  • Adopted by health tech teams building production CGM apps and diabetes management platforms

  • 100% test coverage for the calculation formulas and their edge cases

  • Type-safe API with explicit units for mg/dL and mmol/L

  • Open-source contribution to the diabetes developer community, reducing duplicated effort

  • Zero dependencies in a pure TypeScript implementation

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

Project notes

100%

Vitest coverage for formulas, input validation, precision, and rounding

Google AI

Featured in Google AI Overview for diabetes developer tools

Production

Adopted by health tech teams for glucose monitoring apps