@nemigo/helpers 0.13.1 → 0.13.3

package/dist/async/space.d.ts

@@ -1,5 +1,6 @@
+import { AsyncLocalStorage } from "async_hooks";
 export declare abstract class AsyncSpace<TX> {
-    private async_storage;
+    __async_storage: AsyncLocalStorage<TX[]>;
     getTX(): TX[];
     space<T>(call: (tx: TX[]) => Promise<T>, auto?: boolean): Promise<T>;
     commit(): Promise<void>;

package/dist/async/space.js

@@ -1,19 +1,19 @@
 import { AsyncLocalStorage } from "async_hooks";
 export class AsyncSpace {
-    async_storage = new AsyncLocalStorage();
+    __async_storage = new AsyncLocalStorage();
     getTX() {
-        const ctx = this.async_storage.getStore();
+        const ctx = this.__async_storage.getStore();
         if (ctx)
             return ctx;
         throw new Error("getTX() called outside of space()");
     }
     async space(call, auto = true) {
-        const ctx = this.async_storage.getStore();
+        const ctx = this.__async_storage.getStore();
         if (ctx)
             return call(ctx);
         // Создаем новое пространство
         const tx = [];
-        const result = await this.async_storage.run(tx, () => call(tx));
+        const result = await this.__async_storage.run(tx, () => call(tx));
         // Автоматически выполняем транзакции, если они есть и включен автокоммит
         if (auto && tx.length > 0) {
             await this.submit(tx);
@@ -22,7 +22,7 @@ export class AsyncSpace {
         return result;
     }
     async commit() {
-        const ctx = this.async_storage.getStore();
+        const ctx = this.__async_storage.getStore();
         if (!ctx)
             throw new Error("commit() called outside of space()");
         await this.submit(ctx);

package/dist/colors.d.ts

@@ -0,0 +1,539 @@
+/**
+ * RGB цвет (красный, зелёный, синий)
+ */
+export interface RGB {
+    /**
+     * Красный канал (0-255)
+     */
+    r: number;
+    /**
+     * Зелёный канал (0-255)
+     */
+    g: number;
+    /**
+     * Синий канал (0-255)
+     */
+    b: number;
+}
+/**
+ * RGBA цвет (красный, зелёный, синий, альфа)
+ */
+export interface RGBA extends RGB {
+    /**
+     * Прозрачность (0-1)
+     */
+    a: number;
+}
+/**
+ * HSL цвет (оттенок, насыщенность, яркость)
+ */
+export interface HSL {
+    /**
+     * Оттенок (0-360)
+     */
+    h: number;
+    /**
+     * Насыщенность (0-100)
+     */
+    s: number;
+    /**
+     * Яркость (0-100)
+     */
+    l: number;
+}
+/**
+ * HSLA цвет (оттенок, насыщенность, яркость, альфа)
+ */
+export interface HSLA extends HSL {
+    /**
+     * Прозрачность (0-1)
+     */
+    a: number;
+}
+/**
+ * HSV цвет (оттенок, насыщенность, значение)
+ */
+export interface HSV {
+    /**
+     * Оттенок (0-360)
+     */
+    h: number;
+    /**
+     * Насыщенность (0-100)
+     */
+    s: number;
+    /**
+     * Значение (0-100)
+     */
+    v: number;
+}
+/**
+ * HSVA цвет (оттенок, насыщенность, значение, альфа)
+ */
+export interface HSVA extends HSV {
+    /**
+     * Прозрачность (0-1)
+     */
+    a: number;
+}
+/**
+ * HEX цвет в формате "#RRGGBB"
+ */
+export type HEX = string;
+/**
+ * HEXA цвет в формате "#RRGGBBAA"
+ */
+export type HEXA = string;
+/**
+ * Ограничивает значение RGB-канала в диапазоне 0-255
+ */
+export declare const clampRgb: (value: number) => number;
+/**
+ * Ограничивает оттенок в диапазоне 0-360
+ */
+export declare const clampHue: (value: number) => number;
+/**
+ * Ограничивает процентное значение в диапазоне 0-100
+ */
+export declare const clampPercent: (value: number) => number;
+/**
+ * Ограничивает значение альфа-канала в диапазоне 0-1
+ */
+export declare const clampAlpha: (value: number) => number;
+/**
+ * Парсит HEX-строку в RGB или RGBA
+ *
+ * Поддерживаемые форматы:
+ * - #RGB
+ * - #RRGGBB
+ * - #RGBA
+ * - #RRGGBBAA
+ *
+ * @param hex - HEX-строка цвета
+ * @returns RGB или RGBA объект, или null если формат неверен
+ *
+ * @example
+ * ```typescript
+ * parseHex("#ff0000"); // { r: 255, g: 0, b: 0 }
+ * parseHex("#f00"); // { r: 255, g: 0, b: 0 }
+ * parseHex("#ff0000ff"); // { r: 255, g: 0, b: 0, a: 1 }
+ * parseHex("#f00f"); // { r: 255, g: 0, b: 0, a: 1 }
+ * parseHex("invalid"); // null
+ * ```
+ */
+export declare const parseHex: (hex: string) => RGB | RGBA | null;
+/**
+ * Парсит RGB/RGBA строку в объект
+ *
+ * Поддерживаемые форматы:
+ * - rgb(r, g, b)
+ * - rgba(r, g, b, a)
+ * - rgb(r g b)
+ * - rgba(r g b / a)
+ *
+ * @param rgb - RGB/RGBA строка
+ * @returns RGB или RGBA объект, или null если формат неверен
+ *
+ * @example
+ * ```typescript
+ * parseRgb("rgb(255, 0, 0)"); // { r: 255, g: 0, b: 0 }
+ * parseRgb("rgba(255, 0, 0, 0.5)"); // { r: 255, g: 0, b: 0, a: 0.5 }
+ * parseRgb("rgb(255 0 0)"); // { r: 255, g: 0, b: 0 }
+ * parseRgb("rgba(255 0 0 / 0.5)"); // { r: 255, g: 0, b: 0, a: 0.5 }
+ * ```
+ */
+export declare const parseRgb: (rgb: string) => RGB | RGBA | null;
+/**
+ * Парсит HSL/HSLA строку в объект
+ *
+ * Поддерживаемые форматы:
+ * - hsl(h, s%, l%)
+ * - hsla(h, s%, l%, a)
+ * - hsl(h s% l%)
+ * - hsla(h s% l% / a)
+ *
+ * @param hsl - HSL/HSLA строка
+ * @returns HSL или HSLA объект, или null если формат неверен
+ *
+ * @example
+ * ```typescript
+ * parseHsl("hsl(0, 100%, 50%)"); // { h: 0, s: 100, l: 50 }
+ * parseHsl("hsla(0, 100%, 50%, 0.5)"); // { h: 0, s: 100, l: 50, a: 0.5 }
+ * parseHsl("hsl(0 100% 50%)"); // { h: 0, s: 100, l: 50 }
+ * ```
+ */
+export declare const parseHsl: (hsl: string) => HSL | HSLA | null;
+/**
+ * Универсальный парсер цвета
+ *
+ * Пробует распознать формат и парсит соответствующим парсером
+ *
+ * @param color - Строка цвета в любом поддерживаемом формате
+ * @returns RGB или RGBA объект, или null если формат не распознан
+ *
+ * @example
+ * ```typescript
+ * parseColor("#ff0000"); // { r: 255, g: 0, b: 0 }
+ * parseColor("rgb(255, 0, 0)"); // { r: 255, g: 0, b: 0 }
+ * parseColor("hsl(0, 100%, 50%)"); // { r: 255, g: 0, b: 0 }
+ * ```
+ */
+export declare const parseColor: (color: string) => RGB | RGBA | null;
+/**
+ * Конвертирует RGB/RGBA в HEX/HEXA строку
+ *
+ * @param rgb - RGB или RGBA объект
+ * @returns HEX строка в формате #RRGGBB или #RRGGBBAA
+ *
+ * @example
+ * ```typescript
+ * rgbToHex({ r: 255, g: 0, b: 0 }); // "#ff0000"
+ * rgbToHex({ r: 255, g: 0, b: 0, a: 0.5 }); // "#ff000080"
+ * ```
+ */
+export declare const rgbToHex: (rgb: RGB | RGBA) => HEX | HEXA;
+/**
+ * Конвертирует HEX строку в RGB/RGBA объект
+ *
+ * @param hex - HEX строка
+ * @returns RGB или RGBA объект
+ * @throws {Error} Если формат HEX неверен
+ *
+ * @example
+ * ```typescript
+ * hexToRgb("#ff0000"); // { r: 255, g: 0, b: 0 }
+ * hexToRgb("#f00"); // { r: 255, g: 0, b: 0 }
+ * ```
+ */
+export declare const hexToRgb: (hex: string) => RGB | RGBA;
+/**
+ * Конвертирует RGB/RGBA в HSL/HSLA
+ *
+ * @param rgb - RGB или RGBA объект
+ * @returns HSL или HSLA объект
+ *
+ * @example
+ * ```typescript
+ * rgbToHsl({ r: 255, g: 0, b: 0 }); // { h: 0, s: 100, l: 50 }
+ * rgbToHsl({ r: 255, g: 255, b: 255 }); // { h: 0, s: 0, l: 100 }
+ * ```
+ */
+export declare const rgbToHsl: (rgb: RGB | RGBA) => HSL | HSLA;
+/**
+ * Конвертирует HSL/HSLA в RGB/RGBA
+ *
+ * @param hsl - HSL или HSLA объект
+ * @returns RGB или RGBA объект
+ *
+ * @example
+ * ```typescript
+ * hslToRgb({ h: 0, s: 100, l: 50 }); // { r: 255, g: 0, b: 0 }
+ * hslToRgb({ h: 0, s: 0, l: 100 }); // { r: 255, g: 255, b: 255 }
+ * ```
+ */
+export declare const hslToRgb: (hsl: HSL | HSLA) => RGB | RGBA;
+/**
+ * Конвертирует RGB/RGBA в HSV/HSVA
+ *
+ * @param rgb - RGB или RGBA объект
+ * @returns HSV или HSVA объект
+ *
+ * @example
+ * ```typescript
+ * rgbToHsv({ r: 255, g: 0, b: 0 }); // { h: 0, s: 100, v: 100 }
+ * rgbToHsv({ r: 0, g: 0, b: 0 }); // { h: 0, s: 0, v: 0 }
+ * ```
+ */
+export declare const rgbToHsv: (rgb: RGB | RGBA) => HSV | HSVA;
+/**
+ * Конвертирует HSV/HSVA в RGB/RGBA
+ *
+ * @param hsv - HSV или HSVA объект
+ * @returns RGB или RGBA объект
+ *
+ * @example
+ * ```typescript
+ * hsvToRgb({ h: 0, s: 100, v: 100 }); // { r: 255, g: 0, b: 0 }
+ * hsvToRgb({ h: 0, s: 0, v: 0 }); // { r: 0, g: 0, b: 0 }
+ * ```
+ */
+export declare const hsvToRgb: (hsv: HSV | HSVA) => RGB | RGBA;
+/**
+ * Форматирует RGB/RGBA в CSS-строку
+ *
+ * @param rgb - RGB или RGBA объект
+ * @returns CSS-строка в формате rgb(r, g, b) или rgba(r, g, b, a)
+ *
+ * @example
+ * ```typescript
+ * toRgbString({ r: 255, g: 0, b: 0 }); // "rgb(255, 0, 0)"
+ * toRgbString({ r: 255, g: 0, b: 0, a: 0.5 }); // "rgba(255, 0, 0, 0.5)"
+ * ```
+ */
+export declare const toRgbString: (rgb: RGB | RGBA) => string;
+/**
+ * Форматирует RGB/RGBA в HEX-строку
+ *
+ * @param rgb - RGB или RGBA объект
+ * @returns HEX-строка в формате #RRGGBB или #RRGGBBAA
+ *
+ * @example
+ * ```typescript
+ * toHexString({ r: 255, g: 0, b: 0 }); // "#ff0000"
+ * toHexString({ r: 255, g: 0, b: 0, a: 0.5 }); // "#ff000080"
+ * ```
+ */
+export declare const toHexString: (rgb: RGB | RGBA) => string;
+/**
+ * Форматирует HSL/HSLA в CSS-строку
+ *
+ * @param hsl - HSL или HSLA объект
+ * @returns CSS-строка в формате hsl(h, s%, l%) или hsla(h, s%, l%, a)
+ *
+ * @example
+ * ```typescript
+ * toHslString({ h: 0, s: 100, l: 50 }); // "hsl(0, 100%, 50%)"
+ * toHslString({ h: 0, s: 100, l: 50, a: 0.5 }); // "hsla(0, 100%, 50%, 0.5)"
+ * ```
+ */
+export declare const toHslString: (hsl: HSL | HSLA) => string;
+/**
+ * Вычисляет относительную яркость цвета по формуле WCAG
+ *
+ * @param rgb - RGB объект
+ * @returns Относительная яркость (0-1)
+ *
+ * @see https://www.w3.org/TR/WCAG20/#relativeluminancedef
+ *
+ * @example
+ * ```typescript
+ * getLuminance({ r: 255, g: 255, b: 255 }); // 1 (белый)
+ * getLuminance({ r: 0, g: 0, b: 0 }); // 0 (чёрный)
+ * getLuminance({ r: 255, g: 0, b: 0 }); // 0.2126 (красный)
+ * ```
+ */
+export declare const getLuminance: (rgb: RGB) => number;
+/**
+ * Вычисляет контрастность между двумя цветами по формуле WCAG
+ *
+ * @param rgb1 - Первый RGB объект
+ * @param rgb2 - Второй RGB объект
+ * @returns Коэффициент контрастности (1-21)
+ *
+ * @see https://www.w3.org/TR/WCAG20/#contrast-ratiodef
+ *
+ * @example
+ * ```typescript
+ * getContrast({ r: 255, g: 255, b: 255 }, { r: 0, g: 0, b: 0 }); // 21 (максимальный контраст)
+ * getContrast({ r: 255, g: 255, b: 255 }, { r: 255, g: 255, b: 255 }); // 1 (нет контраста)
+ * ```
+ */
+export declare const getContrast: (rgb1: RGB, rgb2: RGB) => number;
+/**
+ * Класс для работы с цветами
+ *
+ * Поддерживает конвертацию между форматами, манипуляции с цветом и вычисление характеристик
+ *
+ * @example
+ * ```typescript
+ * const color = new Color("#ff0000");
+ * color.rgb; // { r: 255, g: 0, b: 0 }
+ * color.hex; // "#ff0000"
+ * color.lighten(20).hex; // "#ff6666"
+ * color.luminance(); // 0.2126
+ * ```
+ */
+export declare class Color {
+    private _rgb;
+    /**
+     * Создаёт экземпляр Color
+     *
+     * @param color - Строка цвета или RGB/RGBA объект
+     * @throws {Error} Если формат цвета не распознан
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000");
+     * new Color("rgb(255, 0, 0)");
+     * new Color({ r: 255, g: 0, b: 0 });
+     * new Color({ r: 255, g: 0, b: 0, a: 0.5 });
+     * ```
+     */
+    constructor(color: string | RGB | RGBA);
+    /**
+     * Получает RGB представление цвета
+     */
+    get rgb(): RGB;
+    /**
+     * Получает RGBA представление цвета
+     */
+    get rgba(): RGBA;
+    /**
+     * Получает HSL представление цвета
+     */
+    get hsl(): HSL;
+    /**
+     * Получает HSLA представление цвета
+     */
+    get hsla(): HSLA;
+    /**
+     * Получает HSV представление цвета
+     */
+    get hsv(): HSV;
+    /**
+     * Получает HSVA представление цвета
+     */
+    get hsva(): HSVA;
+    /**
+     * Получает HEX представление цвета
+     */
+    get hex(): string;
+    /**
+     * Осветляет цвет
+     *
+     * @param amount - Процент осветления (0-100)
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").lighten(20).hex; // "#ff6666"
+     * ```
+     */
+    lighten(amount: number): Color;
+    /**
+     * Затемняет цвет
+     *
+     * @param amount - Процент затемнения (0-100)
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").darken(20).hex; // "#990000"
+     * ```
+     */
+    darken(amount: number): Color;
+    /**
+     * Увеличивает насыщенность цвета
+     *
+     * @param amount - Процент увеличения насыщенности (0-100)
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff6666").saturate(50).hex; // "#ff1a1a"
+     * ```
+     */
+    saturate(amount: number): Color;
+    /**
+     * Уменьшает насыщенность цвета
+     *
+     * @param amount - Процент уменьшения насыщенности (0-100)
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").desaturate(50).hex; // "#bf4040"
+     * ```
+     */
+    desaturate(amount: number): Color;
+    /**
+     * Устанавливает прозрачность цвета
+     *
+     * @param alpha - Значение альфа-канала (0-1)
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").opacity(0.5).hex; // "#ff000080"
+     * ```
+     */
+    opacity(alpha: number): Color;
+    /**
+     * Инвертирует цвет
+     *
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").invert().hex; // "#00ffff"
+     * ```
+     */
+    invert(): Color;
+    /**
+     * Смешивает цвет с другим цветом
+     *
+     * @param color - Цвет для смешивания
+     * @param weight - Вес первого цвета (0-1), по умолчанию 0.5
+     * @returns Новый экземпляр Color
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").mix(new Color("#0000ff")).hex; // "#800080"
+     * new Color("#ff0000").mix(new Color("#0000ff"), 0.75).hex; // "#bf0040"
+     * ```
+     */
+    mix(color: Color, weight?: number): Color;
+    /**
+     * Вычисляет относительную яркость цвета
+     *
+     * @returns Относительная яркость (0-1)
+     *
+     * @example
+     * ```typescript
+     * new Color("#ffffff").luminance(); // 1
+     * new Color("#000000").luminance(); // 0
+     * ```
+     */
+    luminance(): number;
+    /**
+     * Вычисляет контрастность с другим цветом
+     *
+     * @param color - Цвет для сравнения
+     * @returns Коэффициент контрастности (1-21)
+     *
+     * @example
+     * ```typescript
+     * new Color("#ffffff").contrast(new Color("#000000")); // 21
+     * new Color("#ffffff").contrast(new Color("#ffffff")); // 1
+     * ```
+     */
+    contrast(color: Color): number;
+    /**
+     * Проверяет, является ли цвет светлым
+     *
+     * @returns true, если яркость > 0.5
+     *
+     * @example
+     * ```typescript
+     * new Color("#ffffff").isLight(); // true
+     * new Color("#000000").isLight(); // false
+     * ```
+     */
+    isLight(): boolean;
+    /**
+     * Проверяет, является ли цвет тёмным
+     *
+     * @returns true, если яркость <= 0.5
+     *
+     * @example
+     * ```typescript
+     * new Color("#000000").isDark(); // true
+     * new Color("#ffffff").isDark(); // false
+     * ```
+     */
+    isDark(): boolean;
+    /**
+     * Преобразует цвет в строку
+     *
+     * @param format - Формат вывода (hex, rgb, hsl), по умолчанию hex
+     * @returns Строковое представление цвета
+     *
+     * @example
+     * ```typescript
+     * new Color("#ff0000").toString(); // "#ff0000"
+     * new Color("#ff0000").toString("rgb"); // "rgb(255, 0, 0)"
+     * new Color("#ff0000").toString("hsl"); // "hsl(0, 100%, 50%)"
+     * ```
+     */
+    toString(format?: "hex" | "rgb" | "hsl"): string;
+}