Update README, add examples and configure building

README.md

@@ -0,0 +1,151 @@
+# text-graph.js
+
+`text-graph.js` is a JavaScript/TypeScript library that allows you to create charts in the terminal and browser console.
+It provides functionality to generate line charts and create a dashboard with multiple charts.
+
+## Features
+
+- Create line charts
+- Drawing multiple series on one plot
+- Creating dashboards with multiple charts
+- Colors for chart elements
+- Built-in axis scale functions (i.e. log)
+- Built-in different data overflow handling functions (i.e. linear scale, clapm, etc)
+- Built-in different data compression functions (i.e. mean, max, etc)
+
+## Installation
+
+```shell
+npm install text-graph.js
+```
+
+### Run from source
+
+```shell
+# clone repo
+git clone https://github.com/DrA1ex/text-graph.js.git
+cd ./text-graph.js
+
+# install dependencies
+npm install
+
+# Run example
+npx tsx ./examples/dashboard.ts
+```
+
+## Get Started
+
+```javascript
+// Importing the Plot class
+import {Plot} from 'text-graph.js';
+
+// Creating a new instance of the Plot class with a width of 80 characters and height of 20 characters
+const plot = new Plot(80, 20);
+
+// Adding a new series to the plot and storing its ID
+const id = plot.addSeries();
+
+// Defining a function that takes a number "x" as input and calculates a mathematical expression
+const fn = (x) => Math.pow(Math.sin(x), 3) + Math.pow(Math.cos(x), 3) - 1.5 * Math.sin(x) * Math.cos(x);
+
+// Iterating over a range of values from -2 to just below 2, incrementing by 0.05 at each step
+for (let x = -2; x < 2; x += 0.05) {
+    // Adding an entry to the series with the given ID, calculated using the function "fn"
+    plot.addSeriesEntry(id, fn(x));
+}
+
+// Printing the chart output to the console
+console.log(plot.paint());
+```
+
+Source code: [link](/examples/get-started.ts)
+
+## Usage
+
+To use `text-graph.js`, follow these steps:
+
+1. Import the necessary classes and enums:
+
+```javascript
+import {
+    Plot, PlotTilePositionFlags, PlotAxisScale, PlotSeriesAggregationFn, PlotSeriesOverflow, Color
+} from 'text-graph.js';
+```
+
+2. Define the plot options:
+
+```javascript
+const plotOptions = {
+    showAxis: true,
+    title: 'Chart Title',
+    horizontalBoundary: 1,
+    verticalBoundary: 2,
+    titlePosition: PlotTilePositionFlags.top,
+    axisScale: PlotAxisScale.linear,
+    aggregation: PlotSeriesAggregationFn.mean,
+}
+```
+
+3. Create a plot instance:
+
+```javascript
+const width = 60;
+const height = 20;
+const plot = new Plot(width, height, plotOptions);
+```
+
+4. Define the series configurations:
+
+```javascript
+const plotSeriesConfig1 = {
+    color: Color.cyan,
+    overflow: PlotSeriesOverflow.logScale,
+};
+
+const plotSeriesConfig2 = {
+    color: Color.magenta,
+    overflow: PlotSeriesOverflow.clamp,
+};
+```
+
+5. Add plot series to the plot:
+
+```javascript
+const seriesId1 = plot.addSeries(plotSeriesConfig1);
+const seriesId2 = plot.addSeries(plotSeriesConfig2);
+```
+
+6. Iterate over your data and update the plot:
+
+```javascript
+const data1 = [1, 2, 3];
+for (const value of data1) {
+    plot.addSeriesEntry(seriesId1, value);
+}
+
+const data2 = [0, -1, -2];
+for (const value of data2) {
+    plot.addSeriesEntry(seriesId2, value);
+}
+
+const chartData = plot.paint();
+console.clear()
+console.log(chartData);
+```
+
+## Examples
+
+### Single Series Chart
+
+Source code: [link](/examples/single.ts)
+
+### Multi-line Series Chart 
+
+Source code: [link](/examples/multi-series.ts)
+
+### Dashboard
+
+Source code: [link](/examples/dashboard.ts)
+## License
+
+`text-graph.js` is released under the [BSD-3-Clause License](/LICENSE).

src/examples/dashboard.ts → examples/dashboard.ts

@@ -1,5 +1,5 @@
-import {Color, PlotAxisScale, PlotSeriesAggregationFn, PlotSeriesOverflow} from "../enum";
-import {MultiPlotChart} from "../multi-plot";
+import {Color, PlotAxisScale, PlotSeriesAggregationFn, PlotSeriesOverflow} from "../src/enum";
+import {MultiPlotChart} from "../src/multi-plot";
 
 const chart = new MultiPlotChart();
 
@@ -18,7 +18,7 @@ chart.addPlot({xOffset: 42, yOffset: 16, width: 60, height: 15}, {
     aggregation: PlotSeriesAggregationFn.mean
 });
 
