sugarsense-glucose-units 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sugar Sense (https://sugarsense.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# 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](https://sugarsense.io), a CGM monitoring app for iOS, Apple Watch and Android that connects to FreeStyle Libre, Dexcom and [Nightscout](https://nightscout.github.io/) 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
+
+```sh
+npm install sugarsense-glucose-units
+```
+
+## Usage
+
+```js
+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](https://sugarsense.io) 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](https://app.sugarsense.io) and a free [download page](https://sugarsense.io/download).
+
+## License
+
+MIT

package/index.cjs

@@ -0,0 +1,153 @@
+'use strict';
+
+// Glucose unit and zone helpers, extracted from Sugar Sense (https://sugarsense.io).
+// All internal math is mg/dL; mmol/L exists only as a display conversion.
+// This library is informational only and contains no dosing logic.
+
+const MMOL_PER_MGDL = 0.0555;
+
+// ADA-aligned defaults used by Sugar Sense for new accounts (mg/dL).
+const DEFAULT_THRESHOLDS = Object.freeze({
+  veryLow: 55,
+  low: 70,
+  high: 180,
+  veryHigh: 250,
+});
+
+// CGM trend codes: 1 falling fast, 2 falling, 3 steady, 4 rising, 5 rising fast.
+const TREND_ARROWS = Object.freeze({ 1: '↓', 2: '↘', 3: '→', 4: '↗', 5: '↑' });
+const TREND_NAMES = Object.freeze({
+  1: 'fallingFast',
+  2: 'falling',
+  3: 'steady',
+  4: 'rising',
+  5: 'risingFast',
+});
+
+function assertFinite(value, name) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) throw new TypeError(`${name} must be a finite number`);
+  return n;
+}
+
+function assertThresholds(t) {
+  const veryLow = assertFinite(t.veryLow, 'thresholds.veryLow');
+  const low = assertFinite(t.low, 'thresholds.low');
+  const high = assertFinite(t.high, 'thresholds.high');
+  const veryHigh = assertFinite(t.veryHigh, 'thresholds.veryHigh');
+  if (!(veryLow < low && low < high && high < veryHigh)) {
+    throw new RangeError('thresholds must satisfy veryLow < low < high < veryHigh');
+  }
+  return { veryLow, low, high, veryHigh };
+}
+
+// mg/dL -> mmol/L (unrounded). Use formatGlucose for the 1-decimal display form.
+function mgdlToMmol(mgdl) {
+  return assertFinite(mgdl, 'mgdl') * MMOL_PER_MGDL;
+}
+
+// mmol/L -> mg/dL, rounded to the nearest whole number.
+function mmolToMgdl(mmol) {
+  return Math.round(assertFinite(mmol, 'mmol') / MMOL_PER_MGDL);
+}
+
+// Display formatting identical to the Sugar Sense apps:
+// mmol/L is shown with exactly 1 decimal, mg/dL as a whole number.
+function formatGlucose(mgdl, unit = 'mgdl') {
+  const v = assertFinite(mgdl, 'mgdl');
+  if (unit === 'mmol') return (v * MMOL_PER_MGDL).toFixed(1);
+  if (unit === 'mgdl') return String(Math.round(v));
+  throw new RangeError("unit must be 'mgdl' or 'mmol'");
+}
+
+function trendArrow(code) {
+  return TREND_ARROWS[code] || '';
+}
+
+function trendName(code) {
+  return TREND_NAMES[code] || '';
+}
+
+// Zone boundaries are inclusive on the out-of-range side:
+//   veryLow : value <= veryLow
+//   low     : veryLow < value <= low
+//   inRange : low < value < high
+//   high    : high <= value < veryHigh
+//   veryHigh: value >= veryHigh
+function classifyZone(mgdl, thresholds = DEFAULT_THRESHOLDS) {
+  const v = assertFinite(mgdl, 'mgdl');
+  const t = assertThresholds(thresholds);
+  if (v >= t.veryHigh) return 'veryHigh';
+  if (v <= t.veryLow) return 'veryLow';
+  if (v >= t.high) return 'high';
+  if (v <= t.low) return 'low';
+  return 'inRange';
+}
+
+// Five-band distribution over an array of mg/dL values (numbers or {value}).
+// Percentages sum to ~100; empty input returns zero counts and percentages.
+function timeInRange(readings, thresholds = DEFAULT_THRESHOLDS) {
+  const t = assertThresholds(thresholds);
+  const counts = { veryLow: 0, low: 0, inRange: 0, high: 0, veryHigh: 0 };
+  for (const r of readings) {
+    const v = typeof r === 'object' && r !== null ? r.value : r;
+    counts[classifyZone(v, t)]++;
+  }
+  const total = readings.length;
+  const pct = (c) => (total === 0 ? 0 : (c / total) * 100);
+  return {
+    total,
+    counts,
+    percent: {
+      veryLow: pct(counts.veryLow),
+      low: pct(counts.low),
+      inRange: pct(counts.inRange),
+      high: pct(counts.high),
+      veryHigh: pct(counts.veryHigh),
+    },
+  };
+}
+
+// Percent of readings strictly inside the target band (edges are out of range).
+// Returns null for empty input.
+function inRangePercent(readings, thresholds = DEFAULT_THRESHOLDS) {
+  const t = assertThresholds(thresholds);
+  if (readings.length === 0) return null;
+  let inRange = 0;
+  for (const r of readings) {
+    const v = assertFinite(typeof r === 'object' && r !== null ? r.value : r, 'reading');
+    if (v > t.low && v < t.high) inRange++;
+  }
+  return (inRange / readings.length) * 100;
+}
+
+// Glucose Management Indicator (approximates lab A1C, %) from mean mg/dL.
+// International consensus formula (Bergenstal et al., 2018).
+function gmi(meanMgdl) {
+  return 3.31 + 0.02392 * assertFinite(meanMgdl, 'meanMgdl');
+}
+
+// A reading older than staleMinutes (default 15, the Sugar Sense rule) is stale
+// and should be presented as "no current data". Timestamps in epoch ms.
+function isStale(readingTimeMs, nowMs = Date.now(), staleMinutes = 15) {
+  const ts = assertFinite(readingTimeMs, 'readingTimeMs');
+  const now = assertFinite(nowMs, 'nowMs');
+  return now - ts > staleMinutes * 60 * 1000;
+}
+
+module.exports = {
+  MMOL_PER_MGDL,
+  DEFAULT_THRESHOLDS,
+  TREND_ARROWS,
+  TREND_NAMES,
+  mgdlToMmol,
+  mmolToMgdl,
+  formatGlucose,
+  trendArrow,
+  trendName,
+  classifyZone,
+  timeInRange,
+  inRangePercent,
+  gmi,
+  isStale,
+};

package/index.d.ts

@@ -0,0 +1,35 @@
+export declare const MMOL_PER_MGDL: number;
+
+export interface Thresholds {
+  veryLow: number;
+  low: number;
+  high: number;
+  veryHigh: number;
+}
+
+export declare const DEFAULT_THRESHOLDS: Readonly<Thresholds>;
+
+export type TrendCode = 1 | 2 | 3 | 4 | 5;
+export declare const TREND_ARROWS: Readonly<Record<TrendCode, string>>;
+export declare const TREND_NAMES: Readonly<Record<TrendCode, string>>;
+
+export type Zone = 'veryLow' | 'low' | 'inRange' | 'high' | 'veryHigh';
+
+export type Reading = number | { value: number };
+
+export interface TimeInRangeResult {
+  total: number;
+  counts: Record<Zone, number>;
+  percent: Record<Zone, number>;
+}
+
+export declare function mgdlToMmol(mgdl: number): number;
+export declare function mmolToMgdl(mmol: number): number;
+export declare function formatGlucose(mgdl: number, unit?: 'mgdl' | 'mmol'): string;
+export declare function trendArrow(code: number): string;
+export declare function trendName(code: number): string;
+export declare function classifyZone(mgdl: number, thresholds?: Thresholds): Zone;
+export declare function timeInRange(readings: Reading[], thresholds?: Thresholds): TimeInRangeResult;
+export declare function inRangePercent(readings: Reading[], thresholds?: Thresholds): number | null;
+export declare function gmi(meanMgdl: number): number;
+export declare function isStale(readingTimeMs: number, nowMs?: number, staleMinutes?: number): boolean;

package/index.mjs

@@ -0,0 +1,20 @@
+import m from './index.cjs';
+
+export const {
+  MMOL_PER_MGDL,
+  DEFAULT_THRESHOLDS,
+  TREND_ARROWS,
+  TREND_NAMES,
+  mgdlToMmol,
+  mmolToMgdl,
+  formatGlucose,
+  trendArrow,
+  trendName,
+  classifyZone,
+  timeInRange,
+  inRangePercent,
+  gmi,
+  isStale,
+} = m;
+
+export default m;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "sugarsense-glucose-units",
+  "version": "0.1.0",
+  "description": "Blood glucose unit conversion (mg/dL to mmol/L), CGM trend arrows, glucose zone classification, time in range and GMI helpers. Zero dependencies. Extracted from the Sugar Sense CGM monitoring app.",
+  "keywords": [
+    "glucose",
+    "blood-glucose",
+    "diabetes",
+    "cgm",
+    "mmol",
+    "mgdl",
+    "time-in-range",
+    "gmi",
+    "dexcom",
+    "freestyle-libre",
+    "nightscout"
+  ],
+  "homepage": "https://sugarsense.io",
+  "bugs": {
+    "email": "info@sugarsense.io"
+  },
+  "license": "MIT",
+  "author": "Sugar Sense (https://sugarsense.io)",
+  "type": "commonjs",
+  "main": "./index.cjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.cjs"
+    }
+  },
+  "files": [
+    "index.cjs",
+    "index.mjs",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}