📊 console-graph

The Sparkline Logger

A tiny, zero-dependency sparkline logger that turns your console into a real-time dashboard.
Track numerical values over time with beautiful ASCII sparklines.

---

The Problem

You're tracking a numerical value (like memory usage, CPU load, or sensor readings) over time and want to see the trend, not just a list of numbers.

The Solution

Memory: [▁▂▃▅▆▇█▇▆▅▃▂▁▂▃▅▇█▆▄] 45MB
CPU:    [▃▅▇█▇▅▃▁▃▅▇█▇▅▃▁▃▅▇█] 72%

console-graph gives you console.graph(value) — a sparkline logger that maintains a rolling buffer and prints a tiny ASCII sparkline with every call. Turn the console into a real-time dashboard for streaming data, no heavy GUI needed.

✨ Features

• Zero Config — Works out of the box with sensible defaults
• Zero Dependencies — Tiny footprint, lightning-fast
• Browser + Node — Works in Chrome DevTools AND the terminal
• Color Gradients — 5 built-in ANSI/CSS color themes
• Auto-scaling — Adapts to your data range automatically
• TypeScript — Full type definitions included
• ESM + CJS — Dual module support

📦 Installation

npm install console-graph

🚀 Quick Start

Method 1: console.graph() (Zero Config)

The easiest way — just import the register module and go:

import 'console-graph/register';

// That's it! Now use console.graph() anywhere:
console.graph(45, { label: 'Memory', unit: 'MB' });
console.graph(48, { label: 'Memory', unit: 'MB' });
console.graph(52, { label: 'Memory', unit: 'MB' });
// → Memory: [▁▃▅] 52MB

// CommonJS
require('console-graph/register');
console.graph(72, { label: 'CPU', unit: '%' });

Method 2: ConsoleGraph Class (Full Control)

import { ConsoleGraph } from 'console-graph';

const mem = new ConsoleGraph({
  label: 'Memory',
  unit: 'MB',
  bufferSize: 20,
  gradient: 'heat',
});

// In your monitoring loop:
setInterval(() => {
  const usage = process.memoryUsage().heapUsed / 1024 / 1024;
  mem.log(usage);
}, 1000);

Method 3: One-shot Sparkline

import { sparkline } from 'console-graph';

const data = [3, 7, 2, 8, 5, 9, 1, 6, 4, 8];
console.log(sparkline(data, { label: 'Trend' }));
// → Trend: [▂▆▁▇▄█▁▅▃▇] 8

⚙️ API Reference

new ConsoleGraph(options?)

Option	Type	Default	Description
bufferSize	number	20	Max number of data points in the rolling window
label	string	''	Label prefix (e.g. 'Memory', 'CPU')
unit	string	''	Unit suffix (e.g. 'MB', '%', 'ms')
min	number	auto	Fixed minimum value (auto-scales if omitted)
max	number	auto	Fixed maximum value (auto-scales if omitted)
color	boolean	true	Enable ANSI (Node) or CSS (browser) colors
gradient	string	'green'	Color theme: 'green' 'heat' 'cool' 'mono' 'ocean' 'none'
showStats	boolean	false	Append min/max/avg statistics
showBounds	boolean	false	Show the current scale range
inline	boolean	false	Overwrite the same line (Node TTY only)
brackets	string	'[]'	Bracket characters around sparkline
format	function	built-in	Custom value formatter (value) => string

Methods

Method	Returns	Description
.log(value)	string	Push value, print sparkline, return plain text
.push(value)	void	Push value without printing (silent)
.print()	string	Print current state without pushing
.toString()	string	Get plain sparkline string (no printing)
.reset()	void	Clear the buffer
.stats()	object	Get { min, max, avg, current, count }
.buffer	number[]	Snapshot of the current buffer

sparkline(values, options?)

Generate a sparkline string from an array of numbers. Same options as ConsoleGraph.

sparkline([1, 5, 3, 8, 2, 7]); // → [▁▅▃█▁▆] 7

GraphDashboard

Manage multiple named graphs for dashboard-style output:

import { GraphDashboard } from 'console-graph';

const dash = new GraphDashboard({ bufferSize: 30 });

setInterval(() => {
  dash.log('CPU', getCpuUsage(), { unit: '%', gradient: 'heat' });
  dash.log('Memory', getMemUsage(), { unit: 'MB', gradient: 'green' });
  dash.log('Latency', getLatency(), { unit: 'ms', gradient: 'ocean' });
  dash.print(); // renders all graphs
}, 500);

🎨 Color Gradients

Gradient	Look	Best for
green	🟢🟢🟡🟡🔴🔴	General metrics (low=good, high=bad)
heat	🔵🟢🟡🟠🔴	Temperature / intensity scales
cool	🔵🔵🩵🩵⚪⚪	Calm, informational data
mono	⚫⚫⚪⚪⚪⚪	Minimal, no-distraction style
ocean	🔵🩵🟢🟡	Layered / wave-like data
none	—	No color, plain Unicode only

🌐 Browser Support

Works natively in Chrome DevTools, Firefox, Safari, and Edge consoles with CSS-based color styling:

<script type="module">
  import 'https://cdn.jsdelivr.net/npm/console-graph/dist/register.mjs';

  // Now open DevTools and check the console:
  setInterval(() => {
    console.graph(Math.random() * 100, {
      label: 'Random',
      unit: '%',
      gradient: 'ocean'
    });
  }, 500);
</script>

💡 Real-World Use Cases

Memory Monitoring

const mem = new ConsoleGraph({ label: 'Heap', unit: 'MB', gradient: 'green' });
setInterval(() => {
  mem.log(process.memoryUsage().heapUsed / 1e6);
}, 1000);

API Response Times

import 'console-graph/register';

async function fetchData(url) {
  const start = Date.now();
  const res = await fetch(url);
  console.graph(Date.now() - start, { label: 'API', unit: 'ms', gradient: 'heat' });
  return res;
}

Sensor Data Logging

const temp = new ConsoleGraph({
  label: 'Temp',
  unit: '°C',
  min: -20,
  max: 50,
  gradient: 'heat',
  showStats: true,
});

sensor.on('reading', (value) => temp.log(value));

Build/CI Performance

const buildTime = new ConsoleGraph({
  label: 'Build',
  unit: 's',
  gradient: 'green',
  bufferSize: 30,
  showBounds: true,
});

// After each build step:
buildTime.log(elapsed);

📄 License

MIT © 2026