styled-string-builder
Version:
String Styler class based on a builder design pattern
173 lines (172 loc) • 7 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.StyledString = void 0;
exports.style = style;
const constants_1 = require("./constants.cjs");
const colors_1 = require("./colors.cjs");
/**
* @class StyledString
* @description A class that extends string functionality with ANSI color and style options.
* @summary StyledString provides methods to apply various ANSI color and style options to text strings.
* It implements the ColorizeOptions interface and proxies native string methods to the underlying text.
* This class allows for chaining of styling methods and easy application of colors and styles to text.
*
* @implements {ColorizeOptions}
* @param {string} text - The initial text string to be styled.
*/
class StyledString {
constructor(text) {
this.text = text;
// Basic colors
Object.entries(constants_1.StandardForegroundColors).forEach(([name, code]) => {
Object.defineProperty(this, name, {
get: () => this.foreground(code),
});
});
Object.entries(constants_1.BrightForegroundColors).forEach(([name, code]) => {
Object.defineProperty(this, name, {
get: () => this.foreground(code),
});
});
// Background colors
Object.entries(constants_1.StandardBackgroundColors).forEach(([name, code]) => {
Object.defineProperty(this, name, {
get: () => this.background(code),
});
});
Object.entries(constants_1.BrightBackgroundColors).forEach(([name, code]) => {
Object.defineProperty(this, name, {
get: () => this.background(code),
});
});
// Styles
Object.entries(constants_1.styles).forEach(([name, code]) => {
Object.defineProperty(this, name, {
get: () => this.style(code),
});
});
}
/**
* @description Clears all styling from the text.
* @summary Removes all ANSI color and style codes from the text.
* @return {StyledString} The StyledString instance with cleared styling.
*/
clear() {
this.text = (0, colors_1.clear)(this.text);
return this;
}
/**
* @description Applies raw ANSI codes to the text.
* @summary Allows direct application of ANSI escape sequences to the text.
* @param {string} rawAnsi - The raw ANSI escape sequence to apply.
* @return {StyledString} The StyledString instance with the raw ANSI code applied.
*/
raw(rawAnsi) {
this.text = (0, colors_1.raw)(this.text, rawAnsi);
return this;
}
/**
* @description Applies a foreground color to the text.
* @summary Sets the text color using ANSI color codes.
* @param {number} n - The ANSI color code for the foreground color.
* @return {StyledString} The StyledString instance with the foreground color applied.
*/
foreground(n) {
this.text = (0, colors_1.colorizeANSI)(this.text, n);
return this;
}
/**
* @description Applies a background color to the text.
* @summary Sets the background color of the text using ANSI color codes.
* @param {number} n - The ANSI color code for the background color.
* @return {StyledString} The StyledString instance with the background color applied.
*/
background(n) {
this.text = (0, colors_1.colorizeANSI)(this.text, n, true);
return this;
}
/**
* @description Applies a text style to the string.
* @summary Sets text styles such as bold, italic, or underline using ANSI style codes.
* @param {number | string} n - The style code or key from the styles object.
* @return {StyledString} The StyledString instance with the style applied.
*/
style(n) {
if (typeof n === "string" && !(n in constants_1.styles)) {
console.warn(`Invalid style: ${n}`);
return this;
}
this.text = (0, colors_1.applyStyle)(this.text, n);
return this;
}
/**
* @description Applies a 256-color foreground color to the text.
* @summary Sets the text color using the extended 256-color palette.
* @param {number} n - The color number from the 256-color palette.
* @return {StyledString} The StyledString instance with the 256-color foreground applied.
*/
color256(n) {
this.text = (0, colors_1.colorize256)(this.text, n);
return this;
}
/**
* @description Applies a 256-color background color to the text.
* @summary Sets the background color using the extended 256-color palette.
* @param {number} n - The color number from the 256-color palette.
* @return {StyledString} The StyledString instance with the 256-color background applied.
*/
bgColor256(n) {
this.text = (0, colors_1.colorize256)(this.text, n, true);
return this;
}
/**
* @description Applies an RGB foreground color to the text.
* @summary Sets the text color using RGB values.
* @param {number} r - The red component (0-255).
* @param {number} g - The green component (0-255).
* @param {number} b - The blue component (0-255).
* @return {StyledString} The StyledString instance with the RGB foreground color applied.
*/
rgb(r, g, b) {
this.text = (0, colors_1.colorizeRGB)(this.text, r, g, b);
return this;
}
/**
* @description Applies an RGB background color to the text.
* @summary Sets the background color using RGB values.
* @param {number} r - The red component (0-255).
* @param {number} g - The green component (0-255).
* @param {number} b - The blue component (0-255).
* @return {StyledString} The StyledString instance with the RGB background color applied.
*/
bgRgb(r, g, b) {
this.text = (0, colors_1.colorizeRGB)(this.text, r, g, b, true);
return this;
}
/**
* @description Converts the StyledString to a regular string.
* @summary Returns the underlying text with all applied styling.
* @return {string} The styled text as a regular string.
*/
toString() {
return this.text;
}
}
exports.StyledString = StyledString;
/**
* @description Applies styling to a given text string.
* @summary This function takes a string and returns a StyledString object, which is an enhanced
* version of the original string with additional methods for applying various ANSI color and style
* options. It sets up a mapper object with methods for different styling operations and then
* defines properties on the text string to make these methods accessible.
*
* @param {string[]} t The input text to be styled.
* @return {StyledString} A StyledString object with additional styling methods.
*
* @function style
*
* @memberOf StyledString
*/
function style(...t) {
return new StyledString(t.join(" "));
}