simple-ascii-chart-cli 2.2.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +108 -23
  2. package/dist/cli.js +621 -63
  3. package/dist/index.d.ts +2 -0
  4. package/dist/index.js +23 -0
  5. package/dist/options.d.ts +28 -0
  6. package/dist/options.js +59 -0
  7. package/dist/validators.d.ts +2 -2
  8. package/dist/validators.js +164 -84
  9. package/package.json +5 -4
  10. package/dist/tests/cli.test.d.ts +0 -1
  11. package/dist/tests/cli.test.js +0 -39
  12. package/dist/tests/validators.test.d.ts +0 -1
  13. package/dist/tests/validators.test.js +0 -105
package/README.md CHANGED
@@ -33,7 +33,7 @@ npm install -g simple-ascii-chart-cli
33
33
  Or add it as a project dependency:
34
34
 
35
35
  ```bash
36
- yarn add simple-ascii-chart
36
+ yarn add simple-ascii-chart-cli
37
37
  ```
38
38
 
39
39
  Then use it in your project:
@@ -68,32 +68,111 @@ https://simple-ascii-chart.vercel.app/api?input=[[1,2],[2,3],[3,4]]&settings={"w
68
68
  Run the CLI by passing your data and desired options:
69
69
 
70
70
  ```bash
71
- simple-ascii-chart-cli --input '[[1, 2], [2, 3], [3, 4]]' --title "Sample Chart"
71
+ simple-ascii-chart --input '[[1, 2], [2, 3], [3, 4]]' --title "Sample Chart"
72
72
  ```
73
73
 
74
+ Compatibility alias: `simple-ascii-chart-cli` is also available.
75
+
74
76
  ### CLI Options
75
77
 
