@reliverse/relico 1.2.0 → 1.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2024 Nazarii Korniienko
+Copyright (c) Nazar Kornienko (blefnk), Bleverse, Reliverse
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -4,20 +4,20 @@
 
 [sponsor](https://github.com/sponsors/blefnk) — [discord](https://discord.gg/Pb8uKbwpsJ) — [repo](https://github.com/reliverse/relico) — [npm](https://npmjs.com/@reliverse/relico)
 
-## 🌟 Why Relico?
+## Why Relico?
 
-Because terminal styling shouldn’t feel like duct tape. **Relico** brings design-system-level polish to your CLI logs, banners, errors, and output — without battling your runtime, shell, or platform. Terminal styling should be *fun*, not frustrating. Relico makes it feel *right*.
+Because terminal styling shouldn't feel like duct tape. **Relico** brings design-system-level polish to your CLI logs, banners, errors, and output — without battling your runtime, shell, or platform. Terminal styling should be *fun*, not frustrating. Relico makes it feel *right*.
 
+- ⚡ **Blazing-fast & lightweight** — type-safe, runtime-safe, build-time aware, zero bloat, zero dependencies, zero configuration
 - 🎨 **80+ built-in colors** — easily customize or override with your own [`HEX`](https://chatgpt.com/share/67fd24cd-e7b0-8008-a815-f33d01f33758) palette
 - 🧩 **Themeable by default** — end-users can configure themes+typography+colors via `relico.config.ts`, developers via `await initUserConfig({ ... })`
 - 🌈 **Smart color detection** — full support for truecolor (16M), 256-color, and fallback modes across environments
 - 🦄 **A modern alternative** to `chalk`, `kleur`, `colorette`, `gradient-string`, and legacy console hacks
 - 🧠 **Typed, chainable, DX-optimized** — with autocompletion, inline docs, and expressive API ergonomics
 - 🌿 **Respects your environment** — including `NO_COLOR`, `FORCE_COLOR`, and terminal capabilities
-- ⚡ **Blazing-fast & lightweight** — zero bloat, runtime-safe, build-time aware, minimal dependencies
 - 🛡️ **Cross-platform & runtime-ready** — works everywhere — even when your users' terminals are weird — in Node.js, Bun, Deno, CI, Windows, macOS, Linux, Docker & more
 - 🎯 **Precision-crafted ANSI output** — every color, reset, and style code is finely tuned for contrast, legibility, and glitch-free rendering — even in flaky terminals (as far as Node.js permits)
-- 🦾 **Relico isn’t just about color** — it’s about communication — make your CLI users' output more than readable — make it feel *intentional*.
+- 🦾 **Relico isn't just about color** — it's about communication — make your CLI users' output more than readable — make it feel *intentional*.
 
 <img src="./example/example.png" width="50%" alt="Available Relico colors" />
 
@@ -28,6 +28,64 @@ bun add @reliverse/relico
 # bun • pnpm • yarn • npm
 ```
 
+## Performance
+
+```bash
+$ bun bench
+$ bun examples/benchmarks/performance.ts
+
+🚀 Relico Performance Benchmarks
+==================================================
+C:/B/R/reliverse/relico/dist-npm/bin/mod.js
+
+Basic color access: 107.02ms (934 379 ops/sec)
+Chained colors: 191.49ms (522 227 ops/sec)
+RGB color creation: 73.79ms (1 355 276 ops/sec)
+Hex color creation: 87.73ms (1 139 866 ops/sec)
+HSL color creation: 78.10ms (1 280 444 ops/sec)
+Chain function: 226.13ms (442 219 ops/sec)
+Background colors: 208.55ms (479 492 ops/sec)
+Bright colors: 124.96ms (800 282 ops/sec)
+Pastel colors: 126.03ms (793 446 ops/sec)
+Multiline text (small): 165.08ms (605 769 ops/sec)
+Multiline text (large): 1089.44ms (91 790 ops/sec)
+
+Bundle Size Test:
+Core exports imported: 5
+```
+
+```bash
+$ bun size
+$ bun examples/benchmarks/bundle-size.ts
+
+📦 Bundle Size Analysis
+==============================
+C:/B/R/reliverse/relico/dist-npm/bin/mod.js
+
+Size:
+- File size: 12.9KB
+- Declaration file size: 2.9KB
+- Total bundle size: 15.8KB
+
+Breakdown:
+- Color data: 554B (4.2%)
+- Logic: 12.4KB (95.8%)
+```
+
+## 🔥 Important Notice
+
+Relico (v1.3.0+) was recently rewritten from scratch:
+
+- To have zero dependencies and zero configuration
+- Include only the really necessary for daily usage features
+- To be as fast as possible
+
+Some missing important features may be added back in the coming future.
+
+This means everything or most of the things described below in this readme may be different now.
+
+The readme will be updated soon.
+
 ## Configuration
 
 **If you're end-user OR developer, create `relico.config.ts` in your root**:
@@ -119,7 +177,7 @@ const brandColors: DefaultColorKeys[] = ["magentaBright", "maroon"];
 
 ## Color Detection
 
-Relico detects your terminal’s capability:
+Relico detects your terminal's capability:
 
 ```ts
 import { colorSupport } from "@reliverse/relico";
@@ -293,7 +351,7 @@ Relico draws inspiration from all — and goes beyond them with modern configs,
 
 ## 🛠 Contributing
 
-We’d love your help! Bug? Feature? Example? PR it!  
+We'd love your help! Bug? Feature? Example? PR it!  
 Or hop into [Discord](https://discord.gg/Pb8uKbwpsJ) to discuss CLI theming and terminal art 💜
 
 ```bash

package/bin/mod.d.ts

@@ -1,357 +1,75 @@
-/** A color definition: [primary, secondary]. */
-export type ColorDefinition = [string, string];
-/** A list of default color keys. */
-export declare const defaultColorKeys: readonly ["reset", "bold", "dim", "italic", "underline", "inverse", "hidden", "strikethrough", "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "gray", "bgBlack", "bgRed", "bgGreen", "bgYellow", "bgBlue", "bgMagenta", "bgCyan", "bgWhite", "blackBright", "redBright", "greenBright", "yellowBright", "blueBright", "magentaBright", "cyanBright", "whiteBright", "bgBlackBright", "bgRedBright", "bgGreenBright", "bgYellowBright", "bgBlueBright", "bgMagentaBright", "bgCyanBright", "bgWhiteBright", "redPastel", "greenPastel", "yellowPastel", "bluePastel", "magentaPastel", "cyanPastel", "bgRedPastel", "bgGreenPastel", "bgYellowPastel", "bgBluePastel", "bgMagentaPastel", "bgCyanPastel", "orange", "pink", "purple", "teal", "lime", "brown", "navy", "maroon", "olive", "silver", "bgOrange", "bgPink", "bgPurple", "bgTeal", "bgLime", "bgBrown", "bgNavy", "bgMaroon", "bgOlive", "bgSilver", "gray10", "gray20", "gray30", "gray40", "gray50", "gray60", "gray70", "gray80", "gray90"];
-/** Union of all default color keys */
-export type DefaultColorKeys = (typeof defaultColorKeys)[number];
-/**
- * Format keys that must NOT be overridden by the user.
- * We'll exclude them from IntelliSense and also skip them at runtime.
- */
-type RestrictedKeys = "reset" | "bold" | "dim" | "italic" | "underline" | "inverse" | "hidden" | "strikethrough";
-/** All the keys user is allowed to override */
-type OverridableColorKeys = Exclude<DefaultColorKeys, RestrictedKeys>;
-/** A map of user-overridable color definitions (no format keys) */
-export type OverridableColorMap = Partial<Record<OverridableColorKeys, ColorDefinition>>;
-/**
- * `relico.config.ts` configuration options.
- * Note: `customColors` is restricted to OverridableColorMap.
- */
-export type RelicoConfig = {
-    /**
-     * Determines which ANSI mode is used:
-     * - 0: no color
-     * - 1: basic ANSI (8 colors)
-     * - 2: 256 color palette
-     * - 3: 24-bit truecolor (default)
-     */
-    colorLevel?: 0 | 1 | 2 | 3;
-    /**
-     * Theme to use for color definitions.
-     * - "primary": primary theme (default)
-     * - "secondary": secondary theme
-     */
-    theme?: "primary" | "secondary";
-    /**
-     * Custom color definitions.
-     * - Theming: ["primary", "secondary"]
-     */
-    customColors?: OverridableColorMap;
-    /**
-     * Enable auto-detection of terminal color support
-     * Default: true
-     */
-    autoDetect?: boolean;
+type ColorLevel = 0 | 1 | 2 | 3;
+type Rgb = {
+    r: number;
+    g: number;
+    b: number;
 };
-export type IRelicoColors = {
-    reset(text: string | number): string;
-    bold(text: string | number): string;
-    dim(text: string | number): string;
-    italic(text: string | number): string;
-    underline(text: string | number): string;
-    inverse(text: string | number): string;
-    hidden(text: string | number): string;
-    strikethrough(text: string | number): string;
-    black(text: string | number): string;
-    red(text: string | number): string;
-    green(text: string | number): string;
-    yellow(text: string | number): string;
-    blue(text: string | number): string;
-    magenta(text: string | number): string;
-    cyan(text: string | number): string;
-    white(text: string | number): string;
-    gray(text: string | number): string;
-    bgBlack(text: string | number): string;
-    bgRed(text: string | number): string;
-    bgGreen(text: string | number): string;
-    bgYellow(text: string | number): string;
-    bgBlue(text: string | number): string;
-    bgMagenta(text: string | number): string;
-    bgCyan(text: string | number): string;
-    bgWhite(text: string | number): string;
-    blackBright(text: string | number): string;
-    redBright(text: string | number): string;
-    greenBright(text: string | number): string;
-    yellowBright(text: string | number): string;
-    blueBright(text: string | number): string;
-    magentaBright(text: string | number): string;
-    cyanBright(text: string | number): string;
-    whiteBright(text: string | number): string;
-    bgBlackBright(text: string | number): string;
-    bgRedBright(text: string | number): string;
-    bgGreenBright(text: string | number): string;
-    bgYellowBright(text: string | number): string;
-    bgBlueBright(text: string | number): string;
-    bgMagentaBright(text: string | number): string;
-    bgCyanBright(text: string | number): string;
-    bgWhiteBright(text: string | number): string;
-    redPastel(text: string | number): string;
-    greenPastel(text: string | number): string;
-    yellowPastel(text: string | number): string;
-    bluePastel(text: string | number): string;
-    magentaPastel(text: string | number): string;
-    cyanPastel(text: string | number): string;
-    bgRedPastel(text: string | number): string;
-    bgGreenPastel(text: string | number): string;
-    bgYellowPastel(text: string | number): string;
-    bgBluePastel(text: string | number): string;
-    bgMagentaPastel(text: string | number): string;
-    bgCyanPastel(text: string | number): string;
-    orange(text: string | number): string;
-    pink(text: string | number): string;
-    purple(text: string | number): string;
-    teal(text: string | number): string;
-    lime(text: string | number): string;
-    brown(text: string | number): string;
-    navy(text: string | number): string;
-    maroon(text: string | number): string;
-    olive(text: string | number): string;
-    silver(text: string | number): string;
-    bgOrange(text: string | number): string;
-    bgPink(text: string | number): string;
-    bgPurple(text: string | number): string;
-    bgTeal(text: string | number): string;
-    bgLime(text: string | number): string;
-    bgBrown(text: string | number): string;
-    bgNavy(text: string | number): string;
-    bgMaroon(text: string | number): string;
-    bgOlive(text: string | number): string;
-    bgSilver(text: string | number): string;
-    gray10(text: string | number): string;
-    gray20(text: string | number): string;
-    gray30(text: string | number): string;
-    gray40(text: string | number): string;
-    gray50(text: string | number): string;
-    gray60(text: string | number): string;
-    gray70(text: string | number): string;
-    gray80(text: string | number): string;
-    gray90(text: string | number): string;
+type SgrOp = {
+    kind: "style";
+    open: number[];
+} | {
+    kind: "fg-basic";
+    idx: number;
+    bright: boolean;
+} | {
+    kind: "bg-basic";
+    idx: number;
+    bright: boolean;
+} | {
+    kind: "fg-256";
+    code: number;
+} | {
+    kind: "bg-256";
+    code: number;
+} | {
+    kind: "fg-true";
+    rgb: Rgb;
+} | {
+    kind: "bg-true";
+    rgb: Rgb;
 };
-export declare const re: IRelicoColors;
-/**
- * Configures the library with a partial or complete
- * `RelicoConfig`. Invalid fields are ignored.
- */
-export declare function configure(userInput: unknown): void;
-/**
- * Returns a color function by name (or `reset` or identity if not found).
- * Uses cached functions for better performance.
- */
-/**
- * Colorizes text with a color function.
- */
-/**
- * Sets the color level (0=none, 1=basic, 2=256, 3=truecolor).
- */
-export declare function setColorLevel(level: 0 | 1 | 2 | 3): void;
-/**
- * Returns a custom "rgb" color function if level is truecolor, otherwise identity.
- * Uses caching for better performance.
- * @param r Red component (0-255)
- * @param g Green component (0-255)
- * @param b Blue component (0-255)
- */
-export declare function rgb(r: number, g: number, b: number): (text: string | number) => string;
-/**
- * Returns a custom background "bgRgb" color function.
- * Uses caching for better performance.
- * @param r Red component (0-255)
- * @param g Green component (0-255)
- * @param b Blue component (0-255)
- */
-export declare function bgRgb(r: number, g: number, b: number): (text: string | number) => string;
-/**
- * Creates a color function from a hex string or color name
- * @param color Hex string (e.g., "#ff0000") or color name (e.g., "red")
- */
-export declare function hex(color: string): (text: string | number) => string;
-/**
- * Creates a background color function from a hex string or color name
- * @param color Hex string (e.g., "#ff0000") or color name (e.g., "red")
- */
-export declare function bgHex(color: string): (text: string | number) => string;
-/**
- * Creates an HSL color from hue, saturation, and lightness values
- * @param h Hue (0-360)
- * @param s Saturation (0-100)
- * @param l Lightness (0-100)
- */
-export declare function hsl(h: number, s: number, l: number): (text: string | number) => string;
-/**
- * Creates a background HSL color
- * @param h Hue (0-360)
- * @param s Saturation (0-100)
- * @param l Lightness (0-100)
- */
-export declare function bgHsl(h: number, s: number, l: number): (text: string | number) => string;
-/**
- * Chain multiple color formatters together
- * @param formatters Array of color formatters to apply in sequence
- */
-export declare function chain(...formatters: ((text: string | number) => string)[]): (text: string | number) => string;
-/**
- * Creates a rainbow text effect
- * @param text The text to colorize
- * @param saturation Saturation (0-100)
- * @param lightness Lightness (0-100)
- * @param options Additional options
- * @returns The rainbow-colorized text
- */
-export declare function rainbow(text: string, saturation?: number, lightness?: number, options?: {
-    startHue?: number;
-    endHue?: number;
-}): string;
-/**
- * Creates a gradient text effect between multiple colors
- * @param text The text to colorize
- * @param colors Array of colors (hex, rgb, hsl, or named colors)
- * @param options Additional options (smoothing, distribution)
- * @returns The gradient-colorized text
- */
-export declare function multiGradient(text: string, colors: string[], options?: {
-    smoothing?: number;
-    distribution?: "even" | "weighted";
-}): string;
-/**
- * Creates a gradient text effect between two colors
- * @param text The text to colorize
- * @param startColor Starting color (hex, rgb, hsl, or named color)
- * @param endColor Ending color (hex, rgb, hsl, or named color)
- * @param options Additional options (smoothing)
- * @returns The gradient-colorized text
- */
-export declare function gradient(text: string, startColor: string, endColor: string, options?: {
-    smoothing?: number;
-}): string;
-/**
- * Blend two colors together with a given ratio
- * @param color1 First color
- * @param color2 Second color
- * @param ratio Blend ratio (0-1, 0 = color1, 1 = color2)
- * @returns A formatter function with the blended color
- */
-export declare function blend(color1: string, color2: string, ratio?: number): (text: string | number) => string;
-/**
- * Checks if a color meets WCAG contrast guidelines against another color
- * @param foreground Foreground color
- * @param background Background color (defaults to white)
- * @returns Object with contrast ratio and pass/fail for AA and AAA levels
- */
-export declare function checkContrast(foreground: string, background?: string): {
-    ratio: number;
-    passesAA: boolean;
-    passesAAA: boolean;
-    passesAALarge: boolean;
-    passesAAALarge: boolean;
+type ApplyInput = string | number;
+type FormatCallable = ((input: ApplyInput) => string) & {
+    readonly [OP_SYMBOL]: SgrOp[];
 };
-/**
- * Find an accessible color by adjusting lightness until it meets contrast requirements
- * @param color Base color to adjust
- * @param background Background color to check contrast against
- * @param targetRatio Minimum contrast ratio to achieve (4.5 = AA, 7 = AAA)
- * @returns A color with sufficient contrast
- */
-export declare function getAccessibleColor(color: string, background?: string, targetRatio?: number): string;
-export type ColorSupport = {
-    isColorSupported: boolean;
-    isForced: boolean;
-    isDisabled: boolean;
-    terminalName: string;
-    colorLevel: 0 | 1 | 2 | 3;
+type BaseColorName = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "gray" | "orange" | "pink" | "purple" | "teal" | "lime" | "brown" | "navy" | "maroon" | "olive" | "silver";
+type ColorName = BaseColorName | GrayScaleName | BrightColorName | PastelColorName | BgColorName;
+type GrayScaleName = "gray10" | "gray20" | "gray30" | "gray40" | "gray50" | "gray60" | "gray70" | "gray80" | "gray90";
+type BrightColorName = "blackBright" | "redBright" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright" | "whiteBright" | "orangeBright" | "pinkBright" | "purpleBright" | "tealBright" | "limeBright" | "brownBright" | "navyBright" | "maroonBright" | "oliveBright" | "silverBright";
+type PastelColorName = "blackPastel" | "redPastel" | "greenPastel" | "yellowPastel" | "bluePastel" | "magentaPastel" | "cyanPastel" | "whitePastel" | "grayPastel" | "orangePastel" | "pinkPastel" | "purplePastel" | "tealPastel" | "limePastel" | "brownPastel" | "navyPastel" | "maroonPastel" | "olivePastel" | "silverPastel";
+type BgColorName = `bg${Capitalize<BaseColorName>}` | `bg${Capitalize<GrayScaleName>}` | `bg${Capitalize<BrightColorName>}` | `bg${Capitalize<PastelColorName>}`;
+type MkRgbFn = (r: number, g: number, b: number) => Re;
+type MkHexFn = (hex: string) => Re;
+type MkHslFn = (h: number, s: number, l: number) => Re;
+type StyleKeys = "reset" | "bold" | "dim" | "italic" | "underline" | "inverse" | "hidden" | "strikethrough";
+type Re = FormatCallable & {
+    readonly [K in StyleKeys]: Re;
+} & {
+    readonly [K in ColorName]: Re;
+} & {
+    readonly [K in BgColorName]: Re;
+} & {
+    readonly rgb: MkRgbFn;
+    readonly hex: MkHexFn;
+    readonly hsl: MkHslFn;
+    readonly bgRgb: MkRgbFn;
+    readonly bgHex: MkHexFn;
+    readonly bgHsl: MkHslFn;
 };
-export declare const colorSupport: ColorSupport;
-/**
- * Creates a safe background color wrapping that prevents spillover to new lines
- * @param text The text to colorize
- * @param bgColorFn Background color formatter function
- * @param textColorFn Optional text color formatter function
- * @returns Safely wrapped colored text
- */
-export declare function colorWrap(text: string, bgColorFn: (text: string | number) => string, textColorFn?: (text: string | number) => string): string;
-/**
- * Smart background color function that prevents background color overflow
- * Apply background color to text while ensuring it doesn't spill over to new lines
- * @param color Background color (hex, named, etc.)
- * @param text Optional text to colorize immediately
- */
-export declare function safeBg(color: string, text?: string | number): ((text: string | number) => string) | string;
-/**
- * Apply background and foreground colors while preventing spillover
- * @param bgColor Background color
- * @param fgColor Foreground color
- * @param text Optional text to colorize immediately
- */
-export declare function safeColor(bgColor: string, fgColor: string, text?: string | number): ((text: string | number) => string) | string;
-/**
- * Creates a color function that automatically ensures good contrast
- * @param color Base color to use
- * @param background Background color to check contrast against
- * @param targetRatio Minimum contrast ratio to achieve (4.5 = AA, 7 = AAA)
- */
-export declare function autoContrast(color: string, background?: string, targetRatio?: number): (text: string | number) => string;
-/**
- * Creates a color scheme from a base color
- * @param baseColor The main color to generate a scheme from
- * @returns Object with various related colors
- */
-export declare function createColorScheme(baseColor: string): {
-    base: (text: string | number) => string;
-    light: (text: string | number) => string;
-    dark: (text: string | number) => string;
-    bright: (text: string | number) => string;
-    pastel: (text: string | number) => string;
-    bg: (text: string | number) => string;
-    bgLight: (text: string | number) => string;
-    accent: (text: string | number) => string;
-};
-/**
- * Creates a highlighted text with colored background and contrasting text
- * @param text Text to highlight
- * @param bgColor Background color
- * @param options Additional options
- */
-export declare function highlight(text: string, bgColor: string, options?: {
-    padding?: number;
-    border?: boolean;
-    borderColor?: string;
-}): string;
-/**
- * Creates an ANSI link (works in supported terminals)
- * @param text Link text to display
- * @param url The URL to link to
- * @param color Optional color for the link text
- */
-export declare function link(text: string, url: string, color?: string): string;
-/**
- * Colorize a JSON object with syntax highlighting
- * @param obj Object to stringify and colorize
- * @param options Options for JSON stringification
- */
-export declare function colorizeJson(obj: unknown, options?: {
-    indent?: number;
-    compact?: boolean;
-}): string;
-/**
- * Initialize user configuration with optional programmatic overrides
- * @param programmaticConfig Optional configuration to override settings
- * @param userSettingsPrecedence If true, user file settings take precedence over programmatic
- */
-export declare function initUserConfig(programmaticConfig?: Partial<RelicoConfig>, userSettingsPrecedence?: boolean): Promise<void>;
-/**
- * Provides type safety and IntelliSense for user configuration.
- * Example usage in `relico.config.ts`:
- * ```ts
- * import { defineConfig } from "@reliverse/relico-cfg";
- * export default defineConfig({
- *   colorLevel: 3,
- *   theme: "secondary",
- *   customColors: {
- *     red: ["#f00", "#c00"],
- *     blue: ["#0af", "#08f"],
- *     green: ["#00ff00", "#00cc00"],
- *   },
- * });
- * ```
- */
-export declare function defineConfig(cfg: RelicoConfig): RelicoConfig;
+declare const OP_SYMBOL: unique symbol;
+export declare const setColorLevel: (level: ColorLevel) => void;
+export declare const re: Re;
+export declare const rgb: MkRgbFn;
+export declare const hex: MkHexFn;
+export declare const hsl: MkHslFn;
+export declare const bgRgb: MkRgbFn;
+export declare const bgHex: MkHexFn;
+export declare const bgHsl: MkHslFn;
+export declare const chain: (...parts: FormatCallable[]) => Re;
+export declare const parseRgb: (value: string) => Rgb | null;
+export declare const parseHsl: (value: string) => {
+    h: number;
+    s: number;
+    l: number;
+} | null;
 export {};