🩺 clinical_lab_values

Type-safe clinical laboratory values with unit conversion, reference ranges, and clinical interpretation for Dart & Flutter.

Built by a Flutter developer with a medical background — because converting mg/dL to mmol/L is easy, but knowing whether 7.8 mmol/L is normal, prediabetes, or diabetes is what actually matters.

---

Why this exists

Generic unit converters already exist. In healthcare apps the interesting part isn't the arithmetic — it's the clinical meaning of a value. This package provides:

• 🔄 Bidirectional conversion between clinical units
• 📊 Reference ranges based on international guidelines (ADA, NCEP, WHO)
• 🩺 Clinical categorization (normal / prediabetes / diabetes / …)
• 👤 Sex- and context-adjusted ranges where applicable
• 🎯 A type-safe API — units and categories are per-metric enums, so you can't mix up a glucose unit with a cholesterol unit at compile time

Supported metrics

Metric	Status
Glucose (fasting / postprandial / random)	✅ v0.1.0
HbA1c (NGSP % ↔ IFCC mmol/mol)	✅ v0.1.0
Total Cholesterol, HDL, LDL, Triglycerides + LipidPanel	✅ v0.1.0
Creatinine (sex-adjusted)	✅ v0.1.0

Installation

dependencies:
  clinical_lab_values: ^0.1.0

Usage

import 'package:clinical_lab_values/clinical_lab_values.dart';

final glucose = Glucose(
  value: 7.8,
  unit: GlucoseUnit.mmolL,
  context: GlucoseContext.fasting,
);

glucose.convertTo(GlucoseUnit.mgDl); // ≈ 140.5
glucose.category;                    // GlucoseCategory.diabetes
glucose.isInNormalRange;             // false
glucose.severity;                    // Severity.moderate
glucose.referenceRange.description;  // "3.9–5.5 mmol/L (fasting)"

Context matters — the same number means something different after a meal:

Glucose(value: 7.8, unit: GlucoseUnit.mmolL,
        context: GlucoseContext.postprandial).category;
// GlucoseCategory.prediabetes

Lipid panel

final panel = LipidPanel(
  totalCholesterol: TotalCholesterol(value: 6.5, unit: CholesterolUnit.mmolL),
  hdl: Hdl(value: 1.0, unit: CholesterolUnit.mmolL),
  ldl: Ldl(value: 4.5, unit: CholesterolUnit.mmolL),
  triglycerides: Triglycerides(value: 2.2, unit: CholesterolUnit.mmolL),
);

panel.totalCholesterolHdlRatio;              // ≈ 6.5 (exact)
panel.nonHdlCholesterol(CholesterolUnit.mmolL); // ≈ 5.5 (exact)
panel.cardiovascularRisk;                    // CardiovascularRisk.high (heuristic)

cardiovascularRisk is a coarse, lipid-only heuristic — not a validated risk score (see doc/REFERENCES.md). The ratio and non-HDL numbers are exact.

Sex-specific reference ranges

final creatinine = Creatinine(
  value: 1.3,
  unit: CreatinineUnit.mgDl,
  patient: PatientContext(sex: PatientSex.female),
);
creatinine.category; // CreatinineCategory.elevated (female upper bound 1.1)

Medical references

All reference ranges and conversion formulas are documented in doc/REFERENCES.md. Sources include the American Diabetes Association (ADA) Standards of Care, NCEP ATP III, and IFCC molar-mass conversions.

Disclaimer

This package is a developer tool, not a medical device. It must not be used as the sole basis for clinical decisions. Always consult qualified healthcare professionals.

Contributing

Contributions are welcome — new metrics especially. See doc/ADDING_NEW_METRIC.md for the step-by-step pattern every metric follows.

License

MIT — see LICENSE.