Table Print

Data visualization

bar(value, maxVal?, width?, color?) → string

Unicode bar chart using █ (filled) and ░ (empty).

bar(0.8)                    // 20-wide green bar, 80% filled
bar(0.5, 1.0, 30, YELLOW)  // 30-wide yellow bar, 50% filled
bar(3500, 10000, 40, RED)   // scale to custom max

center(text, width) → string

Center-align text in a fixed-width field. Used inside cell formatters.

renderTable(options)

Full bordered table with box-drawing characters.

renderTable({
  columns: [
    { header: "#", width: 4 },
    { header: "Model", width: 20, align: "left" },
    { header: "Score", width: 8,
      format: (cell, ri, row) => {
        const v = parseFloat(cell);
        const color = v >= 0.8 ? GREEN : v >= 0.5 ? YELLOW : RED;
        return `${BOLD}${color}${center(cell, 8)}${RESET}`;
      }
    },
  ],
  rows: data,
  rowBg: (i, row) => i < 3 ? BG_GREEN : i % 2 === 0 ? BG_ROW : "",
});

Options:

• columns: ColumnDef[] — header, width, optional format function, optional align
• rows: string[][] — raw cell values as strings
• rowBg?: (rowIndex, row) => string — return ANSI bg code or ""
• indent?: number — left margin (default 2)

When a column has a format function, it receives the raw cell string and must return a styled+aligned string of exactly width characters (use center() for alignment inside the formatter).

Visual conventions

These conventions produce consistent, professional output across all experiments.

Color semantics

Score color thresholds

const color = v >= 0.8 ? GREEN : v >= 0.5 ? YELLOW : RED;

Row backgrounds

// Top 3 highlighted
rowBg: (i) => i < 3 ? BG_GREEN : i % 2 === 0 ? BG_ROW : ""

Star rankings

// Stars for top 3
const rankStr = rank <= 3
  ? `${BOLD}${GREEN} ★${rank.toString().padStart(2)}${RESET}`
  : `  ${rank.toString().padStart(2)}`;

Script structure

Every display script follows this pattern:

#!/usr/bin/env bun
export {};
import { clear, title, subtitle, note, bar, renderTable, wait, /* colors */ } from "../../tools/table";

// ══════════════════════════════════════════════════════════════
// TABLE 1: Name
// ══════════════════════════════════════════════════════════════
clear();
title("TABLE TITLE IN CAPS");
note("One-line description of what this shows");
console.log();

// ... render table or chart ...

await wait();

// ══════════════════════════════════════════════════════════════
// TABLE 2: Next table
// ══════════════════════════════════════════════════════════════
clear();
title("NEXT TABLE");
// ...

Key patterns:

• clear() before each table so each fills the screen alone (for screenshots)
• await wait() between tables so user controls pacing
• export {}; at top to satisfy Bun's module system
• Section comments with ══════ as visual separators in source code
• Run with: bun experiments/NNN-name/display-tables.ts

Common patterns

Inline bar chart rows (no bordered table)

For comparison views like SFT gain analysis:

for (const [model, base, ft, gain] of data) {
  const baseBar = bar(base, 1.0, 25, base >= 0.7 ? GREEN : YELLOW);
  const ftBar = bar(ft, 1.0, 25, ft >= 0.7 ? GREEN : YELLOW);
  const arrow = gain > 0 ? "▲" : "▼";
  const gainColor = gain > 0 ? GREEN : RED;
  write(`  ${BOLD}${model.padEnd(18)}${RESET}`);
  write(`  Base ${base.toFixed(3)} ${baseBar}  `);
  write(`  FT ${ft.toFixed(3)} ${ftBar}  `);
  write(`  ${gainColor}${arrow} ${gain.toFixed(1)}%${RESET}\n`);
}

Key-value info blocks

subtitle("Configuration");
console.log(`  ${BOLD}Method:${RESET}     LoRA (rank 16, alpha 32)`);
console.log(`  ${BOLD}Data:${RESET}       622 train + 70 eval`);
console.log(`  ${BOLD}Platform:${RESET}   HuggingFace Jobs`);

Findings list

for (const [num, finding, detail] of findings) {
  console.log(`  ${BOLD}${CYAN}Finding ${num}:${RESET}  ${BOLD}${WHITE}${finding}${RESET}`);
  for (const line of detail.split("\n")) {
    console.log(`  ${DIM}${line}${RESET}`);
  }
  console.log();
}

Tier cards

for (const [tier, model, score] of tiers) {
  const bg = tier === "TINY" ? BG_YELLOW : tier === "MEDIUM" ? BG_CYAN : BG_GREEN;
  const color = tier === "TINY" ? YELLOW : tier === "MEDIUM" ? CYAN : GREEN;
  write(`  ${bg}${BOLD}${color}  ${tier.padEnd(8)}${RESET}`);
  write(`  ${BOLD}${WHITE}${model.padEnd(18)}${RESET}`);
  write(`  ${BOLD}${GREEN}${score}${RESET}\n`);
}

Closing banner

console.log(`\n  ${BOLD}${GREEN}${"═".repeat(80)}${RESET}`);
console.log(`  ${BOLD}${GREEN}  Title of the experiment${RESET}`);
console.log(`  ${BOLD}${GREEN}  Summary stats  •  Date${RESET}`);
console.log(`  ${BOLD}${GREEN}${"═".repeat(80)}${RESET}`);

Extending tools/table.ts

When you need a new primitive (sparkline, heatmap, grouped bars), add it to tools/table.ts — not inline in the experiment script. This keeps all visualization primitives in one place. Follow the existing pattern: export a pure function that returns a styled string.