-chart.addPlotSeries(0, {color: Color.red, overflow: PlotSeriesOverflow.skip});
+chart.addPlotSeries(0, {color: Color.red, overflow: PlotSeriesOverflow.clamp});
 chart.addPlotSeries(1, {color: Color.blue, overflow: PlotSeriesOverflow.linearScale});
 chart.addPlotSeries(2, {color: Color.yellow});
 

examples/get-started.ts

@@ -0,0 +1,20 @@
+// Importing the Plot class
+import {Plot} from "../src";
+
+// Creating a new instance of the Plot class with a width of 80 characters and height of 20 characters
+const plot = new Plot(80, 20);
+
+// Adding a new series to the plot and storing its ID
+const id = plot.addSeries();
+
+// Defining a function that takes a number "x" as input and calculates a mathematical expression
+const fn = (x: number) => Math.pow(Math.sin(x), 3) + Math.pow(Math.cos(x), 3) - 1.5 * Math.sin(x) * Math.cos(x);
+
+// Iterating over a range of values from -2 to just below 2, incrementing by 0.05 at each step
+for (let x = -2; x < 2; x += 0.05) {
+    // Adding an entry to the series with the given ID, calculated using the function "fn"
+    plot.addSeriesEntry(id, fn(x));
+}
+
+// Printing the chart output to the console
+console.log(plot.paint());

examples/multi-series.ts

@@ -0,0 +1,58 @@
+import {Color, PlotAxisScale, PlotSeriesAggregationFn, PlotSeriesOverflow, PlotTilePositionFlags} from "../src/enum";
+import {Plot} from "../src/plot";
+
+const plotOptions = {
+    showAxis: true, // Show vertical axis
+    title: "Multi-Series Demo", // Title of the chart
+    titlePosition: PlotTilePositionFlags.top, // Position of the title
+    axisScale: PlotAxisScale.linear, // Scale of the axis
+    aggregation: PlotSeriesAggregationFn.mean, // Aggregation type for data points
+};
+
+const plot = new Plot(80, 20, plotOptions);
+
+const scale = PlotSeriesOverflow.linearScale // Overflow behavior of the series
+const seriesConfig1 = {
+    color: Color.red, // Color of the first series
+    overflow: scale
+};
+
+const seriesConfig2 = {
+    color: Color.green, // Color of the second series
+    overflow: scale
+};
+
+const seriesConfig3 = {
+    color: Color.cyan, // Color of the third series
+    overflow: scale
+};
+
+const seriesId1 = plot.addSeries(seriesConfig1);
+const seriesId2 = plot.addSeries(seriesConfig2);
+const seriesId3 = plot.addSeries(seriesConfig3);
+
+const fn1 = (x: number) => Math.sin(x) * Math.exp(-0.1 * x);
+const fn2 = (x: number) => 0.8 * Math.sin(x) + 0.6 * Math.sin(2 * x) + 0.4 * Math.sin(3 * x);
+const fn3 = (x: number) => Math.sin(x) * Math.cos(2 * x) + Math.cos(x) * Math.sin(2 * x);
+
+const delay = 66;
+
+async function draw() {
+    for (let x = -2; x <= 2; x += 0.03) {
+        plot.addSeriesEntry(seriesId1, fn1(x));
+        plot.addSeriesEntry(seriesId2, fn2(x));
+        plot.addSeriesEntry(seriesId3, fn3(x));
+
+        const chartData = plot.paint();
+        console.clear();
+        console.log(chartData);
+
+        await _delay(delay);
+    }
+}
+
+// Start animated drawing
+draw();
+
+// Auxiliary function to avoid setTimeout in loop
+function _delay(d: number) { return new Promise(resolve => setTimeout(resolve, d))}

examples/single.ts

@@ -0,0 +1,37 @@
+import {Plot} from "../src/plot";
+import {Color, PlotAxisScale, PlotSeriesAggregationFn, PlotSeriesOverflow, PlotTilePositionFlags} from "../src/enum";
+
+// Define the plot options
+const plotOptions = {
+    showAxis: true,
+    horizontalBoundary: 0,
+    verticalBoundary: 1,
+    title: 'Sample Line Chart',
+    titlePosition: PlotTilePositionFlags.top,
+    axisScale: PlotAxisScale.linear,
+    aggregation: PlotSeriesAggregationFn.skip,
+};
+
+// Add a plot to the chart
+const plot = new Plot(80, 20, plotOptions);
+
+// Define the series configuration
+const seriesConfig = {
+    color: Color.yellow,
+    overflow: PlotSeriesOverflow.linearScale,
+};
+
+// Add new plot series
+const seriesId = plot.addSeries(seriesConfig);
+
+// Define function
+const fn = (x: number) => -Math.pow(x, 2) + plot.width * x;
+
+// Add data entries to the series
+for (let i = 0; i <= plot.width; i++) {
+    plot.addSeriesEntry(seriesId, fn(i));
+}
+
+// Generate and print the chart data
+const chartData = plot.paint();
+console.log(chartData);