A groundbreaking, innovative JavaScript library to do something that's literally never been attempted before: formatting an array of data objects as a textual table.
npm install string-table
var stringTable = require('string-table');
var users = [
{ name: 'Dan', gender: 'M', age: 29 },
{ name: 'Adam', gender: 'M', age: 31 },
{ name: 'Lauren', gender: 'F', age: 33 }
];
stringTable.create(users);
/*
* Result:
*
* | name | gender | age |
* -------------------------
* | Dan | M | 29 |
* | Adam | M | 31 |
* | Lauren | F | 33 |
*/
It works with multi-line strings, too!
# This example is in CoffeeScript for readability.
books = [
{
title: 'The Cat in the Hat',
opening:
"""
The sun did not shine.
It was too wet to play.
So we sat in the house
All that cold, cold, wet day.
"""
},
{
title: 'Green Eggs and Ham',
opening:
"""
I am Sam.
Sam I am.
Do you like green eggs and ham?
"""
}
]
stringTable.create(books)
#
# Result:
#
# | title | opening |
# --------------------------------------------------------
# | The Cat in the Hat | The sun did not shine. |
# | | It was too wet to play. |
# | | So we sat in the house |
# | | All that cold, cold, wet day. |
# | Green Eggs and Ham | I am Sam. |
# | | Sam I am. |
# | | Do you like green eggs and ham? |
#
You can also specify options to customize how the table is formatted:
var table = stringTable.create(users, options);
The available options are summarized below.
An array of strings indicating which column headers to include (and in what order)
Default: every property from the first object in the list
stringTable.create(users, { headers: ['age', 'name'] });
/*
* Result:
*
* | age | name |
* ----------------
* | 29 | Dan |
* | 31 | Adam |
* | 33 | Lauren |
*/
Whether or not to capitalize the table's column headers
Default: false
stringTable.create(users, { capitalizeHeaders: true });
/*
* Result:
*
* | Name | Gender | Age |
* -------------------------
* | Dan | M | 29 |
* | Adam | M | 31 |
* | Lauren | F | 33 |
*/
An object mapping column names to formatter functions, which will accept (value, header)
arguments
Default: none
stringTable.create(users, {
formatters: {
name: function(value, header) { return value.toUpperCase(); }
}
});
/*
* Result:
*
* | name | gender | age |
* -------------------------
* | DAN | M | 29 |
* | ADAM | M | 31 |
* | LAUREN | F | 33 |
*/
A formatter may also return an object with the properties { value, format }
, where format
in turn can have the properties { color, alignment }
.
stringTable.create(users, {
formatters: {
gender: function(value, header) {
return {
value: value,
format: {
color: value === 'M' ? 'cyan' : 'magenta',
alignment: 'right'
}
};
}
}
});
/*
* Result:
*
* | name | gender | age |
* ----------------------------
* | Dan | M | 29.00 |
* | Adam | M | 31.00 |
* | Lauren | F | 33.00 |
*
* (Imagine the Ms are cyan and the F is magenta above.)
*/
An object mapping data types ('string'
, 'number'
, 'boolean'
, etc.) to formatter functions (has lower precedence than formatters
option)
Default: none
stringTable.create(users, {
typeFormatters: {
number: function(value, header) { return value.toFixed(2); }
}
});
/*
* Result:
*
* | name | gender | age |
* ----------------------------
* | Dan | M | 29.00 |
* | Adam | M | 31.00 |
* | Lauren | F | 33.00 |
*/
The character(s) used to enclose the table and to delimit cells within the table, respectively
Defaults: '|'
for both
stringTable.create(users, {
outerBorder: '%',
innerBorder: '$'
});
/*
* Result:
*
* % name $ gender $ age %
* -------------------------
* % Dan $ M $ 29 %
* % Adam $ M $ 31 %
* % Lauren $ F $ 33 %
*/
The character used to separate rows in the table
Default: none
stringTable.create(users, { rowSeparator: '~' });
/*
* Result:
*
* | name | gender | age |
* -------------------------
* | Dan | M | 29 |
* ~~~~~~~~~~~~~~~~~~~~~~~~~
* | Adam | M | 31 |
* ~~~~~~~~~~~~~~~~~~~~~~~~~
* | Lauren | F | 33 |
*/
The character used to separate the header row from the table body
Default: '-'
stringTable.create(users, { headerSeparator: '*' });
/*
* Result:
*
* | name | gender | age |
* *************************
* | Dan | M | 29 |
* | Adam | M | 31 |
* | Lauren | F | 33 |
*/