table-layout

What is table-layout?

The table-layout package is a utility for Node.js that allows for the easy formatting of text into a table structure. It provides a way to organize data in rows and columns, with options for customizing alignment, width, and padding. This package is useful for CLI tools and scripts that need to present data in a structured, readable format.

What are table-layout's main functionalities?

Basic table layout

This feature allows you to create a basic table layout by specifying an array of objects, where each object represents a row in the table. The keys of the object represent column names.

const Table = require('table-layout');
const data = [{ colA: 'row 1 column A', colB: 'row 1 column B' }, { colA: 'row 2 column A', colB: 'row 2 column B' }];
const table = new Table(data);
console.log(table.toString());

Custom column width and wrapping

This feature demonstrates how to customize the width of columns and enable text wrapping. It is useful for controlling the appearance of the table and ensuring that it fits within a specific layout.

const Table = require('table-layout');
const data = [{ name: 'Some really long name that exceeds the default column width', age: '30' }];
const options = { columns: [{ name: 'name', width: 30, nowrap: true }, { name: 'age', width: 10 }] };
const table = new Table(data, options);
console.log(table.toString());

Other packages similar to table-layout

cli-table

cli-table is a similar package that provides functionalities for rendering unicode-aided tables on the command line. Compared to table-layout, cli-table focuses more on the visual styling of the table borders and padding but does not offer as much control over text wrapping and column width.

ascii-table

ascii-table is another package for creating ASCII tables. It allows for quick and easy table generation with minimal configuration. While it's simpler and less feature-rich than table-layout, it's suitable for applications that require basic table functionalities without the need for advanced formatting options.

README

table-layout

Styleable plain-text table generator. Useful for formatting console output. Available as both a command-line tool and isomorphic Javascript library.

Install as a library

Add table-layout to your project:

$ npm install --save table-layout

Display an array of objects as a table

Trivial example. Read a JSON file from disk and output a table with a maximum width (in characters) of 60.

import Table from 'table-layout'
import { promises as fs } from 'fs'

const issues = await fs.readFile('./issues.json', 'utf8')
const table = new Table(JSON.parse(issues), { maxWidth: 60 })

console.log(table.toString())

This is the example input file:

[
  {
    "number": 15134,
    "title": "Coveralls has no source available ",
    "login": "ndelangen",
    "comments": 0
  },
  {
    "number": 15133,
    "title": "Fixing --preserve-symlinks. Enhancing node to exploit.",
    "login": "phestermcs",
    "comments": 0
  },
  {
    "number": 15131,
    "title": "Question - Confused about NPM's local installation philosophy",
    "login": "the1mills",
    "comments": 0
  },
  {
    "number": 15130,
    "title": "Question - global npm cache directory if user is root?",
    "login": "ORESoftware",
    "comments": 0
  }
]

This is the output:

 15134  Coveralls has no source available   ndelangen     0
 15133  Fixing --preserve-symlinks.         phestermcs    0
        Enhancing node to exploit.
 15131  Question - Confused about NPM's     the1mills     0
        local installation philosophy
 15130  Question - global npm cache         ORESoftware   0
        directory if user is root?
 15127  how to installa gulp fontfacegen    aramgreat     0
        on Windows 10
 15097  Cannot install package from         mastertinner  3
        tarball out of package.json entry
        generated by npm
 15067  npm "SELF_SIGNED_CERT_IN_CHAIN"     LegendsLyfe   3
        error when installing discord.js
        with .log

Cherry-picked and computed values

Sometimes, your input data might contain a deeper structure or you want to transform or compute some values. Some example input data with structural depth and large numbers you'd like to reformat:

[
  {
    "country": { "name": "USA" },
    "GDP": 19485394000000,
    "population": 325084756
 },
  {
    "country": { "name": "China" },
    "GDP": 12237700479375,
    "population": 1421021791
  },
  {
    "country": { "name": "Japan" },
    "GDP": 4872415104315,
    "population": 127502725
 }
]

Example usage of the column getter function:

import Table from 'table-layout'
import { promises as fs } from 'fs'

const rows = JSON.parse(await fs.readFile('./example/deep-data/gdp.json', 'utf8'))
const germanCurrency = new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' })
const germanNumber = new Intl.NumberFormat('de-DE', { notation: 'compact', maximumSignificantDigits: 3, maximumFractionDigits: 0 })

const table = new Table(rows, {
  maxWidth: 60,
  columns: [
    {
      name: 'country',
      get: (cellValue) => cellValue.name
    },
    {
      name: 'GDP',
      get: (cellValue) => germanCurrency.format(cellValue)
    },
    {
      name: 'population',
      get: (cellValue) => germanNumber.format(cellValue)
    },
  ]
})

console.log(table.toString())

Output.

$ node example/computed-values.js

 USA    19.485.394.000.000,00 €  325 Mio.
 China  12.237.700.479.375,00 €  1,42 Mrd.
 Japan  4.872.415.104.315,00 €   128 Mio.

Colour-scale conditional formatting

See this file for a example of colour-scale formatting (increasing intensity of red/green for more positive/negative values).

API Reference

For the full API documentation, see here.

Load anywhere

This library is compatible with Node.js, the Web and any style of module loader. It can be loaded anywhere, natively without transpilation.

Within a Node.js CommonJS Module:

const Table = require('table-layout')

Within a Node.js ECMAScript Module:

import Table from 'table-layout'

Within a modern browser ECMAScript Module:

import Table from './node_modules/table-layout/dist/index.mjs'

See Also

• gfmt: A github-flavoured-markdown table generator.

---

© 2015-24 Lloyd Brookes <[e-mail]>.

Isomorphic test suite by test-runner. Documented by jsdoc-to-markdown.