@oclif/table 0.4.14 → 0.5.0

package/README.md

@@ -4,20 +4,278 @@
 [![Downloads/week](https://img.shields.io/npm/dw/@oclif/table.svg)](https://npmjs.org/package/@oclif/table)
 [![License](https://img.shields.io/npm/l/@oclif/table.svg)](https://github.com/oclif/table/blob/main/LICENSE)
 
-# Description
+### Description
 
-Print tables to the terminal using [ink](https://www.npmjs.com/package/ink)
+Print beautiful, flexible tables to the terminal using [Ink](https://www.npmjs.com/package/ink). This library powers many oclif/Salesforce CLIs and is built for real-world, production output: wide columns, multi-line cells, smart wrapping/truncation, theming, and great CI behavior.
 
-# Examples
+### Features
 
-You can see examples of how to use it in the [examples](./examples/) directory.
+- Rich rendering via Ink with graceful fallback to plain text in CI
+- Automatic column sizing with max/explicit width support (including percentages)
+- Per-column alignment, padding, and overflow control (wrap, truncate, middle/start/end)
+- Header formatting with `change-case` presets or custom function
+- Multiple border styles (outline, headers-only, vertical/horizontal, none, and more)
+- Sort and filter data, optionally per-column
+- Print multiple tables side-by-side or stacked with layout controls
+- Return a string (`makeTable`) or print directly (`printTable`/`printTables`)
+- TypeScript-first API with excellent types
 
-You can run any of these with the following:
+---
 
+### Requirements
+
+- Node.js >= 18
+- ESM only (this package has `"type": "module"`). Use `import`, not `require`.
+
+### Installation
+
+```bash
+npm install @oclif/table
+# or
+yarn add @oclif/table
+# or
+pnpm add @oclif/table
+# or
+bun add @oclif/table
+```
+
+### Quick start
+
+```js
+import {printTable} from '@oclif/table'
+
+const data = [
+  {name: 'Alice', role: 'Engineer', notes: 'Loves distributed systems'},
+  {name: 'Bob', role: 'Designer', notes: 'Enjoys typography and UI'},
+]
+
+printTable({
+  title: 'Team',
+  data,
+  columns: [
+    {key: 'name', width: 16},
+    {key: 'role', width: 14, horizontalAlignment: 'center'},
+    {key: 'notes', overflow: 'wrap'},
+  ],
+})
+```
+
+To generate a string instead of printing to stdout:
+
+```js
+import {makeTable} from '@oclif/table'
+
+const output = makeTable({data, columns: ['name', 'role', 'notes']})
+// do something with `output`
+```
+
+To print multiple tables in one layout:
+
+```js
+import {printTables} from '@oclif/table'
+
+printTables(
+  [
+    {title: 'Developers', data, columns: ['name', 'role']},
+    {title: 'Notes', data, columns: ['notes']},
+  ],
+  {direction: 'row', columnGap: 4, margin: 1},
+)
+```
+
+---
+
+### API
+
+- `printTable(options)` — renders a single table to stdout.
+- `makeTable(options): string` — renders a single table and returns the output string.
+- `printTables(tables, options?)` — renders multiple tables with layout controls.
+
+All three accept the same `TableOptions<T>` (documented below). `printTables` accepts an array of `TableOptions` plus optional container layout props.
+
+#### TypeScript
+
+```ts
+import type {TableOptions} from '@oclif/table'
+
+type Row = {name: string; age: number}
+const opts: TableOptions<Row> = {
+  data: [{name: 'Ada', age: 36}],
+  columns: [
+    {key: 'name', name: 'Full Name'},
+    {key: 'age', horizontalAlignment: 'right'},
+  ],
+}
+```
+
+---
+
+### Options reference
+
+Below are the most important options with defaults and behavior. See examples in `./examples` for more patterns.
+
+- `data` (required): array of rows, each a plain object.
+- `columns`: list of keys or objects describing each column.
+  - String form: `'name'` (uses key as header)
+  - Object form: `{ key, name?, width?, padding?, overflow?, horizontalAlignment?, verticalAlignment? }`
+    - `name`: header label (defaults to key or formatted with `headerOptions.formatter`)
+    - `width`: number of characters or percentage string like `'50%'`
+    - `padding`: spaces added on both sides (default: table `padding`)
+    - `overflow`: `'wrap' | 'truncate' | 'truncate-start' | 'truncate-middle' | 'truncate-end'`
+    - `horizontalAlignment`: `'left' | 'center' | 'right'`
+    - `verticalAlignment`: `'top' | 'center' | 'bottom'`
+
+- `padding` (number): cell padding for all columns. Default: `1`.
+
+- `maxWidth` (number | percentage | 'none'): maximum table width. Defaults to terminal width.
+  - When the natural table width exceeds `maxWidth`, columns shrink and content wraps/truncates based on `overflow`.
+  - Use `'none'` to allow unlimited width (useful for very wide outputs; users can resize their terminals).
+
+- `width` (number | percentage): exact table width. Overrides `maxWidth`. If wider than the natural width, columns expand evenly.
+
+- `overflow`: cell overflow behavior. Default: `'truncate'`.
+  - `'wrap'` wraps long content
+  - `'truncate'` truncates the end
+  - `'truncate-start' | 'truncate-middle' | 'truncate-end'` choose truncation position
+
+- `headerOptions`: style options for headers.
+  - `formatter`: either a function `(header: string) => string` or a `change-case` preset name:
+    `'camelCase' | 'capitalCase' | 'constantCase' | 'kebabCase' | 'pascalCase' | 'sentenceCase' | 'snakeCase'`
+  - Styling keys (also supported by `titleOptions`):
+    - `color`, `backgroundColor` (named color, hex `#rrggbb`, or `rgb(r,g,b)`)
+    - `bold`, `dimColor`, `italic`, `underline`, `strikethrough`, `inverse`
+  - Default header style is bold blue (unless `noStyle: true`).
+
+- `borderStyle`: border preset. Default: `'all'`.
+  - Available: `'all' | 'headers-only' | 'headers-only-with-outline' | 'headers-only-with-underline' | 'horizontal' | 'horizontal-with-outline' | 'none' | 'outline' | 'vertical' | 'vertical-rows-with-outline' | 'vertical-with-outline'`
+
+- `borderColor`: optional border color. When unset, the terminal's default color is used.
+
+- `horizontalAlignment`: default column alignment. Default: `'left'`.
+
+- `verticalAlignment`: default vertical alignment within cells. Default: `'top'`.
+
+- `filter(row)`: predicate to include/exclude rows.
+
+- `sort`: object mapping keys to `'asc' | 'desc' | (a,b)=>number`. Keys order defines multi-column priority.
+
+- `title`: optional string printed above the table.
+
+- `titleOptions`: style options for the title (same keys as `headerOptions` except `formatter`).
+
+- `trimWhitespace`: when wrapping text, trim whitespace at line boundaries. Default: `true`.
+
+- `noStyle`: disable all styling. Also strips ANSI color codes from your cell content for accurate width calculation.
+
+#### Container options (for `printTables`)
+
+`printTables(tables, containerOptions)` accepts:
+
+- `direction`: `'row' | 'column'` (default `'row'`)
+- `columnGap`, `rowGap`: spacing between tables
+- `alignItems`: `'flex-start' | 'center' | 'flex-end'`
+- `margin`, `marginLeft`, `marginRight`, `marginTop`, `marginBottom`
+
+---
+
+### Behavior and environment variables
+
+- Terminal width detection: by default we use your terminal width. Override with `OCLIF_TABLE_COLUMN_OVERRIDE`.
+  - Example: `OCLIF_TABLE_COLUMN_OVERRIDE=120 node app.js`
+
+- CI-safe output: in CI environments, we automatically fall back to a plain-text renderer (no Ink) for stability.
+  - To force Ink rendering in CI, set `OCLIF_TABLE_SKIP_CI_CHECK=1`.
+
+- Very large data: by default, datasets with 10,000+ rows use the plain-text renderer to avoid memory issues.
+  - Override with `OCLIF_TABLE_LIMIT=<number>` (Salesforce CLIs may also honor `SF_TABLE_LIMIT`).
+
+---
+
+### Advanced examples
+
+Header formatting with `change-case`:
+
+```js
+import {printTable} from '@oclif/table'
+
+printTable({
+  data: [{first_name: 'Ada', last_name: 'Lovelace'}],
+  columns: ['first_name', 'last_name'],
+  headerOptions: {formatter: 'capitalCase'},
+})
 ```
+
+Per-column sizing and overflow:
+
+```js
+printTable({
+  data: [{name: 'A very very long name', notes: 'Multi-line\ncontent supported'}],
+  maxWidth: '80%',
+  columns: [
+    {key: 'name', width: 20, overflow: 'truncate-middle'},
+    {key: 'notes', overflow: 'wrap', horizontalAlignment: 'right'},
+  ],
+})
+```
+
+Switching borders and colors:
+
+```js
+printTable({
+  title: 'Inventory',
+  titleOptions: {bold: true, color: 'cyan'},
+  data: [{item: 'Widget', qty: 10}],
+  columns: ['item', {key: 'qty', horizontalAlignment: 'right'}],
+  borderStyle: 'vertical-with-outline',
+  borderColor: 'green',
+})
+```
+
+---
+
+### Examples directory
+
+This repo contains many runnable examples in `./examples` (including edge cases like very wide/very tall tables). Run any with:
+
+```bash
 tsx examples/basic.ts
 ```
 
-# Contributing
+---
+
+### Testing
+
+This package includes snapshot tests for all examples to ensure consistent output across different environments.
+
+#### Running tests
+
+```bash
+# Run all tests (including snapshot tests)
+yarn test
+
+# Run only snapshot tests
+yarn test:examples
+
+# Update snapshots after intentional changes
+yarn test:examples:update
+```
+
+#### How snapshot testing works
+
+Examples are executed in an isolated child process with:
+
+- Fixed terminal width (`OCLIF_TABLE_COLUMN_OVERRIDE=120`)
+- Disabled CI detection unless an example sets it
+- ESM loader for TypeScript (`ts-node/esm`)
+
+Snapshots live in `test/__snapshots__/examples/*.txt` and mirror the `examples` directory structure.
+
+---
+
+### Contributing
 
 See the [contributing guide](./CONRTIBUTING.md).
+
+### License
+
+MIT © Salesforce

package/lib/table.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import { CellProps, ContainerProps, HorizontalAlignment, Overflow, TableOptions } from './types.js';
-export declare function formatTextWithMargins({ horizontalAlignment, overflow, padding, trimWhitespace, value, width }: {
+export declare function formatTextWithMargins({ horizontalAlignment, overflow, padding, trimWhitespace, value, width, }: {
     overflow: Overflow;
     value: unknown;
     width: number;
@@ -50,7 +50,8 @@ export declare function makeTable<T extends Record<string, unknown>>(options: Ta
  * @template T - An array of records where each record represents a table.
  * @param {Object.<keyof T, TableOptions<T[keyof T]>>} tables - An object containing table options for each table.
  * @param {Omit<ContainerProps, 'children'>} [options] - Optional container properties excluding 'children'.
- * @throws {Error} Throws an error if the total number of rows across all tables exceeds 30,000.
+ * @throws {Error} Throws an error if the total number of rows across all tables exceeds 10,000.
+ * @throws {Error} Throws an error if any of the tables have `maxWidth: "none"`.
  */
 export declare function printTables<T extends Record<string, unknown>[]>(tables: {
     [P in keyof T]: TableOptions<T[P]>;

package/lib/table.js

@@ -34,7 +34,7 @@ function determineTruncatePosition(overflow) {
         }
     }
 }
-export function formatTextWithMargins({ horizontalAlignment, overflow, padding, trimWhitespace = true, value, width }) {
+export function formatTextWithMargins({ horizontalAlignment, overflow, padding, trimWhitespace = true, value, width, }) {
     function calculateMargins(spaces) {
         let marginLeft;
         let marginRight;
@@ -147,7 +147,7 @@ function setupTable(props) {
         borderProps,
         cell: Cell,
         skeleton: BORDER_SKELETONS[config.borderStyle].data,
-        trimWhitespace
+        trimWhitespace,
     });
     const footerComponent = row({
         borderProps,
@@ -283,7 +283,7 @@ export function Skeleton(props) {
  *
  * Implementation inspired by https://github.com/vadimdemedes/ink/blob/master/test/helpers/create-stdout.ts
  */
-const createStdout = () => {
+const createStdout = ({ columns }) => {
     // eslint-disable-next-line unicorn/prefer-event-target
     const stdout = new EventEmitter();
     // Override the rows so that ink doesn't clear the entire terminal when
@@ -292,7 +292,7 @@ const createStdout = () => {
     // https://github.com/vadimdemedes/ink/blob/v5.0.1/src/ink.tsx#L174
     // This might be a bad idea but it works.
     stdout.rows = 10_000;
-    stdout.columns = getColumnWidth();
+    stdout.columns = columns;
     const frames = [];
     stdout.write = (data) => {
         frames.push(data);
@@ -308,8 +308,8 @@ const createStdout = () => {
 };
 class Output {
     stream;
-    constructor() {
-        this.stream = createStdout();
+    constructor(opts) {
+        this.stream = createStdout(opts);
     }
     printLastFrame() {
         process.stdout.write(`${this.stream.lastFrame()}\n`);
@@ -404,7 +404,7 @@ export function printTable(options) {
         renderPlainTable(options);
         return;
     }
-    const output = new Output();
+    const output = new Output({ columns: options.maxWidth === 'none' ? Infinity : getColumnWidth() });
     const instance = render(React.createElement(Table, { ...options }), { stdout: output.stream });
     instance.unmount();
     output.printLastFrame();
@@ -417,7 +417,7 @@ export function printTable(options) {
  * @returns {string} The rendered table as a string.
  */
 export function makeTable(options) {
-    const output = new Output();
+    const output = new Output({ columns: options.maxWidth === 'none' ? Infinity : getColumnWidth() });
     const instance = render(React.createElement(Table, { ...options }), { stdout: output.stream });
     instance.unmount();
     return output.stream.lastFrame() ?? '';
@@ -431,13 +431,17 @@ function Container(props) {
  * @template T - An array of records where each record represents a table.
  * @param {Object.<keyof T, TableOptions<T[keyof T]>>} tables - An object containing table options for each table.
  * @param {Omit<ContainerProps, 'children'>} [options] - Optional container properties excluding 'children'.
- * @throws {Error} Throws an error if the total number of rows across all tables exceeds 30,000.
+ * @throws {Error} Throws an error if the total number of rows across all tables exceeds 10,000.
+ * @throws {Error} Throws an error if any of the tables have `maxWidth: "none"`.
  */
 export function printTables(tables, options) {
     if (tables.reduce((acc, table) => acc + table.data.length, 0) > 10_000) {
         throw new Error('The data is too large to print multiple tables. Please use `printTable` instead.');
     }
-    const output = new Output();
+    if (tables.some((table) => table.maxWidth === 'none')) {
+        throw new Error('printTables does not support `maxWidth: "none". Please use `printTable` instead.');
+    }
+    const output = new Output({ columns: getColumnWidth() });
     const leftMargin = options?.marginLeft ?? options?.margin ?? 0;
     const rightMargin = options?.marginRight ?? options?.margin ?? 0;
     const columns = getColumnWidth() - (leftMargin + rightMargin);

package/lib/types.d.ts

@@ -75,7 +75,7 @@ export type TableOptions<T extends Record<string, unknown>> = {
      */
     padding?: number;
     /**
-     * Maximum width of the table. Can be a number (e.g. 80) or a percentage (e.g. '80%').
+     * Maximum width of the table. Can be a number (e.g. 80) or a percentage (e.g. '80%'). Or set to 'none' for unlimited width.
      *
      * By default, the table will only take up as much space as it needs to fit the content. If it extends beyond the maximum width,
      * it will wrap or truncate the content based on the `overflow` option. In other words, this property allows you to set the width
@@ -86,8 +86,14 @@ export type TableOptions<T extends Record<string, unknown>> = {
      * If you provide a number or percentage that is larger than the terminal width, it will default to the terminal width.
      *
      * If you provide a number or percentage that is too small to fit the table, it will default to the minimum width of the table.
+     *
+     * If you provide 'none', the table will grow to its natural width, unbound by terminal width. This may render poorly in narrow terminals but
+     * it's useful because it will allow all the content to be visible without truncation or wrapping, which allows the user to resize their terminal
+     * to see all the content.
+     *
+     * @throws {Error} If you provide 'none' and you are using `printTables`.
      */
-    maxWidth?: Percentage | number;
+    maxWidth?: Percentage | number | 'none';
     /**
      * Exact width of the table. Can be a number (e.g. 80) or a percentage (e.g. '80%').
      *

package/lib/utils.d.ts

@@ -34,7 +34,7 @@ export declare function getColumnWidth(): number;
  * @param providedWidth - The width value provided.
  * @returns The determined configured width.
  */
-export declare function determineConfiguredWidth(providedWidth: number | Percentage | undefined, columns?: number): number;
+export declare function determineConfiguredWidth(providedWidth: number | Percentage | 'none' | undefined, columns?: number): number;
 export declare function getColumns<T extends Record<string, unknown>>(config: Config<T>, headings: Partial<T>): Column<T>[];
 export declare function getHeadings<T extends Record<string, unknown>>(config: Config<T>): Partial<T>;
 export declare function maybeStripAnsi<T extends Record<string, unknown>[]>(data: T, noStyle: boolean): T;

package/lib/utils.js

@@ -70,6 +70,8 @@ export function getColumnWidth() {
 export function determineConfiguredWidth(providedWidth, columns = getColumnWidth()) {
     if (!providedWidth)
         return columns;
+    if (providedWidth === 'none')
+        return Infinity;
     const num = typeof providedWidth === 'string' && providedWidth.endsWith('%')
         ? Math.floor((Number.parseInt(providedWidth, 10) / 100) * columns)
         : typeof providedWidth === 'string'
@@ -120,6 +122,9 @@ export function getColumns(config, headings) {
         // In that case, we don't want to reduce the column widths and just use the table's natural width.
         if (maxWidth === 0)
             return;
+        // The consumer has indicated they want an unbounded table
+        if (maxWidth === Infinity)
+            return;
         // If the table is too wide, reduce the width of the largest column as little as possible to fit the table.
         // If the table is still too wide, it will reduce the width of the next largest column and so on
         while (tableWidth > maxWidth) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/table",
   "description": "Display table in terminal",
-  "version": "0.4.14",
+  "version": "0.5.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/table/issues",
   "dependencies": {
@@ -17,10 +17,10 @@
   },
   "devDependencies": {
     "@commitlint/config-conventional": "^19",
-    "@eslint/compat": "^1.3.2",
+    "@eslint/compat": "^1.4.0",
     "@oclif/core": "^4",
     "@oclif/prettier-config": "^0.2.1",
-    "@oclif/test": "^4.1.13",
+    "@oclif/test": "^4.1.14",
     "@types/chai": "^4.3.16",
     "@types/mocha": "^10.0.10",
     "@types/node": "^18",
@@ -29,8 +29,8 @@
     "ansis": "^3.17.0",
     "chai": "^4.5.0",
     "commitlint": "^19",
-    "eslint": "^9.35.0",
-    "eslint-config-oclif": "^6.0.102",
+    "eslint": "^9.38.0",
+    "eslint-config-oclif": "^6.0.110",
     "eslint-config-prettier": "^10.1.8",
     "eslint-config-xo": "^0.49.0",
     "eslint-config-xo-react": "^0.28.0",
@@ -75,7 +75,9 @@
     "posttest": "yarn lint",
     "prepack": "yarn run build",
     "prepare": "husky",
-    "test": "mocha --forbid-only \"test/**/*.test.+(ts|tsx)\" --parallel"
+    "test": "mocha --forbid-only \"test/**/*.test.+(ts|tsx)\" --parallel",
+    "test:examples": "mocha --forbid-only \"test/examples.snapshot.test.ts\"",
+    "test:examples:update": "UPDATE_SNAPSHOTS=1 mocha --forbid-only \"test/examples.snapshot.test.ts\""
   },
   "types": "lib/index.d.ts",
   "type": "module"