🖥️ @trap_stevo/terminal-plus

Transform your CLI into a visually striking, feature-rich command layer.
Blend animated gradients, stylish badges, dynamic progress bars, sleek tables, and precision formatting utilities — engineered for legendary terminal output.

🚀 Features

• 🔆 Animated gradient text and smooth-moving animations
• 🏷️ Stylish, icon-enhanced terminal badges
• 📊 Interactive multi-task progress bars with paging
• 📋 Sleek auto-formatted console tables with border styles and gradients
• 🎨 Color formatting utilities
• 🔗 Attach dynamic followers to animations or base content
• 🧠 Byte and time formatting utilities

⚙️ System Requirements

| Requirement | Version | |----------------|--------------------| | Node.js | ≥ 19.x | | npm | ≥ 9.x (recommended)| | OS | Windows, macOS, Linux |

📐 Specifications

| Method | Description | Async | |---------------------------|------------------------------------------------------------------------|:-----:| | constructor(options) | Initializes a new TerminalPlus instance with optional config | ❌ | | log(message, type) | Logs a styled message with timestamp | ❌ | | printGradient(text) | Prints gradient-colored static text to the terminal | ❌ | | printMovingGradient(text, colors, interval) | Displays animated gradient text | ❌ | | printColor(text, opts) | Returns styled text with custom color formatting | ❌ | | printBadge(label, opts) | Prints a stylized badge directly to the terminal | ❌ | | getBadge(label, opts) | Returns the badge as a string (no printing) | ❌ | | drawDivider(type, position, colors, content, width) | Renders a gradient divider line or sci-fi frame | ❌ | | createTable(data, opts) | Renders a formatted, stylized console table | ❌ | | createProgressBar(tasks = [], options = {}) | Displays a multi-task progress bar system | ❌ | | attachFollower(base, content, options = {}) | Dynamically renders content below or inline with an animation | ✅ | | setDefaultGradient(gradient) | Updates the globally used fallback gradient colors | ❌ | | formatBytes(size) | Converts bytes to a readable string with appropriate units | ❌ | | formatSeconds(seconds) | Converts seconds to a hh:mm:ss formatted string | ❌ |

🧰 Methods Overview

constructor(options = {}) — Sync

Initializes the TerminalPlus instance.

Options:

• gradientSpeed (number): Speed of moving gradient (default 100)
• defaultGradient (string[]): Default gradient colors (default ["#00ffff", "#1a73e8"])

log(message, type = "info", typeOptions = {}) — Sync

Log a timestamped message with optional styles.

Parameters:

• message: String to print
• type: "info" | "warn" | "error" | "success" | "debug"
• typeOptions: Override default chalk styles

printGradient(text, colors = this.options.defaultGradient, interval = this.options.gradientSpeed) — Sync

Prints a static gradient text to console.

printMovingGradient(text, colors, interval) — Sync

Returns a moving gradient animation object.

Returns: animation with .start() and .stop() methods

printColor(text, options = {}) — Sync

Returns colored string using inline styles.

Options:

• textColor: hex or color keyword
• backgroundColor: hex or color keyword
• bold, italic, underline etc.

printBadge(label, options = {}) — Sync

Prints a styled badge to the console.

getBadge(label, options = {}) — Sync

Returns the badge string (instead of printing).

Options:

• icon: prepended icon
• textColor, backgroundColor
• gradient: [start, end]
• padding, rounded

🧱 drawDivider(type, position, colors, content, width) — Sync

Draws a gradient divider line or a sci-fi style framed section.

Parameters:

• type (string): "default", "arrow", or "sci-frame" (default: "default")
• position (string|null): "top", "bottom", or null (only applies to "sci-frame")
• colors (string[]): Gradient color pair (default: ["#273140", "#143857"])
• content (string|null): Optional string or pattern to use instead of default line
• width (number): Total width of the divider (default: 116)

// Default sleek divider
terminal.drawDivider();

// Arrow-style divider
terminal.drawDivider("arrow", null, ["#1a3c78", "#1e607e"]);

// Framed section with header
terminal.drawDivider("sci-frame", "top");
terminal.drawDivider("sci-frame", null, ["#1a212b", "#2b7fc5"], " SUPERCL SESSION ", 100);
terminal.drawDivider("sci-frame", "bottom");

// Custom pattern divider
terminal.drawDivider("custom", null, ["#1a3c78", "#338ba8"], "~*~".repeat(30), 120);

createTable(data, options = {}) — Sync

Renders an auto-aligned styled table.

Parameters:

• data: Array of row objects
• options:
  • columnNames: Object map for column labels
  • columnOrder: Array to define column order
  • padding: Cell padding
  • borderStyle: "solid" | "double" | "round" | "bold"
  • gradient: { header, border, title, cell }

createProgressBar(tasks = [], options = {}) — Sync

Creates a multi-task progress bar manager.

Returns: Manager with .updateTaskProgress(name, delta)

attachFollower(base, content, options = {}) — Async

Attaches content (like badge) near an animation or after a delay.

Parameters:

