@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/formatting/tableFormatter.d.ts

@@ -0,0 +1,261 @@
+/**
+ * @fileoverview Table formatter utility for creating tables in multiple formats.
+ * Supports markdown, ASCII, grid (Unicode), and compact table styles with configurable
+ * alignment, truncation, and formatting options.
+ * @module src/utils/formatting/tableFormatter
+ */
+import { type RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Table output style options.
+ *
+ * - `markdown`: GitHub-flavored markdown table with pipe delimiters and alignment indicators.
+ * - `ascii`: Box-drawing table using `+`, `-`, and `|` characters; portable across terminals.
+ * - `grid`: Unicode box-drawing table using `┌─┬─┐` characters; visually cleaner but requires Unicode support.
+ * - `compact`: Borderless table with columns separated by spaces; minimal visual noise.
+ *
+ * @example
+ * ```typescript
+ * const style: TableStyle = 'grid';
+ * ```
+ */
+export type TableStyle = 'markdown' | 'ascii' | 'grid' | 'compact';
+/**
+ * Column alignment options.
+ *
+ * Controls how cell content is padded within its column width.
+ * - `left`: Content flush-left, trailing spaces fill the column.
+ * - `center`: Content centred, padding split evenly (odd remainder goes right).
+ * - `right`: Content flush-right, leading spaces fill the column.
+ *
+ * @example
+ * ```typescript
+ * const alignment: Alignment = 'right';
+ * ```
+ */
+export type Alignment = 'left' | 'center' | 'right';
+/**
+ * Configuration options for table formatting.
+ */
+export interface TableFormatterOptions {
+    /**
+     * Column-specific alignment configuration.
+     * Key is column name (for object arrays) or index (for raw arrays).
+     * @example { name: 'left', age: 'right', email: 'center' }
+     */
+    alignment?: Record<string, Alignment>;
+    /**
+     * Header styling option.
+     * - bold: Headers in bold (markdown only)
+     * - uppercase: Convert headers to uppercase
+     * - none: No special header formatting
+     */
+    headerStyle?: 'bold' | 'uppercase' | 'none';
+    /**
+     * Maximum width for any column. Content exceeding this will be truncated.
+     */
+    maxWidth?: number;
+    /**
+     * Minimum column width (default: 3).
+     */
+    minWidth?: number;
+    /**
+     * Padding around cell content (default: 1 space).
+     */
+    padding?: number;
+    /**
+     * Table style to use for rendering.
+     * - markdown: GitHub-style markdown tables (| Header | Header |)
+     * - ascii: ASCII box drawing with +, -, | characters
+     * - grid: Unicode box-drawing characters (┌─┬─┐)
+     * - compact: Space-separated columns (no borders)
+     */
+    style?: TableStyle;
+    /**
+     * Whether to truncate long content with ellipsis (default: true).
+     * If false, content may wrap or overflow depending on style.
+     */
+    truncate?: boolean;
+}
+/**
+ * Utility class for formatting tabular data into various table styles.
+ *
+ * Provides two rendering methods:
+ * - {@link format} — accepts an array of objects and extracts headers automatically.
+ * - {@link formatRaw} — accepts explicit headers and a 2D string array for full control.
+ *
+ * Column widths are computed from the widest value in each column, clamped by
+ * `minWidth` and `maxWidth`. Content that exceeds `maxWidth` is truncated with
+ * an ellipsis (`...`) when `truncate` is `true` (the default).
+ *
+ * @example
+ * ```typescript
+ * const data = [
+ *   { name: 'Alice', score: 42 },
+ *   { name: 'Bob',   score: 7  },
+ * ];
+ *
+ * // Markdown (default style)
+ * tableFormatter.format(data);
+ * // | name  | score |
+ * // | ----- | ----- |
+ * // | Alice | 42    |
+ * // | Bob   | 7     |
+ *
+ * // Unicode grid with right-aligned score column
+ * tableFormatter.format(data, { style: 'grid', alignment: { score: 'right' } });
+ * ```
+ */
+export declare class TableFormatter {
+    /**
+     * Default formatting options.
+     * @private
+     */
+    private readonly defaultOptions;
+    /**
+     * Format an array of objects as a table.
+     *
+     * Headers are derived from the keys of the first object. Every value is
+     * converted to a string via an internal `stringify` helper that handles
+     * primitives, arrays (JSON), objects (JSON), and special values (`null`,
+     * `undefined`, functions, symbols).
+     *
+     * @template T - Type of objects in the array; must extend `Record<string, unknown>`.
+     * @param data - Array of objects to render. Returns `''` immediately if empty.
+     * @param options - Table formatting options. All fields are optional; defaults apply.
+     * @param context - Optional request context used for correlated debug logging.
+     *   A new context is created automatically when omitted.
+     * @returns Formatted table string in the requested style, or `''` if `data` is empty.
+     * @throws {McpError} With `ValidationError` code if `data` is not an array.
+     * @throws {McpError} With `InternalError` code if rendering fails unexpectedly.
+     *
+     * @example
+     * ```typescript
+     * const data = [
+     *   { name: 'Alice', age: 30, role: 'Engineer' },
+     *   { name: 'Bob',   age: 25, role: 'Designer' },
+     * ];
+     *
+     * // Default markdown output
+     * tableFormatter.format(data);
+     *
+     * // Unicode grid with right-aligned age column
+     * tableFormatter.format(data, { style: 'grid', alignment: { age: 'right' } });
+     * ```
+     */
+    format<T extends Record<string, unknown>>(data: T[], options?: TableFormatterOptions, context?: RequestContext): string;
+    /**
+     * Format a raw 2D string array with explicit headers.
+     *
+     * Unlike {@link format}, no automatic key extraction or value stringification
+     * occurs — callers supply pre-serialized strings. All rows must have exactly
+     * the same number of columns as `headers`; a mismatch throws immediately.
+     *
+     * @param headers - Non-empty array of column header strings.
+     * @param rows - 2D array of string cell values. Every inner array must have
+     *   the same length as `headers`. Returns `''` immediately if `rows` is empty.
+     * @param options - Table formatting options. All fields are optional; defaults apply.
+     * @param context - Optional request context used for correlated debug logging.
+     *   A new context is created automatically when omitted.
+     * @returns Formatted table string in the requested style, or `''` if `rows` is empty.
+     * @throws {McpError} With `ValidationError` code if `headers` is empty or not an array,
+     *   `rows` is not an array, or any row's column count differs from `headers.length`.
+     * @throws {McpError} With `InternalError` code if rendering fails unexpectedly.
+     *
+     * @example
+     * ```typescript
+     * const headers = ['Name', 'Age', 'Role'];
+     * const rows = [
+     *   ['Alice', '30', 'Engineer'],
+     *   ['Bob',   '25', 'Designer'],
+     * ];
+     * const table = tableFormatter.formatRaw(headers, rows, { style: 'ascii' });
+     * ```
+     */
+    formatRaw(headers: string[], rows: string[][], options?: TableFormatterOptions, context?: RequestContext): string;
+    /**
+     * Apply header styling transformations.
+     * @private
+     */
+    private applyHeaderStyle;
+    /**
+     * Calculate column widths and metadata.
+     * @private
+     */
+    private calculateColumns;
+    /**
+     * Render table using the specified style.
+     * @private
+     */
+    private renderTable;
+    /**
+     * Render markdown-style table.
+     * @private
+     */
+    private renderMarkdown;
+    /**
+     * Render ASCII box-drawing table.
+     * @private
+     */
+    private renderAscii;
+    /**
+     * Render Unicode grid table.
+     * @private
+     */
+    private renderGrid;
+    /**
+     * Render compact space-separated table.
+     * @private
+     */
+    private renderCompact;
+    /**
+     * Format a single cell with alignment and truncation.
+     * @private
+     */
+    private formatCell;
+    /**
+     * Convert any value to a string for display in table.
+     * @private
+     */
+    private stringify;
+}
+/**
+ * Singleton instance of {@link TableFormatter}.
+ *
+ * Prefer this over constructing `new TableFormatter()` directly. Use
+ * {@link TableFormatter.format} for object arrays and
+ * {@link TableFormatter.formatRaw} for pre-serialized 2D string arrays.
+ *
+ * @example
+ * ```typescript
+ * import { tableFormatter } from '../../utils/formatting/tableFormatter.js';
+ *
+ * const data = [
+ *   { name: 'Alice', age: 30, role: 'Engineer' },
+ *   { name: 'Bob',   age: 25, role: 'Designer' },
+ * ];
+ *
+ * // Markdown table (default style)
+ * console.log(tableFormatter.format(data));
+ *
+ * // Unicode grid with right-aligned age column
+ * console.log(tableFormatter.format(data, {
+ *   style: 'grid',
+ *   alignment: { age: 'right' },
+ * }));
+ *
+ * // Compact borderless table with uppercase headers
+ * console.log(tableFormatter.format(data, {
+ *   style: 'compact',
+ *   headerStyle: 'uppercase',
+ * }));
+ *
+ * // Raw 2D array (no automatic key extraction)
+ * console.log(tableFormatter.formatRaw(
+ *   ['Name', 'Age'],
+ *   [['Alice', '30'], ['Bob', '25']],
+ *   { style: 'ascii' },
+ * ));
+ * ```
+ */
+export declare const tableFormatter: TableFormatter;
+//# sourceMappingURL=tableFormatter.d.ts.map

package/dist/utils/formatting/tableFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tableFormatter.d.ts","sourceRoot":"","sources":["../../../src/utils/formatting/tableFormatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAEhG;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,cAAc;IACzB;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAQ7B;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtC,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,CAAC,EAAE,qBAAqB,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,MAAM;IAgCT;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,EAAE,MAAM,EAAE,EAAE,EAChB,OAAO,CAAC,EAAE,qBAAqB,EAC/B,OAAO,CAAC,EAAE,cAAc,GACvB,MAAM;IA6ET;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAgCxB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAoBnB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAqCtB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAsCnB;;;OAGG;IACH,OAAO,CAAC,UAAU;IAsClB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAwBrB;;;OAGG;IACH,OAAO,CAAC,UAAU;IAkClB;;;OAGG;IACH,OAAO,CAAC,SAAS;CAmBlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,cAAc,gBAAuB,CAAC"}