voici.js

To display data in a tabular format in the terminal, import the Table class from voici.js, instantiate it with your dataset (an array of objects), and call the .print() method.

voici.js supports various features such as text/column/row styling, highlighting, filtering, dynamic columns, column sizing, accumulation, table export, and sorting.

import { Table } from 'voici.js';

const data = [
  { firstname: 'Homer', lastname: 'Simpson', age: 39 },
  { firstname: 'Marge', lastname: 'Simpson', age: 36 },
  { firstname: 'Bart', lastname: 'Simpson', age: 10 },
  { firstname: 'Lisa', lastname: 'Simpson', age: 8 },
  { firstname: 'Maggie', lastname: 'Simpson', age: 1 }
];

const table = new Table(data);
table.print();

Install the voici.js library using npm to start using it in your Node.js projects.

npm i --save voici.js

Dynamic columns allow you to inject new data into every row based on the existing row content. This is configured via the header.dynamic property in the Config object. Each key in the dynamic object represents a new column name, and its value is a function that takes the current row and its index to compute the cell value.

When a dynamic column is defined, the Table class automatically merges these computed values into the dataset during construction.

const dataset = [{ price: 10 }, { price: 20 }];

const table = new Table(dataset, {
  header: {
    dynamic: {
      // 'tax' is the new column name
      tax: (row) => row.price * 0.2
    }
  }
});

The accumulation feature allows you to add a summary row (e.g., totals, averages) at the bottom of your table. You configure this in body.accumulation.columns. For each specified column, you provide a calculation method. The Table class will compute these values and render them in a special row at the end of the body, often styled differently.

// Example configuration for an accumulation row
const table = new Table(dataset, {
  body: {
    accumulation: {
      columns: {
        age: (values) => values.reduce((a, b) => a + b, 0) / values.length, // Average age
        price: (values) => values.reduce((a, b) => a + b, 0) // Total price
      },
      separator: '─' // Separator between body and accumulation row
    }
  }
});

The calculateAccumulation function is the primary entry point for computing a statistic from a dataset. It takes an array of data and an AccumulationFunction and returns the computed value. If the dataset is empty, it returns null.

import { calculateAccumulation, AccumulationFunction } from './accumulation';

const data = [10, 20, 30, 40];
const mean = calculateAccumulation(data, AccumulationFunction.MEAN);
const sum = calculateAccumulation(data, AccumulationFunction.SUM);
const max = calculateAccumulation(data, AccumulationFunction.MAX);

Dynamic columns allow you to generate column data on the fly based on the row data. You provide a DynamicColumnOption object where each key corresponds to a column in your TDColumns interface, and the value is a function that calculates the cell content.

The function signature is: (row: TRow, index: number) => TDColumns[keyof TDColumns].

type MyRow = { name: string; score: number };
type MyDynamic = { status: string };

const dynamicConfig: DynamicColumnOption<MyRow, MyDynamic> = {
  status: (row, index) => (row.score > 50 ? 'Pass' : 'Fail')
};

Manage table behavior and structure using the following configuration types:

• Config: The primary configuration object for table settings.
• DynamicColumn: (exported as DynamicColumnOption) Defines options for columns that may change or be generated dynamically.
• Sort: Defines sorting logic and direction for table columns.

import { Config, DynamicColumn, Sort } from 'voici.js';

const config: Config = {
  // configuration properties
};

Import stringify from voici.js to convert data structures into a string representation. This is a helper utility for data formatting.

import { stringify } from 'voici.js';

const output = stringify(data);

You can highlight entire rows based on custom logic using the highlightRow property within the body configuration. This property accepts a bgColor and a func.

The func receives the full DatasetRow and the row index. If the function returns true, the row's background color is applied.

const bodyConfig = {
  highlightRow: {
    bgColor: '#FF0000',
    func: (row, index) => row.score < 10
  }
};

You can highlight individual cells using the highlightCell property within the body configuration. This allows for granular control over styling like bold, italic, underline, textColor, and a custom func.

The func signature is: (content: unknown, row: number, col: InferAttributes<TRow, TDColumns>) => boolean.

const bodyConfig = {
  highlightCell: {
    bold: true,
    func: (content, row, col) => typeof content === 'number' && content > 100
  }
};

The Table class is the primary interface for creating and configuring terminal-based data tables. You instantiate it by providing a dataset (an array of objects or arrays) and an optional configuration object. The table automatically infers columns from the first item in the dataset and supports advanced features like dynamic columns, sorting, accumulation (totals/averages), and conditional styling.

import { Table } from './table';

const dataset = [
  { firstname: 'John', lastname: 'Doe', age: 30 },
  { firstname: 'Jane', lastname: 'Smith', age: 25 }
];

// Basic usage
const table = new Table(dataset);

// Print to console
table.print();