@trap_stevo/terminal-plus

🖥️ @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.