sugarsense-glucose-units

Blood glucose unit conversion (mg/dL to mmol/L and back), CGM trend arrows, glucose zone classification, time in range and GMI helpers. Zero dependencies, works in Node and every bundler, ships CommonJS, ESM and TypeScript types.

Extracted from Sugar Sense, a CGM monitoring app for iOS, Apple Watch and Android that connects to FreeStyle Libre, Dexcom and Nightscout and shares glucose with family in real time. These are the exact conventions the app uses in production, published so other diabetes tools can reuse them instead of re-deriving the math.

This library is informational only. It contains no insulin dosing logic and gives no medical advice.

Install

npm install sugarsense-glucose-units

Usage

import {
  mgdlToMmol,
  formatGlucose,
  trendArrow,
  classifyZone,
  timeInRange,
  gmi,
  isStale,
} from 'sugarsense-glucose-units';

mgdlToMmol(100);          // 5.55
formatGlucose(120, 'mmol'); // '6.7'  (display form, 1 decimal)
trendArrow(2);            // '↘'
classifyZone(65);         // 'low'
gmi(154);                 // 6.99  (approximates lab A1C, %)
isStale(readingMs);       // true when older than 15 minutes

timeInRange([50, 60, 100, 150, 200, 300]);
// {
//   total: 6,
//   counts:  { veryLow: 1, low: 1, inRange: 2, high: 1, veryHigh: 1 },
//   percent: { veryLow: 16.7, low: 16.7, inRange: 33.3, high: 16.7, veryHigh: 16.7 }
// }

CommonJS works the same way: const units = require('sugarsense-glucose-units').

Conventions

These match the Sugar Sense production apps and backend:

• All math is done in mg/dL; mmol/L is a display conversion (factor 0.0555, shown with 1 decimal).
• Trend codes are integers 1 to 5: 1 ↓ falling fast, 2 ↘ falling, 3 → steady, 4 ↗ rising, 5 ↑ rising fast (the same scheme Dexcom, Libre and Nightscout data can be normalized to).
• Zones: veryLow | low | inRange | high | veryHigh, with boundaries inclusive on the out-of-range side (a value exactly at the low limit is low, exactly at the high limit is high).
• Default thresholds are 55 / 70 / 180 / 250 mg/dL (DEFAULT_THRESHOLDS), aligned with ADA guidance. Every function accepts custom thresholds.
• Stale rule: a reading older than 15 minutes should be treated as "no current data".

API

| Function | Description | |---|---| | mgdlToMmol(mgdl) | mg/dL to mmol/L, unrounded number | | mmolToMgdl(mmol) | mmol/L to mg/dL, rounded to a whole number | | formatGlucose(mgdl, unit?) | display string: 'mgdl' whole number, 'mmol' 1 decimal | | trendArrow(code) / trendName(code) | arrow symbol / name for trend codes 1 to 5 | | classifyZone(mgdl, thresholds?) | 'veryLow' \| 'low' \| 'inRange' \| 'high' \| 'veryHigh' | | timeInRange(readings, thresholds?) | five-band counts + percentages over an array of readings | | inRangePercent(readings, thresholds?) | percent strictly inside the target band, null when empty | | gmi(meanMgdl) | Glucose Management Indicator (Bergenstal et al., 2018) | | isStale(timeMs, nowMs?, staleMinutes?) | staleness check, 15 min default | | MMOL_PER_MGDL, DEFAULT_THRESHOLDS, TREND_ARROWS, TREND_NAMES | constants |

About Sugar Sense

Sugar Sense turns CGM data into real-time monitoring for the whole family: glucose on the lock screen and Apple Watch, low and high alerts, an automated emergency call on urgent lows, and a Care Circle so loved ones can follow along. There is also a web dashboard and a free download page.

License

MIT