pipechart 1.0.0

package/lib/detect.js

@@ -0,0 +1,177 @@
+'use strict';
+
+// JSON shape auto-detection
+// Determines the best chart type for a given dataset
+
+/**
+ * Check if a value is a finite number.
+ * @param {*} v
+ * @returns {boolean}
+ */
+function isNum(v) {
+  return typeof v === 'number' && isFinite(v);
+}
+
+/**
+ * Check if an object looks like a time-value pair.
+ * Accepts { t, v }, { time, value }, { timestamp, value }, { x, y }
+ * @param {object} obj
+ * @returns {boolean}
+ */
+function isTimeSeries(obj) {
+  if (!obj || typeof obj !== 'object') return false;
+  var hasTime = ('t' in obj) || ('time' in obj) || ('timestamp' in obj) || ('x' in obj);
+  var hasValue = ('v' in obj) || ('value' in obj) || ('y' in obj);
+  return hasTime && hasValue;
+}
+
+/**
+ * Extract the time value from a time-series object.
+ * @param {object} obj
+ * @returns {number|string}
+ */
+function extractTime(obj) {
+  if ('t' in obj) return obj.t;
+  if ('time' in obj) return obj.time;
+  if ('timestamp' in obj) return obj.timestamp;
+  if ('x' in obj) return obj.x;
+  return null;
+}
+
+/**
+ * Extract the numeric value from a time-series object.
+ * @param {object} obj
+ * @returns {number}
+ */
+function extractValue(obj) {
+  if ('v' in obj) return obj.v;
+  if ('value' in obj) return obj.value;
+  if ('y' in obj) return obj.y;
+  return null;
+}
+
+/**
+ * Find the first numeric field in an object.
+ * @param {object} obj
+ * @returns {string|null}
+ */
+function findNumericField(obj) {
+  if (!obj || typeof obj !== 'object') return null;
+  var keys = Object.keys(obj);
+  for (var i = 0; i < keys.length; i++) {
+    if (isNum(obj[keys[i]])) return keys[i];
+  }
+  return null;
+}
+
+/**
+ * Detect the shape of the input data and return a descriptor.
+ *
+ * Returns an object:
+ * {
+ *   type: 'bar' | 'line' | 'spark' | 'hist',
+ *   values: number[],          // extracted numeric values
+ *   labels: string[] | null,   // labels for bar chart
+ *   times:  any[]   | null,    // time axis for line chart
+ *   field:  string  | null     // which field was used
+ * }
+ *
+ * @param {*} data          — parsed JSON input
+ * @param {object} opts     — CLI options (type, field)
+ * @returns {object}
+ */
+function detect(data, opts) {
+  opts = opts || {};
+
+  // ── Flat array of numbers ────────────────────────────────────────────────
+  if (Array.isArray(data) && data.length > 0 && isNum(data[0])) {
+    var allNums = data.every(function(v) { return isNum(v); });
+    if (allNums) {
+      var defaultType = opts.type || (data.length > 60 ? 'hist' : 'spark');
+      return {
+        type: defaultType,
+        values: data,
+        labels: null,
+        times: null,
+        field: null
+      };
+    }
+  }
+
+  // ── Array of objects ─────────────────────────────────────────────────────
+  if (Array.isArray(data) && data.length > 0 && typeof data[0] === 'object' && data[0] !== null) {
+
+    // Time-series: { t, v } or { time, value } etc.
+    if (!opts.field && isTimeSeries(data[0])) {
+      var tsValues = [];
+      var tsTimes = [];
+      var valid = true;
+      for (var i = 0; i < data.length; i++) {
+        var tv = extractValue(data[i]);
+        if (!isNum(tv)) { valid = false; break; }
+        tsValues.push(tv);
+        tsTimes.push(extractTime(data[i]));
+      }
+      if (valid) {
+        return {
+          type: opts.type || 'line',
+          values: tsValues,
+          labels: null,
+          times: tsTimes,
+          field: null
+        };
+      }
+    }
+
+    // Array of objects with a specified or auto-detected numeric field
+    var field = opts.field || findNumericField(data[0]);
+    if (field) {
+      var objValues = [];
+      var objLabels = [];
+      for (var j = 0; j < data.length; j++) {
+        var v = data[j][field];
+        if (!isNum(v)) continue;
+        objValues.push(v);
+        // Use 'name', 'label', 'key', 'id', or index as label
+        var label = data[j].name || data[j].label || data[j].key || data[j].id || String(j);
+        objLabels.push(String(label));
+      }
+      return {
+        type: opts.type || 'bar',
+        values: objValues,
+        labels: objLabels,
+        times: null,
+        field: field
+      };
+    }
+  }
+
+  // ── Single number ────────────────────────────────────────────────────────
+  if (isNum(data)) {
+    return {
+      type: opts.type || 'spark',
+      values: [data],
+      labels: null,
+      times: null,
+      field: null
+    };
+  }
+
+  // ── Fallback: try to extract any numbers we can find ────────────────────
+  return {
+    type: opts.type || 'spark',
+    values: [],
+    labels: null,
+    times: null,
+    field: null
+  };
+}
+
+module.exports = {
+  detect: detect,
+  isNum: isNum,
+  isTimeSeries: isTimeSeries,
+  extractTime: extractTime,
+  extractValue: extractValue,
+  findNumericField: findNumericField
+};

