Custom Brackets, Scaling, & Formatting

You can customize the text surrounding the sparkline chart, override the scaling mechanism, and define custom format functions for values.

---

Custom Brackets

By default, the sparkline is enclosed in standard square brackets ([]). The brackets option accepts a 2-character string that changes the boundary indicators:

import { ConsoleGraph } from 'console-graph';

// Angle brackets
const angle = new ConsoleGraph({ brackets: '<>' });
// Output: Memory: <▃▅█> 78MB

// Double angle quotes (guillemets)
const arrows = new ConsoleGraph({ brackets: '❮❯' });
// Output: Memory: ❮▃▅█❯ 78MB

// Custom symbols
const curly = new ConsoleGraph({ brackets: '{}' });
// Output: Memory: {▃▅█} 78MB

Setting brackets to "" (empty string) will render the sparkline block directly with no surrounding symbols.

---

Bounds & Scaling

By default, console-graph auto-scales. This means the minimum block character (▁) corresponds to the lowest value currently in the buffer, and the maximum block character (█) corresponds to the highest.

While auto-scaling is perfect for seeing trends in volatile data, it can be misleading for relatively static metrics, or metrics with fixed physical limits (like percentages or degrees).

Auto-Scaling (Default)

If you log values between 90 and 95, they will scale dynamically across the full height of the 8 blocks. * 90 $\rightarrow$ ▁ * 95 $\rightarrow$ █ * A change of just 5 looks like a massive swing.

Fixed Bounds

By supplying explicit min and max limits, you lock the height thresholds. This is ideal for percentages, ratings, and physical constraints.

// Lock the graph bounds to standard percentage metrics
const cpuGraph = new ConsoleGraph({
  min: 0,
  max: 100,
  unit: '%'
});

// Logs will scale absolute to 0-100:
cpuGraph.log(5);   // Output: [▁] 5%
cpuGraph.log(50);  // Output: [▁▄] 50%
cpuGraph.log(98);  // Output: [▁▄█] 98%

---

Custom Formatters

By default, values are formatted using an internal compact notation helper (formatValue). It handles trailing decimal points and truncates large values into compact forms (e.g. 12.5K, 4.8M, 1.2B).

If you want custom layouts or need to display currency, times, or custom status strings, provide a custom format function:

const moneyGraph = new ConsoleGraph({
  label: 'Earnings',
  format: (value) => {
    if (value === null || value === undefined) return 'N/A';
    return `$${value.toFixed(2)}`;
  }
});

moneyGraph.log(120.456);
// Output: Earnings: [█] $120.46

Complex Formatter Example: Time Formatting

For durations, you can write formatters that dynamically change time units based on the value's size:

const durationGraph = new ConsoleGraph({
  label: 'Response Time',
  format: (ms) => {
    if (ms === null || ms === undefined) return '—';
    if (ms < 1000) return `${ms.toFixed(0)}ms`;
    const sec = ms / 1000;
    if (sec < 60) return `${sec.toFixed(1)}s`;
    return `${Math.floor(sec / 60)}m ${Math.floor(sec % 60)}s`;
  }
});