Skip to content

API Reference

A comprehensive technical reference for the public modules, classes, and options exported by console-graph.

Global Console Patches

Importing 'console-graph/register' dynamically injects helper methods into the global console namespace.

console.graph(value, options?)

Pushes a value to a named graph instance and immediately logs the updated chart. If a graph with the specified label does not exist, it is initialized on the fly.

  • Parameters:
    • value (number): The numerical value to push and log.
    • options (Object, optional): Graph instantiation configurations. See ConsoleGraph Options below. The options.label acts as the unique identifier key for caching.
  • Returns: string — The plain text representation of the printed sparkline (without ANSI/CSS color codes).

console.graphReset(label?)

Clears the sliding buffer values and resets internal counters.

  • Parameters:
    • label (string, optional): The label of the specific graph to reset. If omitted, all cached graph instances are wiped and reset.

Class: ConsoleGraph

The main class representing a single sparkline stream.

import { ConsoleGraph } from 'console-graph';

new ConsoleGraph(options?)

  • Parameters:
    • options (Object, optional): Configuration configuration.

ConsoleGraph Options

Option Type Default Description
bufferSize number 20 Maximum length of the sliding buffer window.
label string "" Title prefix to identify the graph (e.g. "CPU").
unit string "" Measurement unit suffix appended to the current value (e.g. "MB", "%").
min number auto Fixes the minimum scale value. When omitted, scales automatically dynamically.
max number auto Fixes the maximum scale value. When omitted, scales automatically dynamically.
color boolean true Enables colored output. Automatically resolves to ANSI codes in Node or CSS styling in browser.
gradient string "green" Theme preset to use: "green", "heat", "cool", "mono", "ocean", or "none".
showStats boolean false When true, appends (min:<val> max:<val> avg:<val>) metrics to the logged line.
showBounds boolean false When true, appends [min..max] bounds representing current auto-scale coordinates.
inline boolean false When true, uses carriage returns (\r) to overwrite the console line. (Node TTY only).
brackets string "[]" Two-character string surrounding the sparkline block (e.g., "[]", "<>", "❮❯").
format Function internal Custom value formatting callback: (value: number) => string. Overrides unit.

Methods

.log(value)

Appends a numerical value to the sliding buffer, renders the graph, outputs it to the console, and returns the plain representation.

  • Parameters:
    • value (number | null): The numerical value to add.
  • Returns: string — The plain text representation of the printed sparkline.

.push(value)

Appends a value to the sliding buffer silently without triggering a console log.

  • Parameters:
    • value (number | null): The numerical value to add.
  • Returns: void

.print()

Renders and logs the current buffer state to the console.

  • Returns: string — The plain text representation of the printed sparkline.

.toString()

Formats and returns the plain text representation of the current buffer state without triggering console output.

  • Returns: string — The plain text representation.

.reset()

Wipes the sliding buffer clean and resets call counters.

  • Returns: void

.stats()

Returns calculated statistics of the active buffer.

  • Returns: Object containing:
    • min (number): Smallest value in current buffer.
    • max (number): Largest value in current buffer.
    • avg (number): Mathematical average of the current buffer.
    • current (number): The latest added value.
    • count (number): Total number of values pushed to date.

Properties

.buffer

Returns a copied array snapshot of the active sliding buffer.

  • Type: (number | null)[]

.label

Get or set the active graph label.

  • Type: string

Class: GraphDashboard

Manages multiple independent named graphs, arranging them into a consolidated real-time visual output panel.

import { GraphDashboard } from 'console-graph';

new GraphDashboard(globalOptions?)

  • Parameters:
    • globalOptions (Object, optional): Option fallbacks applied to any graph initialized inside the dashboard. Same structure as ConsoleGraph Options.

Methods

.log(name, value, options?)

Appends a value to the specified graph. If the graph does not exist, it initializes it with the merged configuration of globalOptions and local options.

  • Parameters:
    • name (string): The unique name of the metric graph.
    • value (number): The numerical value to track.
    • options (Object, optional): Overriding options for this specific metric graph.
  • Returns: void

Renders all registered metric graphs together. In Node.js CLI, it shifts the terminal cursor up to overwrite the dashboard block in place, preventing screen flicker. In Browser environments, it clears the console panel and re-renders.

  • Returns: void

.get(name)

Retrieves the underlying ConsoleGraph instance for a specific metric.

  • Parameters:
    • name (string): The metric graph identifier.
    • Returns: ConsoleGraph | undefined

.reset()

Resets the sliding buffers of all tracked graphs.

  • Returns: void

Function: sparkline(values, options?)

A convenience utility function to quickly draw a static sparkline representation from an array of numbers.

import { sparkline } from 'console-graph';
  • Parameters:
    • values (number[]): The array of historical numbers to graph.
    • options (Object, optional): Formatting options (same configurations as ConsoleGraphOptions except bufferSize is auto-set to the length of the array).
  • Returns: string — A fully rendered static sparkline string.

Helper Exports

BLOCKS

An array containing the 8 Unicode characters representing scaling height from bottom to top.

  • Type: string[]
  • Value: ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']

formatValue(value, unit?)

The internal formatter used by ConsoleGraph to format decimal metrics into human-readable compact notation (e.g. thousands to K, millions to M, billions to B).

  • Parameters:
    • value (number): The raw number.
    • unit (string, optional): Optional unit tag.
  • Returns: string (e.g. formatValue(12500, 'B') yields "12.5KB").