• base: the animated base (must have .moving())
• content: string or function returning string
• options:
  • inline: true | false
  • inlinePosition: "left" | "right"
  • spacing: # of lines or spaces
  • delay: in milliseconds

setDefaultGradient(colors: string[]) — Sync

Sets the default gradient colors globally.

formatBytes(size, dynamicUnits = true) — Sync

Formats bytes into readable strings (e.g. 12.3 MB).

formatSeconds(seconds) — Sync

Formats seconds into hh:mm:ss format.

Terminal Components

🗂 Console Table Options

The ConsoleTable supports rich customization for column styling, layout, borders, and gradients. Below provides all the configurable options you can pass when creating a table via createTable(data, options):

| Option | Type | Description | |---------------------|--------------------|----------------------------------------------------------------------------------------------| | padding | number | Space padding inside each cell (default: 1) | | headerAlign | "left" \| "right" \| "center" | Text alignment for header cells (default: "center") | | cellAlign | "left" \| "right" \| "center" | Text alignment for regular cells (default: "left") | | borderStyle | "solid" \| "double" \| "round" \| "bold" | Style of table border characters (default: "solid") | | headerColor | function | Function to apply color/styling to header cell content | | borderColor | function | Function to apply color/styling to border characters | | cellColor | function(content, column, row) | Function to apply color/styling per cell content (default: returns raw content) | | columnOrder | string[] | Define explicit column order instead of automatic detection | | columnNames | object | Map of originalKey : displayLabel to rename column headers | | title | string | Optional table title (rendered above the table) | | tableNumber | number | Optional number to tag the table for reference | | gradient.title | [string, string] | Gradient color pair applied to the title (overrides static color) | | gradient.header | [string, string] | Gradient color pair applied to header text | | gradient.border | [string, string] | Gradient color pair applied to border characters | | gradient.cell | [string, string] | Gradient color pair applied to cell content |

🏷 Terminal Badge Options

The TerminalBadge component enables you to display beautifully styled label badges directly in the terminal with support for colors, gradients, icons, and format types.

You can use it via:

terminal.printBadge("Build Success", options);
const badge = terminal.getBadge("MyCLI", options);

| Option | Type | Description | |---------------------|----------------------|----------------------------------------------------------------------------------------------| | icon | string | Emoji or icon to prepend inside the badge (e.g., "🚀") | | padding | number | Number of spaces on both sides of the content (default: 1) | | backgroundColor | string (hex) | Background color of the badge (default: "#6c63ff") | | textColor | string (hex) | Foreground (text) color inside the badge (default: "#ffffff") | | gradient | [string, string] | Optional gradient colors to override backgroundColor | | type | "sleek" \| "sci-fi" \| "rounded" \| "classic" | Defines the badge frame style (default: "sleek") | | inline | boolean | Whether to render the badge inline or on its own line (default: true) |

📊 Console Progress Bar Options

The ConsoleProgressBarManager allows you to manage multiple terminal-based progress bars with advanced customization. You can create a manager using:

const barManager = terminal.createProgressBar(tasks, options);

Tasks Format

An object with at least:

{ name : "Upload", size : 1000 }

🛠 Options

| Option | Type | Description | |----------------------|-----------------------|-----------------------------------------------------------------------------------------------| | barWidth | number | Total width of the progress bar (default: 40) | | barChar | string | Character used to fill the progress bar (default: "█") | | emptyChar | string | Character used for the unfilled portion (default: "░") | | showPercentage | boolean | Show percentage next to the bar (default: true) | | showCount | boolean | Show current / total progress numbers (default: true) | | showBarBorder | boolean | Surround the bar with borders (default: false) | | barBorderChar | [string, string] | Custom left and right characters for the border (default: ["[", "]"]) | | labelAlign | "left" \| "center" \| "right" | Alignment of the task label (default: "left") | | barGradient | [string, string] | Gradient colors used inside the filled bar section | | textColor | string | Hex color applied to label and percentage (default: "#ffffff") | | completedIcon | string | Optional icon to show when a task reaches 100% (e.g., "✅") | | autoRender | boolean | If true, automatically calls displayPage() and listenForInput() (default: true) |

🔧 Task Methods

After creating the bar manager, you can control tasks with:

barManager.updateTaskProgress(taskName, amount);
barManager.completeTask(taskName);
barManager.completeAll();

Example

const tasks = [
     { name : "Upload", size : 1000 },
     { name : "Process", size : 500 }
];

const barManager = terminal.createProgressBar(tasks, {
     barWidth : 30,
     barChar : "#",
     emptyChar : "-",
     barGradient : ["#00C9FF", "#92FE9D"],
     completedIcon : "✅"
});

// Simulate updates
barManager.updateTaskProgress("Upload", 100);

💡 Console Progress Bar uses cumulative progression — keep calling updateTaskProgress to move it forward.

🔄 Terminal Spinner Options

The TerminalSpinner creates beautiful animated loaders with support for color gradients, shifting, icons, and custom frames.

You can start a spinner using:

const spinner = terminal.createSpinner("Loading...", options);
spinner.start();

// Optional: stop after done
setTimeout(() => spinner.stop("✅ Done!"), 3000);

