pipechart 1.0.0

package/README.md

@@ -0,0 +1,228 @@
+# pipechart
+
+> Zero-dependency CLI tool that pipes JSON to real-time ASCII charts in the terminal.
+
+[![npm version](https://img.shields.io/npm/v/pipechart.svg)](https://www.npmjs.com/package/pipechart)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js >= 12](https://img.shields.io/badge/node-%3E%3D12-brightgreen.svg)](https://nodejs.org)
+
+---
+
+## Install
+
+```bash
+npm install -g pipechart
+```
+
+Or run without installing:
+
+```bash
+npx pipechart --help
+```
+
+---
+
+## Usage
+
+```
+echo '<json>' | pipechart [options]
+cat data.json  | pipechart [options]
+tail -f stream | pipechart --live [options]
+```
+
+### Options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--type <bar\|line\|spark\|hist>` | `-t` | Force chart type (auto-detected if omitted) |
+| `--color <name>` | `-c` | Chart color: `red`, `green`, `blue`, `yellow`, `cyan`, `white` |
+| `--width <n>` | `-w` | Override terminal width (default: `process.stdout.columns`) |
+| `--height <n>` | | Chart height in rows for line/hist (default: `12`) |
+| `--title <text>` | | Print a title above the chart |
+| `--field <key>` | `-f` | Which numeric field to use from objects |
+| `--live` | `-l` | Streaming / live mode — reads NDJSON continuously |
+| `--spark` | `-s` | Force single-line sparkline output |
+| `--help` | `-h` | Show help |
+| `--version` | `-v` | Show version |
+
+---
+
+## Examples
+
+### 1. Sparkline — flat array of numbers
+
+```bash
+echo '[3,1,4,1,5,9,2,6,5,3,5]' | pipechart
+```
+
+```
+▃▁▄▁▅█▂▅▅▃▅  1 – 9
+```
+
+### 2. Bar chart — array of objects
+
+```bash
+echo '[
+  {"name":"Alpha","value":42},
+  {"name":"Beta","value":87},
+  {"name":"Gamma","value":23},
+  {"name":"Delta","value":65}
+]' | pipechart --type bar --color green
+```
+
+```
+Alpha │ ████████████████████████████                            42
+Beta  │ ███████████████████████████████████████████████████████ 87
+Gamma │ ████████████████                                        23
+Delta │ ████████████████████████████████████████████            65
+      └────────────────────────────────────────────────────────────
+       0                                                        87
+```
+
+### 3. Line chart — time-series `{t, v}` objects
+
+```bash
+echo '[
+  {"t":1,"v":10},{"t":2,"v":25},{"t":3,"v":18},
+  {"t":4,"v":40},{"t":5,"v":35},{"t":6,"v":55},
+  {"t":7,"v":48},{"t":8,"v":70}
+]' | pipechart --type line --color cyan --title "Server Latency (ms)"
+```
+
+```
+Server Latency (ms)
+
+ 70 │                                                   //   •
+    │                                                  //
+    │                                      //         //
+    │                                    /// •\\\    //
+    │                                  ///      \\\\\•
+    │                      //         //
+ 40 │                    /// •────────•/
+    │      //          ///
+    │    /// •\\\     //
+    │  ///      \\\\\•/
+    │ //
+ 10 │•/
+    └─────────────────────────────────────────────────────────────
+     1                               5                           8
+```
+
+### 4. Histogram — distribution of values
+
+```bash
+echo '[2,5,8,3,7,1,9,4,6,2,5,8,3,7,1,9,4,6,5,5,5,6,7,8,3,2,1,4,9,6]' \
+  | pipechart --type hist --color yellow --title "Value Distribution"
+```
+
+```
+Value Distribution
+
+ 9 │                  ███████████
+   │                  ███████████
+   │                  ███████████
+   │                  ███████████
+   │███████████        ███████████           ███████████
+   │███████████        ███████████           ███████████
+ 5 │███████████        ███████████           ███████████
+   │███████████        ███████████           ███████████
+   │███████████████████████████████████████████████████████████████
+   │███████████████████████████████████████████████████████████████
+   │███████████████████████████████████████████████████████████████
+ 0 │███████████████████████████████████████████████████████████████
+   └──────────────────────────────────────────────────────────────
+    1                                5                           9
+    n=30  bins=6
+```
+
+### 5. Live streaming mode
+
+```bash
+# Pipe a stream of NDJSON numbers — re-renders in place
+tail -f /var/log/metrics.jsonl | pipechart --live --type line --color green
+
+# Simulate a live stream with a shell loop
+while true; do
+  echo $RANDOM
+  sleep 0.5
+done | pipechart --live --type spark
+```
+
+### 6. Use a specific field from objects
+
+```bash
+echo '[
+  {"host":"web-1","cpu":72.3},
+  {"host":"web-2","cpu":45.1},
+  {"host":"db-1","cpu":88.9}
+]' | pipechart --type bar --field cpu --color red
+```
+
+```
+web-1 │ ████████████████████████████████████████████████████    72.3
+web-2 │ ████████████████████████████████                        45.1
+db-1  │ ████████████████████████████████████████████████████████ 88.9
+      └────────────────────────────────────────────────────────────
+       0                                                        88.9
+```
+
+### 7. Pipe from `jq`
+
+```bash
+curl -s https://api.example.com/metrics \
+  | jq '[.data[] | .response_time]' \
+  | pipechart --type hist --color cyan --title "Response Times"
+```
+
+---
+
+## JSON Shape Auto-Detection
+
+pipechart automatically picks the best chart type based on your data:
+
+| Input shape | Default chart |
+|-------------|---------------|
+| `[1, 2, 3, ...]` — flat numbers, ≤ 60 items | **sparkline** |
+| `[1, 2, 3, ...]` — flat numbers, > 60 items | **histogram** |
+| `[{"t":…,"v":…}, …]` — time-value pairs | **line chart** |
+| `[{"name":…,"value":…}, …]` — labeled objects | **bar chart** |
+
+Override with `--type bar|line|spark|hist`.
+
+---
+
+## Why pipechart?
+
+- **Zero dependencies** — pure Node.js, nothing to audit, nothing to break.
+- **Works over SSH** — renders in any terminal that supports ANSI codes (virtually all of them).
+- **Works on legacy hardware** — Node.js 12+ is all you need; no native addons, no compilation.
+- **Composable** — plays nicely with `jq`, `curl`, `tail -f`, `watch`, and any Unix pipeline.
+- **Instant** — no startup overhead, no network calls, no config files.
+- **Readable source** — ~600 lines of plain ES5-compatible JavaScript; easy to audit and fork.
+
+---
+
+## Package Structure
+
+```
+pipechart/
+├── bin/
+│   └── pipechart.js      # CLI entrypoint (shebang)
+├── lib/
+│   ├── detect.js         # JSON shape detection
+│   ├── render/
+│   │   ├── bar.js        # Horizontal bar chart
+│   │   ├── line.js       # Line chart with ASCII connectors
+│   │   ├── spark.js      # Single-line sparkline
+│   │   └── hist.js       # Vertical histogram
+│   ├── ansi.js           # Color + cursor ANSI helpers
+│   └── scale.js          # Normalization + scaling math
+├── package.json
+└── README.md
+```
+
+---
+
+## License
+
+MIT

package/bin/pipechart.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * pipechart — zero-dependency CLI tool that pipes JSON to real-time ASCII charts
+ *
+ * Usage:
+ *   echo '[1,2,3,4,5]' | pipechart
+ *   cat data.json | pipechart --type bar --color green
+ *   tail -f metrics.jsonl | pipechart --live --type line
+ */
+
+var readline = require('readline');
+var detect   = require('../lib/detect');
+var ansi     = require('../lib/ansi');
+var bar      = require('../lib/render/bar');
+var line     = require('../lib/render/line');
+var spark    = require('../lib/render/spark');
+var hist     = require('../lib/render/hist');
+
+// ── Parse CLI arguments ──────────────────────────────────────────────────────
+
+var args = process.argv.slice(2);
+
+/**
+ * Parse a simple --flag [value] argument list.
+ * Flags without a following value are treated as booleans.
+ * @param {string[]} argv
+ * @returns {object}
+ */
+function parseArgs(argv) {
+  var opts = {};
+  var i = 0;
+  while (i < argv.length) {
+    var arg = argv[i];
+    if (arg.slice(0, 2) === '--') {
+      var key = arg.slice(2);
+      var next = argv[i + 1];
+      if (next !== undefined && next.slice(0, 2) !== '--') {
+        opts[key] = next;
+        i += 2;
+      } else {
+        opts[key] = true;
+        i += 1;
+      }
+    } else if (arg.slice(0, 1) === '-' && arg.length === 2) {
+      var shortKey = arg.slice(1);
+      var shortNext = argv[i + 1];
+      if (shortNext !== undefined && shortNext.slice(0, 1) !== '-') {
+        opts[shortKey] = shortNext;
+        i += 2;
+      } else {
+        opts[shortKey] = true;
+        i += 1;
+      }
+    } else {
+      i += 1;
+    }
+  }
+  return opts;
+}
+
+var opts = parseArgs(args);
+
+// Show help
+if (opts.help || opts.h) {
+  printHelp();
+  process.exit(0);
+}
+
+// Show version
+if (opts.version || opts.v) {
+  try {
+    var pkg = require('../package.json');
+    process.stdout.write(pkg.version + '\n');
+  } catch (e) {
+    process.stdout.write('1.0.0\n');
+  }
+  process.exit(0);
+}
+
+var LIVE_MODE  = !!(opts.live || opts.l);
+var FORCE_TYPE = opts.type || opts.t || null;
+var COLOR      = opts.color || opts.c || 'cyan';
+var WIDTH      = parseInt(opts.width || opts.w, 10) || process.stdout.columns || 80;
+var TITLE      = opts.title || null;
+var FIELD      = opts.field || opts.f || null;
+var SPARK_MODE = !!(opts.spark || opts.s);
+var HEIGHT     = parseInt(opts.height, 10) || 12;
+
+if (SPARK_MODE && !FORCE_TYPE) FORCE_TYPE = 'spark';
+
+// ── Rendering ────────────────────────────────────────────────────────────────
+
+/**
+ * Dispatch to the correct renderer based on detected/forced type.
+ * @param {object} descriptor — from detect.detect()
+ * @returns {string}
+ */
+function renderChart(descriptor) {
+  var type = descriptor.type;
+  var renderOpts = {
+    values: descriptor.values,
+    labels: descriptor.labels,
+    times:  descriptor.times,
+    width:  WIDTH,
+    color:  COLOR,
+    title:  TITLE,
+    height: HEIGHT
+  };
+
+  switch (type) {
+    case 'bar':   return bar.render(renderOpts);
+    case 'line':  return line.render(renderOpts);
+    case 'spark': return spark.render(renderOpts);
+    case 'hist':  return hist.render(renderOpts);
+    default:      return spark.render(renderOpts);
+  }
+}
+
+// ── Live streaming mode ──────────────────────────────────────────────────────
+
+if (LIVE_MODE) {
+  runLiveMode();
+} else {
+  runBatchMode();
+}
+
+// ── Batch mode: read all stdin, parse, render once ───────────────────────────
+
+function runBatchMode() {
+  var chunks = [];
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', function(chunk) {
+    chunks.push(chunk);
+  });
+
+  process.stdin.on('end', function() {
+    var raw = chunks.join('');
+    raw = raw.trim();
+
+    if (!raw) {
+      process.stderr.write('pipechart: no input received. Pipe JSON data to stdin.\n');
+      printHelp();
+      process.exit(1);
+    }
+
+    // Try to parse as a single JSON value first
+    var data;
+    try {
+      data = JSON.parse(raw);
+    } catch (e) {
+      // Try newline-delimited JSON (NDJSON) — collect all valid lines
+      var lines = raw.split('\n');
+      var collected = [];
+      for (var i = 0; i < lines.length; i++) {
+        var l = lines[i].trim();
+        if (!l) continue;
+        try {
+          var parsed = JSON.parse(l);
+          collected.push(parsed);
+        } catch (e2) {
+          // Skip malformed lines gracefully
+        }
+      }
+      if (collected.length === 0) {
+        process.stderr.write('pipechart: could not parse input as JSON.\n');
+        process.exit(1);
+      }
+      data = collected;
+    }
+
+    var descriptor = detect.detect(data, { type: FORCE_TYPE, field: FIELD });
+
+    if (descriptor.values.length === 0) {
+      process.stderr.write('pipechart: no numeric values found in input.\n');
+      process.exit(1);
+    }
+
+    var output = renderChart(descriptor);
+    process.stdout.write(output + '\n');
+  });
+
+  process.stdin.on('error', function(err) {
+    process.stderr.write('pipechart: stdin error: ' + err.message + '\n');
+    process.exit(1);
+  });
+}
+
+// ── Live mode: read NDJSON lines, re-render in place ─────────────────────────
+
+function runLiveMode() {
+  var buffer = [];
+  var lastLineCount = 0;
+  var firstRender = true;
+
+  // Hide cursor for cleaner live output
+  process.stdout.write(ansi.hideCursor());
+
+  // Restore cursor on exit
+  function cleanup() {
+    process.stdout.write(ansi.showCursor());
+    process.stdout.write('\n');
+  }
+  process.on('exit', cleanup);
+  process.on('SIGINT', function() {
+    cleanup();
+    process.exit(0);
+  });
+  process.on('SIGTERM', function() {
+    cleanup();
+    process.exit(0);
+  });
+
+  var rl = readline.createInterface({
+    input: process.stdin,
+    crlfDelay: Infinity
+  });
+
+  rl.on('line', function(rawLine) {
+    rawLine = rawLine.trim();
+    if (!rawLine) return;
+
+    var parsed;
+    try {
+      parsed = JSON.parse(rawLine);
+    } catch (e) {
+      // Skip malformed lines — don't crash
+      return;
+    }
+
+    // Accumulate data points
+    // If the line is an array, replace the buffer (useful for watch-style streams)
+    // If it's a scalar/object, push it
+    if (Array.isArray(parsed)) {
+      buffer = parsed;
+    } else {
+      buffer.push(parsed);
+    }
+
+    // Keep buffer bounded to avoid unbounded memory growth
+    var maxBuffer = WIDTH * 4;
+    if (buffer.length > maxBuffer) {
+      buffer = buffer.slice(buffer.length - maxBuffer);
+    }
+
+    var descriptor = detect.detect(buffer, { type: FORCE_TYPE, field: FIELD });
+    if (descriptor.values.length === 0) return;
+
+    var output = renderChart(descriptor);
+    var outputLines = output.split('\n');
+    var lineCount = outputLines.length;
+
+    if (!firstRender) {
+      // Move cursor up to overwrite previous render
+      process.stdout.write(ansi.cursorUp(lastLineCount));
+    }
+
+    // Clear and rewrite each line
+    for (var i = 0; i < lineCount; i++) {
+      process.stdout.write(ansi.eraseLine() + outputLines[i] + '\n');
+    }
+
+    // If new render is shorter, clear leftover lines
+    if (!firstRender && lineCount < lastLineCount) {
+      for (var j = lineCount; j < lastLineCount; j++) {
+        process.stdout.write(ansi.eraseLine() + '\n');
+      }
+      process.stdout.write(ansi.cursorUp(lastLineCount - lineCount));
+    }
+
+    lastLineCount = lineCount;
+    firstRender = false;
+  });
+
+  rl.on('close', function() {
+    // stdin closed — stay alive showing last render
+  });
+
+  rl.on('error', function(err) {
+    process.stderr.write('pipechart: readline error: ' + err.message + '\n');
+  });
+}
+
+// ── Help text ─────────────────────────────────────────────────────────────────
+
+function printHelp() {
+  var help = [
+    '',
+    ansi.bold(ansi.colorize('pipechart', 'cyan')) + ansi.dim(' — zero-dependency JSON → ASCII charts'),
+    '',
+    ansi.bold('USAGE'),
+    '  echo \'[1,2,3,4,5]\' | pipechart [options]',
+    '  cat data.json     | pipechart --type bar --color green',
+    '  tail -f log.jsonl | pipechart --live --type line',
+    '',
+    ansi.bold('OPTIONS'),
+    '  --type,   -t  <bar|line|spark|hist>   Force chart type',
+    '  --color,  -c  <color>                 Chart color (red|green|blue|yellow|cyan|white)',
+    '  --width,  -w  <n>                     Override terminal width',
+    '  --height      <n>                     Chart height in rows (default: 12)',
+    '  --title       <text>                  Print a title above the chart',
+    '  --field,  -f  <key>                   Which field to use from objects',
+    '  --live,   -l                          Streaming / live mode (NDJSON)',
+    '  --spark,  -s                          Force single-line sparkline output',
+    '  --help,   -h                          Show this help',
+    '  --version,-v                          Show version',
+    '',
+    ansi.bold('EXAMPLES'),
+    '  echo \'[3,1,4,1,5,9,2,6]\' | pipechart',
+    '  echo \'[3,1,4,1,5,9,2,6]\' | pipechart --type hist --color yellow',
+    '  echo \'[{"name":"A","val":10},{"name":"B","val":20}]\' | pipechart --type bar --field val',
+    '  echo \'[{"t":1,"v":3},{"t":2,"v":7}]\' | pipechart --type line',
+    '  tail -f metrics.jsonl | pipechart --live --type spark',
+    ''
+  ].join('\n');
+  process.stdout.write(help);
+}

