graphein

The framework-agnostic, zero-dependency engine behind Graphein — a beautiful, high-performance, agent-first data visualization library.

One chart is one JSON object. Hand the engine a declarative, JSON-serializable ChartSpec and it renders Tableau-class visuals with a tiny hybrid Canvas2D + DOM core — scales, ticks, color, shapes, the pivot engine, and the renderer are all hand-written (no D3/charting dependencies).

Install the zero-dependency engine:

npm install graphein

import { render, type ChartSpec } from 'graphein';

const spec: ChartSpec = {
  type: 'line',
  title: 'Monthly active users',
  data: [
    { month: '2024-01', users: 4200 },
    { month: '2024-02', users: 4650 },
    { month: '2024-03', users: 5010 },
  ],
  encoding: {
    x: { field: 'month', type: 'temporal' },
    y: { field: 'users', type: 'quantitative', format: ',d' },
  },
};

const chart = render('#app', spec);
chart.update(nextSpec); // new data/config (animated)
chart.resize();         // re-measure after a layout change
chart.destroy();        // tear down

Chart types

line · area · bar · scatter · pie/donut · heatmap · kpi · table · matrix (pivot) · box (box-and-whisker) · sankey · choropleth.

Validation

import { validateSpec } from 'graphein';

const { valid, errors, warnings } = validateSpec(spec);

Validation is defensive for any JSON input: nested encodings/scales/ValueRefs are shape-checked, calculate/filter/bin constraints are reported before rendering, and repair skips unsafe or unresolvable JSON Patch operations. Type inference is shared across the engine, numbers-first, strict about calendar dates, and supports dot-path fields.

Agent drafting

import { draft } from 'graphein';

const result = draft(spec, { container: '#app', quality: true });
console.log(result.spec, result.report, result.quality?.stopReason);

Omit quality for the existing single-render default. Opting in allows at most three total whole-visual attempts, including rollback, to fill eligible presentation defaults without changing data or explicit settings. Read quality's iteration/applied/rejected history and unresolved report diagnostics. Authoring repair remains the separate repair / repairLevel policy. Without a container or headless target, quality reports evaluated:false / stopReason:'no-target'. Dashboards return dashboardInstance; charts retain instance; destroy mounted instances when finished.

Documentation

• Agent Guide
• Spec Reference
• JSON Schema
• Examples

MIT © Sachin Patney