@trap_stevo/terminal-plus
Version:
Transform your CLI into a visually striking, feature-rich command layer. Blend animated gradients, stylish badges, dynamic progress bars, sleek tables, and precise formatting utilities — all turning terminal output into a powerful visual experience.
504 lines (365 loc) • 21.5 kB
Markdown
# 🖥️ @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`)
```js
// 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:
```js
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:
```js
const barManager = terminal.createProgressBar(tasks, options);
```
#### Tasks Format
An object with at least:
```js
{ 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:
```js
barManager.updateTaskProgress(taskName, amount);
barManager.completeTask(taskName);
barManager.completeAll();
```
#### Example
```js
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:
```js
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
```bash
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:
```js
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](./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.