toolbox-x 1.0.0

package/dist/Stylog-Df7eq3-j.d.cts

@@ -0,0 +1,519 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { s as CSSColor } from "./Color-B3mgF9Dh.cjs";
+
+//#region src/stylog/constants.d.ts
+/** Records of ANSI-16 colors with values */
+declare const ANSI_16_COLORS: Readonly<{
+  readonly black: readonly [30, 39];
+  readonly red: readonly [31, 39];
+  readonly green: readonly [32, 39];
+  readonly yellow: readonly [33, 39];
+  readonly blue: readonly [34, 39];
+  readonly purple: readonly [35, 39];
+  readonly cyan: readonly [36, 39];
+  readonly white: readonly [37, 39];
+  readonly blackBright: readonly [90, 39];
+  readonly redBright: readonly [91, 39];
+  readonly greenBright: readonly [92, 39];
+  readonly yellowBright: readonly [93, 39];
+  readonly blueBright: readonly [94, 39];
+  readonly purpleBright: readonly [95, 39];
+  readonly cyanBright: readonly [96, 39];
+  readonly whiteBright: readonly [97, 39];
+  readonly bgBlack: readonly [40, 49];
+  readonly bgRed: readonly [41, 49];
+  readonly bgGreen: readonly [42, 49];
+  readonly bgYellow: readonly [43, 49];
+  readonly bgBlue: readonly [44, 49];
+  readonly bgPurple: readonly [45, 49];
+  readonly bgCyan: readonly [46, 49];
+  readonly bgWhite: readonly [47, 49];
+  readonly bgBlackBright: readonly [100, 49];
+  readonly bgRedBright: readonly [101, 49];
+  readonly bgGreenBright: readonly [102, 49];
+  readonly bgYellowBright: readonly [103, 49];
+  readonly bgBlueBright: readonly [104, 49];
+  readonly bgPurpleBright: readonly [105, 49];
+  readonly bgCyanBright: readonly [106, 49];
+  readonly bgWhiteBright: readonly [107, 49];
+}>;
+//#endregion
+//#region src/types/stylog.d.ts
+/** Non-color text styles */
+type TextStyle = 'bold' | 'bolder' | 'dim' | 'italic' | 'underline' | 'strikethrough' | 'inverse';
+/** Represents `ANSI-16` color names available in `LogStyler` */
+type Ansi16Color = keyof typeof ANSI_16_COLORS;
+/** Represents `ANSI-16` color names with `css-` prefix available in `LogStyler` */
+type CSS16Color = `css-${Ansi16Color}`;
+/** Represents the value of `ANSI-16` color codes */
+type Ansi16Value = (typeof ANSI_16_COLORS)[Ansi16Color];
+/** Represents a css color starting with `bg` (e.g. `"bgRed"`). */
+type BGColor = `bg${Capitalize<CSSColor>}`;
+/** Styles allowed for `LogStyler` or `Stylog` */
+type Styles = CSSColor | BGColor | TextStyle;
+/** A `tuple of strings` that represents `ANSI` color code with special closing and ending */
+type AnsiSequence = [string, string];
+/**
+ * * Type representing a fully chainable `LogStyler` instance.
+ *
+ * @remarks
+ * - Each property corresponds to a style and returns a new `Stylog` instance, allowing fluent chaining.
+ * - **This type combines:**
+ *   - The methods of `LogStyler` (e.g., `.style()`, `.log()`)
+ *   - Dynamically generated properties for all available `Styles` that return another `Stylog` instance for chaining.
+ *
+ * @example
+ * Stylog.green.bold.bgBlue.log('Hello World');
+ */
+type StylogChain = LogStyler & { [K in Styles]: StylogChain };
+//#endregion
+//#region src/stylog/Stylog.d.ts
+/**
+ * @class Utility class for styling console log output with `ANSI` (`Node.js`) or `CSS` (Browser).
+ *
+ * @remarks
+ * - Allows chaining of style methods or initializing with predefined styles.
+ * - For fluent, chainable styling with zero configuration use {@link https://toolbox.nazmul-nhb.dev/docs/utilities/misc/stylog Stylog} (`LogStyler` chainable wrapper).
+ *
+ * @example
+ * const styled = new LogStyler(['red', 'bold']);
+ * styled.log('Hello World');
+ *
+ * const logger = new LogStyler();
+ * logger.style('blue', 'dim', 'bold').log('Hello Blue');
+ * logger.style('blue', 'dim', 'bold').toANSI('Hello Blue');
+ * logger.style('blue', 'dim', 'bold').toCSS('Hello Blue');
+ */
+declare class LogStyler {
+  #private;
+  /**
+   * * Creates a new `LogStyler` instance.
+   *
+   * @param styles - Optional array of initial styles to apply (e.g., ['red', 'bold']). Defaults to an empty array.
+   *
+   * @example
+   * const styled = new LogStyler(['red', 'bold']);
+   * styled.log('Hello World');
+   *
+   * const logger = new LogStyler();
+   * logger.style('blue', 'dim', 'bold').log('Hello Blue');
+   * logger.style('blue', 'dim', 'bold').toANSI('Hello Blue');
+   * logger.style('blue', 'dim', 'bold').toCSS('Hello Blue');
+   */
+  constructor(styles?: Styles[]);
+  /**
+   * * Chain multiple styles to the input.
+   *
+   * @param style - One or more styles to apply (color, background, or text style).
+   * @returns A new StylogChain instance with the additional styles applied.
+   *
+   * @remarks
+   *  - When chaining similar styles, only the last one(s) takes effect.
+   *  - All colors applied through `style()` method are `truecolor` in form, to apply `ANSI-16` colors, use `ansi16()` method.
+   *
+   * @example
+   * // Single style
+   * Stylog.style('red').log('Red text');
+   * Stylog.style('red').toANSI('Red text');
+   * Stylog.style('red').toCSS('Red text');
+   *
+   * @example
+   * // Multiple styles at once
+   * Stylog.style('red', 'bold', 'underline').log('Red bold underlined text');
+   * Stylog.style('red', 'bold', 'underline').toANSI('Red bold underlined text');
+   * Stylog.style('red', 'bold', 'underline').toCSS('Red bold underlined text');
+   *
+   * @example
+   * // Mixed foreground and background
+   * Stylog.style('white', 'bgBlue').log('White text on blue background');
+   * Stylog.style('white', 'bgBlue').toANSI('White text on blue background');
+   * Stylog.style('white', 'bgBlue').toCSS('White text on blue background');
+   *
+   * @example
+   * // Building on existing styles
+   * const errorStyle = Stylog.style('red', 'bold');
+   * errorStyle.style('underline').log('Red bold underlined error');
+   * errorStyle.style('underline').toANSI('Red bold underlined error');
+   * errorStyle.style('underline').toCSS('Red bold underlined error');
+   */
+  style(...style: Styles[]): StylogChain;
+  /**
+   * * Apply ANSI 16-color styling to the text.
+   *
+   * @param color - ANSI 16-color name (e.g., 'red', 'cyanBright', 'bgRed').
+   * @returns A new `StylogChain` instance with the `ANSI 16-color` style applied.
+   *
+   * @remarks
+   *  - Only one argument (color) can be passed on a single call.
+   *  - Color applied through `ansi16()` method is `truecolor` in form, to apply `truecolor` colors, use `style()` method.
+   *
+   * @example
+   * // Basic usage
+   * Stylog.ansi16('red').log('Error message');
+   *
+   * @example
+   * // Chaining with other styles
+   * Stylog.ansi16('redBright').bold.italic.log('Bright red bold italic');
+   * Stylog.ansi16('redBright').bold.italic.toANSI('Bright red bold italic');
+   * Stylog.ansi16('redBright').bold.italic.toCSS('Bright red bold italic');
+   *
+   * @example
+   * // Background colors
+   * Stylog.ansi16('bgRed').log('Red background');
+   * Stylog.ansi16('bgRed').toANSI('Red background');
+   * Stylog.ansi16('bgRed').toCSS('Red background');
+   */
+  ansi16(color: Ansi16Color): StylogChain;
+  /**
+   * * Returns styled tuple `[format, cssList]` for Browser.
+   *
+   * @remarks
+   * - This method is specifically designed for browser environments and returns a tuple containing the formatted string with `%c` placeholder and an array of CSS styles (`string[]`).
+   * - Use this when you need direct access to the CSS styling for custom browser output.
+   * - If you want to format with ANSI escape codes, consider using {@link https://toolbox.nazmul-nhb.dev/docs/classes/LogStyler#toansiinput-stringify toANSI} method.
+   *
+   * @param input - Input to style before printing in the shell.
+   * @param stringify - Whether to apply `JSON.stringify()` before styling. Defaults to `false`.
+   * @returns Tuple `[format, cssList]` where:
+   *   - `format`: String with `%c` placeholder for CSS styling
+   *   - `cssList`: Array of CSS style strings
+   *
+   * @example
+   * // Basic usage in browser
+   * const styler = new LogStyler(['red', 'bold']);
+   * const [format, cssList] = styler.toCSS('Error message');
+   * // format: "%cError message"
+   * // cssList: ["color: #FF0000", "font-weight: bold"]
+   *
+   * @example
+   * // Custom browser output handling
+   * const styled = new LogStyler(['blue', 'bgYellow', 'italic']);
+   * const [format, styles] = styled.toCSS('Warning', true);
+   *
+   * // Use with custom logging function
+   * function customLog(formatted: string, styles: string[]) {
+   *   const styleString = styles.join('; ');
+   *   console.log(formatted, styleString);
+   * }
+   * customLog(format, styles);
+   *
+   * @example
+   * // With object stringification
+   * const dataOutput = new LogStyler(['green']).toCSS({ id: 123 }, true);
+   * // format: "%c{\"id\":123}"
+   * // cssList: ["color: #008000"]
+   */
+  toCSS(input: unknown, stringify?: boolean): [`%c${string}`, string[]];
+  /**
+   * * Returns the input as a styled string with ANSI escape codes.
+   *
+   * @remarks
+   * - This method returns ANSI-formatted strings suitable for environments that support ANSI escape codes (terminals, modern browser consoles, etc.).
+   * - For unsupported browsers, consider using the {@link https://toolbox.nazmul-nhb.dev/docs/classes/LogStyler#loginput-stringify log} method to print directly or {@link https://toolbox.nazmul-nhb.dev/docs/classes/LogStyler#tocssinput-stringify toCSS} to get styled tuple `[format, cssList]` for Browser.
+   *
+   * @param input - Input to style before printing in the shell.
+   * @param stringify - Whether to apply `JSON.stringify()` before styling. Defaults to `false`.
+   * @returns The styled string with ANSI escape codes.
+   *
+   * @example
+   * const styled = new LogStyler(['red', 'bold']);
+   * const errorMessage = styled.toANSI('Error occurred, using LogStyler');
+   * // Or with Stylog
+   * const errorMessage = Stylog.red.bold.toANSI('Error occurred, using Stylog');
+   * // Returns: "\x1b[31m\x1b[1mError occurred, using Stylog\xx1b[22m\x1b[39m"
+   *
+   * @example
+   * // Use in console (terminal or modern browser consoles)
+   * console.error(errorMessage);
+   * console.info(Stylog.red.bold.toANSI('I support ANSI!'));
+   */
+  toANSI(input: unknown, stringify?: boolean): string;
+  /**
+   * * Print styled input to the console.
+   *
+   * @param input Input to print to the shell/console.
+   * @param stringify Whether to apply `JSON.stringify()` before printing. Defaults to `false`.
+   */
+  log(input: unknown, stringify?: boolean): void;
+  /**
+   * * Apply a HEX color to the text foreground.
+   *
+   * @param code - HEX color string (e.g., `'#4682B4'` or `'4682B4'`).
+   * @returns A new `StylogChain` instance with the HEX color applied.
+   *
+   * @example
+   * // With hash prefix
+   * Stylog.hex('#4682B4').log('Steel blue text');
+   * Stylog.hex('#4682B4').toANSI('Steel blue text');
+   * Stylog.hex('#4682B4').toCSS('Steel blue text');
+   *
+   * @example
+   * // Without hash prefix
+   * Stylog.hex('4682B4').log('Steel blue text');
+   * Stylog.hex('4682B4').toANSI('Steel blue text');
+   * Stylog.hex('4682B4').toCSS('Steel blue text');
+   *
+   * @example
+   * // Chaining with other styles
+   * Stylog.hex('#FF0000').bold.log('Red bold text');
+   * Stylog.hex('#FF0000').bold.toANSI('Red bold text');
+   * Stylog.hex('#FF0000').bold.toCSS('Red bold text');
+   */
+  hex(code: string): StylogChain;
+  /**
+   * * Apply a HEX color to the text background.
+   *
+   * @param code - HEX color string (e.g., `'#4682B4'` or `'4682B4'`).
+   * @returns A new StylogChain instance with the HEX background color applied.
+   *
+   * @example
+   * // With hash prefix
+   * Stylog.bgHex('#4682B4').log('Steel blue background');
+   * Stylog.bgHex('#4682B4').toANSI('Steel blue background');
+   * Stylog.bgHex('#4682B4').toCSS('Steel blue background');
+   *
+   * @example
+   * // Without hash prefix
+   * Stylog.bgHex('4682B4').log('Steel blue background');
+   * Stylog.bgHex('4682B4').toANSI('Steel blue background');
+   * Stylog.bgHex('4682B4').toCSS('Steel blue background');
+   *
+   * @example
+   * // Chaining with foreground color
+   * Stylog.white.bgHex('#000000').log('White text on black background');
+   * Stylog.white.bgHex('#000000').toANSI('White text on black background');
+   * Stylog.white.bgHex('#000000').toCSS('White text on black background');
+   */
+  bgHex(code: string): StylogChain;
+  /**
+   * * Apply an RGB color to the text foreground using a CSS-like string.
+   *
+   * @param code - RGB color string (e.g., `'rgb(11, 45, 1)'` or `'11, 45, 1'`).
+   * @returns A new `StylogChain` instance with the RGB color applied.
+   *
+   * @example
+   * // Full rgb() syntax
+   * Stylog.rgb('rgb(11, 45, 1)').log('Dark green text');
+   * Stylog.rgb('rgb(11, 45, 1)').toANSI('Dark green text');
+   * Stylog.rgb('rgb(11, 45, 1)').toCSS('Dark green text');
+   *
+   * @example
+   * // Comma-separated values
+   * Stylog.rgb('11, 45, 1').log('Dark green text');
+   * Stylog.rgb('11, 45, 1').toANSI('Dark green text');
+   * Stylog.rgb('11, 45, 1').toCSS('Dark green text');
+   *
+   * @example
+   * // Chaining with other styles
+   * Stylog.rgb('255, 0, 0').bold.log('Red bold text');
+   * Stylog.rgb('255, 0, 0').bold.toANSI('Red bold text');
+   * Stylog.rgb('255, 0, 0').bold.toCSS('Red bold text');
+   */
+  rgb(code: string): StylogChain;
+  /**
+   * * Apply an RGB color to the text foreground using individual components.
+   *
+   * @param red - Red component (`0-255`).
+   * @param green - Green component (`0-255`).
+   * @param blue - Blue component (`0-255`).
+   * @returns A new `StylogChain` instance with the RGB color applied.
+   *
+   * @example
+   * // Individual components
+   * Stylog.rgb(255, 0, 0).log('Red text');
+   * Stylog.rgb(255, 0, 0).toANSI('Red text');
+   * Stylog.rgb(255, 0, 0).toCSS('Red text');
+   *
+   * @example
+   * // With other styles
+   * Stylog.rgb(0, 255, 0).underline.log('Green underlined text');
+   * Stylog.rgb(0, 255, 0).underline.toANSI('Green underlined text');
+   * Stylog.rgb(0, 255, 0).underline.toCSS('Green underlined text');
+   */
+  rgb(red: number, green: number, blue: number): StylogChain;
+  /**
+   * * Apply an RGB color to the text background using a CSS-like string.
+   *
+   * @param code - RGB color string (e.g., `'rgb(225, 169, 196)'` or `'225, 169, 196'`).
+   * @returns A new `StylogChain` instance with the RGB background color applied.
+   *
+   * @example
+   * // Full rgb() syntax
+   * Stylog.bgRGB('rgb(225, 169, 196)').log('Pink background');
+   * Stylog.bgRGB('rgb(225, 169, 196)').toANSI('Pink background');
+   * Stylog.bgRGB('rgb(225, 169, 196)').toCSS('Pink background');
+   *
+   * @example
+   * // Comma-separated values
+   * Stylog.bgRGB('225, 169, 196').log('Pink background');
+   * Stylog.bgRGB('225, 169, 196').toANSI('Pink background');
+   * Stylog.bgRGB('225, 169, 196').toCSS('Pink background');
+   *
+   * @example
+   * // With foreground color
+   * Stylog.black.bgRGB('255, 255, 255').log('Black text on white background');
+   * Stylog.black.bgRGB('255, 255, 255').toANSI('Black text on white background');
+   * Stylog.black.bgRGB('255, 255, 255').toCSS('Black text on white background');
+   */
+  bgRGB(code: string): StylogChain;
+  /**
+   * * Apply an RGB color to the text background using individual components.
+   *
+   * @param red - Red component (`0-255`).
+   * @param green - Green component (`0-255`).
+   * @param blue - Blue component (`0-255`).
+   * @returns A new `StylogChain` instance with the RGB background color applied.
+   *
+   * @example
+   * // Individual components
+   * Stylog.bgRGB(0, 0, 255).log('Blue background');
+   * Stylog.bgRGB(0, 0, 255).toANSI('Blue background');
+   * Stylog.bgRGB(0, 0, 255).toCSS('Blue background');
+   *
+   * @example
+   * // With text styles
+   * Stylog.bgRGB(255, 255, 0).bold.log('Bold text on yellow background');
+   * Stylog.bgRGB(255, 255, 0).bold.toANSI('Bold text on yellow background');
+   * Stylog.bgRGB(255, 255, 0).bold.toCSS('Bold text on yellow background');
+   */
+  bgRGB(red: number, green: number, blue: number): StylogChain;
+  /**
+   * * Apply an HSL color to the text foreground using a CSS-like string.
+   *
+   * @param code - HSL color string (e.g., `'hsl(50 80.5% 40%)'`).
+   * @returns A new `StylogChain` instance with the HSL color applied.
+   *
+   * @example
+   * // Standard HSL syntax
+   * Stylog.hsl('hsl(50 80.5% 40%)').log('Gold text');
+   * Stylog.hsl('hsl(50 80.5% 40%)').toANSI('Gold text');
+   * Stylog.hsl('hsl(50 80.5% 40%)').toCSS('Gold text');
+   *
+   * @example
+   * // With commas
+   * Stylog.hsl('50, 80.5%, 40%').log('Gold text');
+   * Stylog.hsl('50, 80.5%, 40%').toANSI('Gold text');
+   * Stylog.hsl('50, 80.5%, 40%').toCSS('Gold text');
+   *
+   * @example
+   * // Chaining with other styles
+   * Stylog.hsl('120, 100%, 50%').italic.log('Green italic text');
+   * Stylog.hsl('120, 100%, 50%').italic.toANSI('Green italic text');
+   * Stylog.hsl('120, 100%, 50%').italic.toCSS('Green italic text');
+   */
+  hsl(code: string): StylogChain;
+  /**
+   * * Apply an HSL color to the text foreground using individual components.
+   *
+   * @param hue - Hue component (`0-360`).
+   * @param saturation - Saturation component (`0-100`).
+   * @param lightness - Lightness component (`0-100`).
+   * @returns A new `StylogChain` instance with the HSL color applied.
+   *
+   * @example
+   * // Individual components
+   * Stylog.hsl(0, 100, 50).log('Red text');
+   * Stylog.hsl(0, 100, 50).toANSI('Red text');
+   * Stylog.hsl(0, 100, 50).toCSS('Red text');
+   *
+   * @example
+   * // With percentage values
+   * Stylog.hsl(240, 100, 50).log('Blue text');
+   * Stylog.hsl(240, 100, 50).toANSI('Blue text');
+   * Stylog.hsl(240, 100, 50).toCSS('Blue text');
+   */
+  hsl(hue: number, saturation: number, lightness: number): StylogChain;
+  /**
+   * * Apply an HSL color to the text background using a CSS-like string.
+   *
+   * @param code - HSL color string (e.g., `'hsl(50 80.5% 40%)'`).
+   * @returns A new `StylogChain` instance with the HSL background color applied.
+   *
+   * @example
+   * // Standard HSL syntax
+   * Stylog.bgHSL('hsl(50 80.5% 40%)').log('Gold background');
+   * Stylog.bgHSL('hsl(50 80.5% 40%)').toANSI('Gold background');
+   * Stylog.bgHSL('hsl(50 80.5% 40%)').toCSS('Gold background');
+   *
+   * @example
+   * // With commas
+   * Stylog.bgHSL('50, 80.5%, 40%').log('Gold background');
+   * Stylog.bgHSL('50, 80.5%, 40%').toANSI('Gold background');
+   * Stylog.bgHSL('50, 80.5%, 40%').toCSS('Gold background');
+   *
+   * @example
+   * // With foreground color
+   * Stylog.white.bgHSL('0, 100%, 50%').log('White text on red background');
+   * Stylog.white.bgHSL('0, 100%, 50%').toANSI('White text on red background');
+   * Stylog.white.bgHSL('0, 100%, 50%').toCSS('White text on red background');
+   */
+  bgHSL(code: string): StylogChain;
+  /**
+   * * Apply an HSL color to the text background using individual components.
+   *
+   * @param hue - Hue component (`0-360`).
+   * @param saturation - Saturation component (`0-100`).
+   * @param lightness - Lightness component (`0-100`).
+   * @returns A new StylogChain instance with the HSL background color applied.
+   *
+   * @example
+   * // Individual components
+   * Stylog.bgHSL(120, 100, 50).log('Green background');
+   * Stylog.bgHSL(120, 100, 50).toANSI('Green background');
+   * Stylog.bgHSL(120, 100, 50).toCSS('Green background');
+   *
+   * @example
+   * // With text styles
+   * Stylog.bgHSL(300, 100, 50).bold.log('Bold text on purple background');
+   * Stylog.bgHSL(300, 100, 50).bold.toANSI('Bold text on purple background');
+   * Stylog.bgHSL(300, 100, 50).bold.toCSS('Bold text on purple background');
+   */
+  bgHSL(hue: number, saturation: number, lightness: number): StylogChain;
+}
+/**
+ * * Styled console logger with chainable, type-safe color and text effects for both `Node.js` (`ANSI true-color`) and browsers (`CSS` via `%c`).
+ *
+ * @remarks
+ * - Chain any mix of foreground colors (e.g. `green`), background colors (e.g. `bgBlue`), and text styles (e.g. `bold`, `italic`, `underline`).
+ * - In browsers, styles are applied using `CSS`; in `Node.js`, `ANSI` escape codes are used.
+ * - When multiple styles of the same category are chained, the last one wins.
+ * - Use `.log(value, stringify?)` to print; set `stringify` to `true` to serialize with `JSON.stringify`.
+ * - If you need custom reusable style configurations, use {@link https://toolbox.nazmul-nhb.dev/docs/classes/LogStyler Stylog} class.
+ *
+ * @example
+ * // Simple color
+ * Stylog.green.log('Ready');
+ *
+ * @example
+ * // Foreground + background + effect, with JSON stringification
+ * Stylog.green.bgBlue.bold.log({ a: 121 }, true);
+ *
+ * @example
+ * // Reusable base chain
+ * const base = Stylog.underline;
+ * base.red.log('Error');
+ * base.error.log('Error');
+ * base.bgYellow.bold.log('Caution');
+ *
+ * @example
+ * // Works in the browser console too
+ * Stylog.cornflowerblue.italic.log('Hello from the browser');
+ */
+declare const Stylog: StylogChain;
+//#endregion
+export { AnsiSequence as a, Styles as c, Ansi16Value as i, StylogChain as l, Stylog as n, BGColor as o, Ansi16Color as r, CSS16Color as s, LogStyler as t, TextStyle as u };