package/lib/render/bar.js

@@ -0,0 +1,131 @@
+'use strict';
+
+// Horizontal bar chart renderer
+
+var ansi = require('../ansi');
+var scale = require('../scale');
+
+var BAR_CHAR = '\u2588'; // █
+var HALF_BAR = '\u258C'; // ▌
+
+/**
+ * Render a horizontal bar chart.
+ *
+ * @param {object} opts
+ * @param {number[]}  opts.values   — data values
+ * @param {string[]}  opts.labels   — bar labels (parallel to values)
+ * @param {number}    opts.width    — total terminal width
+ * @param {string}    [opts.color]  — ANSI color name
+ * @param {string}    [opts.title]  — chart title
+ * @returns {string}  — multi-line string ready to print
+ */
+function render(opts) {
+  var values = opts.values || [];
+  var labels = opts.labels || [];
+  var width  = opts.width  || 80;
+  var color  = opts.color  || 'cyan';
+  var title  = opts.title  || null;
+
+  if (values.length === 0) {
+    return ansi.colorize('(no data)', 'dim');
+  }
+
+  var lines = [];
+
+  // Title
+  if (title) {
+    lines.push(ansi.bold(ansi.colorize(title, color)));
+    lines.push('');
+  }
+
+  var minVal = scale.min(values);
+  var maxVal = scale.max(values);
+
+  // Determine label column width
+  var maxLabelLen = 0;
+  for (var i = 0; i < values.length; i++) {
+    var lbl = labels[i] !== undefined ? String(labels[i]) : String(i);
+    if (lbl.length > maxLabelLen) maxLabelLen = lbl.length;
+  }
+  // Cap label width at 20 chars
+  var labelWidth = Math.min(maxLabelLen, 20);
+
+  // Value suffix width: " 12345.67"
+  var maxValStr = scale.formatNum(maxVal);
+  var valWidth = maxValStr.length + 1; // +1 for space
+
+  // Available bar width
+  var barAreaWidth = width - labelWidth - valWidth - 3; // 3 = " │ "
+  if (barAreaWidth < 4) barAreaWidth = 4;
+
+  // Axis info
+  var axisMin = Math.min(0, minVal);
+  var axisMax = maxVal;
+  if (axisMax === axisMin) axisMax = axisMin + 1;
+
+  // Zero line position (for negative values)
+  var zeroPos = scale.mapToRange(0, axisMin, axisMax, barAreaWidth);
+
+  for (var j = 0; j < values.length; j++) {
+    var val = values[j];
+    var label = labels[j] !== undefined ? String(labels[j]) : String(j);
+    label = scale.truncate(label, labelWidth);
+    label = scale.padRight(label, labelWidth);
+
+    var barLen = scale.mapToRange(Math.max(val, 0), axisMin, axisMax, barAreaWidth);
+    var negLen = val < 0 ? scale.mapToRange(Math.abs(val), 0, axisMax - axisMin, barAreaWidth) : 0;
+
+    var bar;
+    if (val >= 0) {
+      // Positive bar: spaces up to zero, then bar
+      var prefix = zeroPos > 0 ? scale.padRight('', zeroPos) : '';
+      bar = prefix + ansi.colorize(repeat(BAR_CHAR, barLen), color);
+    } else {
+      // Negative bar: spaces, then bar going left, then zero marker
+      var negBar = ansi.colorize(repeat(BAR_CHAR, negLen), 'red');
+      var afterNeg = scale.padRight('', zeroPos - negLen);
+      bar = afterNeg + negBar;
+    }
+
+    // Pad bar area to full width
+    var rawBarLen = (val >= 0 ? zeroPos + barLen : zeroPos) ;
+    var padding = barAreaWidth - rawBarLen;
+    if (padding < 0) padding = 0;
+    bar = bar + scale.padRight('', padding);
+
+    var valStr = scale.padLeft(scale.formatNum(val), valWidth);
+
+    lines.push(
+      ansi.dim(label) + ' \u2502 ' + bar + ansi.dim(valStr)
+    );
+  }
+
+  // Bottom axis
+  var axisLine = scale.padRight('', labelWidth) + ' \u2514' + repeat('\u2500', barAreaWidth + 1);
+  lines.push(ansi.dim(axisLine));
+
+  // Axis labels: min and max
+  var minLabel = scale.formatNum(axisMin);
+  var maxLabel = scale.formatNum(axisMax);
+  var axisLabels = scale.padRight('', labelWidth + 2) +
+    minLabel +
+    scale.padRight('', barAreaWidth - minLabel.length - maxLabel.length) +
+    maxLabel;
+  lines.push(ansi.dim(axisLabels));
+
+  return lines.join('\n');
+}
+
+/**
+ * Repeat a character n times.
+ * @param {string} ch
+ * @param {number} n
+ * @returns {string}
+ */
+function repeat(ch, n) {
+  var s = '';
+  for (var i = 0; i < n; i++) s += ch;
+  return s;
+}
+
+module.exports = { render: render };

