@ibm/ibmi-mcp-server 0.1.0

package/dist/utils/formatting/sqlFormattingUtils.js

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview SQL formatting utilities for database result presentation.
+ * Provides type-aware formatting helpers for SQL results, including column alignment
+ * and type indicators.
+ * @module src/utils/formatting/sqlFormattingUtils
+ */
+/**
+ * IBM i DB2 numeric data types that should be right-aligned in tables.
+ * @private
+ */
+const NUMERIC_TYPES = new Set([
+    "INTEGER",
+    "SMALLINT",
+    "BIGINT",
+    "DECIMAL",
+    "NUMERIC",
+    "FLOAT",
+    "REAL",
+    "DOUBLE",
+    "DECFLOAT",
+    "INT",
+    "DEC",
+]);
+/**
+ * IBM i DB2 text data types that should be left-aligned in tables.
+ * @private
+ */
+const TEXT_TYPES = new Set([
+    "VARCHAR",
+    "CHAR",
+    "CHARACTER",
+    "CLOB",
+    "VARGRAPHIC",
+    "GRAPHIC",
+    "DBCLOB",
+    "BLOB",
+    "BINARY",
+    "VARBINARY",
+]);
+/**
+ * IBM i DB2 temporal data types that should be left-aligned in tables.
+ * @private
+ */
+const TEMPORAL_TYPES = new Set(["DATE", "TIME", "TIMESTAMP", "TIMESTMP"]);
+/**
+ * Determine the appropriate column alignment based on IBM i DB2 data type.
+ * Numeric types are right-aligned for better visual comparison,
+ * while text and temporal types are left-aligned.
+ *
+ * @param columnType - The database column type (e.g., 'INTEGER', 'VARCHAR')
+ * @returns The recommended alignment for this column type
+ *
+ * @example
+ * ```typescript
+ * getColumnAlignment('INTEGER');    // 'right'
+ * getColumnAlignment('VARCHAR');    // 'left'
+ * getColumnAlignment('TIMESTAMP');  // 'left'
+ * getColumnAlignment('UNKNOWN');    // 'left' (default)
+ * ```
+ */
+export function getColumnAlignment(columnType) {
+    if (!columnType) {
+        return "left"; // Default for unknown types
+    }
+    // Normalize type name (uppercase, remove precision/scale info)
+    const normalizedType = columnType.toUpperCase().split("(")[0].trim();
+    // Check type categories
+    if (NUMERIC_TYPES.has(normalizedType)) {
+        return "right";
+    }
+    if (TEXT_TYPES.has(normalizedType) || TEMPORAL_TYPES.has(normalizedType)) {
+        return "left";
+    }
+    // Default to left alignment for unknown types
+    return "left";
+}
+/**
+ * Format a column header with type indicator.
+ * Appends the data type in parentheses for LLM clarity.
+ *
+ * @param columnName - The column name
+ * @param columnType - The database column type (optional)
+ * @returns Formatted header string
+ *
+ * @example
+ * ```typescript
+ * formatColumnHeader('EMPLOYEE_ID', 'INTEGER');
+ * // Returns: 'EMPLOYEE_ID (INTEGER)'
+ *
+ * formatColumnHeader('NAME', 'VARCHAR(50)');
+ * // Returns: 'NAME (VARCHAR)'
+ *
+ * formatColumnHeader('STATUS');
+ * // Returns: 'STATUS'
+ * ```
+ */
+export function formatColumnHeader(columnName, columnType) {
+    if (!columnType) {
+        return columnName;
+    }
+    // Extract base type without precision/scale
+    const baseType = columnType.split("(")[0].trim().toUpperCase();
+    return `${columnName} (${baseType})`;
+}
+/**
+ * Build a column alignment map for use with TableFormatter.
+ * Maps column names to their appropriate alignment based on their data types.
+ *
+ * @param columns - Array of column definitions with name and type
+ * @returns Record mapping column names to alignment values
+ *
+ * @example
+ * ```typescript
+ * const columns = [
+ *   { name: 'ID', type: 'INTEGER' },
+ *   { name: 'NAME', type: 'VARCHAR' },
+ *   { name: 'SALARY', type: 'DECIMAL' }
+ * ];
+ *
+ * buildColumnAlignmentMap(columns);
+ * // Returns: { ID: 'right', NAME: 'left', SALARY: 'right' }
+ * ```
+ */
+export function buildColumnAlignmentMap(columns) {
+    const alignmentMap = {};
+    for (const column of columns) {
+        alignmentMap[column.name] = getColumnAlignment(column.type);
+    }
+    return alignmentMap;
+}
+//# sourceMappingURL=sqlFormattingUtils.js.map

