Getting Started

GlucoseIQ 1.0 is a zero-dependency TypeScript engine for CGM & diabetes analytics — the AGP series, Time-in-Range, 25+ cited metrics, meal response, and a live trend model. Pure functions in, render-ready data out.

Install

npm install @glucoseiq/core

pnpm add @glucoseiq/core

yarn add @glucoseiq/core

bun add @glucoseiq/core

Zero runtime dependencies. Node ≥24, TypeScript-first, ESM + CJS, ~15 KB gzipped.

Your first report

import { analyzeGlucose } from '@glucoseiq/core'

const readings = [
  { value: 120, unit: 'mg/dL', timestamp: '2024-01-01T08:00:00Z' },
  { value: 135, unit: 'mg/dL', timestamp: '2024-01-01T08:05:00Z' },
  // ... your CGM data
]

const report = analyzeGlucose(readings, { timeZone: 'America/New_York' })

report.gmi                            // 6.8  — Glucose Management Indicator
report.timeInRange.inRange.percentage // 72.5 — % in 70–180 mg/dL
report.tightRange.inRange             // 58.1 — % in 70–140 mg/dL
report.risk.gri.zone                  // 'B'  — Glycemia Risk Index zone
report.episodes.summary.hypoCount     // 3    — ≥15-min hypo events
report.agpProfile.bins                // 288 time-of-day percentile bins

One normalized pass produces the whole report: summary scalars, enhanced 5-range Time-in-Range, tight range, the full risk-metric set, hypo/hyper episodes, data sufficiency, and the AGP band series.

Draw it — with zero dependencies

import { agpChartToSVG, tirBarToSVG, trendTileToSVG } from '@glucoseiq/core'

element.innerHTML = agpChartToSVG(readings, { theme: 'dark' })

Every renderer returns a self-contained SVG string — drop it into HTML, email, a PDF, a README, React Server Components, or any framework.

Choose your next step

Build a dashboard

Go from readings to a complete AGP, Time-in-Range, and live-reading dashboard in about ten minutes.

Understand the engine

Learn the contracts and processing model that keep GlucoseIQ portable, deterministic, and headless.

Connect CGM data

Normalize Dexcom, Libre, and Nightscout payloads into one vendor-neutral reading model.

Use React

Add memoized analysis hooks and ready-made AGP, TIR, and trend components to React applications.

Design your own UI

Use shared glucose zones, colors, glyphs, and CSS variables across web and native surfaces.

Browse the API

Explore every public function, contract, constant, and typed error generated from source.

Not medical advice

GlucoseIQ is for informational and educational purposes only. It does not constitute medical advice, diagnosis, or treatment.

Mixed units are safe

mg/dL and mmol/L input can be mixed freely — every function normalizes correctly, and metrics whose published formulas are calibrated for mg/dL convert first. International data never silently produces wrong numbers.