package/lib/render/hist.js

@@ -0,0 +1,151 @@
+'use strict';
+
+// Histogram renderer — vertical bars using █ blocks, auto-bins
+
+var ansi = require('../ansi');
+var scale = require('../scale');
+
+var FULL_BLOCK  = '\u2588'; // █
+var UPPER_HALF  = '\u2580'; // ▀  (top half block, for finer resolution)
+var LOWER_HALF  = '\u2584'; // ▄
+
+/**
+ * Render a histogram.
+ *
+ * @param {object} opts
+ * @param {number[]}  opts.values   — raw data values (will be binned)
+ * @param {number}    opts.width    — terminal width
+ * @param {string}    [opts.color]  — ANSI color name
+ * @param {string}    [opts.title]  — chart title
+ * @param {number}    [opts.height] — chart height in rows (default: 12)
+ * @param {number}    [opts.bins]   — number of bins (default: auto)
+ * @returns {string}
+ */
+function render(opts) {
+  var values = opts.values || [];
+  var width  = opts.width  || 80;
+  var color  = opts.color  || 'yellow';
+  var title  = opts.title  || null;
+  var height = opts.height || 12;
+
+  if (values.length === 0) {
+    return ansi.colorize('(no data)', 'dim');
+  }
+
+  // Y-axis label width
+  var maxCount = 0; // will be set after binning
+
+  // Auto-determine bin count: Sturges' rule, capped to available width
+  var yLabelWidth = 5; // placeholder, recalculated below
+  var plotWidth = width - yLabelWidth - 2;
+  if (plotWidth < 4) plotWidth = 4;
+
+  var binCount = opts.bins || Math.min(
+    Math.max(Math.ceil(Math.log2(values.length) + 1), 5),
+    plotWidth
+  );
+
+  var bins = scale.autoBin(values, binCount);
+
+  // Find max count for scaling
+  for (var i = 0; i < bins.length; i++) {
+    if (bins[i].count > maxCount) maxCount = bins[i].count;
+  }
+
+  // Recalculate y-axis label width based on actual max count
+  yLabelWidth = String(maxCount).length + 1;
+  plotWidth = width - yLabelWidth - 2;
+  if (plotWidth < 4) plotWidth = 4;
+
+  // Each bin gets at least 1 column; distribute evenly
+  var colsPerBin = Math.max(1, Math.floor(plotWidth / bins.length));
+  // Actual used width
+  var usedWidth = colsPerBin * bins.length;
+
+  var lines = [];
+
+  if (title) {
+    lines.push(ansi.bold(ansi.colorize(title, color)));
+    lines.push('');
+  }
+
+  // Build grid row by row (top to bottom)
+  for (var row = 0; row < height; row++) {
+    // What count value does this row represent?
+    // row 0 = top = maxCount, row height-1 = bottom = 0
+    var rowThreshold = maxCount * (1 - row / (height - 1));
+
+    // Y-axis label
+    var yLabel = '';
+    if (row === 0) {
+      yLabel = String(maxCount);
+    } else if (row === Math.floor(height / 2)) {
+      yLabel = String(Math.round(maxCount / 2));
+    } else if (row === height - 1) {
+      yLabel = '0';
+    }
+    yLabel = scale.padLeft(yLabel, yLabelWidth);
+
+    var rowStr = '';
+    for (var b = 0; b < bins.length; b++) {
+      var binHeight = (bins[b].count / maxCount) * height;
+      var filledRows = height - Math.ceil(binHeight); // rows from top that are empty
+
+      var cellChar;
+      if (row < filledRows) {
+        // Empty above the bar
+        cellChar = repeat(' ', colsPerBin);
+      } else {
+        // Filled bar cell
+        cellChar = ansi.colorize(repeat(FULL_BLOCK, colsPerBin), color);
+      }
+      rowStr += cellChar;
+    }
+
+    // Pad to usedWidth if needed
+    var rawLen = bins.length * colsPerBin;
+    if (rawLen < plotWidth) {
+      rowStr += repeat(' ', plotWidth - rawLen);
+    }
+
+    lines.push(ansi.dim(yLabel) + ' \u2502' + rowStr);
+  }
+
+  // Bottom axis
+  var axisLine = scale.padRight('', yLabelWidth) + ' \u2514' + repeat('\u2500', usedWidth);
+  lines.push(ansi.dim(axisLine));
+
+  // Bin range labels: first bin min and last bin max
+  var minVal = scale.min(values);
+  var maxVal = scale.max(values);
+  var minLabel = scale.formatNum(minVal);
+  var maxLabel = scale.formatNum(maxVal);
+  var midLabel = scale.formatNum((minVal + maxVal) / 2);
+
+  var labelLine = scale.padRight('', yLabelWidth + 2) +
+    minLabel +
+    scale.padRight('', Math.floor(usedWidth / 2) - minLabel.length - Math.floor(midLabel.length / 2)) +
+    midLabel +
+    scale.padRight('', usedWidth - Math.floor(usedWidth / 2) - Math.ceil(midLabel.length / 2) - maxLabel.length) +
+    maxLabel;
+  lines.push(ansi.dim(labelLine));
+
+  // Count label
+  lines.push(ansi.dim(scale.padRight('', yLabelWidth + 2) + 'n=' + values.length + '  bins=' + binCount));
+
+  return lines.join('\n');
+}
+
+/**
+ * Repeat a character n times.
+ * @param {string} ch
+ * @param {number} n
+ * @returns {string}
+ */
+function repeat(ch, n) {
+  var s = '';
+  for (var i = 0; i < n; i++) s += ch;
+  return s;
+}
+
+module.exports = { render: render };