package/dist/utils/formatting/sqlFormattingUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlFormattingUtils.js","sourceRoot":"","sources":["../../../src/utils/formatting/sqlFormattingUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;GAGG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,SAAS;IACT,UAAU;IACV,QAAQ;IACR,SAAS;IACT,SAAS;IACT,OAAO;IACP,MAAM;IACN,QAAQ;IACR,UAAU;IACV,KAAK;IACL,KAAK;CACN,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACzB,SAAS;IACT,MAAM;IACN,WAAW;IACX,MAAM;IACN,YAAY;IACZ,SAAS;IACT,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,WAAW;CACZ,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAA8B;IAC/D,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,MAAM,CAAC,CAAC,4BAA4B;IAC7C,CAAC;IAED,+DAA+D;IAC/D,MAAM,cAAc,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC;IAEtE,wBAAwB;IACxB,IAAI,aAAa,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;QACtC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;QACzE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,8CAA8C;IAC9C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAkB,EAClB,UAAmB;IAEnB,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,4CAA4C;IAC5C,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAChE,OAAO,GAAG,UAAU,KAAK,QAAQ,GAAG,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAA+C;IAE/C,MAAM,YAAY,GAA8B,EAAE,CAAC;IAEnD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC"}

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

@@ -0,0 +1,268 @@
+/**
+ * @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 "../index.js";
+/**
+ * Table output style options.
+ */
+export type TableStyle = "markdown" | "ascii" | "grid" | "compact";
+/**
+ * Column alignment options.
+ */
+export type Alignment = "left" | "center" | "right";
+/**
+ * Configuration options for table formatting.
+ */
+export interface TableFormatterOptions {
+    /**
+     * 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;
+    /**
+     * 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>;
+    /**
+     * Maximum width for any column. Content exceeding this will be truncated.
+     */
+    maxWidth?: number;
+    /**
+     * Whether to truncate long content with ellipsis (default: true).
+     * If false, content may wrap or overflow depending on style.
+     */
+    truncate?: boolean;
+    /**
+     * Header styling option.
+     * - bold: Headers in bold (markdown only)
+     * - uppercase: Convert headers to uppercase
+     * - none: No special header formatting
+     */
+    headerStyle?: "bold" | "uppercase" | "none";
+    /**
+     * Minimum column width (default: 3).
+     */
+    minWidth?: number;
+    /**
+     * Padding around cell content (default: 1 space).
+     */
+    padding?: number;
+    /**
+     * String to use for NULL/undefined values (default: '-').
+     * Use this to display NULL values in a more readable format.
+     */
+    nullReplacement?: string;
+}
+/**
+ * Result from table formatting with metadata.
+ * Includes the formatted table string and statistics about NULL values.
+ */
+export interface TableFormattingResult {
+    /**
+     * The formatted table as a string.
+     */
+    table: string;
+    /**
+     * Metadata about the formatting operation.
+     */
+    metadata: {
+        /**
+         * Count of NULL/undefined values per column.
+         * Key is column name (or index for raw arrays).
+         */
+        nullCounts: Record<string, number>;
+    };
+}
+/**
+ * Utility class for formatting tabular data into various table styles.
+ * Provides methods for rendering arrays of objects or raw 2D arrays as tables.
+ */
+export declare class TableFormatter {
+    /**
+     * Default formatting options.
+     * @private
+     */
+    private readonly defaultOptions;
+    /**
+     * Track NULL value counts per column during formatting.
+     * Reset before each formatting operation.
+     * @private
+     */
+    private nullCounts;
+    /**
+     * Format an array of objects as a table.
+     * Automatically extracts headers from object keys.
+     *
+     * @template T - Type of objects in the array
+     * @param data - Array of objects to format
+     * @param options - Table formatting options
+     * @param context - Optional request context for logging
+     * @returns Formatted table string
+     * @throws {McpError} If data is invalid or formatting fails
+     *
+     * @example
+     * ```typescript
+     * const data = [
+     *   { name: 'Alice', age: 30, role: 'Engineer' },
+     *   { name: 'Bob', age: 25, role: 'Designer' }
+     * ];
+     * const table = tableFormatter.format(data, { style: 'grid' });
+     * ```
+     */
+    format<T extends Record<string, unknown>>(data: T[], options?: TableFormatterOptions, context?: RequestContext): string;
+    /**
+     * Format a raw 2D array with explicit headers.
+     * Provides full control over headers and cell values.
+     *
+     * @param headers - Array of column headers
+     * @param rows - 2D array of cell values
+     * @param options - Table formatting options
+     * @param context - Optional request context for logging
+     * @returns Formatted table string
+     * @throws {McpError} If headers/rows are invalid or formatting fails
+     *
+     * @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;
+    /**
+     * Format an array of objects as a table with NULL value tracking.
+     * Returns both the formatted table and metadata about NULL values.
+     *
+     * @template T - Type of objects in the array
+     * @param data - Array of objects to format
+     * @param options - Table formatting options
+     * @param context - Optional request context for logging
+     * @returns Object containing formatted table and metadata
+     * @throws {McpError} If data is invalid or formatting fails
+     *
+     * @example
+     * ```typescript
+     * const data = [
+     *   { name: 'Alice', age: 30, salary: null },
+     *   { name: 'Bob', age: 25, salary: 50000 }
+     * ];
+     * const result = tableFormatter.formatWithMetadata(data, { style: 'grid' });
+     * console.log(result.table);
+     * console.log(result.metadata.nullCounts); // { salary: 1 }
+     * ```
+     */
+    formatWithMetadata<T extends Record<string, unknown>>(data: T[], options?: TableFormatterOptions, context?: RequestContext): TableFormattingResult;
+    /**
+     * Format a raw 2D array with NULL value tracking.
+     * Returns both the formatted table and metadata about NULL values.
+     *
+     * Note: For raw arrays, NULL tracking uses column indices as keys.
+     *
+     * @param headers - Array of column headers
+     * @param rows - 2D array of cell values (may contain null/undefined)
+     * @param options - Table formatting options
+     * @param context - Optional request context for logging
+     * @returns Object containing formatted table and metadata
+     * @throws {McpError} If headers/rows are invalid or formatting fails
+     *
+     * @example
+     * ```typescript
+     * const headers = ['Name', 'Age', 'Salary'];
+     * const rows = [
+     *   ['Alice', 30, null],
+     *   ['Bob', 25, 50000]
+     * ];
+     * const result = tableFormatter.formatRawWithMetadata(headers, rows);
+     * console.log(result.metadata.nullCounts); // { '2': 1 } (column index 2)
+     * ```
+     */
+    formatRawWithMetadata(headers: string[], rows: (string | null | undefined)[][], options?: TableFormatterOptions, context?: RequestContext): TableFormattingResult;
+    /**
+     * 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.
+     * Tracks NULL values per column when columnKey is provided.
+     * @private
+     */
+    private stringify;
+}
+/**
+ * Singleton instance of TableFormatter.
+ * Use this instance to format tabular data into various table styles.
+ *
+ * @example
+ * ```typescript
+ * import { tableFormatter } from '../index.js';
+ *
+ * const data = [
+ *   { name: 'Alice', age: 30, role: 'Engineer' },
+ *   { name: 'Bob', age: 25, role: 'Designer' }
+ * ];
+ *
+ * // Markdown table (default)
+ * console.log(tableFormatter.format(data));
+ *
+ * // Grid table with right-aligned age
+ * console.log(tableFormatter.format(data, {
+ *   style: 'grid',
+ *   alignment: { age: 'right' }
+ * }));
+ *
+ * // Compact table with uppercase headers
+ * console.log(tableFormatter.format(data, {
+ *   style: 'compact',
+ *   headerStyle: 'uppercase'
+ * }));
+ * ```
+ */
+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":"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"}