output/table

(no submodules)

Purpose

table renders structured data as a formatted ASCII table with header row, optional borders, and configurable column alignment. It computes column widths from the full data set — header and all rows — ensuring that every column is at least as wide as its widest cell. The result is a plain multi-line string ready for console output or piping.

The function is pure: it takes a TableOptions object and returns a string. No state, no I/O, no mutations.

Features

Automatic column width calculation: each column is as wide as its widest cell across all rows
Three alignment modes per column: "left" (default), "right", "center"
Border mode (default on): header and data rows separated by ─┼─ divider
Border-off mode: columns joined with two spaces
Handles empty rows gracefully — returns header-only output
Property-tested: column widths always >= max cell content width

Usage: Basic Example

import { table } from "@suaveplan/cli/output/table/table";

const out = table({
  headers: ["Name", "Role", "Since"],
  rows: [
    ["Alice", "Admin", "2022"],
    ["Bob", "User", "2023"],
  ],
});
console.log(out);
// Name  │ Role  │ Since
// ──────┼───────┼──────
// Alice │ Admin │ 2022
// Bob   │ User  │ 2023

Usage: Advanced Example

import { table } from "@suaveplan/cli/output/table/table";

const out = table({
  headers: ["Package", "Version", "Size"],
  rows: [
    ["@suaveplan/error", "0.1.0", "12 kB"],
    ["@suaveplan/cli", "0.1.0", "48 kB"],
  ],
  alignment: ["left", "center", "right"],
  border: true,
});
console.log(out);

API Reference

`table(opts: TableOptions): string`

Renders the table and returns the formatted string.

opts.headers: string[] — column header labels. Determines the number of columns.

opts.rows: string[][] — data rows. Each row is an array of string cells. Extra cells beyond headers.length are ignored; missing cells are treated as empty.

opts.alignment?: Alignment[] — per-column alignment ("left" | "right" | "center"). Defaults to "left" for any column not specified.

opts.border?: boolean — whether to render │ column separators and ─┼─ divider line. Default true.

`Alignment`

"left" | "right" | "center" — the alignment mode for a table column.

`TableOptions`

The full options type. Corresponds to TableOptionsSchema for Zod validation.

Implementation Notes

Column widths are computed with a single Math.max pass over [headers, ...rows]. Cells are padded with String.prototype.padEnd (left/center) or String.prototype.padStart (right via the align helper). The divider line joins "─".repeat(width) segments with "─┼─". When border is false, the divider is omitted and segments are joined with " " instead of " │ ". Trailing whitespace on each row is trimmed to keep output clean.

3.0 KiB Raw Blame History