🛠 Options

| Option | Type | Description | |--------------------------|--------------------------|-----------------------------------------------------------------------------------------------| | preset | string | Built-in spinner style (e.g., "dots", "rocket", etc.) | | frames | string[] | Custom array of frame strings (overrides preset if provided) | | interval | number | Milliseconds between each frame (default: 80) | | textColor | string \| string[] | Text color or gradient colors array | | backgroundColor | string \| string[] | Background color or gradient colors array | | icon | string | Emoji or icon prepended to the spinner label (e.g., "🚀") | | prefix | string | String to show before the spinner block | | suffix | string | String to show after the spinner block | | padding | number | Number of spaces around the spinner text (default: 1) | | inline | boolean | Whether to print on the same line (true) or as a new line per frame (false) | | gradientShift | boolean | Enable live shifting of text/background gradients per frame | | textGradientSpeed | number | Number of frames before shifting text gradient (default: 1) | | bgGradientSpeed | number | Number of frames before shifting background gradient (default: 1) | | textGradientReverse | boolean | Reverse the direction of text gradient shift | | bgGradientReverse | boolean | Reverse the direction of background gradient shift |

🎞️ Built-in Spinner Presets

| Preset | Description | |--------------|---------------------------------| | dots | Classic braille spinner | | line | Rotating slashes | | arrows | Directional arrow cycle | | circle | Circular quadrant spinner | | bounce | Bouncing dot loader | | bar | Progress bar simulation | | grow | Vertical growth bar | | clock | Analog clock face rotation | | simple | Expanding ellipsis | | supercape | Superhero flying dash | | fireball | Flame swipe with momentum | | magic | Glowing spell swirl | | rocket | Rocket launch animation | | retro | Alien + UFO loop |

📦 Install

npm install @trap_stevo/terminal-plus

🚀 Example Usage

Here’s a full example of how to use TerminalPlus to build a legendarily appealing terminal output:

const TerminalPlus = require("@trap_stevo/terminal-plus");

const terminal = new TerminalPlus({
     gradientSpeed : 75,
     defaultGradient : ["#FF00FF", "#00FFFF"]
});

// 🔹 Gradient Text
terminal.printGradient("✨ Welcome to LegendaryTerminal ✨");

// 🔹 Moving Gradient (animated)
const badge = terminal.getBadge("MyCLI", {
     icon : "🚀",
     backgroundColor : "#007BFF",
     textColor : "#ffffff",
     padding : 2,
     rounded : true
});

const anim = terminal.printMovingGradient("✨ Animating with style...", ["#FF6B6B", "#FFD93D"]);
anim.setFollower(badge);

setTimeout(() => {
     anim.stop();
     console.log("\n✅ Animation done.\n");
}, 3000);

// 🔹 Terminal Badge
terminal.printBadge("MyCLI", {
     icon : "🚀",
     backgroundColor : "#007BFF",
     textColor : "#ffffff",
     padding : 2,
     rounded : true
});

// 🔹 Custom Styled Badge with Gradient
terminal.printBadge("Build Success", {
     icon : "✅",
     gradient : ["#28a745", "#85e085"],
     textColor : "#000000",
     padding : 1,
     rounded : true
});

// 🔹 Console Table
const tableOutput = terminal.createTable([
     { name : "Alice", role : "Admin", age : 30 },
     { name : "Bob", role : "User", age : 25 }
], {
     columnNames : { name : "Name", role : "Role", age : "Age" },
     gradient : {
          header : ["#00C9FF", "#92FE9D"],
          cell : ["#FFDEE9", "#B5FFFC"]
     },
     borderStyle : "round"
});

console.log("\n" + tableOutput);

// 🔹 Styled Text Using applyColor
const styled = terminal.printColor("🛡 SECURE", {
     backgroundColor : "#222831",
     textColor : "#00FFF5"
});

process.stdout.write(styled);

// 🔹 Inline Badge Follower
terminal.attachFollower(styled, badge, { inline : true });

// 🔹 Byte & Time Format Utilities
console.log("\nFile size:", terminal.formatBytes(12582912));
console.log("Estimated time:", terminal.formatSeconds(9876));

setTimeout(() => {
          const spinner = terminal.createSpinner("Launching to the stars...", {
               preset : "rocket",
               textColor : ["#00FFF5", "#1A73E8", "#9D00FF"],
               backgroundColor : ["#0F1117", "#11131A", "#0F1117"],
               gradientShift : true,
               textGradientSpeed : 0.1,
               bgGradientSpeed : 2,
               textGradientReverse : false,
               bgGradientReverse : true,
               interval : 100
          });
          
          setTimeout(() =>  {
               spinner.stop("🚀 We have liftoff!");
          }, 4000);
}, 3000);

🧠 Customize every visual element, combine components, and inject dynamic elegance into every CLI interaction.

📜 License

See License in LICENSE.md

🧙 Terminal Magic. Command Layer Power.

Turn everyday terminal output into a high-impact visual experience.
Use it to elevate your CLI tools, installation wizards, developer scripts, or deployment logs with elegance and clarity.

Let your terminal shine with color, clarity, and control.