package/lib/ansi.js

@@ -0,0 +1,131 @@
+'use strict';
+
+// ANSI escape code helpers — color, cursor movement, screen control
+
+var COLORS = {
+  red:     '\x1b[31m',
+  green:   '\x1b[32m',
+  yellow:  '\x1b[33m',
+  blue:    '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan:    '\x1b[36m',
+  white:   '\x1b[37m',
+  bright_red:     '\x1b[91m',
+  bright_green:   '\x1b[92m',
+  bright_yellow:  '\x1b[93m',
+  bright_blue:    '\x1b[94m',
+  bright_cyan:    '\x1b[96m',
+  bright_white:   '\x1b[97m',
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m'
+};
+
+/**
+ * Wrap text in an ANSI color code.
+ * @param {string} text
+ * @param {string} colorName  — key from COLORS, or null/undefined for no color
+ * @returns {string}
+ */
+function colorize(text, colorName) {
+  if (!colorName || !COLORS[colorName]) return text;
+  return COLORS[colorName] + text + COLORS.reset;
+}
+
+/**
+ * Bold text.
+ * @param {string} text
+ * @returns {string}
+ */
+function bold(text) {
+  return COLORS.bold + text + COLORS.reset;
+}
+
+/**
+ * Dim text.
+ * @param {string} text
+ * @returns {string}
+ */
+function dim(text) {
+  return COLORS.dim + text + COLORS.reset;
+}
+
+/**
+ * Move cursor to top-left of screen (for live re-render).
+ * @returns {string}
+ */
+function cursorHome() {
+  return '\x1b[H';
+}
+
+/**
+ * Clear the entire screen.
+ * @returns {string}
+ */
+function clearScreen() {
+  return '\x1b[2J';
+}
+
+/**
+ * Clear from cursor to end of screen.
+ * @returns {string}
+ */
+function clearToEnd() {
+  return '\x1b[J';
+}
+
+/**
+ * Hide the terminal cursor.
+ * @returns {string}
+ */
+function hideCursor() {
+  return '\x1b[?25l';
+}
+
+/**
+ * Show the terminal cursor.
+ * @returns {string}
+ */
+function showCursor() {
+  return '\x1b[?25h';
+}
+
+/**
+ * Move cursor up N lines.
+ * @param {number} n
+ * @returns {string}
+ */
+function cursorUp(n) {
+  return '\x1b[' + n + 'A';
+}
+
+/**
+ * Move cursor to beginning of line.
+ * @returns {string}
+ */
+function cursorLineStart() {
+  return '\r';
+}
+
+/**
+ * Erase current line.
+ * @returns {string}
+ */
+function eraseLine() {
+  return '\x1b[2K';
+}
+
+module.exports = {
+  COLORS: COLORS,
+  colorize: colorize,
+  bold: bold,
+  dim: dim,
+  cursorHome: cursorHome,
+  clearScreen: clearScreen,
+  clearToEnd: clearToEnd,
+  hideCursor: hideCursor,
+  showCursor: showCursor,
+  cursorUp: cursorUp,
+  cursorLineStart: cursorLineStart,
+  eraseLine: eraseLine
+};