Data Operations

Sorting

Sort any table by column name. Supports ascending and descending order.

const table = new Table();
table.addColumn('Name');
table.addColumn('Age');
table.addRows([
    { Name: 'Charlie', Age: 35 },
    { Name: 'Alice', Age: 28 },
    { Name: 'Bob', Age: 42 }
]);

// Sort alphabetically by Name (ascending is default)
table.sort('Name');

// Sort numerically by Age, descending
table.sort('Age', 'desc');

TIP

Sorting is in-place — it modifies the existing table.rows array. Call sort() before render().

Pagination

Split a large table into pages for display:

// Paginate: 10 rows per page
table.paginate(10);
const page1 = table.render(); // Renders first 10 rows

// Or get all pages at once as separate Table instances
const pages = table.getPages(10);
pages.forEach((page, i) => {
    console.log(`--- Page ${i + 1} ---`);
    console.log(page.render());
});

Footers & Summaries

Manual Footer

Set a custom footer with setFooter():

table.setFooter({ Name: 'Total', Age: '—', Score: 285 });

Automatic Summarize

Compute and append a summary row automatically:

const table = new Table();
table.addColumn('Product');
table.addColumn('Sales');
table.addColumn('Profit');

table.addRows([
    { Product: 'Widget A', Sales: 100, Profit: 30 },
    { Product: 'Widget B', Sales: 250, Profit: 80 },
    { Product: 'Widget C', Sales: 75,  Profit: 20 }
]);

// Sum specific columns
table.summarize(['Sales', 'Profit'], 'sum');
console.log(table.render());

Expected output:

╭──────────┬───────┬────────╮
│ Product  │ Sales │ Profit │
├──────────┼───────┼────────┤
│ Widget A │ 100   │ 30     │
│ Widget B │ 250   │ 80     │
│ Widget C │ 75    │ 20     │
├──────────┼───────┼────────┤
│          │ 425   │ 130    │
╰──────────┴───────┴────────╯

Available algorithms: 'sum', 'avg', 'count'

Aggregations Class

Use the Aggregations class for standalone statistical calculations:

import { Aggregations } from 'cmd-table';

const values = [10, 20, 30, 40, 50];

Aggregations.sum(values);         // 150
Aggregations.avg(values);         // 30
Aggregations.min(values);         // 10
Aggregations.max(values);         // 50
Aggregations.count(values);       // 5
Aggregations.stdDev(values);      // 14.14
Aggregations.variance(values);    // 200
Aggregations.percentile(values, 0.9); // 90th percentile → 46

Pivot Tables

Group rows by a column and aggregate values. Great for summarizing datasets.

import { PivotTable } from 'cmd-table';

const salesData = [
    { Region: 'North', Product: 'A', Amount: 100 },
    { Region: 'North', Product: 'B', Amount: 200 },
    { Region: 'South', Product: 'A', Amount: 150 },
    { Region: 'South', Product: 'B', Amount: 300 },
    { Region: 'North', Product: 'A', Amount: 50 }
];

const pivot = PivotTable.create(salesData, {
    groupBy: 'Region',
    targetColumn: 'Amount',
    algorithm: 'sum'  // 'sum' | 'avg' | 'min' | 'max' | 'count' | custom function
});
console.log(pivot.render());

Expected output:

╭────────┬────────╮
│ Region │ Amount │
├────────┼────────┤
│ North  │ 350    │
│ South  │ 450    │
╰────────┴────────╯

Pivot with Custom Aggregator

const pivot = PivotTable.create(salesData, {
    groupBy: 'Region',
    targetColumn: 'Amount',
    algorithm: (values) => Math.max(...values) - Math.min(...values) // Range
});

Pivot Columns

You can also add additional pivot columns:

const pivot = PivotTable.create(salesData, {
    groupBy: 'Region',
    targetColumn: 'Amount',
    algorithm: 'sum',
    pivotColumn: 'Product'  // Creates one column per unique Product value
});

CrossTab (Matrix View)

Generate a two-dimensional matrix from your data — rows vs columns:

import { CrossTab } from 'cmd-table';

const salesData = [
    { Product: 'Widget', Month: 'Jan', Amount: 100 },
    { Product: 'Widget', Month: 'Feb', Amount: 150 },
    { Product: 'Gadget', Month: 'Jan', Amount: 200 },
    { Product: 'Gadget', Month: 'Feb', Amount: 250 }
];

const matrix = CrossTab.create(salesData, {
    rowKey: 'Product',
    colKey: 'Month',
    valueKey: 'Amount',
    aggregator: 'sum',    // 'sum' | 'count' | 'first' | 'last' | custom function
    missingValue: 0       // Fill missing intersections with 0
});
console.log(matrix.render());

Expected output:

╭────────┬─────┬─────╮
│        │ Jan │ Feb │
├────────┼─────┼─────┤
│ Widget │ 100 │ 150 │
│ Gadget │ 200 │ 250 │
╰────────┴─────┴─────╯

Transpose (Matrix Flip)

Swap the rows and columns of an existing table using the transpose() method. This is highly useful when you have a vast number of columns but few rows, and you want to display the metrics vertically for better readability.

const table = new Table();
table.addColumn('Metric');
table.addColumn('ServerA');
table.addColumn('ServerB');

table.addRow({ Metric: 'CPU', ServerA: '50%', ServerB: '90%' });
table.addRow({ Metric: 'RAM', ServerA: '16GB', ServerB: '32GB' });

// Returns a brand-new Table instance
const transposed = table.transpose();

console.log(transposed.render());

Expected output:

╭─────────┬───────┬──────╮
│ Field   │ Row 1 │ Row 2│
├─────────┼───────┼──────┤
│ Metric  │ CPU   │ RAM  │
│ ServerA │ 50%   │ 16GB │
│ ServerB │ 90%   │ 32GB │
╰─────────┴───────┴──────╯

• Returns a new Table instance; the original table is not mutated.
• The Field column represents the original column headers.
• Data columns are dynamically named Row 1, Row 2, etc.
• Preserves the theme and compact options of the original table.

Diff Tables

Compare two datasets side-by-side using Table.compare(). It highlights differences with ANSI colors:

• Green rows: Added in the new dataset
• Red rows: Removed from the old dataset
• Yellow cells: Modified values

import { Table } from 'cmd-table';

const oldData = [
  { id: 1, name: 'Alice', role: 'Engineer' },
  { id: 2, name: 'Bob', role: 'Designer'   }
];

const newData = [
  { id: 1, name: 'Alice', role: 'Lead Engineer' }, // Role changed
  { id: 3, name: 'Charlie', role: 'Manager'     }  // Added (Bob removed)
];

// Compare using a primary key
const diffTable = Table.compare(oldData, newData, {
  primaryKey: 'id',
  showUnchanged: false
});

console.log(diffTable.render());

Options:

• primaryKey?: string: If provided, matches objects by this key regardless of order. Otherwise, matches sequentially by array index.
• showUnchanged?: boolean: Default is true. Set to false to only display rows with additions, deletions, or modifications.