package/lib/render/line.js

@@ -0,0 +1,239 @@
+'use strict';
+
+// Line chart renderer — plots points across terminal width
+// Connects adjacent points with ASCII slope characters
+
+var ansi = require('../ansi');
+var scale = require('../scale');
+
+// Characters used to draw the line
+var CHARS = {
+  dot:       '\u2022', // •  point
+  horiz:     '\u2500', // ─  flat
+  up:        '/',      //    rising
+  down:      '\\',     //    falling
+  vert:      '\u2502', // │  vertical
+  cross:     '\u253C', // ┼  axis cross
+  axisH:     '\u2500', // ─
+  axisV:     '\u2502', // │
+  corner:    '\u2514', // └
+  tickH:     '\u252C', // ┬
+  tickV:     '\u251C'  // ├
+};
+
+/**
+ * Render a line chart.
+ *
+ * @param {object} opts
+ * @param {number[]}  opts.values   — data values
+ * @param {any[]}     [opts.times]  — time labels (parallel to values)
+ * @param {number}    opts.width    — terminal width
+ * @param {string}    [opts.color]  — ANSI color name
+ * @param {string}    [opts.title]  — chart title
+ * @param {number}    [opts.height] — chart height in rows (default: 12)
+ * @returns {string}
+ */
+function render(opts) {
+  var values = opts.values || [];
+  var times  = opts.times  || null;
+  var width  = opts.width  || 80;
+  var color  = opts.color  || 'cyan';
+  var title  = opts.title  || null;
+  var height = opts.height || 12;
+
+  if (values.length === 0) {
+    return ansi.colorize('(no data)', 'dim');
+  }
+
+  var minVal = scale.min(values);
+  var maxVal = scale.max(values);
+  // Give a little padding so points don't sit on the very edge
+  var range = maxVal - minVal;
+  if (range === 0) range = 1;
+
+  // Y-axis label width
+  var yLabelWidth = Math.max(
+    scale.formatNum(minVal).length,
+    scale.formatNum(maxVal).length
+  ) + 1;
+
+  // Available plot width (after y-axis)
+  var plotWidth = width - yLabelWidth - 2; // 2 = "│ "
+  if (plotWidth < 4) plotWidth = 4;
+
+  // Downsample or map values to plotWidth columns
+  var plotValues = values;
+  if (values.length > plotWidth) {
+    plotValues = downsample(values, plotWidth);
+  }
+
+  var cols = plotValues.length;
+
+  // Build a 2D grid: grid[row][col] = char or ' '
+  var grid = [];
+  for (var r = 0; r < height; r++) {
+    var row = [];
+    for (var c = 0; c < plotWidth; c++) {
+      row.push(' ');
+    }
+    grid.push(row);
+  }
+
+  /**
+   * Map a data value to a grid row (0 = top, height-1 = bottom).
+   */
+  function valueToRow(v) {
+    var norm = scale.normalize(v, minVal - range * 0.05, maxVal + range * 0.05);
+    var row = Math.round((1 - norm) * (height - 1));
+    if (row < 0) row = 0;
+    if (row >= height) row = height - 1;
+    return row;
+  }
+
+  // Plot points and connecting lines
+  for (var i = 0; i < cols; i++) {
+    var col = Math.floor(i * plotWidth / cols);
+    if (col >= plotWidth) col = plotWidth - 1;
+
+    var row = valueToRow(plotValues[i]);
+
+    if (i === 0) {
+      grid[row][col] = CHARS.dot;
+    } else {
+      var prevCol = Math.floor((i - 1) * plotWidth / cols);
+      if (prevCol >= plotWidth) prevCol = plotWidth - 1;
+      var prevRow = valueToRow(plotValues[i - 1]);
+
+      // Draw the point
+      grid[row][col] = CHARS.dot;
+
+      // Connect with slope character
+      if (prevRow === row) {
+        // Flat — fill horizontal between prevCol+1 and col-1
+        for (var fc = prevCol + 1; fc < col; fc++) {
+          if (grid[row][fc] === ' ') grid[row][fc] = CHARS.horiz;
+        }
+      } else {
+        // Sloped — draw diagonal connector
+        var rowStep = prevRow < row ? 1 : -1;
+        var colStep = col > prevCol ? 1 : -1;
+        var dr = Math.abs(row - prevRow);
+        var dc = Math.abs(col - prevCol);
+        var ch = rowStep > 0 ? CHARS.down : CHARS.up;
+
+        if (dc === 0) {
+          // Vertical segment
+          for (var vr = prevRow + rowStep; vr !== row; vr += rowStep) {
+            if (grid[vr][col] === ' ') grid[vr][col] = CHARS.vert;
+          }
+        } else {
+          // Bresenham-like diagonal
+          var err = 0;
+          var cr = prevRow;
+          var cc = prevCol;
+          for (var step = 0; step < dc + dr; step++) {
+            err += dr;
+            if (err * 2 >= dc) {
+              cr += rowStep;
+              err -= dc;
+            } else {
+              cc += colStep;
+            }
+            if (cr !== row || cc !== col) {
+              if (cc >= 0 && cc < plotWidth && cr >= 0 && cr < height) {
+                if (grid[cr][cc] === ' ') grid[cr][cc] = ch;
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Render lines
+  var lines = [];
+
+  if (title) {
+    lines.push(ansi.bold(ansi.colorize(title, color)));
+    lines.push('');
+  }
+
+  for (var row2 = 0; row2 < height; row2++) {
+    // Y-axis label (only at top, middle, bottom)
+    var yLabel = '';
+    if (row2 === 0) {
+      yLabel = scale.formatNum(maxVal);
+    } else if (row2 === Math.floor(height / 2)) {
+      yLabel = scale.formatNum((minVal + maxVal) / 2);
+    } else if (row2 === height - 1) {
+      yLabel = scale.formatNum(minVal);
+    }
+    yLabel = scale.padLeft(yLabel, yLabelWidth);
+
+    var rowStr = '';
+    for (var col2 = 0; col2 < plotWidth; col2++) {
+      var ch2 = grid[row2][col2];
+      if (ch2 !== ' ') {
+        rowStr += ansi.colorize(ch2, color);
+      } else {
+        rowStr += ' ';
+      }
+    }
+
+    lines.push(ansi.dim(yLabel) + ' ' + CHARS.axisV + rowStr);
+  }
+
+  // X axis
+  var xAxisLine = scale.padRight('', yLabelWidth) + ' ' + CHARS.corner + repeat(CHARS.axisH, plotWidth);
+  lines.push(ansi.dim(xAxisLine));
+
+  // X axis labels (first, middle, last time label)
+  if (times && times.length > 0) {
+    var t0 = String(times[0]);
+    var tMid = String(times[Math.floor(times.length / 2)]);
+    var tEnd = String(times[times.length - 1]);
+    var xLabels = scale.padRight('', yLabelWidth + 2) +
+      t0 +
+      scale.padRight('', Math.floor(plotWidth / 2) - t0.length - Math.floor(tMid.length / 2)) +
+      tMid +
+      scale.padRight('', plotWidth - Math.floor(plotWidth / 2) - Math.ceil(tMid.length / 2) - tEnd.length) +
+      tEnd;
+    lines.push(ansi.dim(xLabels));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Downsample an array to targetLen by averaging buckets.
+ * @param {number[]} values
+ * @param {number} targetLen
+ * @returns {number[]}
+ */
+function downsample(values, targetLen) {
+  var result = [];
+  var bucketSize = values.length / targetLen;
+  for (var i = 0; i < targetLen; i++) {
+    var start = Math.floor(i * bucketSize);
+    var end   = Math.floor((i + 1) * bucketSize);
+    if (end > values.length) end = values.length;
+    var sum = 0;
+    for (var j = start; j < end; j++) sum += values[j];
+    result.push(sum / (end - start));
+  }
+  return result;
+}
+
+/**
+ * Repeat a character n times.
+ * @param {string} ch
+ * @param {number} n
+ * @returns {string}
+ */
+function repeat(ch, n) {
+  var s = '';
+  for (var i = 0; i < n; i++) s += ch;
+  return s;
+}
+
+module.exports = { render: render };