Diabetic Utils

A modern TypeScript utility library for glucose, A1C, and diabetic health data. No bloat. No guesswork. Just sharp utilities built for real-world usage.

⚠️ This is a full v1 rewrite - rebuilt from the ground up with strict TypeScript types, runtime guards, and modular, test-driven architecture. No bloat. No guesswork. Just sharp utilities built for real-world usage.

---

📦 Installation

Install from npm:

npm install diabetic-utils
# or
pnpm add diabetic-utils
# or
yarn add diabetic-utils

⚡ Quick Usage

import {
  estimateGMI,
  estimateA1CFromAverage,
  mgDlToMmolL,
  mmolLToMgDl,
  calculateTimeInRange,
  formatGlucose,
  parseGlucoseString,
  isValidGlucoseValue,
  getGlucoseLabel,
} from 'diabetic-utils'

estimateGMI(100, 'mg/dL') // → 5.4
estimateGMI('5.5 mmol/L') // → ~12.1
estimateGMI({ value: 100, unit: 'mg/dL' }) // → 5.4

// You can also automatically label glucose values as low, normal, or high:
getGlucoseLabel(60, 'mg/dL') // 'low'
getGlucoseLabel(5.5, 'mmol/L') // 'normal'
getGlucoseLabel(200, 'mg/dL') // 'high'

🧑‍💻 Full Examples

Here are some real-world TypeScript examples to get you started:

// Convert mg/dL to mmol/L
const mmol = mgDlToMmolL(100) // 5.5

// Convert mmol/L to mg/dL
const mgdl = mmolLToMgDl(7.2) // 130

// Estimate A1C from average glucose (mg/dL)
const a1c = estimateA1CFromAverage(120, 'mg/dL') // 5.9

// Estimate A1C from average glucose (mmol/L)
const a1c2 = estimateA1CFromAverage(6.7, 'mmol/L') // 6.7

// Calculate Time-in-Range (TIR)
const readings = [90, 110, 150, 200, 80]
const tir = calculateTimeInRange(readings, 70, 180) // e.g., 60

// Format a glucose value
const formatted = formatGlucose(5.5, 'mmol/L') // '5.5 mmol/L'

// Label glucose status
const status = getGlucoseLabel(65, 'mg/dL') // 'low'

// Parse a glucose string
const { value, unit } = parseGlucoseString('7.2 mmol/L')

// Validate a glucose value
const isValid = isValidGlucoseValue(value, unit) // true

// ...and more!

🛠️ Why diabetic-utils?

• Zero-bloat, focused utilities
• 100% test coverage
• TypeScript-first, works in JS too
• Perfect for apps, research, and data science

🧱 Architecture Highlights

• ✅ Fully tested core utilities with edge case coverage via Vitest
• ✅ Input guards and string parsing for robust DX - protect users from malformed data
• ✅ Strictly typed inputs and outputs using modern TypeScript best practices
• ✅ Predictable, composable function signatures designed for safe integrations
• ✅ Developer-first architecture: clear folder structure, import aliases, and helper separation
• ✅ Built with CGM apps, dashboards, and wearable integrations in mind
• ✅ Readable, ergonomic API that's easy to use in both clinical and wellness-focused tools
• ✅ Performance-focused - zero external runtime dependencies

🌱 Coming Soon

• ⏱️ More time-in-range (TIR) utilities
• 🧠 Predictive A1C & glucose trends
• 🔁 Advanced glucose unit conversions
• 🏷️ Glucose formatting & status labeling (low, normal, high)
• 🧪 Lab value constants, ranges, and typed result models
• 🌐 Docs site: diabeticutils.com

🚦 Launch Status

• Docs: Complete
• Code: Modular, clean, scalable
• Coverage: 100%
• NPM: Live!

✍️ Author

Built by @marklearst

Pushing pixels with purpose. Tools for humans.

🌐 Connect

• X (Twitter): @marklearst
• LinkedIn: Mark Learst
• GitHub: marklearst
• Portfolio: marklearst.com
• Website: diabeticutils.com (coming soon)

💬 Mention or DM me if you use diabetic-utils in your project—I'd love to feature your work!

⭐ Star the repo, share on socials, and help us build the best diabetes data toolkit together!

👨🏻‍💻 Developer Notes

Check back!