@heinrichb/console-toolkit 1.0.7 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heinrichb/console-toolkit",
-	"version": "1.0.7",
+	"version": "1.0.8",
 	"description": "A versatile TypeScript utility library for enhanced console logging, formatting, and layout management.",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -14,9 +14,10 @@
 	],
 	"scripts": {
 		"demo": "bun run scripts/run-demo.ts",
-		"test": "bun run build && bun test src",
-		"test:coverage": "bun run build && bun test src --coverage --coverage-threshold=100",
-		"build": "bun x tsc",
+		"test": "bun test src",
+		"test:coverage": "bun test src --coverage --coverage-threshold=100",
+		"build": "bun run scripts/build.ts",
+		"typecheck": "bun x tsc --noEmit",
 		"format:check": "prettier --check \"src/**/*.{ts,json,md}\"",
 		"format:write": "prettier --write \"src/**/*.{ts,json,md}\"",
 		"lint": "eslint \"src/**/*.ts\"",
@@ -37,7 +38,6 @@
 		"eslint": "^10.0.2",
 		"eslint-config-prettier": "^10.1.8",
 		"globals": "^17.3.0",
-		"jiti": "^2.6.1",
 		"prettier": "^3.8.1",
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.56.1"

package/dist/components/progress.d.ts

@@ -1,75 +0,0 @@
-import { PrintLine, PrintStyle } from "../core/types";
-export interface ProgressBarOptions {
-    /**
-     * Progress value between 0.0 and 1.0.
-     */
-    progress: number;
-    /**
-     * Width of the progress bar (excluding brackets and percentage).
-     * Defaults to 20.
-     */
-    width?: number;
-    /**
-     * Base style for the entire progress bar.
-     */
-    style?: PrintStyle;
-    /**
-     * Style for the brackets (start and end characters).
-     * Defaults to `style`.
-     */
-    bracketStyle?: PrintStyle;
-    /**
-     * Specific style for the start bracket. Overrides `bracketStyle`.
-     */
-    startStyle?: PrintStyle;
-    /**
-     * Specific style for the end bracket. Overrides `bracketStyle`.
-     */
-    endStyle?: PrintStyle;
-    /**
-     * Style for the bar (filled and empty parts).
-     * Defaults to `style`.
-     */
-    barStyle?: PrintStyle;
-    /**
-     * Specific style for the filled part. Overrides `barStyle`.
-     */
-    fillStyle?: PrintStyle;
-    /**
-     * Specific style for the empty part. Overrides `barStyle`.
-     */
-    emptyStyle?: PrintStyle;
-    /**
-     * Style for the percentage text.
-     * Defaults to `style`.
-     */
-    percentageStyle?: PrintStyle;
-    /**
-     * Character to use for the start bracket. Defaults to `[`.
-     */
-    startChar?: string;
-    /**
-     * Character to use for the end bracket. Defaults to `]`.
-     */
-    endChar?: string;
-    /**
-     * Character to use for the filled part. Defaults to `█`.
-     */
-    fillChar?: string;
-    /**
-     * Character to use for the empty part. Defaults to `░`.
-     */
-    emptyChar?: string;
-    /**
-     * Whether to show the percentage text. Defaults to `true`.
-     */
-    showPercentage?: boolean;
-    /**
-     * Custom formatter for the percentage text.
-     */
-    formatPercentage?: (progress: number) => string;
-}
-/**
- * Creates a PrintLine representing a progress bar.
- */
-export declare function createProgressBar(options: ProgressBarOptions): PrintLine;

package/dist/components/progress.js

@@ -1,42 +0,0 @@
-/**
- * Creates a PrintLine representing a progress bar.
- */
-export function createProgressBar(options) {
-    const { progress, width = 20, style, bracketStyle, startStyle, endStyle, barStyle, fillStyle, emptyStyle, percentageStyle, startChar = "[", endChar = "]", fillChar = "█", emptyChar = "░", showPercentage = true, formatPercentage } = options;
-    // Clamp progress
-    const p = Math.max(0, Math.min(1, progress));
-    // Calculate filled width
-    const filledWidth = Math.round(p * width);
-    const emptyWidth = width - filledWidth;
-    // Resolve styles (Defaults)
-    const resolvedBracketStyle = bracketStyle ?? style;
-    const resolvedStartStyle = startStyle ?? resolvedBracketStyle;
-    const resolvedEndStyle = endStyle ?? resolvedBracketStyle;
-    const resolvedBarStyle = barStyle ?? style;
-    const resolvedFillStyle = fillStyle ?? resolvedBarStyle;
-    const resolvedEmptyStyle = emptyStyle ?? resolvedBarStyle;
-    const resolvedPercentageStyle = percentageStyle ?? style;
-    const segments = [];
-    // Start Bracket
-    if (startChar) {
-        segments.push({ text: startChar, style: resolvedStartStyle });
-    }
-    // Filled Part
-    if (filledWidth > 0) {
-        segments.push({ text: fillChar.repeat(filledWidth), style: resolvedFillStyle });
-    }
-    // Empty Part
-    if (emptyWidth > 0) {
-        segments.push({ text: emptyChar.repeat(emptyWidth), style: resolvedEmptyStyle });
-    }
-    // End Bracket
-    if (endChar) {
-        segments.push({ text: endChar, style: resolvedEndStyle });
-    }
-    // Percentage
-    if (showPercentage) {
-        const percentageText = formatPercentage ? formatPercentage(p) : ` ${Math.round(p * 100)}%`;
-        segments.push({ text: percentageText, style: resolvedPercentageStyle });
-    }
-    return { segments };
-}

package/dist/components/progress.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/components/progress.test.js

@@ -1,105 +0,0 @@
-import { expect, test, describe } from "bun:test";
-import { createProgressBar } from "./progress";
-function getText(line) {
-    return line.segments.map((s) => s.text).join("");
-}
-describe("createProgressBar", () => {
-    test("generates a default progress bar at 0%", () => {
-        const line = createProgressBar({ progress: 0 });
-        const text = getText(line);
-        // Default format: [░░░░░░░░░░░░░░░░░░░░] 0%
-        expect(text).toContain("[");
-        expect(text).toContain("]");
-        expect(text).toContain("0%");
-        expect(text).toContain("░");
-    });
-    test("generates a default progress bar at 50%", () => {
-        const line = createProgressBar({ progress: 0.5 });
-        const text = getText(line);
-        expect(text).toContain("50%");
-        expect(text).toContain("█");
-        expect(text).toContain("░");
-    });
-    test("generates a default progress bar at 100%", () => {
-        const line = createProgressBar({ progress: 1.0 });
-        const text = getText(line);
-        expect(text).toContain("100%");
-        // Should not contain empty char
-        // But wait, width default 20. 100% means 20 filled. 0 empty.
-        expect(text).not.toContain("░");
-    });
-    test("allows custom width", () => {
-        const width = 10;
-        const line = createProgressBar({ progress: 0.5, width });
-        const segments = line.segments;
-        const filled = segments.find((s) => s.text.includes("█"));
-        const empty = segments.find((s) => s.text.includes("░"));
-        // 50% of 10 is 5.
-        expect(filled?.text.length).toBe(5);
-        expect(empty?.text.length).toBe(5);
-    });
-    test("applies styles correctly", () => {
-        const line = createProgressBar({
-            progress: 0.5,
-            style: { color: "blue" },
-            bracketStyle: { color: "red" },
-            barStyle: { color: "green" },
-            percentageStyle: { color: "yellow" }
-        });
-        const start = line.segments.find((s) => s.text === "[");
-        const filled = line.segments.find((s) => s.text.includes("█"));
-        const end = line.segments.find((s) => s.text === "]");
-        const percentage = line.segments.find((s) => s.text.includes("%"));
-        expect(start?.style).toEqual({ color: "red" });
-        expect(filled?.style).toEqual({ color: "green" });
-        expect(end?.style).toEqual({ color: "red" });
-        expect(percentage?.style).toEqual({ color: "yellow" });
-    });
-    test("cascades styles (general style -> specific)", () => {
-        const line = createProgressBar({
-            progress: 0.5,
-            style: { color: "blue" }
-        });
-        line.segments.forEach((s) => {
-            if (s.text.trim().length > 0) {
-                expect(s.style).toEqual({ color: "blue" });
-            }
-        });
-    });
-    test("allows custom characters", () => {
-        const line = createProgressBar({
-            progress: 0.5,
-            startChar: "<",
-            endChar: ">",
-            fillChar: "=",
-            emptyChar: "-"
-        });
-        const text = getText(line);
-        expect(text).toContain("<");
-        expect(text).toContain(">");
-        expect(text).toContain("=");
-        expect(text).toContain("-");
-    });
-    test("hides percentage", () => {
-        const line = createProgressBar({
-            progress: 0.5,
-            showPercentage: false
-        });
-        const text = getText(line);
-        expect(text).not.toContain("%");
-    });
-    test("formats percentage custom", () => {
-        const line = createProgressBar({
-            progress: 0.5,
-            formatPercentage: (p) => `${p * 10}/10`
-        });
-        const text = getText(line);
-        expect(text).toContain("5/10");
-    });
-    test("clamping progress", () => {
-        const lineLow = createProgressBar({ progress: -0.1 });
-        expect(getText(lineLow)).toContain("0%");
-        const lineHigh = createProgressBar({ progress: 1.1 });
-        expect(getText(lineHigh)).toContain("100%");
-    });
-});

package/dist/components/spinner.d.ts

@@ -1,36 +0,0 @@
-export type SpinnerFrames = string[];
-export interface SpinnerOptions {
-    /**
-     * The array of frames to cycle through.
-     */
-    frames: SpinnerFrames;
-    /**
-     * The interval in milliseconds between frames.
-     * Defaults to 80ms.
-     */
-    interval?: number;
-}
-/**
- * Common spinner frame presets.
- */
-export declare const SPINNERS: {
-    dots: string[];
-    lines: string[];
-    arrows: string[];
-    circle: string[];
-    square: string[];
-};
-/**
- * A stateful spinner that calculates the current frame based on elapsed time.
- * Designed to be used within a render loop (e.g. Printer.print loop).
- */
-export declare class Spinner {
-    private frames;
-    private interval;
-    private startTime;
-    constructor(options: SpinnerOptions);
-    /**
-     * Returns the current frame based on the elapsed time.
-     */
-    getFrame(): string;
-}

package/dist/components/spinner.js

@@ -1,33 +0,0 @@
-/**
- * Common spinner frame presets.
- */
-export const SPINNERS = {
-    dots: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
-    lines: ["-", "\\", "|", "/"],
-    arrows: ["←", "↖", "↑", "↗", "→", "↘", "↓", "↙"],
-    circle: ["◐", "◓", "◑", "◒"],
-    square: ["▖", "▘", "▝", "▗"]
-};
-/**
- * A stateful spinner that calculates the current frame based on elapsed time.
- * Designed to be used within a render loop (e.g. Printer.print loop).
- */
-export class Spinner {
-    frames;
-    interval;
-    startTime;
-    constructor(options) {
-        this.frames = options.frames;
-        this.interval = options.interval ?? 80;
-        this.startTime = Date.now();
-    }
-    /**
-     * Returns the current frame based on the elapsed time.
-     */
-    getFrame() {
-        const now = Date.now();
-        const elapsed = now - this.startTime;
-        const index = Math.floor(elapsed / this.interval) % this.frames.length;
-        return this.frames[index];
-    }
-}

package/dist/components/spinner.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/components/spinner.test.js

@@ -1,53 +0,0 @@
-import { expect, test, describe, spyOn, afterEach, beforeEach } from "bun:test";
-import { Spinner, SPINNERS } from "./spinner";
-describe("Spinner Class", () => {
-    let now = 1000;
-    // Mock Date.now() to control time
-    const dateSpy = spyOn(Date, "now").mockImplementation(() => now);
-    beforeEach(() => {
-        now = 1000;
-        dateSpy.mockClear();
-        dateSpy.mockImplementation(() => now);
-    });
-    afterEach(() => {
-        dateSpy.mockClear();
-    });
-    test("initializes with correct defaults", () => {
-        const spinner = new Spinner({ frames: ["a", "b"] });
-        expect(spinner.getFrame()).toBe("a");
-    });
-    test("advances frames over time", () => {
-        const spinner = new Spinner({ frames: ["a", "b", "c"], interval: 100 });
-        // t=0 (1000)
-        expect(spinner.getFrame()).toBe("a");
-        // t=50 (1050) -> still frame 0
-        now = 1050;
-        expect(spinner.getFrame()).toBe("a");
-        // t=100 (1100) -> frame 1
-        now = 1100;
-        expect(spinner.getFrame()).toBe("b");
-        // t=200 (1200) -> frame 2
-        now = 1200;
-        expect(spinner.getFrame()).toBe("c");
-        // t=300 (1300) -> frame 0 (loop)
-        now = 1300;
-        expect(spinner.getFrame()).toBe("a");
-    });
-    test("uses custom interval", () => {
-        const spinner = new Spinner({ frames: ["a", "b"], interval: 50 });
-        // t=0
-        expect(spinner.getFrame()).toBe("a");
-        // t=50 -> frame 1
-        now = 1050;
-        expect(spinner.getFrame()).toBe("b");
-    });
-});
-describe("Spinner Presets", () => {
-    test("dots preset exists and has frames", () => {
-        expect(SPINNERS.dots).toBeDefined();
-        expect(SPINNERS.dots.length).toBeGreaterThan(0);
-    });
-    test("lines preset exists", () => {
-        expect(SPINNERS.lines).toBeDefined();
-    });
-});

package/dist/core/layout.d.ts

@@ -1,25 +0,0 @@
-import { PrintLine, PrintStyle } from "./types";
-import { Printer } from "./printer";
-/**
- * Merges multiple columns of PrintLines into a single layout.
- * Ensures proper alignment by padding shorter lines.
- *
- * @param columns - Array of columns, where each column is an array of PrintLines.
- * @param separator - String used to separate columns.
- * @param defaultStyle - Style to apply to the separator and padding.
- * @param widths - Optional fixed widths for each column.
- * @returns A single array of PrintLines representing the merged output.
- */
-export declare function mergeMultipleColumns(columns: PrintLine[][], separator?: string, defaultStyle?: PrintStyle, widths?: number[]): PrintLine[];
-/**
- * Prints multiple columns of styled content to the console.
- * A convenience wrapper around `mergeMultipleColumns` and `Printer.print`.
- *
- * @param columns - Array of columns to print.
- * @param options - Layout options (widths, separator, custom printer).
- */
-export declare function printColumns(columns: PrintLine[][], options?: {
-    widths?: number[];
-    separator?: string;
-    printer?: Printer;
-}): void;

package/dist/core/layout.js

@@ -1,55 +0,0 @@
-import { computeMaxWidth, padLine } from "./utils";
-import { Printer } from "./printer";
-// -----------------
-// Core Layout & Printing
-// -----------------
-/**
- * Merges multiple columns of PrintLines into a single layout.
- * Ensures proper alignment by padding shorter lines.
- *
- * @param columns - Array of columns, where each column is an array of PrintLines.
- * @param separator - String used to separate columns.
- * @param defaultStyle - Style to apply to the separator and padding.
- * @param widths - Optional fixed widths for each column.
- * @returns A single array of PrintLines representing the merged output.
- */
-export function mergeMultipleColumns(columns, separator = "     ", defaultStyle, widths) {
-    if (columns.length === 0)
-        return [];
-    const maxLines = Math.max(...columns.map((c) => c.length));
-    const colWidths = columns.map((col, i) => {
-        if (widths?.[i] !== undefined)
-            return widths[i];
-        return computeMaxWidth(col);
-    });
-    const output = [];
-    for (let i = 0; i < maxLines; i++) {
-        let segments = [];
-        for (let j = 0; j < columns.length; j++) {
-            const line = columns[j][i] || { segments: [] };
-            // If not the last column, pad it
-            if (j < columns.length - 1) {
-                const padded = padLine(line, colWidths[j], defaultStyle);
-                segments = [...segments, ...padded.segments, { text: separator, style: defaultStyle }];
-            }
-            else {
-                // Last column, just add segments
-                segments = [...segments, ...line.segments];
-            }
-        }
-        output.push({ segments });
-    }
-    return output;
-}
-/**
- * Prints multiple columns of styled content to the console.
- * A convenience wrapper around `mergeMultipleColumns` and `Printer.print`.
- *
- * @param columns - Array of columns to print.
- * @param options - Layout options (widths, separator, custom printer).
- */
-export function printColumns(columns, options = {}) {
-    const { widths, separator = "     ", printer = new Printer() } = options;
-    const mergedLines = mergeMultipleColumns(columns, separator, undefined, widths);
-    printer.print({ lines: mergedLines });
-}

package/dist/core/layout.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/core/layout.test.js

@@ -1,52 +0,0 @@
-import { expect, test, describe, spyOn, afterEach } from "bun:test";
-import { mergeMultipleColumns, printColumns } from "./layout";
-import { getLineLength } from "./utils";
-const lineA = { segments: [{ text: "Hello" }] };
-const lineB = { segments: [{ text: "World!!" }] };
-describe("Layout Utilities", () => {
-    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true);
-    afterEach(() => {
-        stdoutSpy.mockClear();
-    });
-    test("mergeMultipleColumns handles asymmetric column lengths", () => {
-        // Column 1: [lineA]
-        // Column 2: [lineB, lineB]
-        // Separator: " | "
-        // Default Style: undefined
-        // Widths: [10] (first col width 10)
-        const merged = mergeMultipleColumns([[lineA], [lineB, lineB]], " | ", undefined, [10]);
-        expect(merged.length).toBe(2);
-        // Second merged line:
-        // Col 1 is empty (pad to 10) + " | " + Col 2 (lineB, length 7)
-        // 10 + 3 + 7 = 20
-        expect(getLineLength(merged[1])).toBe(20);
-    });
-    test("printColumns executes correctly", () => {
-        printColumns([[lineA], [lineB]]);
-        expect(stdoutSpy).toHaveBeenCalled();
-        const output = stdoutSpy.mock.calls[0][0];
-        expect(output).toContain("Hello");
-        expect(output).toContain("World!!");
-    });
-    test("printColumns handles undefined style in segments", () => {
-        const lineNoStyle = { segments: [{ text: "NoStyle" }] };
-        printColumns([[lineNoStyle]]);
-        expect(stdoutSpy).toHaveBeenCalled();
-        const output = stdoutSpy.mock.calls[0][0];
-        expect(output).toContain("NoStyle");
-    });
-    test("printColumns handles empty columns", () => {
-        printColumns([]);
-        // Should just print nothing or minimal output (if logic handles empty array gracefully)
-        // mergeMultipleColumns returns []
-        // printer.print({ lines: [] }) -> might output clear sequence or empty string
-        expect(stdoutSpy).toHaveBeenCalled();
-    });
-    test("printColumns handles 3 columns", () => {
-        printColumns([[lineA], [lineA], [lineB]]);
-        expect(stdoutSpy).toHaveBeenCalled();
-        const output = stdoutSpy.mock.calls[0][0];
-        expect(output).toContain("Hello");
-        expect(output).toContain("World!!");
-    });
-});

package/dist/core/printer.d.ts

@@ -1,33 +0,0 @@
-import { PrintBlock, PrinterOptions } from "./types";
-/**
- * Handles rendering PrintBlocks to the terminal with support for interactive/live overwriting.
- */
-export declare class Printer {
-    private linesRendered;
-    private isLive;
-    private data?;
-    constructor(options?: PrinterOptions);
-    /**
-     * Generates the clear sequence to move cursor and clear previously rendered lines.
-     */
-    private getClearSequence;
-    /**
-     * Clears the console using the stored line count.
-     */
-    clear(): void;
-    /**
-     * Renders the PrintBlock to the standard output.
-     * If data is provided, updates the internal state.
-     *
-     * @param data - Optional data to update the printer with.
-     */
-    print(data?: PrintBlock): void;
-    /**
-     * Resolves the block's vertical gradient (if any) to a solid color for the specific line.
-     */
-    private resolveBlockColorForLine;
-    /**
-     * Renders a single line.
-     */
-    private renderLine;
-}