diff --git a/dist/ascii-table3.d.ts b/dist/ascii-table3.d.ts new file mode 100644 index 0000000..c77ad6a --- /dev/null +++ b/dist/ascii-table3.d.ts @@ -0,0 +1,514 @@ +/** + * Type imports. + */ +export type SectionStyle = import("./types").SectionStyle; +/** + * Type imports. + */ +export type Borders = import("./types").Borders; +/** + * Type imports. + */ +export type Style = import("./types").Style; +/** + * Type imports. + */ +export type ColumnFormatJSON = import("./types").ColumnFormatJSON; +/** + * Type imports. + */ +export type FormattingJSON = import("./types").FormattingJSON; +/** + * Type imports. + */ +export type TableJSON = import("./types").TableJSON; +/** + * Class for creating beautiful ASCII tables. + */ +export class AsciiTable3 { + /** + * Returns whether a value is numeric or not, irrespective of its type. + * @static + * @param {*} value Value to test. + * @returns {boolean} Whether the value is numeric or not. + */ + static isNumeric(value: any): boolean; + /** + * Pads the start of a string with a given string until the maximum length limit is reached. + * @param {string} str String to pad at the beggining. + * @param {number} maxLength The resulting string max lenght. + * @param {string} fillStr The new pad at the begginning (optional, defaults to ' '). + * @returns {string} Start-padded string. + */ + static padStart(str: string, maxLength: number, fillStr?: string): string; + /** + * Pads the end of a string with a given string until the maximum length limit is reached. + * @param {string} str String to pad at the end. + * @param {number} maxLength The resulting string max lenght. + * @param {string} fillStr The new pad at the end (optional, defaults to ' '). + * @returns {string} End-padded string. + */ + static padEnd(str: string, maxLength: number, fillStr?: string): string; + /** + * Generic string alignment. + * @static + * @param {number} direction The desired aligment direction according to the enum (left, right or center). + * @param {*} value The value to align. + * @param {number} len The maximum alignment length. + * @param {string} pad The pad char (optional, defaults to ' '). + * @returns {string} Aligned string. + */ + static align(direction: number, value: any, len: number, pad?: string): string; + /** + * Left string alignment. + * @static + * @param {*} value The value to align. + * @param {number} len The maximum alignment length. + * @param {string} [pad] The pad char (optional, defaults to ' '). + * @returns {string} Left aligned string. + */ + static alignLeft(value: any, len: number, pad?: string): string; + /** + * Right string alignment. + * @static + * @param {*} value The value to align. + * @param {number} len The maximum alignment length. + * @param {string} [pad] The pad char (optional, defaults to ' '). + * @returns {string} Right aligned string. + */ + static alignRight(value: any, len: number, pad?: string): string; + /** + * Center string alignment. + * @static + * @param {*} value The value to align. + * @param {number} len The maximum alignment length. + * @param {string} [pad] The pad char (optional, defaults to ' '). + * @returns {string} Center aligned string. + */ + static alignCenter(value: any, len: number, pad?: string): string; + /** + * Attempt to do intelligent alignment of provided value (string inputs will be left aligned, number types will be right aligned). + * @static + * @param {*} value The value to align. + * @param {number} len The maximum alignment length. + * @param {string} [pad] The pad char (optional, defaults to ' '). + */ + static alignAuto(value: any, len: number, pad?: string): string; + /** + * Wraps a string into multiple lines of a limited width. + * @param {string} str The string to wrap. + * @param {number} maxWidth The maximum width for the wrapped string. + * @returns {string} The wrapped string. + */ + static wordWrap(str: string, maxWidth: number): string; + /** + * Wraps a string into multiple lines of a limited width (simple string, no ANSI chars). + * @param {string} str The string to wrap. + * @param {number} maxWidth The maximum width for the wrapped string. + * @returns {string} The wrapped string. + */ + static wordWrapBasic(str: string, maxWidth: number): string; + /** + * Truncates a string up to a maximum number of characters (if needed). + * In case of truncation, '...' are appended to the end of the string. + * @static + * @param {string} str The string to truncate. + * @param {number} maxSize The string maximum size. + * @returns {string} The truncated string. + */ + static truncateString(str: string, maxSize: number): string; + /** + * Create a new array at the given len, filled with the given value, mainly used internally. + * @static + * @param {number} len Length of array. + * @param {*} [value] The fill value (optional). + * @returns {*[]} Array filled with with desired value. + */ + static arrayFill(len: number, value?: any): any[]; + /** + * Increases existing array size up to the desired limit. + * @static + * @param {*[]} array The array to increase. + * @param {number} len The desired array size. + * @param {*} [value] The fill value (optional). + */ + static arrayResize(array: any[], len: number, value?: any): void; + /** + * Default constructor. + * @param {string} [title] The table title (optional). + */ + constructor(title?: string); + /** @type {Style[]} */ + styles: Style[]; + /** + * Sets the output style for this table instance. + * @param {string} name The desired style name (defaults to "ramac" if not found). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setStyle(name: string): AsciiTable3; + style: any; + /** + * Gets the output style for this table instance. + * @returns {Style} The current table style settings. + */ + getStyle(): Style; + /** + * Gets all available pre-defined styles for this table. + * @returns {Style[]} Array of predefined border styles. + */ + getStyles(): Style[]; + /** + * Adds a new style to the style library. + * @param {Style} style The style object to add. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + addStyle(style: Style): AsciiTable3; + /** + * Removes border from table. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + removeBorder(): AsciiTable3; + /** + * Clear / reset all table data. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + clear(): AsciiTable3; + dataAlign: any; + colWidths: number[]; + wrapping: any; + /** + * Reset all row data, maintains title and headings. + * @returns {object} The AsciiTable3 object instance. + */ + clearRows(): object; + rows: any[]; + /** + * Title setter. + * @param {string} title The title to set (optional, defaults to ''). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setTitle(title?: string): AsciiTable3; + title: string; + /** + * Title getter. + * @returns {string} The table title. + */ + getTitle(): string; + /** + * Title alignment setter. + * @param {number} direction The desired title aligment direction according to the enum (left, right or center). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setTitleAlign(direction: number): AsciiTable3; + titleAlignment: number; + /** + * Left title alignment setter. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setTitleAlignLeft(): AsciiTable3; + /** + * Right title alignment setter. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setTitleAlignRight(): AsciiTable3; + /** + * Center title alignment setter. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setTitleAlignCenter(): AsciiTable3; + /** + * Title alignment getter. + * @returns {number} The table title alignment direction. + */ + getTitleAlign(): number; + /** + * Table heading setter. + * @param {*[]} args Headings to set. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setHeading(...args: any[]): AsciiTable3; + heading: any; + /** + * Table heading getter. + * @returns {*[]} Array with heading values. + */ + getHeading(): any[]; + /** + * Heading alignment setter. + * @param {number} direction The desired heading aligment direction according to the enum (left, right or center). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setHeadingAlign(direction: number): AsciiTable3; + headingAlign: number; + /** + * Left heading alignment setter. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setHeadingAlignLeft(): AsciiTable3; + /** + * Right heading alignment setter. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setHeadingAlignRight(): AsciiTable3; + /** + * Center heading alignment setter. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setHeadingAlignCenter(): AsciiTable3; + /** + * Heading alignment getter. + * @returns {number} The instance heading alignment. + */ + getHeadingAlign(): number; + /** + * Table row adder. + * @param {*[]} args Row cell values to set. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + addRow(...args: any[]): AsciiTable3; + /** + * Adds row to table only if all numeric values are not 0 (zero). + * @param {*[]} args Row cell values to set. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + addNonZeroRow(...args: any[]): AsciiTable3; + /** + * Bulk addRow operation. + * @param {*[][]} rows Multidimensional array of rows. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + addRowMatrix(rows: any[][]): AsciiTable3; + /** + * Table rows getter. + * @returns {*[]} Array with row cell values (column array). + */ + getRows(): any[]; + /** + * Sets cell value for this row and column combination. + * @param {number} row Desired row number (1-based index). + * @param {number} col Desired column number (1-based index). + * @param {*} value The cell value to set. + */ + setCell(row: number, col: number, value: any): void; + /** + * Gets cell value for this row and column combination. + * @param {number} row Desired row number (1-based index). + * @param {number} col Desired column number (1-based index). + * @returns {*} The cell value. + */ + getCell(row: number, col: number): any; + /** + * Sets the preset width for a given column rendering output. + * @param {number} idx Column index to align (starts at 1). + * @param {number} width The maximum width for this column (in characters). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setWidth(idx: number, width: number): AsciiTable3; + /** + * Gets the preset width for a given column rendering output. + * @param {number} idx Column index to align (starts at 1). + * @returns {number} The maximum rendered size for this column. + */ + getWidth(idx: number): number; + /** + * Sets the present widths for each column using an array. + * @param {number[]} widths Array with widths for columns. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setWidths(widths: number[]): AsciiTable3; + /** + * Gets the present widths for each column (if any). + * @returns {number[]} Array with widths for columns. + */ + getWidths(): number[]; + /** + * Sets the internal cell margin (in characters) + * @param {number} margin + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setCellMargin(margin: number): AsciiTable3; + cellMargin: number; + /** + * Gets the internal cell margin (in characters) + * @returns {number} The cell margin in characters. + */ + getCellMargin(): number; + /** + * Sets the alignment direction for a given column. + * @param {number} idx Column index to align (starts at 1). + * @param {number} direction Desired alignment direction. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setAlign(idx: number, direction: number): AsciiTable3; + /** + * Get the alignment direction for a given column. + * @param {number} idx Column index to align (starts at 1). + * @returns {number} The alignment set for a column. + */ + getAlign(idx: number): number; + /** + * Sets the alignment direction for all table columns. + * @param {number[]} directions Desired alignment directions. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setAligns(directions: number[]): AsciiTable3; + /** + * Gets the alignment direction for all columns. + * @returns {number[]} Array with alignment settings for all columns. + */ + getAligns(): number[]; + /** + * Sets left alignment direction for a given column. + * @param {number} idx Column index to align (starts at 1). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setAlignLeft(idx: number): AsciiTable3; + /** + * Sets right alignment direction for a given column. + * @param {number} idx Column index to align (starts at 1). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setAlignRight(idx: number): AsciiTable3; + /** + * Sets center alignment direction for a given column. + * @param {number} idx Column index to align (starts at 1). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setAlignCenter(idx: number): AsciiTable3; + /** + * Sets the wrapping property for a specific column (wrapped content will generate more than one data row if needed). + * @param {number} idx Column index to align (starts at 1). + * @param {boolean} wrap Whether to wrap the content (default is true). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setWrapped(idx: number, wrap?: boolean): AsciiTable3; + /** + * Gets the wrapping setting for a given column. + * @param {number} idx Column index to get wrapping (starts at 1). + */ + isWrapped(idx: number): boolean; + /** + * Sets wrapping for all table columns. + * @param {boolean[]} wrapping Boolean array of wrapping settings. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + setWrappings(wrappings: any): AsciiTable3; + /** + * Gets the wrapping settings for all columns. + * @returns {boolean[]} Array with wrapping settings for all columns. + */ + getWrappings(): boolean[]; + /** + * Justify all columns to be the same width. + * @param {boolean} enabled Boolean for turning justify on or off (default is true). + */ + setJustify(enabled?: boolean): AsciiTable3; + justify: boolean; + /** + * Returns whether all columns are to be rendered with the same width. + * @returns {boolean} Whether all columns are to be rendered with the same width. + */ + isJustify(): boolean; + /** + * Transposes table by exchanging rows for columns. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + transpose(): AsciiTable3; + /** + * Return the JSON representation of the table, this also allows us to call JSON.stringify on the instance. + * @returns {string} The table JSON representation. + */ + toJSON(): string; + /** + * Populate the table from json object, should match the toJSON output above. + * @param {TableJSON} obj Object with table definition according to JSON structure. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + fromJSON(obj: TableJSON): AsciiTable3; + /** + * Sorts the table rows based on a specific methods. + * @param {function} func The comparison function to use when sorting. + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + sort(func: Function): AsciiTable3; + /** + * Sorts the table rows based on specific methods for a column. + * @param {number} idx The column number to base sort on (starts at 1). + * @param {function} func The comparison function to use when sorting (optional, for compatibility with AsciiTable). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + sortColumn(idx: number, func?: Function): AsciiTable3; + /** + * Reverse sorts the table rows based on specific methods for a column. + * @param {number} idx The column number to base sort on (starts at 1). + * @returns {AsciiTable3} The AsciiTable3 object instance. + */ + sortColumnDesc(idx: number): AsciiTable3; + /** + * Get the column sizes for table rendering (in characters). + * @private + * @returns {number[]} Array with column sizes for rendering. + */ + private getColumnsWidth; + /** + * Get string with the rendering of a horizontal line. + * @private + * @param {SectionStyle} posStyle The line style for the desired position (between top, middle and bottom). + * @param {number[]} colsWidth Array with the desired width for each data column. + * @returns {string} String representation of table horizontal line. + */ + private getHorizontalLine; + /** + * Get array of wrapped row data from a "normal" row. + * @private + * @param {*[]} row Row of data. + * @returns {string[]} Array of data rows after word wrapping. + */ + private getWrappedRows; + /** + * Get string with the rendering of a heading row (truncating if needed). + * @private + * @param {Style} posStyle The heading row style. + * @param {number[]} colsWidth Array with the desired width for each heading column. + * @param {string} row The heading row to generate. + * @returns {string} String representation of table heading row line. + */ + private getHeadingRowTruncated; + /** + * Get string with the rendering of a heading row. + * @private + * @param {Style} posStyle The heading row style. + * @param {number[]} colsWidth Array with the desired width for each heading column. + * @returns {string} String representation of table heading row line. + */ + private getHeadingRow; + /** + * Get string with the rendering of a data row (truncating if needed). + * @private + * @param {Style} posStyle The data row style. + * @param {number[]} colsWidth Array with the desired width for each data column. + * @param {*[]} row Array with cell values for this row. + * @returns {string} String representation of table data row line. + */ + private getDataRowTruncated; + /** + * Get string with the rendering of a data row (please not that it may result in several rows, depending on wrap settings). + * @private + * @param {Style} posStyle The data row style. + * @param {number[]} colsWidth Array with the desired width for each data column. + * @param {*[]} row Array with cell values for this row. + * @returns {string} String representation of table data row line. + */ + private getDataRow; + /** + * Render the instance as a string for output. + * @returns {string} String rendiring of this instance table. + */ + toString(): string; +} +export namespace AlignmentEnum { + const LEFT: number; + const RIGHT: number; + const CENTER: number; + const AUTO: number; +} diff --git a/ascii-table3.d.ts b/dist/types.d.ts similarity index 98% rename from ascii-table3.d.ts rename to dist/types.d.ts index 51f5218..071f397 100644 --- a/ascii-table3.d.ts +++ b/dist/types.d.ts @@ -6,12 +6,12 @@ * @property {string} right The right border character. * @property {string} colSeparator The column separator character. */ -export type SectionStyle = { + export type SectionStyle = { left: string, center: string, right: string, colSeparator: string -}; +} /** * Borders style definition. @@ -26,7 +26,7 @@ export type SectionStyle = { middle: SectionStyle, bottom: SectionStyle, data: SectionStyle - }; + } /** * Type definition for a table style. @@ -37,7 +37,7 @@ export type SectionStyle = { export type Style = { name: string, borders: Borders -}; +} /** * @typedef {object} ColumnFormatJSON @@ -49,7 +49,7 @@ export type ColumnFormatJSON = { aligns: number[], widths: number[], wrappings: boolean[] -}; +} /** * @typedef {object} FormattingJSON @@ -61,7 +61,7 @@ export type FormattingJSON = { titleAlign: number, columns: ColumnFormatJSON, justify: boolean -}; +} /** * @typedef {object} TableJSON @@ -75,4 +75,4 @@ export type TableJSON = { heading: string[], rows: string[][], formatting: FormattingJSON -}; +} \ No newline at end of file diff --git a/index.js b/index.js index 99e48b7..573e1c4 100644 --- a/index.js +++ b/index.js @@ -1 +1 @@ -module.exports = require('./ascii-table3'); \ No newline at end of file +module.exports = require('./src/ascii-table3'); \ No newline at end of file diff --git a/package.json b/package.json index 28be784..cf11b98 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ascii-table3", - "version": "0.7.8", + "version": "0.8.0", "author": "João Simões (https://github.com/AllMightySauron)", "description": "Javascript ASCII renderer for beautiful console-based tables", "repository": { @@ -20,6 +20,7 @@ } ], "main": "index.js", + "types": "dist/ascii-table3.d.ts", "engines": { "node": ">=11.14.0" }, @@ -27,10 +28,13 @@ "qa": "npm run hint && npm run coverage", "hint": "jshint ./", "test": "mocha -R spec", - "coverage": "nyc mocha" + "coverage": "nyc mocha", + "build": "copyfiles -u 1 \"src/**/*.d.ts\" dist && npx tsc" }, "devDependencies": { "jshint": "^2.12.0", + "typescript": "^4.9.3", + "copyfiles": "^2.4.1", "mocha": "^9.2.2", "nyc": "^15.1.0" }, diff --git a/sample_list_dir.js b/sample_list_dir.js index 2a22405..e5fd021 100644 --- a/sample_list_dir.js +++ b/sample_list_dir.js @@ -3,7 +3,7 @@ // load modules const fs = require('fs'); const chalk = require('chalk'); -const { AsciiTable3 } = require('./ascii-table3'); +const { AsciiTable3 } = require('./src/ascii-table3'); // get path to list from command line const path = process.argv.length <= 2 ? '.' : process.argv[2]; @@ -11,7 +11,7 @@ const path = process.argv.length <= 2 ? '.' : process.argv[2]; // build table const dirTable = new AsciiTable3(`Directory: ${path}`) - .setHeading(chalk.red('Type'), 'Name', 'Size (bytes)', 'Last change') + .setHeading('Type', 'Name', 'Size (bytes)', 'Last change') .setAlignRight(3).setWidth(4, 30); try { @@ -37,7 +37,16 @@ try { const size = type == 'Directory' ? '-' : new Intl.NumberFormat().format(stat.size); // add new table row - dirTable.addRow(chalk.green(type), chalk.blue(item), size, chalk.yellow(stat.ctime)); + switch (type) { + case 'Directory': + dirTable.addRow(chalk.blue(type), chalk.blue(item), chalk.blue(size), chalk.blue(stat.ctime)); + break; + case 'Socket': + dirTable.addRow(chalk.red(type), chalk.red(item), chalk.red(size), chalk.red(stat.ctime)); + break; + default: + dirTable.addRow(type, item, size, stat.ctime); + } } catch (err) { console.log(`${err}`); } diff --git a/samples.js b/samples.js index 42bb7ff..1b2d854 100644 --- a/samples.js +++ b/samples.js @@ -3,7 +3,7 @@ // example 1: base table console.log ('>>>>>> example 1. base table'); -const { AsciiTable3 } = require('./ascii-table3'); +const { AsciiTable3 } = require('./src/ascii-table3'); // create table const table = diff --git a/ascii-table3.js b/src/ascii-table3.js similarity index 94% rename from ascii-table3.js rename to src/ascii-table3.js index 49f0e2f..90c2ea4 100644 --- a/ascii-table3.js +++ b/src/ascii-table3.js @@ -2,18 +2,18 @@ /** * Type imports. - * @typedef { import("./ascii-table3").SectionStyle } SectionStyle - * @typedef { import("./ascii-table3").Borders } Borders - * @typedef { import("./ascii-table3").Style } Style - * @typedef { import("./ascii-table3").ColumnFormatJSON } ColumnFormatJSON - * @typedef { import("./ascii-table3").FormattingJSON } FormattingJSON - * @typedef { import("./ascii-table3").TableJSON } TableJSON + * @typedef { import("./types").SectionStyle } SectionStyle + * @typedef { import("./types").Borders } Borders + * @typedef { import("./types").Style } Style + * @typedef { import("./types").ColumnFormatJSON } ColumnFormatJSON + * @typedef { import("./types").FormattingJSON } FormattingJSON + * @typedef { import("./types").TableJSON } TableJSON */ /** * Filename containing rendering styles. */ -const STYLES_FILENAME = 'ascii-table3.styles.json'; +const STYLES_FILENAME = '../ascii-table3.styles.json'; /** * Alignment direction enum. @@ -47,9 +47,10 @@ class AsciiTable3 { } /** - * Returns wether a value is numeric or not, irrespective of its type. + * Returns whether a value is numeric or not, irrespective of its type. * @static * @param {*} value Value to test. + * @returns {boolean} Whether the value is numeric or not. */ static isNumeric(value) { return !isNaN(parseFloat(value)) && isFinite(value); @@ -59,7 +60,7 @@ class AsciiTable3 { * Pads the start of a string with a given string until the maximum length limit is reached. * @param {string} str String to pad at the beggining. * @param {number} maxLength The resulting string max lenght. - * @param {string} fillStr The new pad at the begginning. + * @param {string} fillStr The new pad at the begginning (optional, defaults to ' '). * @returns {string} Start-padded string. */ static padStart(str, maxLength, fillStr = ' ') { @@ -97,7 +98,7 @@ class AsciiTable3 { * Pads the end of a string with a given string until the maximum length limit is reached. * @param {string} str String to pad at the end. * @param {number} maxLength The resulting string max lenght. - * @param {string} fillStr The new pad at the end. + * @param {string} fillStr The new pad at the end (optional, defaults to ' '). * @returns {string} End-padded string. */ static padEnd(str, maxLength, fillStr = ' ') { @@ -133,10 +134,11 @@ class AsciiTable3 { /** * Generic string alignment. * @static - * @param {AlignmentEnum} direction The desired aligment direction according to the enum (left, right or center) + * @param {number} direction The desired aligment direction according to the enum (left, right or center). * @param {*} value The value to align. * @param {number} len The maximum alignment length. * @param {string} pad The pad char (optional, defaults to ' '). + * @returns {string} Aligned string. */ static align(direction, value, len, pad = ' ') { const strValue = '' + value; @@ -158,6 +160,7 @@ class AsciiTable3 { * @param {*} value The value to align. * @param {number} len The maximum alignment length. * @param {string} [pad] The pad char (optional, defaults to ' '). + * @returns {string} Left aligned string. */ static alignLeft(value, len, pad = ' ') { return this.align(AlignmentEnum.LEFT, value, len, pad); @@ -169,6 +172,7 @@ class AsciiTable3 { * @param {*} value The value to align. * @param {number} len The maximum alignment length. * @param {string} [pad] The pad char (optional, defaults to ' '). + * @returns {string} Right aligned string. */ static alignRight(value, len, pad = ' ') { return this.align(AlignmentEnum.RIGHT, value, len, pad); @@ -180,6 +184,7 @@ class AsciiTable3 { * @param {*} value The value to align. * @param {number} len The maximum alignment length. * @param {string} [pad] The pad char (optional, defaults to ' '). + * @returns {string} Center aligned string. */ static alignCenter(value, len, pad = ' ') { return this.align(AlignmentEnum.CENTER, value, len, pad); @@ -205,7 +210,7 @@ class AsciiTable3 { /** * Wraps a string into multiple lines of a limited width. * @param {string} str The string to wrap. - * @param {num} maxWidth The maximum width for the wrapped string. + * @param {number} maxWidth The maximum width for the wrapped string. * @returns {string} The wrapped string. */ static wordWrap(str, maxWidth) { @@ -240,7 +245,7 @@ class AsciiTable3 { /** * Wraps a string into multiple lines of a limited width (simple string, no ANSI chars). * @param {string} str The string to wrap. - * @param {num} maxWidth The maximum width for the wrapped string. + * @param {number} maxWidth The maximum width for the wrapped string. * @returns {string} The wrapped string. */ static wordWrapBasic(str, maxWidth) { @@ -323,7 +328,7 @@ class AsciiTable3 { /** * Increases existing array size up to the desired limit. * @static - * @param {Array} array The array to increase. + * @param {*[]} array The array to increase. * @param {number} len The desired array size. * @param {*} [value] The fill value (optional). */ @@ -427,8 +432,8 @@ class AsciiTable3 { /** * Title setter. - * @param {string} title The title to set. - * @returns {object} The AsciiTable3 object instance. + * @param {string} title The title to set (optional, defaults to ''). + * @returns {AsciiTable3} The AsciiTable3 object instance. */ setTitle(title = '') { this.title = title; @@ -446,7 +451,7 @@ class AsciiTable3 { /** * Title alignment setter. - * @param {AlignmentEnum} direction The desired title aligment direction according to the enum (left, right or center) + * @param {number} direction The desired title aligment direction according to the enum (left, right or center). * @returns {AsciiTable3} The AsciiTable3 object instance. */ setTitleAlign(direction) { @@ -481,7 +486,7 @@ class AsciiTable3 { /** * Title alignment getter. - * @returns {AlignmentEnum} The table title alignment direction. + * @returns {number} The table title alignment direction. */ getTitleAlign() { return this.titleAlignment; @@ -514,7 +519,7 @@ class AsciiTable3 { /** * Heading alignment setter. - * @param {AlignmentEnum} direction The desired heading aligment direction according to the enum (left, right or center) + * @param {number} direction The desired heading aligment direction according to the enum (left, right or center). * @returns {AsciiTable3} The AsciiTable3 object instance. */ setHeadingAlign(direction) { @@ -549,7 +554,7 @@ class AsciiTable3 { /** * Heading alignment getter. - * @returns {AlignmentEnum} The instance heading alignment. + * @returns {number} The instance heading alignment. */ getHeadingAlign() { return this.headingAlign; @@ -608,7 +613,7 @@ class AsciiTable3 { /** * Bulk addRow operation. - * @param {*[]} rows Multidimensional array of rows. + * @param {*[][]} rows Multidimensional array of rows. * @returns {AsciiTable3} The AsciiTable3 object instance. */ addRowMatrix(rows) { @@ -729,7 +734,7 @@ class AsciiTable3 { /** * Sets the alignment direction for a given column. * @param {number} idx Column index to align (starts at 1). - * @param {AlignmentEnum} direction Desired alignment direction. + * @param {number} direction Desired alignment direction. * @returns {AsciiTable3} The AsciiTable3 object instance. */ setAlign(idx, direction) { @@ -750,7 +755,7 @@ class AsciiTable3 { /** * Get the alignment direction for a given column. * @param {number} idx Column index to align (starts at 1). - * @returns {AlignmentEnum} The alignment set for a column. + * @returns {number} The alignment set for a column. */ getAlign(idx) { var result = AlignmentEnum.AUTO; @@ -765,7 +770,7 @@ class AsciiTable3 { /** * Sets the alignment direction for all table columns. - * @param {AlignmentEnum[]} directions Desired alignment directions. + * @param {number[]} directions Desired alignment directions. * @returns {AsciiTable3} The AsciiTable3 object instance. */ setAligns(directions) { @@ -776,7 +781,7 @@ class AsciiTable3 { /** * Gets the alignment direction for all columns. - * @returns {AlignmentEnum[]} Array with alignment settings for all columns. + * @returns {number[]} Array with alignment settings for all columns. */ getAligns() { if (!this.dataAlign) { @@ -870,8 +875,8 @@ class AsciiTable3 { } /** - * Gets the alignment direction for all columns. - * @returns {AlignmentEnum[]} Array with alignment settings for all columns. + * Gets the wrapping settings for all columns. + * @returns {boolean[]} Array with wrapping settings for all columns. */ getWrappings() { if (!this.wrapping) { @@ -1120,7 +1125,7 @@ class AsciiTable3 { * Get array of wrapped row data from a "normal" row. * @private * @param {*[]} row Row of data. - * @returns Array of data rows after word wrapping. + * @returns {string[]} Array of data rows after word wrapping. */ getWrappedRows(row) { // setup a new wrapped row diff --git a/src/types.d.ts b/src/types.d.ts new file mode 100644 index 0000000..071f397 --- /dev/null +++ b/src/types.d.ts @@ -0,0 +1,78 @@ +/** + * Type definition for table section style. + * @typedef {Object} SectionStyle + * @property {string} left The left border character. + * @property {string} center The center border character. + * @property {string} right The right border character. + * @property {string} colSeparator The column separator character. + */ + export type SectionStyle = { + left: string, + center: string, + right: string, + colSeparator: string +} + + /** + * Borders style definition. + * @typedef {Object} Borders + * @property {SectionStyle} top The style for top section borders (above heading). + * @property {SectionStyle} middle The style for middle section borders (between heading and data). + * @property {SectionStyle} bottom The style for bottom section borders (below data). + * @property {SectionStyle} data The style for data row borders. + */ + export type Borders = { + top: SectionStyle, + middle: SectionStyle, + bottom: SectionStyle, + data: SectionStyle + } + +/** + * Type definition for a table style. + * @typedef {Object} Style + * @property {string} name Style name. + * @property {Borders} borders The border styles for each section. + */ +export type Style = { + name: string, + borders: Borders +} + +/** + * @typedef {object} ColumnFormatJSON + * @property {number[]} aligns Alignment setting for each data column. + * @property {number[]} widths Width setting for each data column. + * @property {boolean[]} wrappings Wrapping setting for each data column. + */ +export type ColumnFormatJSON = { + aligns: number[], + widths: number[], + wrappings: boolean[] +} + +/** + * @typedef {object} FormattingJSON + * @property {number} titleAlign Title alignment setting. + * @property {ColumnFormatJSON} columns Format settings for each column. + * @property {boolean} justify Whether to justify table columns. + */ +export type FormattingJSON = { + titleAlign: number, + columns: ColumnFormatJSON, + justify: boolean +} + +/** + * @typedef {object} TableJSON + * @property {string} title Table title text. + * @property {string[]} heading Array of table column headings. + * @property {string[][]} rows Array of table rows (each row contains an array of data columns). + * @property {FormattingJSON} formatting Table formatting settings. + */ +export type TableJSON = { + title: string, + heading: string[], + rows: string[][], + formatting: FormattingJSON +} \ No newline at end of file diff --git a/test/ascii-table3.test.js b/test/ascii-table3.test.js index 7d3834f..0131762 100644 --- a/test/ascii-table3.test.js +++ b/test/ascii-table3.test.js @@ -2,7 +2,7 @@ const assert = require('assert'); const chalk = require('chalk'); -const { AsciiTable3, AlignmentEnum } = require('../ascii-table3'); +const { AsciiTable3, AlignmentEnum } = require('../src/ascii-table3'); // static methods describe('String methods', () => { diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..cbb4b95 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,22 @@ +{ + // src files + "include": ["src/**/*"], + + "compilerOptions": { + // Tells TypeScript to read JS files, as + // normally they are ignored as source files + "allowJs": true, + + // Generate d.ts files + "declaration": true, + + // This compiler run should + // only output d.ts files + "emitDeclarationOnly": true, + + // Types should go into this directory. + // Removing this would place the .d.ts files + // next to the .js files + "outDir": "dist" + } + } \ No newline at end of file