asciichart: terminal line charts from a single JavaScript function

plot() takes an array and returns a string: no canvas, no DOM, no side effects

asciichart's design is minimal. You give the plot() function a JavaScript array of numbers, and it returns a string containing the ASCII representation of a line chart. That string goes wherever strings go: console.log() in Node.js, a pre element's textContent in a browser, or stdout in a terminal process. No canvas, no DOM manipulation, no event system and no rendering context is involved.

This matters for environments where a canvas is absent or irrelevant. A Node.js background job reporting progress to its own logs, a command-line tool outputting diagnostics alongside its other text, or a browser page using a fixed-width font in a pre element can all accept a string directly without installing a charting library that depends on graphics rendering.

All JavaScript code lives in a single file, asciichart.js, at the repository root. No runtime dependencies exist, which the README and package.json both confirm. Mocha, nyc, eslint and a few other utilities appear in devDependencies in package.json for testing and documentation purposes, but none of them ship to npm consumers.

Width is locked to data array length, and there is no width parameter

The README states that the width of the chart will always equal the length of the data series. That sentence is easy to skip, but it changes how you size the output. To produce a chart that is 80 characters wide, you need exactly 80 data points. A series with many more points than your terminal's column count will wrap and become unreadable.

Height works differently. By default, height and range are determined automatically from the values in the series. Passing `height: 6` in the config object rescales the chart to fit that many lines. The README shows a cosine series ranging from -15 to +15 given `{ height: 6 }`, with a comment saying "this rescales the graph to ±3 lines". Auto-ranging suits monitoring dashboards where the current spread of values matters more than a fixed scale.

The axis offset, controlled by the `offset` property, sets how far the y-axis sits from the left edge. The minimum value documented in the README is 2. Below that, the README gives no description of what happens, and no error message is mentioned.

npm install asciichart, one require() call and one plot() call

The npm package is named asciichart. Installing it in Node.js takes one command:

npm install asciichart

The README's first JavaScript example builds a sine wave over 120 points and plots it:

var asciichart = require ('asciichart')
var s0 = new Array (120)
for (var i = 0; i < s0.length; i++)
    s0[i] = 15 * Math.sin (i * ((Math.PI * 4) / s0.length))
console.log (asciichart.plot (s0))

Running that prints a sine wave with y-axis labels on the left. For browsers, the README gives an HTML page that includes asciichart.js as a script tag and calls the same plot() API from a script block, writing output to the console rather than the DOM.

A Python port is included in the repository under asciichartpy/ and is published on PyPI as asciichartpy. Its setup.py reads the package name and version directly from package.json, appending "py" to form the PyPI name, which means the Python and JavaScript packages share a version number with no Python-specific changelog.

The config object's four fields: offset, padding, height and a format function

plot() accepts an optional second argument, a plain object, with four documented properties. The offset field sets how many characters the y-axis label area occupies from the left, with 3 as the example value. The padding field is a string of spaces that right-aligns the axis labels; the README shows seven spaces as the default. The height field sets a fixed chart height in lines.

The format function controls how each y-axis label is rendered. It receives the numeric value and an index, and must return a string of the same length as the padding string, because the implementation slices from the right:

var config = {
    offset:  3,          // axis offset from the left (min 2)
    padding: '       ',  // padding string for label formatting (can be overridden)
    height:  10,         // any height you want

    // the label format function applies default padding
    format:  function (x, i) { return (padding + x.toFixed (2)).slice (-padding.length) }
}

The second argument `i` in the format function is documented in the code comment only as an index parameter. What it indexes, whether that is the label position or something else, is never explained in the README. Using it for anything beyond the default pattern requires reading asciichart.js.

An array of arrays draws multiple series, and colors use named constants

When you pass an array of arrays to plot(), each inner array renders as a separate line on the same chart. The README shows two series plotted together:

console.log (asciichart.plot ([ s2, s3 ]))

Color is set per series through the config object's colors property, which takes an array of color values in the same order as the series array. The README shows four constants referenced from the module: asciichart.blue, asciichart.green, asciichart.default and undefined. Passing undefined is described as equivalent to asciichart.default.

var config = {
    colors: [
        asciichart.blue,
        asciichart.green,
        asciichart.default,
        undefined,
    ]
}

Beyond blue, green and default, the README documents no other color constants. Whether a red, yellow or any other named constant exists is not stated. Finding the full list requires reading asciichart.js directly.

GitHub labels this repository Python, but asciichart.js holds the library

GitHub's file-based language detection marks the repository's primary language as Python. This happens because the Python port lives under asciichartpy/ and the repository also includes setup.py, setup.cfg, tox.ini and MANIFEST.in, along with a README.rst alongside the README.md at the root. That file count tips the detector toward Python even though the library consumers use is asciichart.js.

A close reading of setup.py reveals an unusual versioning arrangement. The Python package derives both its name and its version from package.json:

name=package['name'] + 'py',
version=package['version'],

A developer pinning asciichartpy to a specific version has no way to determine from that number alone whether any Python source files changed, since the version follows the JavaScript side.

Another detail visible only in setup.py: the classifiers list Python 2.7, 3.3, 3.4, 3.5 and 3.6 as supported versions, and they stop there. No classifiers for more recent Python appear in setup.py, even though the package installs and runs on them. The file was not updated to reflect those environments despite ongoing development on the JavaScript side.

No bar type, no scatter, and output width cannot be set independently of data length

asciichart draws line charts only. The README shows no bar type, no scatter plot, no histogram and no area variant. No extension point for custom renderers exists, so a project that later needs a different chart type must replace the library entirely.

Interactivity is out of scope by design. Since the output is a string, it cannot respond to mouse events or resize when a terminal window grows. Any use case involving hover tooltips, zoom or pan requires a different approach.

The width constraint is the most common practical problem. Nothing in the library downsamples input before plotting, and the README gives no guidance on preparing data before a plot() call. Controlling the number of points passed to plot() falls entirely to the caller, with no utility function provided for that step.

Editorial conclusion

Use asciichart when you need a quick terminal view of numeric data in a Node.js or Python script, want zero runtime dependencies, and a line chart fits your data. Skip it when you need bar, scatter or area types, when users need interactive hover or zoom, or when your series has more points than columns your terminal can display. Before committing to it, verify that your data length matches the column width you have available, because there is no width parameter to limit the output. For Python use, read setup.py to check whether the pinned version reflects Python-specific changes, since the version number follows JavaScript releases.

Frequently asked questions

Official sources

1. Issues
2. kroitor/asciichart on GitHub
3. License: MIT
4. README