adclours
Version:
A powerful and lightweight advanced CLI coloring tool built with pure Node.js. This module offers efficient and fast terminal output coloring without external dependencies.
638 lines (457 loc) • 22.9 kB
Markdown
# adclours.mjs - A Comprehensive Terminal Styling Module
`adclours.mjs` is a powerful, comprehensive, and chainable JavaScript module designed for styling terminal text with an extensive range of colors and formatting options. Leveraging a Proxy-based fluent API, it offers over 50 features, including basic and bright colors, 24-bit true color (RGB/HEX), 256-color palette support, text effects, utility functions for layout, and advanced features like spinners and logging.
## Features
This section provides a detailed overview of all the features available in `adclours.mjs`, categorized for easy navigation.
### Table of Contents
* [1. Chainable Styling API (`color` object)](#1-chainable-styling-api-color-object)
* [Basic Usage](#basic-usage)
* [Available Styles](#available-styles)
* [Basic Foreground Colors](#basic-foreground-colors)
* [Bright/Hi-intensity Foreground Colors](#brighthi-intensity-foreground-colors)
* [Basic Background Colors](#basic-background-colors)
* [Bright/Hi-intensity Background Colors](#brighthi-intensity-background-colors)
* [2. Advanced Color Support](#2-advanced-color-support)
* [RGB Colors (24-bit True Color)](#rgb-colors-24-bit-true-color)
* [HEX Colors](#hex-colors)
* [256-Color Palette](#256-color-palette)
* [Extended Named Colors (Over 50!)](#extended-named-colors-over-50)
* [3. Text Effects and Utilities](#3-text-effects-and-utilities)
* [`strip(text)`](#striptext)
* [`rainbow(text)`](#rainbowtext)
* [`gradient(text, startHex, endHex)`](#gradienttext-starthex-endhex)
* [`progressBar(value, total, options)`](#progressbarvalue-total-options)
* [`box(text, options)`](#boxtext-options)
* [`center(text, width)`](#centertext-width)
* [`wrap(text, width)`](#wraptext-width)
* [`asciiArt(text)`](#asciiarttext)
* [`pad(text, width, side, char)`](#padtext-width-side-char)
* [`table(rows, options)`](#tablerows-options)
* [`line(width, text)`](#linewidth-text)
* [`title(title, subtitle, width)`](#titletitle-subtitle-width)
* [`list(items, options)`](#listitems-options)
* [`blend(text, color1, color2, ratio, mode)`](#blendtext-color1-color2-ratio-mode)
* [`generateShades(baseColor, count, direction)`](#generateshadesbasecolor-count-direction)
* [`findNearestColor(inputColor)`](#findnearestcolorinputcolor)
* [4. Advanced Components](#4-advanced-components)
* [`Spinner` Class](#spinner-class)
* [`animate(text, options)`](#animatetext-options)
* [5. Structured Logging System (`log` object)](#5-structured-logging-system-log-object)
### 1. Chainable Styling API (`color` object)
The core of `adclours.mjs` is the `color` object, which provides a highly intuitive and chainable API for applying styles and colors. You can combine multiple styles and colors seamlessly.
**Basic Usage:**
```javascript
import { color } from 'adclours';
console.log(color.red('This is red text.'));
console.log(color.bold.green('This is bold green text.'));
console.log(color.underline.blue.bgYellow('Underlined blue text with yellow background.'));
```
**Available Styles:**
* `color.reset`: Resets all applied styles.
* `color.bold`: Makes text bold.
* `color.dim`: Dims the text.
* `color.italic`: Makes text italic.
* `color.underline`: Underlines the text.
* `color.inverse`: Inverts foreground and background colors.
* `color.hidden`: Hides the text.
* `color.strikethrough`: Adds a strikethrough to the text.
* `color.overline`: Adds an overline to the text.
**Basic Foreground Colors:**
`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
```javascript
console.log(color.red('Hello'));
console.log(color.cyan('World'));
```
**Bright/Hi-intensity Foreground Colors:**
`gray`, `brightRed`, `brightGreen`, `brightYellow`, `brightBlue`, `brightMagenta`, `brightCyan`, `brightWhite`
```javascript
console.log(color.brightGreen('Success!'));
console.log(color.gray('Dimmed text.'));
```
**Basic Background Colors:**
`bgBlack`, `bgRed`, `bgGreen`, `bgYellow`, `bgBlue`, `bgMagenta`, `bgCyan`, `bgWhite`
```javascript
console.log(color.bgBlue('Blue Background'));
console.log(color.black.bgGreen('Black text on Green background'));
```
**Bright/Hi-intensity Background Colors:**
`bgGray`, `bgBrightRed`, `bgBrightGreen`, `bgBrightYellow`, `bgBrightBlue`, `bgBrightMagenta`, `bgBrightCyan`, `bgBrightWhite`
```javascript
console.log(color.bgBrightYellow('Bright Yellow Background'));
```
### 2. Advanced Color Support
`adclours.mjs` goes beyond basic ANSI colors, offering true color and 256-color palette support.
#### RGB Colors (24-bit True Color)
Specify colors using Red, Green, and Blue values (0-255).
* `color.rgb(r, g, b)(text)`: Sets foreground color.
* `color.bgRgb(r, g, b)(text)`: Sets background color.
```javascript
import { color } from 'adclours';
console.log(color.rgb(255, 100, 0)('Orange text.'));
console.log(color.bgRgb(50, 200, 150)('Text with custom background.'));
```
#### HEX Colors
Use 6-digit hexadecimal color codes.
* `color.hex('#RRGGBB')(text)`: Sets foreground color.
* `color.bgHex('#RRGGBB')(text)`: Sets background color.
```javascript
import { color } from 'adclours';
console.log(color.hex('#FF4500')('OrangeRed text.'));
console.log(color.bgHex('#8A2BE2')('Text with BlueViolet background.'));
```
#### 256-Color Palette
Access the 256-color terminal palette by index (0-255).
* `color.color256(code)(text)`: Sets foreground color.
* `color.bg256(code)(text)`: Sets background color.
```javascript
import { color } from 'adclours';
console.log(color.color256(208)('Orange from 256 palette.'));
console.log(color.bg256(18)('Dark blue background from 256 palette.'));
```
#### Extended Named Colors (Over 50!)
In addition to basic and bright colors, `adclours.mjs` includes a vast array of named colors for convenience, which are internally converted to HEX/RGB.
**Supported Named Colors:**
`maroon`, `darkred`, `firebrick`, `crimson`, `tomato`, `coral`, `indianred`, `lightcoral`, `salmon`, `darksalmon`, `lightsalmon`, `orangered`, `darkorange`, `orange`, `gold`, `yellowgreen`, `olivedrab`, `olive`, `darkolivegreen`, `forestgreen`, `seagreen`, `mediumseagreen`, `darkcyan`, `teal`, `darkturquoise`, `turquoise`, `lightseagreen`, `cadetblue`, `steelblue`, `cornflowerblue`, `royalblue`, `mediumblue`, `darkblue`, `navy`, `midnightblue`, `indigo`, `darkmagenta`, `purple`, `mediumorchid`, `orchid`, `violet`, `plum`, `thistle`, `silver`, `lightgray`, `darkgray`, `dimgray`, `slategray`, `lightslategray`, `rosybrown`, `palevioletred`, `hotpink`, `deeppink`, `fuchsia`, `paleturquoise`, `lightblue`, `skyblue`, `deepskyblue`, `dodgerblue`, `azure`, `aliceblue`, `ghostwhite`, `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`, `brightRed`, `brightGreen`, `brightYellow`, `brightBlue`, `brightMagenta`, `brightCyan`, `brightWhite`
```javascript
import { color } from 'adclours';
console.log(color.gold('Golden text.'));
console.log(color.teal('Teal colored message.'));
console.log(color.hotpink.bold('Hot Pink and Bold!'));
```
### 3. Text Effects and Utilities
Beyond simple coloring, `adclours.mjs` provides functions for various text manipulations and effects.
#### `strip(text)`
Removes all ANSI escape codes from a string, returning plain text. Useful for calculating actual string length or logging.
```javascript
import { color, strip } from 'adclours';
const coloredText = color.red('Hello ') + color.bold('World!');
console.log(coloredText); // Outputs colored text
console.log(strip(coloredText)); // Outputs "Hello World!"
console.log(strip(coloredText).length); // Outputs 12
```
#### `rainbow(text)`
Applies a vibrant rainbow effect to the input text, coloring each character sequentially through a spectrum.
```javascript
import { rainbow } from 'adclours';
console.log(rainbow('Welcome to the Rainbow!'));
```
#### `gradient(text, startHex, endHex)`
Applies a smooth color gradient across the characters of the text, transitioning from a starting HEX color to an ending HEX color.
```javascript
import { gradient } from 'adclours';
console.log(gradient('Beautiful Gradient Text', '#FF0000', '#0000FF')); // Red to Blue gradient
```
#### `progressBar(value, total, options)`
Generates a customizable terminal-based progress bar.
* `value`: Current progress value.
* `total`: Total value for completion.
* `options`:
* `width` (default: `50`): Total width of the bar.
* `filledChar` (default: `'█'`): Character for the filled portion.
* `emptyChar` (default: `'░'`): Character for the empty portion.
The bar automatically changes color based on progress (red < 30%, yellow < 70%, green >= 70%).
```javascript
import { progressBar } from 'adclours';
console.log(progressBar(10, 100));
console.log(progressBar(50, 100, { width: 30, filledChar: '=', emptyChar: '-' }));
console.log(progressBar(90, 100));
```
#### `box(text, options)`
Draws a decorative box around the given text. Supports multi-line text.
* `text`: The content to be boxed.
* `options`:
* `borderColor` (default: `'white'`): Color of the box border (uses named colors).
* `style` (default: `'single'`): Border style (`'single'`, `'double'`, or `'triple'`).
* `padding` (default: `1`): Space between the text and the border.
```javascript
import { box, color } from 'adclours';
const message = `
${color.bold('Important Message:')}
${color.yellow('Please review the updated documentation.')}
${color.dim('Version 2.0.0 is now available.')}
`;
console.log(box(message, { borderColor: 'blue', style: 'double', padding: 2 }));
console.log(box(color.bold.cyan('Important Notice'), { borderColor: 'red', padding: 2 }));
```
#### `center(text, width)`
Centers the given text within a specified terminal width. ANSI escape codes are ignored for width calculation.
```javascript
import { center, color } from 'adclours';
const terminalWidth = 80;
console.log(center(color.yellow('Centered Text'), terminalWidth));
console.log(center('Another centered line', terminalWidth));
```
#### `wrap(text, width)`
Wraps long text to fit within a specified terminal width, breaking lines at word boundaries.
```javascript
import { wrap } from 'adclours';
const longText = "This is a very long sentence that needs to be wrapped to fit into a smaller terminal width for better readability and presentation.";
console.log(wrap(longText, 30));
```
#### `asciiArt(text)`
Converts input text into large ASCII art characters. Currently supports uppercase letters A, B, C, D, E, L, O, R, S, P, I, T, M.
```javascript
import { asciiArt, color } from 'adclours';
console.log(color.magenta(asciiArt('CODE')));
console.log(color.cyan(asciiArt('ADCLOURS')));
```
#### `pad(text, width, side, char)`
Pads text with a specified character to reach a target width.
* `text`: The text to pad.
* `width`: The total desired width.
* `side` (default: `'right'`): Side to pad on (`'left'` or `'right'`).
* `char` (default: `' '`): The padding character.
```javascript
import { pad, color } from 'adclours';
console.log(pad(color.green('Success'), 20, 'right', '.')); // "Success............."
console.log(pad(color.red('Error'), 20, 'left', '-')); // "-------------Error"
```
#### `table(rows, options)`
Creates a simple, formatted table in the terminal.
* `rows`: An array of arrays, where the first inner array is the header row.
* `options`:
* `align` (default: `['left']`): An array of alignment strings (`'left'`, `'right'`, `'center'`) for each column.
```javascript
import { table, color } from 'adclours';
const data = [
[color.bold('Name'), color.bold('Age'), color.bold('City')],
['Alice', '30', 'New York'],
['Bob', '24', 'London'],
['Charlie', '35', 'Paris']
];
console.log(table(data, { align: ['left', 'center', 'right'] }));
```
#### `line(width, text)`
Generates a horizontal line, optionally with text centered within it.
* `width`: The total width of the line.
* `text` (default: `''`): Optional text to embed in the center.
```javascript
import { line, color } from 'adclours';
console.log(color.dim(line(50)));
console.log(color.blue(line(50, 'SECTION START')));
console.log(color.dim(line(50)));
```
#### `title(title, subtitle, width)`
Creates a formatted title block, optionally with a subtitle, centered within a given width.
* `title`: The main title string.
* `subtitle` (default: `''`): An optional subtitle string.
* `width`: The total width for centering.
```javascript
import { title, color } from 'adclours';
console.log(title(color.bold.green('APPLICATION STATUS'), 'Version 1.0.0', 60));
```
#### `list(items, options)`
Formats an array of strings into a bulleted list.
* `items`: An array of strings, each representing a list item.
* `options`:
* `symbol` (default: `'•'`): The bullet symbol to use.
```javascript
import { list } from 'adclours';
const tasks = [
'Complete documentation',
'Implement new feature',
'Fix reported bugs'
];
console.log(list(tasks));
console.log(list(['Item A', 'Item B'], { symbol: '➤' }));
```
#### `blend(text, color1, color2, ratio, mode)`
Blends two colors and applies the resulting color to the text.
* `text`: The text to color.
* `color1`, `color2`: The two colors to blend (can be named color strings, hex codes, or `[r, g, b]` arrays).
* `ratio` (default: `0.5`): Blending ratio (0.0 for pure `color1`, 1.0 for pure `color2`).
* `mode` (default: `'normal'`): Blending mode (`'normal'`, `'multiply'`, `'screen'`).
```javascript
import { blend } from 'adclours';
console.log(blend('Blended Color', 'red', 'blue', 0.5)); // 50% red, 50% blue
console.log(blend('Multiply Blend', '#FF0000', '#00FF00', 0.5, 'multiply')); // Red and Green multiplied
```
#### `generateShades(baseColor, count, direction)`
Generates an array of color-formatted strings representing shades of a base color.
* `baseColor`: The starting color (named color string, hex code, or `[r, g, b]` array).
* `count` (default: `5`): Number of shades to generate.
* `direction` (default: `'darken'`): `'darken'` or `'lighten'`.
```javascript
import { generateShades } from 'adclours';
const redShades = generateShades('red', 5, 'darken');
redShades.forEach((shade, i) => console.log(shade(`Shade ${i + 1}`)));
const blueTints = generateShades('#0000FF', 3, 'lighten');
blueTints.forEach((tint, i) => console.log(tint(`Tint ${i + 1}`)));
```
#### `findNearestColor(inputColor)`
Finds the closest named color from the extended color list to a given input color (RGB or HEX).
* `inputColor`: The color to find the nearest match for (named color string, hex code, or `[r, g, b]` array).
```javascript
import { findNearestColor } from 'adclours';
console.log(`Nearest color to #FF6347 (Tomato): ${findNearestColor('#FF6347')}`);
console.log(`Nearest color to [0, 128, 0] (Dark Green): ${findNearestColor([0, 128, 0])}`);
```
### 4. Advanced Components
#### `Spinner` Class
Provides an animated terminal spinner for indicating ongoing processes.
* `constructor(frames, text, interval, styleFn = color.white)`:
* `frames`: An array of characters for the animation frames (e.g., `['-', '\', '|', '/']`).
* `text`: The text to display next to the spinner.
* `interval`: The animation speed in milliseconds.
* `styleFn`: A `color` function to style the spinner (e.g., `color.cyan`).
* `spinner.start()`: Starts the spinner animation.
* `spinner.stop(finalChar = '✔', finalText = 'Done!', finalColor = 'green')`: Stops the spinner, replaces it with a final character, and displays a final message.
```javascript
import { Spinner, color } from 'adclours';
const spinner = new Spinner(['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'], 'Loading data...', 100, color.cyan);
spinner.start();
setTimeout(() => {
spinner.stop('✔', 'Data Loaded Successfully!', 'green');
}, 3000);
```
#### `animate(text, options)`
Applies simple text animations like blinking or pulsing.
* `text`: The text to animate.
* `options`:
* `effect` (default: `'blink'`): The animation effect (`'blink'` or `'pulse'`).
* `interval` (default: `500`): Interval between animation frames in milliseconds.
* `duration` (default: `3000`): Total duration of the animation in milliseconds.
```javascript
import { animate, color } from 'adclours';
console.log('Starting animation...');
animate(color.red.bold('ALERT: System Overload!'), { effect: 'blink', duration: 4000 });
setTimeout(() => {
console.log('\nStarting pulse animation...');
animate(color.blue('Pulsing Message'), { effect: 'pulse', interval: 200, duration: 4000 });
}, 6000);
```
### 5. Structured Logging System (`log` object)
A convenient utility for structured console logging with timestamps and colored prefixes.
* `log.info(msg)`: Prints an informational message (blue `ⓘ`).
* `log.success(msg)`: Prints a success message (green `✔`).
* `log.warn(msg)`: Prints a warning message (yellow `▲`).
* `log.error(msg)`: Prints an error message (red `✖`).
* `log.debug(msg)`: Prints a debug message (dim `🐛 [DEBUG]`) only if `process.env.DEBUG` is set to `'true'`.
```javascript
import { log } from 'adclours';
log.info('Application started.');
log.success('Operation completed successfully.');
log.warn('Configuration file not found, using defaults.');
log.error('Failed to connect to the database!');
// To see debug messages, run your Node.js script with: DEBUG=true node your_script.mjs
process.env.DEBUG = 'true'; // For demonstration
log.debug('This is a debug message.');
delete process.env.DEBUG; // Clean up
```
## License and Terms
`adclours` is an open-source project developed by **Smart Tell Line**. It is licensed under the **MIT License**.
* The full text of the MIT License can be found in the [`LICENSE`](./LICENSE) file.
* Additional terms and conditions are detailed in the [`TERMS_AND_CONDITIONS.md`](./TERMS_AND_CONDITIONS.md) file.
We encourage contributions and feedback from the community to make `adclours` even better!
## Installation
`adclours` is available as a package on npm. You can install it using your preferred package manager:
```bash
npm install adclours
# or
yarn add adclours
# or
pnpm add adclours
```
### Usage
Once installed, you can import and use `adclours` in your JavaScript files:
```javascript
// your_script.mjs
import { color, log, Spinner } from 'adclours'; // Note: import from 'adclours' not './adclours.mjs'
console.log(color.green('adclours is ready!'));
log.info('Starting application...');
```
Make sure your `package.json` has `"type": "module"` if you are using ES modules in a Node.js environment.
```json
{
"name": "my-project",
"version": "1.0.0",
"type": "module", // <--- Add this line
"main": "index.js",
"scripts": {
"start": "node index.mjs"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": ""
}
```
### Direct Import (Alternative)
If you prefer not to use a package manager, you can still directly import the `adclours.mjs` module file into your project:
1. **Save the file:** Save the `adclours.mjs` content into your project directory.
2. **Import:** Use ES module imports in your JavaScript files, referencing the local file path:
```javascript
// your_script.mjs
import { color, log, Spinner } from './adclours.mjs'; // Note: import from './adclours.mjs'
console.log(color.green('adclours.mjs is ready!'));
log.info('Starting application...');
```
## Usage Examples
Here are some combined examples demonstrating the power and flexibility of `adclours.mjs`.
```javascript
// example.mjs
import { color, log, progressBar, box, asciiArt, line, title, Spinner, animate } from 'adclours'; // Or './adclours.mjs' if direct import
async function runDemo() {
console.clear(); // Clear console for a clean demo
// --- Welcome Title ---
console.log(title(color.bold.cyan('ADCLOURS DEMO'), 'Terminal Styling Powerhouse', 80));
console.log(line(80, color.dim('START')));
console.log('\n');
// --- Basic Styling ---
log.info('Demonstrating basic text styling:');
console.log(color.red('This is red.'));
console.log(color.bold.green('This is bold green.'));
console.log(color.underline.magenta.bgCyan('Underlined magenta on cyan background.'));
console.log('\n');
// --- Advanced Colors ---
log.info('Showcasing advanced color capabilities:');
console.log(color.rgb(255, 165, 0)('Orange RGB text.'));
console.log(color.bgHex('#4CAF50')('Text with a Material Green background.'));
console.log(color.color256(160)('Deep red from 256-color palette.'));
console.log(color.gold('This text is golden!'));
console.log('\n');
// --- Progress Bar ---
log.info('Progress Bar in action:');
let progress = 0;
const total = 100;
const interval = setInterval(() => {
process.stdout.write(`\r${progressBar(progress, total)}`);
progress += 5;
if (progress > total) {
clearInterval(interval);
console.log('\n');
log.success('Progress complete!');
console.log('\n');
}
}, 100);
await new Promise(resolve => setTimeout(resolve, 2500)); // Wait for progress bar
// --- Box Example ---
log.info('Text inside a custom box:');
const boxedContent = `
${color.bold('Important Message:')}
${color.yellow('Please review the updated documentation.')}
${color.dim('Version 2.0.0 is now available.')}
`;
console.log(box(boxedContent, { borderColor: 'blue', style: 'double', padding: 2 }));
console.log('\n');
// --- ASCII Art ---
log.info('Generating ASCII Art:');
console.log(color.brightGreen(asciiArt('CODE')));
console.log('\n');
// --- Spinner ---
log.info('Starting a spinner for a simulated task:');
const spinner = new Spinner(['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'], 'Processing files...', 80, color.cyan);
spinner.start();
await new Promise(resolve => setTimeout(resolve, 3000));
spinner.stop('✔', 'Files Processed!', 'green');
console.log('\n');
// --- Animation ---
log.info('Demonstrating text animation (blinking):');
animate(color.red.bold('ALERT: System Overload!'), { effect: 'blink', duration: 4000 });
await new Promise(resolve => setTimeout(resolve, 5000)); // Wait for animation to finish
console.log('\n');
console.log(line(80, color.dim('END')));
log.info('Demo finished. Explore adclours.mjs for more!');
}
runDemo();
```
Listen carefully developers. This module is cross platform and cross run time, meaning it can be used without error in nodejs, deno, and Typescript. The URL to use or a import it in deno is https://cdn.jsdelivr.net/npm/adclours@latest/adclours.mjs