📈 MLTimeGraph

English · Deutsch

A TypeScript library for visualizing measurement data — turn time series into clear, readable charts quickly, with a focus on reporting and incident analysis.

Fully typed · i18n-aware · DOM-free SVG output (browser & server) · zero runtime dependencies · ESM-only

Install

npm install ml-time-graph     # or: pnpm add / yarn add

Requires Node 18+. The library is ESM-only — works out of the box in any modern bundler (Vite, Rollup, esbuild, Webpack 5+, Next.js, Astro, …) and in Node ESM ("type": "module" in your package.json, or .mjs files).

Four subpath imports:

| Import | Purpose | | --- | --- | | ml-time-graph | User API — mount, MLTimeGraph, SVGRenderer, attachTooltip, all input + style types | | ml-time-graph/analyze | Aggregation + statistics (aggregateBySlot, rollingMkt, rollingStdDev, downsample, …) | | ml-time-graph/interaction | Optional widgets (Zoom, Minimap, Tooltip) | | ml-time-graph/internals | Building blocks for custom renderers (free render-functions, scales, axis classes, DrawCommand model, …) |

Plain HTML / CDN

No build step? Pull it straight from an ESM CDN that proxies npm:

<div id="chart"></div>
<script type="module">
  import { mount } from 'https://esm.sh/ml-time-graph@1';
  // or: 'https://cdn.jsdelivr.net/npm/ml-time-graph@1/+esm'

  mount('#chart', {
    series: [{ name: 'Temp', data: [/* … */] }],
  });
</script>

Pin a major version (@1) to avoid surprise breaking changes.

Quickstart

import { mount } from 'ml-time-graph';

mount('#chart', {
  series: [{
    name: 'Temperature',
    style: { line: { color: '#ef4444' } },
    data: [
      { time: Date.UTC(2026, 0, 1, 0), value: 18.2 },
      { time: Date.UTC(2026, 0, 1, 1), value: 19.1 },
    ],
  }],
  tooltip: { show: true },   // optional hover tooltip with visual picks
});

📖 Usage & API → USAGE.md

Gallery

A typical sensor visualisation (left), multi-zone hatched fills for incident-style reports (center), and a sensor stream with statistic overlays (right: ±2σ band + 12 h MKT) — all rendered with the same library, all live in the demo gallery (pnpm dev).

🔄 Go Port & 1:1 Rendering Parity

Need server-side rendering of the exact same charts? There is a 1:1 Go port of this engine available at gitlab.com/mlc0911/mlctimegraph/go-time-graph.

Both the TypeScript and Go libraries:

• Process the exact same JSON configuration schema.
• Generate identical SVG structures and layout calculations.
• Support multiple Y-axes on both left and right sides (each additional axis is automatically offset horizontally by 50px to prevent overlaps).
• Are continuously tested for rendering parity using shared test fixtures.

Why another chart library?

Every charting library I relied on professionally eventually switched its license from free to paid — a real problem when you can't follow that move: you end up having to replace "old" libraries or maintain them yourself (e.g. keeping up with browser changes).

I don't need a hundred chart types.

MLTimeGraph is not meant to cover a thousand chart types. The focus is on turning measurements — time + values — into clear charts quickly, with particular attention to incident analysis: e.g. when sensors monitor equipment and the after-the-fact evaluation is what matters.

Goals

• ✅ No browser dependency — rendering is decoupled from the DOM (SVG string, in the browser and server-side)
• ✅ Fully typed — TypeScript throughout
• ✅ Easy integration into existing projects
• ✅ i18n-aware — localized time axes and formatting
• ✅ Simple yet thorough configuration — colors, line widths, styles
• ✅ Typical measurement visualizations:
  • region highlights
  • thresholds (lines, fills, zones)
  • min / max / avg displays
  • incident analysis — mark notable events and values

Non-goals

• ❌ High performance — not needed for the main use case (reporting, analysis)
• ❌ Full interactivity — zoom/pan yes, but within limits
• ❌ GPU performance optimizations and the like

Outlook / under consideration

• "Live" rendering options
• Simple backend integration (where does my data come from?)
• Svelte wrapper

Demos & development

pnpm install
pnpm dev          # start the demo gallery (Vite)

| Script | Purpose | | --- | --- | | pnpm dev | run the demo gallery locally | | pnpm test | test suite (Vitest) | | pnpm typecheck | type-check the library | | pnpm typecheck:demos | type-check the demos | | pnpm build | build the library (ESM bundle + types) |

License

© 2026 Michael Lechner — MIT with an Attribution clause (see LICENSE).

Use, modification and distribution — including in commercial and closed-source products — are free of charge, provided the author "Michael Lechner" is visibly credited (e.g. in documentation, a legal-notices page, or an About/credits screen) and the copyright notice is retained in the source.

Without attribution: organizations that prefer not to display the attribution can obtain a commercial license on request that waives it — contact: ‹[email protected]›.

Originally a test of Crush development with Ollama + a new LLM — passed 😉, but it did need some rework.