@seedcord/utils 0.6.1 → 0.7.0-next.0

package/dist/index.mjs

@@ -6,6 +6,19 @@ import * as path from "node:path";
 * Exhaustiveness guard for discriminated unions. Place in the `default` branch of a `switch` over a
 * union's discriminant: if a new variant is added without a matching case, the call fails to compile.
 * Throws at runtime if reached with a value the types said was impossible.
+*
+* @example
+* ```ts
+* type Shape = { kind: 'circle' } | { kind: 'square' };
+*
+* function area(shape: Shape): number {
+*   switch (shape.kind) {
+*     case 'circle': return Math.PI;
+*     case 'square': return 1;
+*     default: return assertNever(shape); // compile error if a Shape variant is added
+*   }
+* }
+* ```
 */
 function assertNever(value) {
 	throw new Error(`Unhandled discriminated union member: ${JSON.stringify(value)}`);
@@ -28,6 +41,17 @@ function isTsOrJsFile(entry) {
 * @param dir - The directory path to traverse.
 * @param callback - A function that will be called for each imported module. It receives the full file path, the file's relative path, and the imported module as arguments.
 * @returns A Promise that resolves when the traversal is complete.
+*
+* @example
+* ```ts
+* await traverseDirectory(
+*   './commands',
+*   (fullPath, relativePath, imported) => {
+*     for (const exported of Object.values(imported)) register(exported);
+*   },
+*   logger
+* );
+* ```
 */
 async function traverseDirectory(dir, callback, logger) {
 	let entries;
@@ -49,6 +73,14 @@ async function traverseDirectory(dir, callback, logger) {
 * @param filePath - The file path to format.
 * @param options - Formatting options.
 * @returns The formatted file path.
+*
+* @example
+* ```ts
+* // cwd is /repo
+* formatFilePath('/repo/src/Bot.ts'); // './src/Bot.ts'
+* formatFilePath('/repo/src/Bot.ts', { onlyDir: true }); // './src'
+* formatFilePath('/repo/src/Bot.ts', { prefix: '' }); // 'src/Bot.ts'
+* ```
 */
 function formatFilePath(filePath, options = {}) {
 	const { onlyDir = false, prefix = "./" } = options;
@@ -104,6 +136,11 @@ function currentTime() {
 *
 * @param digits - The number of digits for the generated code.
 * @returns A random numeric code with the specified number of digits.
+*
+* @example
+* ```ts
+* generateCode(6); // e.g. 482915
+* ```
 */
 function generateCode(digits) {
 	const min = Math.pow(10, digits - 1);
@@ -157,6 +194,14 @@ const DURATION_PATTERN = new RegExp(`^(\\d+)(${Object.keys(UNIT_MS).join("|")})$
 *
 * @param input - The duration string to parse.
 * @returns The duration in milliseconds, or `null` if `input` is not a well-formed positive duration.
+*
+* @example
+* ```ts
+* parseDuration('24h'); // 86400000
+* parseDuration('30m'); // 1800000
+* parseDuration('1.5h'); // null
+* parseDuration('foo'); // null
+* ```
 */
 function parseDuration(input) {
 	const match = DURATION_PATTERN.exec(input);
@@ -174,6 +219,12 @@ function parseDuration(input) {
 * @param num2 - The second number.
 *
 * @returns The percentage of the first number in the second number with two decimal places.
+*
+* @example
+* ```ts
+* percentage(25, 200); // 12.5
+* percentage(1, 3); // 33.33
+* ```
 */
 function percentage(num1, num2) {
 	return Number((num1 / num2 * 100).toFixed(2));
@@ -187,6 +238,12 @@ function percentage(num1, num2) {
 * @param num - The number to be rounded.
 * @param precision - The number of decimal places to round to.
 * @returns The rounded number.
+*
+* @example
+* ```ts
+* round(3.14159, 2); // 3.14
+* round(2.5, 0); // 3
+* ```
 */
 function round(num, precision) {
 	const factor = Math.pow(10, precision);
@@ -430,6 +487,11 @@ function keepDefined(source, ...keys) {
 * Returns the word with its first letter capitalized and the rest in lowercase.
 * @param word - The word to be formatted.
 * @returns The formatted word.
+*
+* @example
+* ```ts
+* capitalize('hELLO'); // 'Hello'
+* ```
 */
 function capitalize(word) {
 	return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
@@ -442,55 +504,320 @@ function capitalize(word) {
 *
 * @param arr - The array of strings or numbers
 * @returns The length of the longest element when converted to string
+*
+* @example
+* ```ts
+* longestStringLength(['ab', 12345]); // 5
+* ```
 */
 function longestStringLength(arr) {
 	return Math.max(...arr.map((el) => el.toString().length));
 }
 
 //#endregion
-//#region src/strings/generateAsciiTable.ts
-/**
-* Generates an ASCII table from the provided data.
-*
-* @param data - The data to be displayed in the table.
-* @returns The generated ASCII table as a string.
-*/
-function generateAsciiTable(data) {
-	if (data.length === 0) return "";
-	const firstRow = data[0];
-	if (!firstRow || firstRow.length === 0) return "";
-	let table = "";
-	const columnWidths = [];
-	for (let i = 0; i < firstRow.length; i++) {
-		let maxWidth = 0;
-		for (const row of data) {
-			const cell = row[i];
-			if (cell !== void 0) maxWidth = Math.max(maxWidth, cell.length);
+//#region src/strings/renderTable/borders.ts
+const DOUBLE = {
+	top: {
+		left: "╔",
+		mid: "╦",
+		right: "╗",
+		fill: "═"
+	},
+	bottom: {
+		left: "╚",
+		mid: "╩",
+		right: "╝",
+		fill: "═"
+	},
+	sep: {
+		left: "╟",
+		mid: "╫",
+		right: "╢",
+		fill: "─"
+	},
+	headerSep: {
+		left: "╠",
+		mid: "╬",
+		right: "╣",
+		fill: "═"
+	},
+	vertical: "║"
+};
+const ROUNDED = {
+	top: {
+		left: "╭",
+		mid: "┬",
+		right: "╮",
+		fill: "─"
+	},
+	bottom: {
+		left: "╰",
+		mid: "┴",
+		right: "╯",
+		fill: "─"
+	},
+	sep: {
+		left: "├",
+		mid: "┼",
+		right: "┤",
+		fill: "─"
+	},
+	headerSep: {
+		left: "├",
+		mid: "┼",
+		right: "┤",
+		fill: "─"
+	},
+	vertical: "│"
+};
+const ASCII = {
+	top: {
+		left: "+",
+		mid: "+",
+		right: "+",
+		fill: "-"
+	},
+	bottom: {
+		left: "+",
+		mid: "+",
+		right: "+",
+		fill: "-"
+	},
+	sep: {
+		left: "+",
+		mid: "+",
+		right: "+",
+		fill: "-"
+	},
+	headerSep: {
+		left: "+",
+		mid: "+",
+		right: "+",
+		fill: "-"
+	},
+	vertical: "|"
+};
+const BORDERS = {
+	double: DOUBLE,
+	rounded: ROUNDED,
+	ascii: ASCII
+};
+
+//#endregion
+//#region src/strings/renderTable/displayWidth.ts
+const segmenter = new Intl.Segmenter();
+const ZERO_WIDTH_RANGES = [
+	[8203, 8203],
+	[768, 879],
+	[6832, 6911],
+	[7616, 7679],
+	[8400, 8447],
+	[65056, 65071]
+];
+const WIDE_RANGES = [
+	[4352, 4447],
+	[11904, 12350],
+	[12353, 13311],
+	[13312, 19903],
+	[19968, 40959],
+	[40960, 42191],
+	[44032, 55203],
+	[63744, 64255],
+	[65072, 65103],
+	[65280, 65376],
+	[65504, 65510],
+	[127744, 129791],
+	[131072, 262141]
+];
+function inRanges(cp, ranges) {
+	return ranges.some(([lo, hi]) => cp >= lo && cp <= hi);
+}
+function segmentWidth(segment) {
+	const cp = segment.codePointAt(0) ?? 0;
+	if (inRanges(cp, ZERO_WIDTH_RANGES)) return 0;
+	return inRanges(cp, WIDE_RANGES) ? 2 : 1;
+}
+function displayWidth(text) {
+	let width = 0;
+	for (const { segment } of segmenter.segment(text)) width += segmentWidth(segment);
+	return width;
+}
+function segments(text) {
+	return Array.from(segmenter.segment(text), (entry) => entry.segment);
+}
+function takeWidth(text, maxColumns) {
+	let width = 0;
+	let taken = "";
+	for (const segment of segments(text)) {
+		const next = width + segmentWidth(segment);
+		if (next > maxColumns) break;
+		width = next;
+		taken += segment;
+	}
+	return taken;
+}
+function hardBreak(token, maxColumns) {
+	const pieces = [];
+	let rest = token;
+	while (displayWidth(rest) > maxColumns) {
+		const head = takeWidth(rest, maxColumns);
+		pieces.push(head);
+		rest = rest.slice(head.length);
+	}
+	if (rest.length > 0) pieces.push(rest);
+	return pieces;
+}
+function wrapText(text, maxColumns) {
+	const lines = [];
+	let current = "";
+	for (const token of text.split(" ")) {
+		const candidate = current === "" ? token : `${current} ${token}`;
+		if (displayWidth(candidate) <= maxColumns) {
+			current = candidate;
+			continue;
+		}
+		if (current !== "") lines.push(current);
+		if (displayWidth(token) <= maxColumns) {
+			current = token;
+			continue;
 		}
-		columnWidths.push(maxWidth);
+		const pieces = hardBreak(token, maxColumns);
+		current = pieces.pop() ?? "";
+		lines.push(...pieces);
 	}
-	const createLine = (char, left, intersect, right) => {
-		let line = left;
-		columnWidths.forEach((width, index) => {
-			line += char.repeat(width + 2);
-			if (index < columnWidths.length - 1) line += intersect;
-			else line += right;
-		});
-		line += "\n";
-		return line;
+	if (current !== "" || lines.length === 0) lines.push(current);
+	return lines;
+}
+
+//#endregion
+//#region src/strings/renderTable/cells.ts
+const ELLIPSIS = "…";
+function wrapFence(content) {
+	return `\`\`\`\n${content}\`\`\``;
+}
+function truncate(content, maxWidth) {
+	if (displayWidth(content) <= maxWidth) return content;
+	return takeWidth(content, maxWidth - displayWidth(ELLIPSIS)) + ELLIPSIS;
+}
+function isNumericColumn(grid, col, header) {
+	const cells = (header ? grid.slice(1) : grid).map((row) => row[col] ?? "").filter((cell) => cell !== "");
+	return cells.length > 0 && cells.every((cell) => !Number.isNaN(Number(cell)));
+}
+function padCell(content, columnWidth, align) {
+	const slack = columnWidth - displayWidth(content);
+	if (align === "right") return " ".repeat(slack) + content;
+	if (align === "center") {
+		const left = Math.floor(slack / 2);
+		return " ".repeat(left) + content + " ".repeat(slack - left);
+	}
+	return content + " ".repeat(slack);
+}
+
+//#endregion
+//#region src/strings/renderTable/markdown.ts
+function renderMarkdown(grid, columnCount, alignments, pad) {
+	const escapeCell = (value) => value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+	const escaped = grid.map((row) => Array.from({ length: columnCount }, (_, col) => escapeCell(row[col] ?? "")));
+	const columnWidths = Array.from({ length: columnCount }, (_, col) => escaped.reduce((max, row) => Math.max(max, displayWidth(row[col] ?? "")), 0));
+	const cell = (content, col) => pad + padCell(content, columnWidths[col] ?? 0, alignments[col] ?? "left") + pad;
+	const row = (cells) => `|${columnWidths.map((_, col) => cell(cells[col] ?? "", col)).join("|")}|`;
+	const delimiterCell = (col) => {
+		const align = alignments[col] ?? "left";
+		if (align === "center") return " :---: ";
+		if (align === "right") return " ---: ";
+		return " --- ";
 	};
-	table += createLine("═", "╔", "╦", "╗");
-	data.forEach((row, rowIndex) => {
-		table += "║";
-		row.forEach((cell, columnIndex) => {
-			const columnWidth = columnWidths[columnIndex];
-			if (columnWidth !== void 0) table += ` ${cell.padEnd(columnWidth)} ║`;
-		});
-		table += "\n";
-		if (rowIndex < data.length - 1) table += createLine("─", "╠", "╬", "╣");
-		else table += createLine("═", "╚", "╩", "╝");
+	const [head = [], ...body] = escaped;
+	const delimiter = `|${columnWidths.map((_, col) => delimiterCell(col)).join("|")}|`;
+	return `${[
+		row(head),
+		delimiter,
+		...body.map(row)
+	].join("\n")}\n`;
+}
+
+//#endregion
+//#region src/strings/renderTable/renderSingle.ts
+function renderSingle(data, options) {
+	if (data.length === 0) return "";
+	const { align, border = "rounded", header = true, padding = 1, emptyCell = "", numericAlign = false, maxWidth, overflow = "wrap", fence } = options ?? {};
+	const columnCount = data.reduce((max, row) => Math.max(max, row.length), 0);
+	if (columnCount === 0) return "";
+	const grid = data.map((row) => Array.from({ length: columnCount }, (_, i) => {
+		const cell = (row[i] ?? "").replace(/\r?\n/g, " ");
+		const filled = cell === "" ? emptyCell : cell;
+		if (maxWidth === void 0 || overflow !== "truncate") return filled;
+		return truncate(filled, maxWidth);
+	}));
+	const alignments = Array.from({ length: columnCount }, (_, col) => {
+		const explicit = typeof align === "string" ? align : align?.[col];
+		if (explicit) return explicit;
+		if (numericAlign && isNumericColumn(grid, col, header)) return "right";
+		return "left";
 	});
-	return table;
+	const pad = " ".repeat(padding);
+	if (border === "markdown") {
+		const md = renderMarkdown(grid, columnCount, alignments, pad);
+		return fence ? wrapFence(md) : md;
+	}
+	const wrap = maxWidth !== void 0 && overflow === "wrap";
+	const rows = grid.map((row) => row.map((cell) => wrap ? wrapText(cell, maxWidth) : [cell]));
+	const columnWidths = Array.from({ length: columnCount }, (_, col) => rows.reduce((max, row) => Math.max(max, (row[col] ?? []).reduce((w, line) => Math.max(w, displayWidth(line)), 0)), 0));
+	const chars = BORDERS[border];
+	function drawLine(part) {
+		const segments = columnWidths.map((width) => part.fill.repeat(width + padding * 2));
+		return part.left + segments.join(part.mid) + part.right;
+	}
+	function renderRow(row) {
+		const lineCount = row.reduce((max, cellLines) => Math.max(max, cellLines.length), 1);
+		return Array.from({ length: lineCount }, (_, line) => columnWidths.map((width, col) => pad + padCell(row[col]?.[line] ?? "", width, alignments[col] ?? "left") + pad).join(chars.vertical)).map((line) => chars.vertical + line + chars.vertical).join("\n");
+	}
+	const lines = [drawLine(chars.top)];
+	rows.forEach((row, rowIndex) => {
+		lines.push(renderRow(row));
+		if (rowIndex >= rows.length - 1) return;
+		lines.push(drawLine(header && rowIndex === 0 ? chars.headerSep : chars.sep));
+	});
+	lines.push(drawLine(chars.bottom));
+	const body = `${lines.join("\n")}\n`;
+	return fence ? wrapFence(body) : body;
+}
+
+//#endregion
+//#region src/strings/renderTable/pagination.ts
+const DEFAULT_BUDGET = 2e3;
+function paginate(data, options) {
+	if (data.length === 0) return [];
+	const { budget = DEFAULT_BUDGET, ...tableOptions } = options;
+	const header = tableOptions.header === false ? void 0 : data[0];
+	const body = header ? data.slice(1) : data;
+	const render = (rows) => renderSingle(header ? [header, ...rows] : rows, tableOptions);
+	if (body.length === 0) return [render([])];
+	const pages = [];
+	let current = [];
+	for (const row of body) {
+		if (current.length === 0 || render([...current, row]).length <= budget) {
+			current.push(row);
+			continue;
+		}
+		pages.push(render(current));
+		current = [row];
+	}
+	pages.push(render(current));
+	return pages;
+}
+
+//#endregion
+//#region src/strings/renderTable/renderTable.ts
+function renderTable(data, options) {
+	if (options) validateOptions(options);
+	if (options && "budget" in options) return paginate(data, options);
+	return renderSingle(data, options);
+}
+function validateOptions(options) {
+	const { maxWidth, padding } = options;
+	if (maxWidth !== void 0 && (!Number.isInteger(maxWidth) || maxWidth < 1)) throw new RangeError(`renderTable maxWidth must be a positive integer, got ${maxWidth}`);
+	if (padding !== void 0 && (!Number.isInteger(padding) || padding < 0)) throw new RangeError(`renderTable padding must be a non-negative integer, got ${padding}`);
 }
 
 //#endregion
@@ -540,8 +867,8 @@ function prettyDifference(numBefore, numAfter) {
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.6.1";
+const version = "0.7.0-next.0";
 
 //#endregion
-export { assertNever, capitalize, currentTime, filterCirculars, formatFilePath, fyShuffle, generateAsciiTable, generateCode, hasKeys, isTsOrJsFile, keepDefined, longestStringLength, ordinal, parseDuration, percentage, prettify, prettyDifference, round, roundToDenomination, toEpochSeconds, traverseDirectory, version };
+export { assertNever, capitalize, currentTime, filterCirculars, formatFilePath, fyShuffle, generateCode, hasKeys, isTsOrJsFile, keepDefined, longestStringLength, ordinal, parseDuration, percentage, prettify, prettyDifference, renderTable, round, roundToDenomination, toEpochSeconds, traverseDirectory, version };
 //# sourceMappingURL=index.mjs.map