{"id":28154302,"url":"https://github.com/marklearst/diabetic-utils","last_synced_at":"2026-02-28T12:11:16.827Z","repository":{"id":291320120,"uuid":"977262552","full_name":"marklearst/diabetic-utils","owner":"marklearst","description":"🩸 A modern TypeScript utility library for glucose, A1C, and diabetic health data.","archived":false,"fork":false,"pushed_at":"2025-11-11T21:27:47.000Z","size":1340,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-24T00:04:51.963Z","etag":null,"topics":["a1c-calculator","diabetes","diabetic","glucose","glucose-monitoring","typescript","utilities","utility-library"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/diabetic-utils","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marklearst.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-03T19:44:22.000Z","updated_at":"2025-11-12T03:10:01.000Z","dependencies_parsed_at":"2025-07-11T01:51:54.584Z","dependency_job_id":"7e9871d1-fdc0-4484-853e-ecf5e0044fe4","html_url":"https://github.com/marklearst/diabetic-utils","commit_stats":null,"previous_names":["marklearst/diabetic-utils"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/marklearst/diabetic-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marklearst%2Fdiabetic-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marklearst%2Fdiabetic-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marklearst%2Fdiabetic-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marklearst%2Fdiabetic-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marklearst","download_url":"https://codeload.github.com/marklearst/diabetic-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marklearst%2Fdiabetic-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29933114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T09:58:13.507Z","status":"ssl_error","status_checked_at":"2026-02-28T09:57:57.047Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a1c-calculator","diabetes","diabetic","glucose","glucose-monitoring","typescript","utilities","utility-library"],"created_at":"2025-05-15T06:13:17.648Z","updated_at":"2026-02-28T12:11:16.820Z","avatar_url":"https://github.com/marklearst.png","language":"TypeScript","readme":"# 🩸 Diabetic Utils\n\nBuilt and maintained by Mark Learst.\n\n**The professional TypeScript toolkit for diabetes analytics and clinical-grade health data.**\n\n![Diabetic Utils Logo](https://raw.githubusercontent.com/marklearst/diabetic-utils/refs/heads/main/assets/dujs.png)\n\nA 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 backed by authoritative clinical references.\n\n\u003e ⚠️ **v1.4+** features enhanced TIR calculations, 100% test coverage, zero `any` types, and clinical-grade glucose variability analytics. Trusted by developers, clinicians, and researchers.\n\n---\n\n## 📊 Status \u0026 Quality\n\n![Status](https://img.shields.io/badge/status-stable-brightgreen)\n[![codecov](https://codecov.io/gh/marklearst/diabetic-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/marklearst/diabetic-utils)\n![CI](https://github.com/marklearst/diabetic-utils/actions/workflows/ci-cd.yml/badge.svg)\n![TypeScript](https://img.shields.io/badge/TypeScript-100%25_Strict-blue?logo=typescript)\n![Coverage](https://img.shields.io/badge/coverage-100%25-success)\n![npm](https://img.shields.io/npm/v/diabetic-utils)\n![npm downloads](https://img.shields.io/npm/dm/diabetic-utils)\n![License](https://img.shields.io/github/license/marklearst/diabetic-utils)\n\n---\n\n## 🚀 What's New in v1.4.0\n\n### 🎯 Enhanced Time-in-Range (TIR)\nClinical-grade TIR calculations per **International Consensus 2019** and **ADA 2024 Guidelines**:\n- **5-Range Enhanced TIR**: Very Low, Low, In Range, High, Very High\n- **Pregnancy TIR**: Tighter targets (63-140 mg/dL / 3.5-7.8 mmol/L)\n- **Clinical Recommendations**: Automated insights based on targets\n- **Population-Specific Goals**: Standard, older-adults, high-risk\n\n### 🛡️ Type Safety Excellence\n- **Zero `any` types** - Complete type safety throughout\n- **Type Predicates** - Better TypeScript narrowing\n- **Literal Types** - `as const` for autocomplete perfection\n- **Named Return Types** - `ConversionResult` interface\n\n### 📚 Self-Documenting Code\n- **Named Constants**: `GMI_COEFFICIENTS` with clinical references\n- **Working Examples**: Every function has `@example` tags\n- **Test Helpers**: Reusable test utilities for your own projects\n\n### ✅ 100% Test Coverage\n- 205 passing tests\n- Every line, branch, and function covered\n- Defensive code properly documented\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install diabetic-utils\n# or\npnpm add diabetic-utils\n# or\nyarn add diabetic-utils\n```\n\n**Requirements:** TypeScript 4.5+ or JavaScript (ES2020+)\n\n---\n\n## ⚡ Quick Start\n\n### Basic Conversions \u0026 Calculations\n\n```typescript\nimport {\n  mgDlToMmolL,\n  mmolLToMgDl,\n  estimateGMI,\n  estimateA1CFromAverage\n} from 'diabetic-utils'\n\n// Glucose unit conversions\nmgDlToMmolL(180)  // → 10.0\nmmolLToMgDl(5.5)  // → 99\n\n// GMI calculation (multiple input formats)\nestimateGMI(100, 'mg/dL')              // → 5.4\nestimateGMI('5.5 mmol/L')              // → 5.4\nestimateGMI({ value: 100, unit: 'mg/dL' })  // → 5.4\n\n// A1C estimation\nestimateA1CFromAverage(154, 'mg/dL')  // → 7.0\n```\n\n### Enhanced Time-in-Range (NEW!)\n\n```typescript\nimport { calculateEnhancedTIR } from 'diabetic-utils'\nimport type { GlucoseReading } from 'diabetic-utils'\n\nconst readings: GlucoseReading[] = [\n  { value: 120, unit: 'mg/dL', timestamp: '2024-01-01T08:00:00Z' },\n  { value: 95,  unit: 'mg/dL', timestamp: '2024-01-01T08:05:00Z' },\n  { value: 180, unit: 'mg/dL', timestamp: '2024-01-01T08:10:00Z' },\n  // ... more readings\n]\n\nconst result = calculateEnhancedTIR(readings)\n\nconsole.log(`TIR: ${result.inRange.percentage}%`)\n// TIR: 72.5%\n\nconsole.log(`Very Low: ${result.veryLow.percentage}%`)\n// Very Low: 0.5%\n\nconsole.log(`Assessment: ${result.meetsTargets.overallAssessment}`)\n// Assessment: good\n\nconsole.log(result.meetsTargets.recommendations)\n// ['Excellent glycemic control! All metrics meet clinical targets...']\n```\n\n### Pregnancy TIR (NEW!)\n\n```typescript\nimport { calculatePregnancyTIR } from 'diabetic-utils'\n\nconst result = calculatePregnancyTIR(readings)\n\nconsole.log(`TIR (63-140 mg/dL): ${result.inRange.percentage}%`)\n// TIR (63-140 mg/dL): 85.2%\n\nconsole.log(`Meets pregnancy targets: ${result.meetsPregnancyTargets}`)\n// Meets pregnancy targets: true\n\nconsole.log(result.recommendations)\n// ['Excellent glycemic control for pregnancy!...']\n```\n\n### Glucose Labeling \u0026 Validation\n\n```typescript\nimport {\n  getGlucoseLabel,\n  isHypo,\n  isHyper,\n  isValidGlucoseValue\n} from 'diabetic-utils'\n\n// Label glucose values\ngetGlucoseLabel(60, 'mg/dL')   // → 'low'\ngetGlucoseLabel(5.5, 'mmol/L') // → 'normal'\ngetGlucoseLabel(200, 'mg/dL')  // → 'high'\n\n// Clinical checks\nisHypo(65, 'mg/dL')   // → true\nisHyper(180, 'mg/dL') // → false\n\n// Validation\nisValidGlucoseValue(120, 'mg/dL')  // → true\nisValidGlucoseValue(-10, 'mg/dL')  // → false\n```\n\n### Clinical Variability Analytics\n\n```typescript\nimport {\n  glucoseStandardDeviation,\n  glucoseCoefficientOfVariation,\n  glucosePercentiles,\n  calculateMAGE\n} from 'diabetic-utils'\n\nconst data = [90, 100, 110, 120, 130, 140, 150, 160, 170, 180]\n\n// Standard deviation (unbiased sample SD, n-1)\nglucoseStandardDeviation(data)  // → 30.28\n\n// Coefficient of variation (CV%)\nglucoseCoefficientOfVariation(data)  // → 22.43\n\n// Percentiles (nearest-rank method)\nglucosePercentiles(data, [10, 50, 90])\n// → { 10: 90, 50: 130, 90: 170 }\n\n// MAGE (Mean Amplitude of Glycemic Excursions)\nconst mage = calculateMAGE(readings)\nconsole.log(`MAGE: ${mage.value} mg/dL`)\n```\n\n### Custom Thresholds\n\n```typescript\nimport { getGlucoseLabel, isHypo, getA1CCategory } from 'diabetic-utils'\n\n// Custom hypoglycemia threshold\nisHypo(75, 'mg/dL', { mgdl: 80 })  // → true\n\n// Custom hyperglycemia threshold\nisHyper(9.0, 'mmol/L', { mmoll: 8.5 })  // → true\n\n// Custom glucose label thresholds\ngetGlucoseLabel(75, 'mg/dL', {\n  hypo: { mgdl: 80 },\n  hyper: { mgdl: 160 }\n})  // → 'low'\n\n// Custom A1C category cutoffs\ngetA1CCategory(6.5, {\n  normalMax: 6.0,\n  prediabetesMax: 7.0\n})  // → 'prediabetes'\n```\n\n---\n\n## 🌟 Features\n\n### Core Utilities\n- ✅ **Glucose Conversions**: mg/dL ⇄ mmol/L\n- ✅ **A1C Calculations**: GMI, eAG, A1C estimation\n- ✅ **Time-in-Range**: Enhanced TIR (5 ranges), Pregnancy TIR\n- ✅ **HOMA-IR**: Insulin resistance calculation\n- ✅ **Variability Metrics**: SD, CV, MAGE, percentiles\n- ✅ **Validation**: Input guards, string parsing\n- ✅ **Labeling**: Glucose status (low/normal/high)\n\n### Quality \u0026 DX\n- ✅ **TypeScript-First**: 100% strict mode, zero `any` types\n- ✅ **100% Test Coverage**: 205 tests, all edge cases covered\n- ✅ **Zero Dependencies**: No bloat, tree-shakable\n- ✅ **Clinical References**: ADA, CDC, ISPAD, PubMed citations\n- ✅ **TSDoc**: Complete API documentation\n- ✅ **ESM + CJS**: Works everywhere\n- ✅ **Type Predicates**: Better type narrowing\n- ✅ **Named Constants**: Self-documenting formulas\n\n---\n\n## 🏆 Why Choose Diabetic Utils?\n\n### Clinical-Grade Accuracy\nEvery formula, threshold, and calculation is sourced from authoritative clinical guidelines:\n- **International Consensus on Time in Range (2019)** - TIR calculations\n- **ADA Standards of Care (2024)** - Pregnancy targets, A1C guidelines\n- **ISPAD Guidelines (2018)** - Glucose variability metrics\n- **NIH/NIDDK** - HOMA-IR, eAG formulas\n\n### Production-Ready\n- **100% Test Coverage** - Every line tested\n- **Type-Safe** - Catch errors at compile time\n- **Zero Dependencies** - Small bundle, no supply chain risk\n- **Modern ESM** - Tree-shakable, works with Vite, Next.js, etc.\n\n### Developer-Friendly\n- **Clear API** - Predictable function signatures\n- **Great DX** - Autocomplete with literal types\n- **Working Examples** - Copy-paste ready code\n- **Test Helpers** - Utilities for your own tests\n\n### Unique Features\n**Only TypeScript/JavaScript library with:**\n- Enhanced TIR (5-range breakdown)\n- Pregnancy-specific TIR metrics\n- Clinical-grade MAGE calculation\n- Type predicates for validation\n\n---\n\n## 📚 Full API Reference\n\n### Glucose Conversions\n- `mgDlToMmolL(value)` - Convert mg/dL to mmol/L\n- `mmolLToMgDl(value)` - Convert mmol/L to mg/dL\n- `convertGlucoseUnit({ value, unit })` - Generic unit conversion\n\n### A1C \u0026 GMI\n- `estimateA1CFromAverage(glucose, unit)` - A1C from average glucose\n- `estimateGMI(input, unit?)` - GMI from average glucose\n- `a1cToGMI(a1c)` - Convert A1C to GMI\n- `a1cToAverageGlucose(a1c, unit)` - A1C to eAG\n\n### Time-in-Range\n- `calculateTimeInRange(readings, low, high)` - Basic TIR\n- `calculateEnhancedTIR(readings, options?)` - 5-range TIR\n- `calculatePregnancyTIR(readings, options?)` - Pregnancy TIR\n\n### Glucose Analysis\n- `getGlucoseLabel(value, unit, thresholds?)` - Label as low/normal/high\n- `isHypo(value, unit, threshold?)` - Check hypoglycemia\n- `isHyper(value, unit, threshold?)` - Check hyperglycemia\n- `isValidGlucoseValue(value, unit)` - Validate glucose value\n\n### A1C Analysis\n- `getA1CCategory(a1c, cutoffs?)` - Categorize A1C\n- `isA1CInTarget(a1c, target?)` - Check if A1C meets target\n\n### Variability Metrics\n- `glucoseStandardDeviation(readings)` - SD (unbiased)\n- `glucoseCoefficientOfVariation(readings)` - CV%\n- `glucosePercentiles(readings, percentiles)` - Percentile ranks\n- `calculateMAGE(readings)` - Mean Amplitude of Glycemic Excursions\n\n### Insulin Metrics\n- `calculateHOMAIR(glucose, insulin, unit)` - HOMA-IR\n- `isValidInsulin(value)` - Validate insulin value\n\n### Utilities\n- `parseGlucoseString(str)` - Parse \"120 mg/dL\" → { value, unit }\n- `formatGlucose(value, unit)` - Format glucose with unit\n- `isValidGlucoseString(str)` - Validate glucose string\n\n**[View Complete API Docs →](https://marklearst.github.io/diabetic-utils/)**\n\n---\n\n## 🧪 Test Helpers (NEW!)\n\nUse our test utilities in your own projects:\n\n```typescript\nimport {\n  createGlucoseReadings,\n  COMMON_TEST_VALUES,\n  TEST_TIMESTAMP_BASE\n} from 'diabetic-utils/tests/test-helpers'\n\n// Create test data easily\nconst readings = createGlucoseReadings([100, 110, 120], 'mg/dL', 5)\n// → 3 readings at 5-minute intervals\n\n// Use common test values\nconst { NORMAL_GLUCOSE_MGDL, HYPO_GLUCOSE_MGDL } = COMMON_TEST_VALUES\n```\n\n---\n\n## 🔬 Clinical References\n\nAll calculations are based on peer-reviewed clinical sources:\n\n- **Time-in-Range**: [International Consensus (2019)](https://diabetesjournals.org/care/article/42/8/1593)\n- **Pregnancy TIR**: [ADA Standards of Care (2024)](https://diabetesjournals.org/care/article/47/Supplement_1/S282)\n- **A1C/eAG**: [Nathan et al. (2008)](https://diabetesjournals.org/care/article/31/8/1473)\n- **HOMA-IR**: [Matthews et al. (1985)](https://diabetesjournals.org/diabetes/article/34/12/1212)\n- **MAGE**: [Service et al. (1970)](https://diabetesjournals.org/diabetes/article/19/9/644)\n- **Variability**: [ISPAD Guidelines (2018)](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7445493/)\n\n---\n\n## 🏗️ Architecture\n\n```\ndiabetic-utils/\n├── src/\n│   ├── index.ts           # Main exports\n│   ├── constants.ts       # Clinical thresholds \u0026 formulas\n│   ├── types.ts           # TypeScript types\n│   ├── conversions.ts     # Glucose unit conversions\n│   ├── a1c.ts            # A1C \u0026 GMI calculations\n│   ├── tir.ts            # Basic time-in-range\n│   ├── tir-enhanced.ts   # Enhanced \u0026 pregnancy TIR\n│   ├── glucose.ts        # Glucose utilities\n│   ├── alignment.ts      # HOMA-IR\n│   ├── variability.ts    # SD, CV, percentiles\n│   ├── mage.ts           # MAGE calculation\n│   ├── formatters.ts     # String formatting\n│   ├── guards.ts         # Type guards\n│   └── validators.ts     # Input validation\n├── tests/\n│   ├── test-helpers.ts   # Shared test utilities\n│   └── *.test.ts         # 100% coverage tests\n└── dist/                 # Built output (ESM + CJS)\n```\n\n**Key Principles:**\n- ✅ Zero dependencies\n- ✅ Tree-shakable modules\n- ✅ Strict TypeScript\n- ✅ 100% test coverage\n- ✅ Clinical references in TSDoc\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please follow these steps:\n\n1. **Fork** the repository\n2. **Create** your feature branch: `git checkout -b feat/my-feature`\n3. **Add tests** for any new functionality\n4. **Ensure** 100% coverage: `pnpm test:coverage`\n5. **Commit** with [conventional commits](https://www.conventionalcommits.org/): `git commit -m \"feat: add new feature\"`\n6. **Push** to your branch: `git push origin feat/my-feature`\n7. **Open** a pull request\n\n### Development Commands\n\n```bash\n# Install dependencies\npnpm install\n\n# Run tests\npnpm test\n\n# Run tests with coverage\npnpm test:coverage\n\n# Build library\npnpm build\n\n# Lint code\npnpm lint\n\n# Type check\npnpm typecheck\n```\n\n---\n\n## 📝 Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.\n\n---\n\n## 📄 License\n\nThis project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.\n\n© 2024–2025 [Mark Learst](https://marklearst.com)\n\nUse it, fork it, build something that matters.\n\n---\n\n## 🔗 Links\n\n- 📦 [NPM Package](https://www.npmjs.com/package/diabetic-utils)\n- 📚 [API Documentation](https://marklearst.github.io/diabetic-utils/)\n- 🐙 [GitHub Repository](https://github.com/marklearst/diabetic-utils)\n- 🌐 [Website](https://diabeticutils.com) _(coming soon)_\n\n---\n\n## 🙋‍♂️ Author\n\n**Mark Learst**\nFull-stack developer, diabetes advocate, and open source contributor.\n\n- 🐦 X (Twitter): [@marklearst](https://x.com/marklearst)\n- 💼 LinkedIn: [Mark Learst](https://linkedin.com/in/marklearst)\n- 🌐 Portfolio: [marklearst.com](https://marklearst.com)\n\n\u003e 💬 Using diabetic-utils in your project? [Let me know](https://x.com/marklearst)—I'd love to feature it!\n\u003e ⭐ Star the repo and help us build the best diabetes toolkit together!\n\n---\n\n## 💬 Support\n\n- 🐛 **Bug Reports**: [Open an issue](https://github.com/marklearst/diabetic-utils/issues)\n- 💡 **Feature Requests**: [Start a discussion](https://github.com/marklearst/diabetic-utils/discussions)\n- 📧 **Email**: mark@marklearst.com\n\n---\n\n## 📝 A Personal Note\n\nI 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.\n\nThat'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 research, or just trying to understand your own data, I hope diabetic-utils can help.\n\nLet's work together to make diabetes management better, one data point at a time. 🩸\n\n---\n\n**Built with ❤️ by the diabetes community, for the diabetes community.**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarklearst%2Fdiabetic-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarklearst%2Fdiabetic-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarklearst%2Fdiabetic-utils/lists"}