The professional TypeScript toolkit for diabetes analytics and clinical-grade health data.
A modern, strictly-typed utility library for glucose, A1C, insulin, and diabetes metrics. Designed for reliability, transparency, and real-world clinical use—no bloat, no guesswork, just robust utilities and authoritative references.
⚠️ v1+ is a full rewrite: strict TypeScript, runtime validation, modular design, and 100% test coverage. Trusted by developers, clinicians, and researchers alike.
Install from npm:
npm install diabetic-utils
# or
pnpm add diabetic-utils
# or
yarn add diabetic-utilsimport {
estimateGMI,
estimateA1CFromAverage,
mgDlToMmolL,
mmolLToMgDl,
calculateTimeInRange,
formatGlucose,
parseGlucoseString,
isValidGlucoseValue,
getGlucoseLabel,
isHypo,
isHyper,
getA1CCategory,
isA1CInTarget,
} 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'- TypeScript-first, fully typed API
- Glucose, A1C, GMI, HOMA-IR, and time-in-range utilities
- Input parsing and robust clinical validation
- Labeling and categorization helpers
- Centralized clinical constants and thresholds
- 100% test coverage (unit, edge, and error cases)
- No dependencies, no bloat
- Authoritative references (ADA, CDC, PubMed, ISPAD)
- Modern TSDoc and auto-generated API documentation
- Modern TypeScript-first API: Strict types, runtime validation, and full TSDoc coverage.
- 100% Test Coverage: Every function, edge case, and error branch is tested.
- Clinical-Grade Analytics: HOMA-IR, A1C, GMI, TIR, and glucose variability metrics with authoritative references.
- Input Validation: All clinical values are validated with robust, reusable guards.
- No Bloat, No Guesswork: Focused, modular utilities—tree-shakable and production-ready.
- Trusted References: All algorithms and thresholds are transparently sourced from ADA, CDC, PubMed, and ISPAD guidelines.
- Ready for SDKs and Apps: Small bundle, ESM/CJS support, and zero dependencies.
- Alignment Module:
- Added
alignment.tsfor HOMA-IR calculation and glycemic marker alignment. - Fully documented with clinical references and disclaimers.
- 100% test coverage including edge cases and invalid input handling.
- Added
- Modern Validators:
- New
validators.tsfor insulin and future biomarker validation.
- New
- Constants Centralized:
- All clinical thresholds and formulas now in
constants.ts.
- All clinical thresholds and formulas now in
- Improved TSDoc:
- All public and internal functions now feature detailed TSDoc with clinical context.
- Magic Numbers Eliminated:
- All formulas use named constants for clarity and maintainability.
- Robust Error Handling:
- Functions throw clear, descriptive errors on invalid input.
- Authoritative References:
- Only trusted, relevant clinical sources cited.
- API Reference: Auto-generated Typedoc documentation covers all functions, types, and constants.
- Usage Examples: See the "Full Examples" and "Quick Usage" sections below for real-world TypeScript snippets.
getGlucoseLabel(5.5, 'mmol/L') // 'normal' getGlucoseLabel(200, 'mg/dL') // 'high'
// --- // Configurable clinical thresholds (NEW!) // ---
// Custom hypo threshold (mg/dL) isHypo(75, 'mg/dL', { mgdl: 80 }) // true isHypo(85, 'mg/dL', { mgdl: 80 }) // false
// Custom hyper threshold (mmol/L) isHyper(9.0, 'mmol/L', { mmoll: 8.5 }) // true isHyper(8.0, 'mmol/L', { mmoll: 8.5 }) // false
// Custom thresholds for labeling getGlucoseLabel(75, 'mg/dL', { hypo: { mgdl: 80 } }) // 'low' getGlucoseLabel(170, 'mg/dL', { hyper: { mgdl: 160 } }) // 'high' getGlucoseLabel(100, 'mg/dL', { hypo: { mgdl: 80 }, hyper: { mgdl: 160 } }) // 'normal'
// Custom A1C category cutoffs getA1CCategory(6.0, { normalMax: 6.0, prediabetesMax: 7.0 }) // 'normal' getA1CCategory(6.5, { normalMax: 6.0, prediabetesMax: 7.0 }) // 'prediabetes' getA1CCategory(7.5, { normalMax: 6.0, prediabetesMax: 7.0 }) // 'diabetes'
// --- // Clinical-Grade Glucose Variability Analytics (NEW!) // ---
// Calculate unbiased sample standard deviation (SD)
glucoseStandardDeviation([90, 100, 110, 120, 130, 140, 150, 160, 170, 180]) // 30.28
// Calculate coefficient of variation (CV)
glucoseCoefficientOfVariation([90, 100, 110, 120, 130, 140, 150, 160, 170, 180]) // 22.43
// Calculate percentiles (nearest-rank method)
glucosePercentiles( [90, 100, 110, 120, 130, 140, 150, 160, 170, 180], [10, 25, 50, 75, 90] ) // { 10: 90, 25: 110, 50: 130, 75: 160, 90: 170 }
## Clinical-Grade Glucose Variability Analytics
Diabetic Utils is the **only TypeScript/JavaScript library** offering clinical-grade, research-backed glucose variability metrics:
- **Standard Deviation (SD):** Unbiased sample SD (n-1), as used in clinical research and guidelines ([See ADA 2019](https://care.diabetesjournals.org/content/42/8/1593), [See ISPAD 2019](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7445493/)).
- **Coefficient of Variation (CV):** SD divided by mean, multiplied by 100. Used to assess glycemic variability in clinical trials.
- **Percentiles:** Nearest-rank method, standard in research and clinical reporting.
### Usage Examples
```typescript
import {
glucoseStandardDeviation,
glucoseCoefficientOfVariation,
glucosePercentiles,
} from 'diabetic-utils'
const data = [90, 100, 110, 120, 130, 140, 150, 160, 170, 180]
glucoseStandardDeviation(data) // 30.28
glucoseCoefficientOfVariation(data) // 22.43
glucosePercentiles(data, [10, 50, 90]) // { 10: 90, 50: 130, 90: 170 }
References:
These analytics make diabetic-utils uniquely suited for research, clinical trials, and advanced diabetes management apps.
Contributions, issues and feature requests are welcome!
- Fork the repository
- Create your feature branch (
git checkout -b my-feature) - Commit your changes (
git commit -am 'Add new feature') - Push to the branch (
git push origin my-feature) - Open a pull request
See CHANGELOG.md for release notes and version history.
This project is licensed under the MIT License. See the LICENSE file for details.
For questions, issues, or feature requests, open an issue on GitHub or email [email protected].
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!- Zero-bloat, focused utilities
- 100% test coverage
- TypeScript-first, works in JS too
- Perfect for apps, research, and data science
- ✅ 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
- ⏱️ 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
- Docs: Complete
- Code: Modular, clean, scalable
- Coverage: 100%
- NPM: Live!
Built by @marklearst
Pushing pixels with purpose. Tools for humans.
- 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!
I built diabetic-utils because I believe in the power of data-driven diabetes management. As someone who's lived with diabetes, I know how hard it can be to make sense of the numbers. That's why I've poured my heart into creating a library that's both clinically accurate and easy to use. Whether you're building an app, working on a research project, or just trying to make sense of your own data, I hope diabetic-utils can help. Let's work together to make diabetes management better, one data point at a time.
- This library follows semver for versioning.
- All calculations are based on peer-reviewed medical sources. (See: NIH A1C, ADA conversion formulas)
- Unit tests live in
/testand run automatically via CI. - API will stay stable for all
1.xreleases—any breaking change will be in2.0. - Planned next: [ ] Add more unit conversions, [ ] Support for Type 1-specific metrics.
- Got a formula you want to see? File an issue or PR!
This project is licensed under the MIT License. © 2024–2025 Mark Learst
Use it, fork it, build something that matters.