Getting Started

Install @glucoseiq/core to analyze CGM readings in TypeScript. It returns typed metrics and chart-ready series without runtime dependencies.

Install

npm install @glucoseiq/core

Zero runtime dependencies in @glucoseiq/core. Node ≥24, TypeScript-first, ESM + CJS.

Your first report

import { analyzeGlucose, type GlucoseReading } from '@glucoseiq/core'

const readings: GlucoseReading[] = [
  { 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' })

if (!report.valid || !report.timeInRange || !report.tightRange ||
    !report.risk || !report.episodes || !report.agpProfile) {
  throw new Error('The input did not contain enough valid CGM data')
}

report.gmi                            // 6.4: Glucose Management Indicator
report.timeInRange.inRange.percentage // 100: % in 70–180 mg/dL
report.tightRange.inRange             // 100: % in 70–140 mg/dL
report.risk.gri.zone                  // 'A': Glycemia Risk Index zone
report.episodes.summary.hypoCount     // 0: ≥15-min hypo events
report.agpProfile.bins                // 288 time-of-day percentile bins

One normalized pass produces an analytics summary: scalar statistics, enhanced 5-range Time-in-Range, tight range, a selected risk-metric block, hypo/hyper episodes, data sufficiency, and an AGP-style percentile-band series.

Render an SVG without a DOM

import {
  agpChartToSVG,
  type GlucoseReading,
} from '@glucoseiq/core'

const readings: GlucoseReading[] = [
  { value: 120, unit: 'mg/dL', timestamp: '2024-01-01T08:00:00Z' },
  { value: 135, unit: 'mg/dL', timestamp: '2024-01-01T08:05:00Z' },
]
const element = document.createElement('div')

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

Every renderer returns a self-contained SVG string. Browser applications can embed trusted output as markup; email, PDF, README, native, and other hosts need host-specific embedding, conversion, or application integration.

Choose your next step

Build a dashboard

Build a React dashboard from normalized readings.

Understand the engine

Follow data from ingestion through analysis to rendering.

Connect CGM data

Normalize Dexcom, Libre, or Nightscout payloads.

Use React

Add analysis hooks and SVG components to a React application.

Design your own UI

Use shared glucose zones and presentation tokens.

Browse the API

Find the public exports for each package.

Not medical advice

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

Know which unit contract you are using

Mixed-unit-aware APIs inspect the unit on every GlucoseReading and normalize a mixed mg/dL and mmol/L series. Legacy calculateTIR instead requires all readings and target bounds in one homogeneous unit. Numeric-array APIs require one homogeneous unit and the matching positional argument or option where the signature provides one.