76
- | Option | Alias | Type | Description |
77
- |-----------------|-------|----------|-------------------------------------------------------------------------------------------------|
78
- | `--input` | `-i` | string | The data to be plotted (in JSON format). Required. |
79
- | `--options` | `-o` | string | Additional plot settings (in JSON format). |
80
- | `--width` | `-w` | number | Width of the plot. |
81
- | `--height` | `-h` | number | Height of the plot. |
82
- | `--title` | `-t` | string | Title for the plot. |
83
- | `--xLabel` | | string | Label for the x-axis. |
84
- | `--yLabel` | | string | Label for the y-axis. |
85
- | `--color` | `-c` | array | Colors for plot elements, specified as ANSI color names. |
86
- | `--axisCenter` | | array | Coordinates for axis center alignment. |
87
- | `--yRange` | | array | Y-axis range in the format `[min, max]`. |
88
- | `--showTickLabel`| | boolean | Show tick labels on the axis if set to true. |
89
- | `--thresholds` | | array | Array of threshold points or lines with optional color. |
90
- | `--legend` | | string | Legend settings (position and series labels) in JSON format. |
91
- | `--formatter` | | string | Custom formatter function for axis values, as a JavaScript function string. |
92
- | `--lineFormatter`| | string | Function to customize line appearance, as a JavaScript function string. |
93
- | `--symbols` | | string | Custom symbols for axis, chart, and background elements, in JSON format. |
94
- | `--fillArea` | | boolean | Fills the plot area if set to true. |
95
- | `--hideXAxis` | | boolean | Hides the x-axis if set to true. |
96
- | `--hideYAxis` | | boolean | Hides the y-axis if set to true. |
78
+ | Option | Alias | Type | Description |
79
+ |-------------------|-------|----------|-------------------------------------------------------------------------------------------------------|
80
+ | `--input` | `-i` | string | Inline input payload (JSON by default). |
81
+ | `--input-file` | | string | Read static input from a file path. |
82
+ | `--format` | | string | Static input format: `json`, `csv`, `tsv`, `space`. Auto-detected when omitted. |
83
+ | `--delimiter` | | string | Custom delimiter for delimited static input. |
84
+ | `--header` | | boolean | Treat first delimited row as a header row. |
85
+ | `--x-col` | | string | X selector for delimited input (1-based index or header name). |
86
+ | `--y-col` | | string | Y selector for delimited input (1-based index or header name). |
87
+ | `--stream` | | boolean | Enable streaming mode and read newline-delimited samples from stdin. |
88
+ | `--window` | | number | Keep only the latest N stream samples. Default: `60`. |
89
+ | `--refresh-ms` | | number | Redraw throttle in milliseconds. Default: `200`. |
90
+ | `--rate` | | boolean | Treat streamed values as counters and plot per-second rates. |
91
+ | `--series` | | number | Stream series count (`1` or `2`). |
92
+ | `--passthrough` | | boolean | Forward streamed stdin lines to stdout while plotting. |
93
+ | `--plot-output` | | string | Plot destination stream: `stdout` or `stderr`. |
94
+ | `--options` | `-o` | string | Additional plot settings as JSON. |
95
+ | `--width` | `-w` | number | Plot width. |
96
+ | `--height` | `-h` | number | Plot height. |
97
+ | `--title` | `-t` | string | Plot title. |
98
+ | `--xLabel` | | string | X axis label. |
99
+ | `--yLabel` | | string | Y axis label. |
100
+ | `--mode` | | string | Graph mode: `line`, `point`, `bar`, `horizontalBar`. |
101
+ | `--color` | `-c` | array | ANSI colors for plot elements. |
102
+ | `--axisCenter` | | array | Axis center coordinates (`--axisCenter 0 0`). |
103
+ | `--yRange` | | array | Y range (`--yRange 0 100`). |
104
+ | `--showTickLabel` | | boolean | Show axis tick labels. |
105
+ | `--thresholds` | | array | JSON object/array string or tokenized JSON objects (`'{"y":2}'`, `'[{"y":2}]'`, `'{"y":2}' '{"x":3}'`). |
106
+ | `--points` | | array | JSON object/array string or tokenized JSON objects (`'{"x":1,"y":2}'`, `'[{"x":1,"y":2}]'`). |
107
+ | `--legend` | | string | Legend settings in JSON format. |
108
+ | `--formatter` | | string | Axis formatter function string. |
109
+ | `--lineFormatter` | | string | Line formatter function string. |
110
+ | `--symbols` | | string | Custom symbols in JSON format. |
111
+ | `--debugMode` | | boolean | Enable chart engine debug mode. |
112
+ | `--fillArea` | | boolean | Fill plot area. |
113
+ | `--hideXAxis` | | boolean | Hide the x axis. |
114
+ | `--hideYAxis` | | boolean | Hide the y axis. |
115
+ | `--verbose` | | boolean | Print stack/details for parse/runtime errors. |
116
+
117
+ Static stdin example (no `--input` needed):
118
+
119
+ ```bash
120
+ printf '1 1\n2 4\n3 9\n' | simple-ascii-chart --format space --title "stdin plot"
121
+ ```
122
+
123
+ Threshold example:
124
+
125
+ ```bash
126
+ simple-ascii-chart --input '[[1,1],[2,2],[3,3]]' --thresholds '{"y":2,"color":"ansiRed"}'
127
+ ```
128
+
129
+ Points example:
130
+
131
+ ```bash
132
+ simple-ascii-chart --input '[[1,1],[2,1],[3,1]]' --points '[{"x":2,"y":3,"color":"ansiGreen"}]'
133
+ ```
134
+
135
+ Debug mode example:
136
+
137
+ ```bash
138
+ simple-ascii-chart --input '[[1,1],[2,2],[3,3]]' --debugMode true
139
+ ```
140
+
141
+ ## Live CPU Chart
142
+
143
+ Stream CPU samples directly into the chart.
144
+
145
+ Input formats accepted by `--stream`:
146
+ - `NUMBER` (x-axis uses sample time; default labels are elapsed like `+0s`, `+1s`)
147
+ - `X,Y`
148
+
149
+ macOS one-liner (`top`-based):
150
+
151
+ ```bash
152
+ while true; do top -l 1 | awk -F'[, %]+' '/^CPU usage:/ {print $3+$6}'; sleep 1; done | simple-ascii-chart --stream --window 60 --height 10 --yRange 0 100 --title "CPU usage %"
153
+ ```
154
+
155
+ Linux one-liner (`vmstat`-based):
156
+
157
+ ```bash
158
+ vmstat 1 | awk 'NR>2 {print 100-$15}' | simple-ascii-chart --stream --window 60 --height 10 --yRange 0 100 --title "CPU usage %"
159
+ ```
160
+
161
+ ## Live Network Bandwidth Chart
162
+
163
+ Stream network bandwidth (Mbps) into the chart.
164
+
165
+ macOS one-liner (default interface, total rx+tx):
166
+
167
+ ```bash
168
+ IFACE=$(route -n get default 2>/dev/null | awk '/interface:/{print $2}'); PREV=$(netstat -ib -I "$IFACE" | awk 'NR>1 {sum+=$7+$10} END {print sum}'); while true; do sleep 1; CUR=$(netstat -ib -I "$IFACE" | awk 'NR>1 {sum+=$7+$10} END {print sum}'); awk -v c="$CUR" -v p="$PREV" 'BEGIN {printf "%.2f\n", (c-p)*8/1000000}'; PREV="$CUR"; done | simple-ascii-chart --stream --window 60 --height 10 --yRange 0 1000 --title "Network Mbps (rx+tx)"
169
+ ```
170
+
171
+ Linux one-liner (default interface, total rx+tx):
172
+
173
+ ```bash
174
+ IFACE=$(ip route | awk '/default/ {print $5; exit}'); PREV_RX=$(cat /sys/class/net/$IFACE/statistics/rx_bytes); PREV_TX=$(cat /sys/class/net/$IFACE/statistics/tx_bytes); while true; do sleep 1; CUR_RX=$(cat /sys/class/net/$IFACE/statistics/rx_bytes); CUR_TX=$(cat /sys/class/net/$IFACE/statistics/tx_bytes); awk -v cr="$CUR_RX" -v pr="$PREV_RX" -v ct="$CUR_TX" -v pt="$PREV_TX" 'BEGIN {printf "%.2f\n", ((cr-pr)+(ct-pt))*8/1000000}'; PREV_RX="$CUR_RX"; PREV_TX="$CUR_TX"; done | simple-ascii-chart --stream --window 60 --height 10 --yRange 0 1000 --title "Network Mbps (rx+tx)"
175
+ ```
97
176
 
98
177
  ## API Reference
99
178
 
@@ -198,3 +277,9 @@ plot(
198
277
  This README includes various examples with plots for titles, multi-series data, axis labels, area filling, custom symbols, and more.
199
278
 
200
279
  For any questions or additional details, see the [documentation](https://simple-ascii-chart.vercel.app/).
280
+
281
+ ## Support
282
+
283
+ If this project helps you, consider supporting my open-source work:
284
+
285
+ [Buy me a coffee](https://buymeacoffee.com/gtktsc)