@nemigo/helpers 0.9.1 → 0.11.0

package/dist/async/index.js

@@ -1,7 +1,7 @@
 /**
  * Создаёт задержку на указанное количество миллисекунд
  */
-export const delay = (ms, success = false) => new Promise((resolve, reject) => setTimeout(success ? resolve : reject, ms));
+export const delay = (ms, success = true) => new Promise((resolve, reject) => setTimeout(success ? resolve : reject, ms));
 /**
  * Создаёт debounce-функцию, которая откладывает выполнение до тех пор, пока не пройдёт указанное время без новых вызовов
  *

package/dist/async/space.js

@@ -11,9 +11,10 @@ export class AsyncSpace {
         const ctx = this.async_storage.getStore();
         if (ctx)
             return call(ctx);
-        //...
+        // Создаем новое пространство
         const tx = [];
         const result = await this.async_storage.run(tx, () => call(tx));
+        // Автоматически выполняем транзакции, если они есть и включен автокоммит
         if (auto && tx.length > 0) {
             await this.submit(tx);
             tx.length = 0;

package/dist/clean.d.ts

@@ -1,13 +1,37 @@
 /**
- * Очищает рекурсивно C КОПИРОВАНИЕМ объект (в т.ч. и массивы) от пустых, неопределенных или нулевых значений.
- * Дополнительно удаляет пустые объекты и массивы, которые могут появиться после очистки.
- * Если аргумент не является объектом, он возвращается без изменений
+ * Глубоко очищает объект (включая массивы) от "пустых" значений с созданием копии.
+ * Удаляет значения: `null`, `undefined`, пустые строки `""`.
+ * После очистки удаляет объекты и массивы, ставшие пустыми.
+ * Не изменяет исходный объект.
+ *
+ * @template O - Тип исходного объекта
+ * @param data - Объект или значение для очистки
+ * @returns Очищенная копия объекта или исходное значение, если это не объект
  *
  * @example
- * const original = { a: 1, b: null, c: { d: '', e: { f: undefined } } };
- * const cleaned = deepObjectClean(original);
+ * ```typescript
+ * const original = {
+ *   a: 1,
+ *   b: null,
+ *   c: {
+ *     d: '',
+ *     e: { f: undefined },
+ *     g: [1, null, '', { h: undefined }]
+ *   }
+ * };
  *
+ * const cleaned = deepObjectClean(original);
  * console.log(cleaned); // { a: 1 }
- * console.log(original); // {{ a: 1, b: null, c: { d: '', e: { f: undefined } } }
+ * console.log(original); // Исходный объект не изменен
+ *
+ * // Работа с массивами
+ * const array = [1, null, '', { a: '', b: 2 }, undefined];
+ * const cleanedArray = deepObjectClean(array);
+ * console.log(cleanedArray); // [1, { b: 2 }]
+ *
+ * // Примитивы возвращаются без изменений
+ * deepObjectClean("hello"); // "hello"
+ * deepObjectClean(null); // null
+ * ```
  */
 export declare const deepObjectClean: <O>(data: O) => O;

package/dist/clean.js

@@ -1,14 +1,38 @@
 /**
- * Очищает рекурсивно C КОПИРОВАНИЕМ объект (в т.ч. и массивы) от пустых, неопределенных или нулевых значений.
- * Дополнительно удаляет пустые объекты и массивы, которые могут появиться после очистки.
- * Если аргумент не является объектом, он возвращается без изменений
+ * Глубоко очищает объект (включая массивы) от "пустых" значений с созданием копии.
+ * Удаляет значения: `null`, `undefined`, пустые строки `""`.
+ * После очистки удаляет объекты и массивы, ставшие пустыми.
+ * Не изменяет исходный объект.
+ *
+ * @template O - Тип исходного объекта
+ * @param data - Объект или значение для очистки
+ * @returns Очищенная копия объекта или исходное значение, если это не объект
  *
  * @example
- * const original = { a: 1, b: null, c: { d: '', e: { f: undefined } } };
- * const cleaned = deepObjectClean(original);
+ * ```typescript
+ * const original = {
+ *   a: 1,
+ *   b: null,
+ *   c: {
+ *     d: '',
+ *     e: { f: undefined },
+ *     g: [1, null, '', { h: undefined }]
+ *   }
+ * };
  *
+ * const cleaned = deepObjectClean(original);
  * console.log(cleaned); // { a: 1 }
- * console.log(original); // {{ a: 1, b: null, c: { d: '', e: { f: undefined } } }
+ * console.log(original); // Исходный объект не изменен
+ *
+ * // Работа с массивами
+ * const array = [1, null, '', { a: '', b: 2 }, undefined];
+ * const cleanedArray = deepObjectClean(array);
+ * console.log(cleanedArray); // [1, { b: 2 }]
+ *
+ * // Примитивы возвращаются без изменений
+ * deepObjectClean("hello"); // "hello"
+ * deepObjectClean(null); // null
+ * ```
  */
 export const deepObjectClean = (data) => {
     if (typeof data !== "object" || data === null)

package/dist/datetime.d.ts

@@ -1,55 +1,82 @@
 import type { Timestamp } from "./types.js";
-/**
- * Русифицированные названия месяцев в родительском падеже
- */
 export declare const months: string[];
-/**
- * Русифицированные сокращённые названия месяцев в родительском падеже
- */
 export declare const abbs: string[];
 /**
- * Шаблонизатор вывода даты и времени из {@link Timestamp}
+ * Универсальный шаблонизатор для форматирования даты и времени.
+ * Поддерживает различные форматы вывода с возможностью указания часового пояса для вывода
  *
- * TS - секунды
+ * **Поддерживаемые токены:**
+ * - `TS` - секунды (00-59)
+ * - `TM` - минуты (00-59)
+ * - `TH` - часы (00-23)
+ * - `DD` - день месяца (01-31)
+ * - `DM` - месяц числом (01-12)
+ * - `DFM` - месяц полным названием (января, февраля, ...)
+ * - `DAM` - месяц сокращённым названием (янв, фев, ...)
+ * - `DY` - год (4 цифры)
  *
- * TM - минуты
- *
- * DD - дни
- *
- * DM - месяц числом
- *
- * DFM - месяц полным названием
+ * @example
+ * ```typescript
+ * formatDateTime(new Date(), 'DD.DM.DY TH:TM:TS');
+ * // "09.10.2023 14:30:59"
  *
- * DAM - месяц сокращённым названием
+ * formatDateTime(Date.now(), 'DFM DY');
+ * // "октября 2023"
  *
- * DY - год
+ * formatDateTime('2023-12-25', 'DD DAM DY', 3);
+ * // "25 дек 2023" (с учетом МСК +3)
  *
- * @example
- * const formatted = dateTimeFormatter(new Date(), 'DD.DM.DY TH:TM:TS');
- * console.log(formatted); // "09.10.2023 14:30:59"
+ * formatDateTime(Date.now(), 'DY-DM-DD TH:TM');
+ * // "2023-10-09 14:30"
+ * ```
  */
 export declare const formatDateTime: (datetime?: Date | Timestamp | string, format?: string, timezone?: number) => string;
 /**
- * Готовый пресет для {@link formatDateTime}
+ * Готовый пресет для форматирования времени в московском часовом поясе (МСК +3).
+ * Использует {@link formatDateTime} с предустановленным форматом и часовым поясом.
  *
- * `DD.DM.DY TH:TM (МСК)` с МСК-флагом
+ * @param timestamp - Временная метка для форматирования (по умолчанию текущее время)
+ * @param format - Шаблон форматирования (по умолчанию "DD.DM.DY TH:TM (МСК)")
+ * @returns Отформатированная строка времени в МСК
  *
  * @example
- * const mskTime = formatMSK(Date.now());
- * console.log(mskTime); // "09.10.2023 14:30 (МСК)"
+ * ```typescript
+ * formatMSK(Date.now());
+ * // "09.10.2023 14:30 (МСК)"
+ *
+ * formatMSK(1696934400000);
+ * // "09.10.2023 14:30 (МСК)"
+ *
+ * formatMSK(Date.now(), 'DD DAM DY TH:TM');
+ * // "09 окт 2023 14:30"
+ * ```
  */
 export declare const formatMSK: (timestamp?: Timestamp, format?: string) => string;
 /**
- * Конвертирует строковые представления даты и времени в {@link Timestamp}
- *
- * @param date - Строка даты в формате "DD.MM.YYYY"
- * @param [time="00:00"] - Строка времени в формате "HH:MM"
- * @param [timezone] - Часовой пояс относительно GMT
+ * Конвертирует строковые представления даты и времени в числовую временную метку (Timestamp).
+ * Поддерживает локальное время и UTC с указанием часового пояса.
  *
- * @returns TimeStamp соответствующий указанной дате и времени или 0 при неверном формате
+ * @param date - Строка даты в формате "DD.MM.YYYY" (день.месяц.год)
+ * @param time - Строка времени в формате "HH:MM" (час:минута), по умолчанию "00:00"
+ * @param timezone - Часовой пояс в часах относительно GMT (опционально)
+ * @returns Timestamp в миллисекундах или 0 при неверном формате входных данных
  *
  * @example
- * const timestamp = toTimeStamp("11.02.2012", "13:45");
- * console.log(timestamp); // Выведет {@link Timestamp} для "11.02.2012 13:45"
+ * ```typescript
+ * toTimeStamp("11.02.2012", "13:45");
+ * // Возвращает Timestamp для 11 февраля 2012, 13:45
+ *
+ * toTimeStamp("25.12.2023");
+ * // Возвращает Timestamp для 25 декабря 2023, 00:00
+ *
+ * toTimeStamp("01.01.2024", "12:00", 3);
+ * // Возвращает Timestamp для 1 января 2024, 12:00 МСК (UTC+3)
+ *
+ * toTimeStamp("invalid", "date");
+ * // Возвращает 0 из-за неверного формата
+ *
+ * toTimeStamp("32.13.2023");
+ * // Возвращает 0 из-за неверной даты
+ * ```
  */
 export declare const toTimeStamp: (date: string, time?: string, timezone?: number) => Timestamp | 0;

package/dist/datetime.js

@@ -1,7 +1,4 @@
 import { pad } from "./index.js";
-/**
- * Русифицированные названия месяцев в родительском падеже
- */
 export const months = [
     "января",
     "февраля",
@@ -16,9 +13,6 @@ export const months = [
     "ноября",
     "декабря",
 ];
-/**
- * Русифицированные сокращённые названия месяцев в родительском падеже
- */
 export const abbs = [
     "янв",
     "фев",
@@ -34,25 +28,33 @@ export const abbs = [
     "дек",
 ];
 /**
- * Шаблонизатор вывода даты и времени из {@link Timestamp}
+ * Универсальный шаблонизатор для форматирования даты и времени.
+ * Поддерживает различные форматы вывода с возможностью указания часового пояса для вывода
  *
- * TS - секунды
+ * **Поддерживаемые токены:**
+ * - `TS` - секунды (00-59)
+ * - `TM` - минуты (00-59)
+ * - `TH` - часы (00-23)
+ * - `DD` - день месяца (01-31)
+ * - `DM` - месяц числом (01-12)
+ * - `DFM` - месяц полным названием (января, февраля, ...)
+ * - `DAM` - месяц сокращённым названием (янв, фев, ...)
+ * - `DY` - год (4 цифры)
  *
- * TM - минуты
- *
- * DD - дни
- *
- * DM - месяц числом
- *
- * DFM - месяц полным названием
+ * @example
+ * ```typescript
+ * formatDateTime(new Date(), 'DD.DM.DY TH:TM:TS');
+ * // "09.10.2023 14:30:59"
  *
- * DAM - месяц сокращённым названием
+ * formatDateTime(Date.now(), 'DFM DY');
+ * // "октября 2023"
  *
- * DY - год
+ * formatDateTime('2023-12-25', 'DD DAM DY', 3);
+ * // "25 дек 2023" (с учетом МСК +3)
  *
- * @example
- * const formatted = dateTimeFormatter(new Date(), 'DD.DM.DY TH:TM:TS');
- * console.log(formatted); // "09.10.2023 14:30:59"
+ * formatDateTime(Date.now(), 'DY-DM-DD TH:TM');
+ * // "2023-10-09 14:30"
+ * ```
  */
 export const formatDateTime = (datetime = Date.now(), format = "DD.DM.DY TH:TM", timezone) => {
     const base = new Date(datetime);
@@ -95,28 +97,53 @@ export const formatDateTime = (datetime = Date.now(), format = "DD.DM.DY TH:TM",
     return result.join("");
 };
 /**
- * Готовый пресет для {@link formatDateTime}
+ * Готовый пресет для форматирования времени в московском часовом поясе (МСК +3).
+ * Использует {@link formatDateTime} с предустановленным форматом и часовым поясом.
  *
- * `DD.DM.DY TH:TM (МСК)` с МСК-флагом
+ * @param timestamp - Временная метка для форматирования (по умолчанию текущее время)
+ * @param format - Шаблон форматирования (по умолчанию "DD.DM.DY TH:TM (МСК)")
+ * @returns Отформатированная строка времени в МСК
  *
  * @example
- * const mskTime = formatMSK(Date.now());
- * console.log(mskTime); // "09.10.2023 14:30 (МСК)"
+ * ```typescript
+ * formatMSK(Date.now());
+ * // "09.10.2023 14:30 (МСК)"
+ *
+ * formatMSK(1696934400000);
+ * // "09.10.2023 14:30 (МСК)"
+ *
+ * formatMSK(Date.now(), 'DD DAM DY TH:TM');
+ * // "09 окт 2023 14:30"
+ * ```
  */
 export const formatMSK = (timestamp = Date.now(), format = "DD.DM.DY TH:TM (МСК)") => formatDateTime(timestamp, format, 3);
 //...
 /**
- * Конвертирует строковые представления даты и времени в {@link Timestamp}
- *
- * @param date - Строка даты в формате "DD.MM.YYYY"
- * @param [time="00:00"] - Строка времени в формате "HH:MM"
- * @param [timezone] - Часовой пояс относительно GMT
+ * Конвертирует строковые представления даты и времени в числовую временную метку (Timestamp).
+ * Поддерживает локальное время и UTC с указанием часового пояса.
  *
- * @returns TimeStamp соответствующий указанной дате и времени или 0 при неверном формате
+ * @param date - Строка даты в формате "DD.MM.YYYY" (день.месяц.год)
+ * @param time - Строка времени в формате "HH:MM" (час:минута), по умолчанию "00:00"
+ * @param timezone - Часовой пояс в часах относительно GMT (опционально)
+ * @returns Timestamp в миллисекундах или 0 при неверном формате входных данных
  *
  * @example
- * const timestamp = toTimeStamp("11.02.2012", "13:45");
- * console.log(timestamp); // Выведет {@link Timestamp} для "11.02.2012 13:45"
+ * ```typescript
+ * toTimeStamp("11.02.2012", "13:45");
+ * // Возвращает Timestamp для 11 февраля 2012, 13:45
+ *
+ * toTimeStamp("25.12.2023");
+ * // Возвращает Timestamp для 25 декабря 2023, 00:00
+ *
+ * toTimeStamp("01.01.2024", "12:00", 3);
+ * // Возвращает Timestamp для 1 января 2024, 12:00 МСК (UTC+3)
+ *
+ * toTimeStamp("invalid", "date");
+ * // Возвращает 0 из-за неверного формата
+ *
+ * toTimeStamp("32.13.2023");
+ * // Возвращает 0 из-за неверной даты
+ * ```
  */
 export const toTimeStamp = (date, time = "00:00", timezone) => {
     const [day, month, year] = date.split(".").map(Number);

package/dist/files.d.ts

@@ -1,22 +1,8 @@
 export declare const fileToBase64: (file: File) => Promise<string>;
 /**
- * Проверяет, является ли файл изображением (исключая SVG)
- *
- * @para file - Объект файла
- * @returns true, если файл является изображением
+ * Проверяет, является ли файл изображением. SVG данную проверку не проходят.
  */
 export declare const isImage: (file: File) => boolean;
-/**
- * Проверяет, является ли файл видео
- */
 export declare const isVideo: (file: File) => boolean;
-/**
- * Проверяет, является ли файл аудио
- */
 export declare const isAudio: (file: File) => boolean;
-/**
- * Преобразует размер файла в человекочитаемый формат
- *
- * @param size - Размер файла в байтах
- */
 export declare const getFileSize: (size: number) => string;

package/dist/files.js

@@ -6,19 +6,10 @@ export const fileToBase64 = (file) => new Promise((resolve, reject) => {
 });
 //...
 /**
- * Проверяет, является ли файл изображением (исключая SVG)
- *
- * @para file - Объект файла
- * @returns true, если файл является изображением
+ * Проверяет, является ли файл изображением. SVG данную проверку не проходят.
  */
 export const isImage = (file) => file.type.startsWith("image/") && !file.type.includes("svg");
-/**
- * Проверяет, является ли файл видео
- */
 export const isVideo = (file) => file.type.startsWith("video/");
-/**
- * Проверяет, является ли файл аудио
- */
 export const isAudio = (file) => file.type.startsWith("audio/");
 //...
 const UNITS = [
@@ -32,11 +23,6 @@ const UNITS = [
     "ZB",
     "YB",
 ];
-/**
- * Преобразует размер файла в человекочитаемый формат
- *
- * @param size - Размер файла в байтах
- */
 export const getFileSize = (size) => {
     const bytes = Math.round(size);
     if (bytes === 0)

package/dist/html.d.ts

@@ -1,39 +1,69 @@
 import type { CanBeNullable, CanBePromise, KEYS } from "./types.js";
 /**
- * Проверка по глобальному `window`
+ * `true`, если глобальный объект `window` отсутствует.
  */
 export declare const isSSR: boolean;
 /**
- * Предотвращает дефолтное поведение события и останавливает всплытие
+ * Предотвращает стандартное поведение события и останавливает его всплытие.
  */
 export declare const preventStop: (e: Event) => void;
 /**
- * Создаёт обработчик события с {@link preventStop}, который выполняется всегда, если иное не задано через `usePreventStop`
- * Коллбэк выполняется аналогично, но уже относительно `condition`
+ * Создаёт обработчик события с вызовом {@link preventStop}, если условие `usePreventStop` истинно.
+ *
+ * 1. Если `usePreventStop` → true (или функция вернёт true), то событие будет остановлено.
+ * 2. Если `condition` → true (или функция вернёт true), то выполнится переданный коллбэк.
+ *
+ * @template T Тип события
+ * @param call Коллбэк для вызова после проверки условия
+ * @param usePreventStop Флаг или функция-условие для вызова {@link preventStop}
+ * @param condition Флаг или функция-условие для вызова `call`
+ * @returns Обработчик события
  */
 export declare const preventStopHook: <T extends Event = Event>(call?: CanBeNullable<(e: T) => CanBePromise>, { usePreventStop, condition, }?: {
     usePreventStop?: ((e: T) => unknown) | unknown;
     condition?: ((e: T) => unknown) | unknown;
 }) => ((e: T) => void);
 /**
- * TODO: актуализация JSDoc
+ * Возвращает обработчик клавиатурных событий.
  *
- * Возвращает обработчик клавиатурных событий, который:
+ * Логика:
+ * 1. Если `usePreventStop === "enter"` и нажата клавиша Enter → вызовется {@link preventStop}.
+ * 2. Если `usePreventStop` — функция/флаг, и она вернёт true → вызовется {@link preventStop}.
+ * 3. Если нажата Enter и `condition` → true, вызовется основной коллбэк.
  *
- * 1. Если `usePreventStop === true`, вызывает {@link preventStop}
- * 2. Если load вернёт `false` (при его наличии), то выполнение остановится
- * 3. Вызывает переданный **prepare-коллбэк** (при его наличии), если он вернёт `false`, то выполнение остановится
- * 4. Вызывает основной коллбэк только при нажатии `Enter`.
+ * @template T Тип события клавиатуры
+ * @param call Основной коллбэк, вызываемый при Enter
+ * @param usePreventStop Условие для вызова {@link preventStop}
+ * @param condition Условие для вызова основного коллбэка
  */
 export declare const enterKeyHook: <T extends KeyboardEvent = KeyboardEvent>(call?: CanBeNullable<(e: T) => CanBePromise>, { usePreventStop, condition, }?: {
     usePreventStop?: "enter" | unknown | ((e: T, isEnter: boolean) => unknown);
     condition?: ((e: T) => unknown) | unknown;
 }) => (e: T) => void;
+/**
+ * Тип события с уточнённым `currentTarget`.
+ */
 export type TargetEvent<E extends Event, N extends HTMLElement = HTMLDivElement> = E & {
     currentTarget: EventTarget & N;
 };
+/**
+ * Тип клавиатурного события с уточнённым `currentTarget`.
+ */
 export type TargetKeyboardEvent<N extends HTMLElement = HTMLDivElement> = TargetEvent<KeyboardEvent, N>;
+/**
+ * Проверяет, является ли событие клавиатурным.
+ */
 export declare const isKeyboardEvent: (e: any) => e is KeyboardEvent;
+/**
+ * Создаёт обработчик контекстного меню.
+ *
+ * Если событие вызвано клавиатурой:
+ *   — координаты берутся из `getBoundingClientRect` текущего элемента.
+ * Если мышью:
+ *   — координаты берутся из `clientX` / `clientY`.
+ *
+ * @param call Коллбэк, принимающий позицию и метаданные о событии
+ */
 export declare const ctxMenuHook: <N extends HTMLElement = HTMLDivElement>(call: (position: {
     left: number;
     top: number;
@@ -45,58 +75,64 @@ export declare const ctxMenuHook: <N extends HTMLElement = HTMLDivElement>(call:
     event: MouseEvent;
 }) => void) => (e: TargetKeyboardEvent<N> | MouseEvent) => void;
 /**
- * Создаёт обработчик событий для указанного элемента или окна
- *
- * @template T - Тип события из `WindowEventMap`
- * @template E - Тип объекта события (по умолчанию `WindowEventMap[T]`)
- *
- * @param {T} event - Ключ события
- * @param {(e: E) => CanBePromise} call - Функция-обработчик события
- * @param {AddEventListenerOptions} [options] - Дополнительные параметры
- * @param {HTMLElement | Window} [target=window] - Целевой элемент для привязки события
+ * Создаёт слушатель события на указанном элементе.
  *
- * @returns Функция для удаления обработчика события
+ * @template M Карта событий
+ * @template T Ключ события
+ * @template E Тип события
+ * @param event Название события
+ * @param call Обработчик события
+ * @param options Параметры слушателя
+ * @param target Целевой элемент (по умолчанию `window`)
+ * @returns Функция для удаления обработчика
  */
 export declare const createEventListener: <const M = WindowEventMap, const T extends KEYS<M> = KEYS<M>, const E = M[T]>(event: T, call: (e: E) => CanBePromise, options?: AddEventListenerOptions, target?: HTMLElement | Window | Document) => (() => void);
 /**
- * Убирает все выделения текста на странице
+ * Убирает фокус на активном элементе страницы
+ */
+export declare const unfocus: () => void;
+/**
+ * Снимает текущее выделение текста на странице.
  */
 export declare const unselect: () => void;
 /**
- * Создаёт once-обработчик события "mousedown" с {@link unselect}
+ * Добавляет одноразовый обработчик `mousedown`, который снимает выделение текста.
  *
- * @returns Функция для удаления обработчика события
+ * @returns Функция для удаления обработчика
  */
 export declare const unselectByMousedown: () => (() => void);
 declare global {
     interface WindowEventMap {
+        /** Кастомное событие для прокрутки страницы к началу */
         rescroll: CustomEvent;
     }
 }
 /**
- * Создаёт обработчик события "rescroll" для прокрутки элемента наверх с плавной анимацией
+ * Создаёт обработчик кастомного события `rescroll`, который плавно прокручивает элемент наверх.
  *
- * @param {HTMLElement} [element=document.documentElement] - Элемент, для которого привязывается обработчик
- * @param {EventListenerOptions} [options] - Дополнительные параметры
- *
- * @returns Функция для удаления обработчика события
+ * @param element Целевой элемент (по умолчанию `document.documentElement`)
+ * @param options Доп. параметры слушателя
+ * @returns Функция для удаления обработчика
  */
 export declare const createRescrollListener: (element?: HTMLElement, options?: EventListenerOptions) => (() => void);
 /**
- * Генерирует и пробрасывает событие "rescroll" на указанный элемент или окно
+ * Диспатчит событие `rescroll` на указанный элемент или окно.
  *
- * @param {HTMLElement | Window} [element=window] - Элемент или окно, на которое будет отправлено событие
- * @returns {boolean} Возвращает результат метода dispatchEvent
+ * @param element Элемент или окно (по умолчанию `window`)
+ * @returns Было ли событие успешно отправлено
  */
 export declare const rescrollDispatch: (element?: HTMLElement | Window) => boolean;
 /**
- * Автоматически изменяет высоту текстового поля (`textarea`) в зависимости от его содержимого
+ * Автоматически изменяет высоту `textarea` в зависимости от содержимого.
+ *
+ * @param area Текстовое поле
  */
 export declare const autoAreaHeight: (area?: HTMLTextAreaElement) => void;
 /**
- * Преобразование `{@link FormData}` в объект
+ * Преобразует {@link FormData} в объект.
  *
- * @param form - данные формы
- * @param multi - поддержка массивов значений
+ * @param form Данные формы
+ * @param multi Если true, то поддерживаются массивы значений для одинаковых ключей
+ * @returns Объект с данными формы
  */
 export declare const formon: <D = any>(form: FormData, multi?: boolean) => D;

package/dist/html.js

@@ -1,15 +1,24 @@
 import { useConditionGuard } from "./index.js";
 /**
- * Проверка по глобальному `window`
+ * `true`, если глобальный объект `window` отсутствует.
  */
 export const isSSR = typeof window === "undefined";
+//...
 /**
- * Предотвращает дефолтное поведение события и останавливает всплытие
+ * Предотвращает стандартное поведение события и останавливает его всплытие.
  */
 export const preventStop = (e) => (e.preventDefault(), e.stopPropagation());
 /**
- * Создаёт обработчик события с {@link preventStop}, который выполняется всегда, если иное не задано через `usePreventStop`
- * Коллбэк выполняется аналогично, но уже относительно `condition`
+ * Создаёт обработчик события с вызовом {@link preventStop}, если условие `usePreventStop` истинно.
+ *
+ * 1. Если `usePreventStop` → true (или функция вернёт true), то событие будет остановлено.
+ * 2. Если `condition` → true (или функция вернёт true), то выполнится переданный коллбэк.
+ *
+ * @template T Тип события
+ * @param call Коллбэк для вызова после проверки условия
+ * @param usePreventStop Флаг или функция-условие для вызова {@link preventStop}
+ * @param condition Флаг или функция-условие для вызова `call`
+ * @returns Обработчик события
  */
 export const preventStopHook = (call, { usePreventStop = true, condition = true, } = {}) => (e) => {
     if (useConditionGuard(usePreventStop, e))
@@ -19,14 +28,17 @@ export const preventStopHook = (call, { usePreventStop = true, condition = true,
 };
 //...
 /**
- * TODO: актуализация JSDoc
+ * Возвращает обработчик клавиатурных событий.
  *
- * Возвращает обработчик клавиатурных событий, который:
+ * Логика:
+ * 1. Если `usePreventStop === "enter"` и нажата клавиша Enter → вызовется {@link preventStop}.
+ * 2. Если `usePreventStop` — функция/флаг, и она вернёт true → вызовется {@link preventStop}.
+ * 3. Если нажата Enter и `condition` → true, вызовется основной коллбэк.
  *
- * 1. Если `usePreventStop === true`, вызывает {@link preventStop}
- * 2. Если load вернёт `false` (при его наличии), то выполнение остановится
- * 3. Вызывает переданный **prepare-коллбэк** (при его наличии), если он вернёт `false`, то выполнение остановится
- * 4. Вызывает основной коллбэк только при нажатии `Enter`.
+ * @template T Тип события клавиатуры
+ * @param call Основной коллбэк, вызываемый при Enter
+ * @param usePreventStop Условие для вызова {@link preventStop}
+ * @param condition Условие для вызова основного коллбэка
  */
 export const enterKeyHook = (call, { usePreventStop = "enter", condition = true, } = {}) => (e) => {
     const isEnter = e.key === "Enter";
@@ -41,7 +53,21 @@ export const enterKeyHook = (call, { usePreventStop = "enter", condition = true,
     if (isEnter && useConditionGuard(condition))
         call?.(e);
 };
+/**
+ * Проверяет, является ли событие клавиатурным.
+ */
 export const isKeyboardEvent = (e) => !!e.code;
+//...
+/**
+ * Создаёт обработчик контекстного меню.
+ *
+ * Если событие вызвано клавиатурой:
+ *   — координаты берутся из `getBoundingClientRect` текущего элемента.
+ * Если мышью:
+ *   — координаты берутся из `clientX` / `clientY`.
+ *
+ * @param call Коллбэк, принимающий позицию и метаданные о событии
+ */
 export const ctxMenuHook = (call) => preventStopHook((event) => {
     if (isKeyboardEvent(event)) {
         const { x, y } = event.currentTarget.getBoundingClientRect();
@@ -53,17 +79,16 @@ export const ctxMenuHook = (call) => preventStopHook((event) => {
 });
 //...
 /**
- * Создаёт обработчик событий для указанного элемента или окна
- *
- * @template T - Тип события из `WindowEventMap`
- * @template E - Тип объекта события (по умолчанию `WindowEventMap[T]`)
- *
- * @param {T} event - Ключ события
- * @param {(e: E) => CanBePromise} call - Функция-обработчик события
- * @param {AddEventListenerOptions} [options] - Дополнительные параметры
- * @param {HTMLElement | Window} [target=window] - Целевой элемент для привязки события
+ * Создаёт слушатель события на указанном элементе.
  *
- * @returns Функция для удаления обработчика события
+ * @template M Карта событий
+ * @template T Ключ события
+ * @template E Тип события
+ * @param event Название события
+ * @param call Обработчик события
+ * @param options Параметры слушателя
+ * @param target Целевой элемент (по умолчанию `window`)
+ * @returns Функция для удаления обработчика
  */
 export const createEventListener = (event, call, options = {}, target = window) => {
     target.addEventListener(event, call, options);
@@ -71,38 +96,45 @@ export const createEventListener = (event, call, options = {}, target = window)
 };
 //...
 /**
- * Убирает все выделения текста на странице
+ * Убирает фокус на активном элементе страницы
+ */
+export const unfocus = () => 
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+document.activeElement?.blur?.();
+/**
+ * Снимает текущее выделение текста на странице.
  */
 export const unselect = () => document.getSelection()?.removeAllRanges();
 /**
- * Создаёт once-обработчик события "mousedown" с {@link unselect}
+ * Добавляет одноразовый обработчик `mousedown`, который снимает выделение текста.
  *
- * @returns Функция для удаления обработчика события
+ * @returns Функция для удаления обработчика
  */
 export const unselectByMousedown = () => createEventListener("mousedown", unselect, { once: true });
 /**
- * Создаёт обработчик события "rescroll" для прокрутки элемента наверх с плавной анимацией
- *
- * @param {HTMLElement} [element=document.documentElement] - Элемент, для которого привязывается обработчик
- * @param {EventListenerOptions} [options] - Дополнительные параметры
+ * Создаёт обработчик кастомного события `rescroll`, который плавно прокручивает элемент наверх.
  *
- * @returns Функция для удаления обработчика события
+ * @param element Целевой элемент (по умолчанию `document.documentElement`)
+ * @param options Доп. параметры слушателя
+ * @returns Функция для удаления обработчика
  */
 export const createRescrollListener = (element = document.documentElement, options) => createEventListener("rescroll", 
 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
 () => element?.scrollTo?.({ top: 0, behavior: "smooth" }), options);
 /**
- * Генерирует и пробрасывает событие "rescroll" на указанный элемент или окно
+ * Диспатчит событие `rescroll` на указанный элемент или окно.
  *
- * @param {HTMLElement | Window} [element=window] - Элемент или окно, на которое будет отправлено событие
- * @returns {boolean} Возвращает результат метода dispatchEvent
+ * @param element Элемент или окно (по умолчанию `window`)
+ * @returns Было ли событие успешно отправлено
  */
 export const rescrollDispatch = (element = window) => 
 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
 element?.dispatchEvent?.(new CustomEvent("rescroll"));
 //...
 /**
- * Автоматически изменяет высоту текстового поля (`textarea`) в зависимости от его содержимого
+ * Автоматически изменяет высоту `textarea` в зависимости от содержимого.
+ *
+ * @param area Текстовое поле
  */
 export const autoAreaHeight = (area) => {
     if (!area)
@@ -111,12 +143,12 @@ export const autoAreaHeight = (area) => {
     area.style.height = `${area.scrollHeight}px`;
     area.scrollTop = area.scrollHeight;
 };
-//...
 /**
- * Преобразование `{@link FormData}` в объект
+ * Преобразует {@link FormData} в объект.
  *
- * @param form - данные формы
- * @param multi - поддержка массивов значений
+ * @param form Данные формы
+ * @param multi Если true, то поддерживаются массивы значений для одинаковых ключей
+ * @returns Объект с данными формы
  */
 export const formon = (form, multi = false) => {
     if (multi) {

package/dist/path.d.ts

@@ -0,0 +1,3 @@
+export declare const pathRegExp: RegExp;
+export declare const toUnixPath: (path: string) => string;
+export declare const isChildPath: (parentPath: string, childPath: string) => boolean;

package/dist/path.js

@@ -0,0 +1,7 @@
+export const pathRegExp = /[\\/]/g;
+export const toUnixPath = (path) => path.replace(pathRegExp, "/");
+export const isChildPath = (parentPath, childPath) => {
+    const uChildPath = toUnixPath(childPath);
+    const nParentPath = toUnixPath(parentPath) + "/";
+    return uChildPath.startsWith(nParentPath);
+};

package/dist/random.d.ts

@@ -1,12 +1,45 @@
 /**
- * Генератор случайных кодов
+ * Генерирует случайный числовой код указанной длины.
+ * Код состоит только из цифр и не может начинаться с нуля.
+ *
+ * @param length - Длина генерируемого кода (по умолчанию 6)
+ * @returns Строка с числовым кодом
+ *
+ * @example
+ * ```typescript
+ * rand(4); // "1234" (пример)
+ * rand(6); // "123456" (пример)
+ * rand(8); // "12345678" (пример)
+ * ```
  */
 export declare const rand: (length?: number) => string;
 /**
- * Генератор случайных ID ( {@link Date.now}:{@link rand} )
+ * Генерирует уникальный ID, состоящий из текущей временной метки и случайного кода.
+ * Формат: `timestamp:randomCode`
+ *
+ * @param length - Длина случайной части кода (по умолчанию 7)
+ * @returns Уникальный ID в формате строки
+ *
+ * @example
+ * ```typescript
+ * randID(4); // "1696934400000:1234" (пример)
+ * randID(6); // "1696934400000:123456" (пример)
+ * ```
  */
 export declare const randID: (length?: number) => string;
 /**
- * Генератор случайных UID
+ * Генерирует случайный UID (уникальный идентификатор) из буквенно-цифровых символов.
+ * Может включать префикс таблицы для организации идентификаторов.
+ *
+ * @param table - Префикс таблицы для организации UID (опционально)
+ * @param length - Длина UID в символах (по умолчанию 20)
+ * @returns Случайный UID в формате строки
+ *
+ * @example
+ * ```typescript
+ * randUID(); // "a1b2c3d4e5f6g7h8i9j0" (пример)
+ * randUID("user", 10); // "user:a1b2c3d4e5" (пример)
+ * randUID("session", 16); // "session:a1b2c3d4e5f6g7h8" (пример)
+ * ```
  */
 export declare const randUID: (table?: string, length?: number) => string;

package/dist/random.js

@@ -1,16 +1,49 @@
 /**
- * Генератор случайных кодов
+ * Генерирует случайный числовой код указанной длины.
+ * Код состоит только из цифр и не может начинаться с нуля.
+ *
+ * @param length - Длина генерируемого кода (по умолчанию 6)
+ * @returns Строка с числовым кодом
+ *
+ * @example
+ * ```typescript
+ * rand(4); // "1234" (пример)
+ * rand(6); // "123456" (пример)
+ * rand(8); // "12345678" (пример)
+ * ```
  */
 export const rand = (length = 6) => {
     const min = Math.pow(10, length - 1);
     return Math.floor(min + Math.random() * 9 * min).toString();
 };
 /**
- * Генератор случайных ID ( {@link Date.now}:{@link rand} )
+ * Генерирует уникальный ID, состоящий из текущей временной метки и случайного кода.
+ * Формат: `timestamp:randomCode`
+ *
+ * @param length - Длина случайной части кода (по умолчанию 7)
+ * @returns Уникальный ID в формате строки
+ *
+ * @example
+ * ```typescript
+ * randID(4); // "1696934400000:1234" (пример)
+ * randID(6); // "1696934400000:123456" (пример)
+ * ```
  */
 export const randID = (length = 7) => `${Date.now()}:${rand(length)}`;
 /**
- * Генератор случайных UID
+ * Генерирует случайный UID (уникальный идентификатор) из буквенно-цифровых символов.
+ * Может включать префикс таблицы для организации идентификаторов.
+ *
+ * @param table - Префикс таблицы для организации UID (опционально)
+ * @param length - Длина UID в символах (по умолчанию 20)
+ * @returns Случайный UID в формате строки
+ *
+ * @example
+ * ```typescript
+ * randUID(); // "a1b2c3d4e5f6g7h8i9j0" (пример)
+ * randUID("user", 10); // "user:a1b2c3d4e5" (пример)
+ * randUID("session", 16); // "session:a1b2c3d4e5f6g7h8" (пример)
+ * ```
  */
 export const randUID = (table, length = 20) => {
     const UID = "abcdefghijklmnopqrstuvwxyz0123456789"; // 36 символов

package/dist/string.d.ts

@@ -1,48 +1,149 @@
 /**
- * Регулярное выражение для захвата всех нецифровых символов из строки
+ * Регулярное выражение для захвата всех нецифровых символов из строки.
+ * Используется для удаления всех символов, кроме цифр 0-9.
  */
 export declare const oDigitRegExp: RegExp;
 /**
- * Чистка строки от всего, кроме цифр
+ * Удаляет все символы из строки, кроме цифр 0-9.
+ *
+ * @param v - Входная строка для очистки
+ * @returns Строка, содержащая только цифры
+ *
+ * @example
+ * ```typescript
+ * oDigitClean("abc123def456"); // "123456"
+ * oDigitClean("+7 (999) 123-45-67"); // "79991234567"
+ * oDigitClean(""); // ""
+ * ```
  */
 export declare const oDigitClean: (v?: string) => string;
 /**
- * Регулярное выражение для захвата пробелов
+ * Регулярное выражение для захвата одного или более пробельных символов подряд.
+ * Включает пробелы, табуляции, переносы строк и другие пробельные символы.
  */
 export declare const spaceRegExp: RegExp;
 /**
- * Заменяет все двойные, тройные и т. д. пробелы на один
+ * Нормализует пробелы в строке: заменяет множественные пробелы на один и удаляет пробелы в начале и конце.
+ *
+ * @param v - Входная строка для нормализации
+ * @returns Строка с нормализованными пробелами
+ *
+ * @example
+ * ```typescript
+ * spaceClean("  hello    world  "); // "hello world"
+ * spaceClean("multiple\n\n\nspaces"); // "multiple spaces"
+ * spaceClean("tab\t\tseparated"); // "tab separated"
+ * ```
  */
 export declare const spaceClean: (v?: string) => string;
 /**
- * Очистка от плейсхолдеров
+ * Удаляет все вхождения плейсхолдера из строки.
+ *
+ * @param str - Входная строка
+ * @param placeholder - Строка или регулярное выражение для удаления (по умолчанию "_")
+ * @returns Строка без плейсхолдеров
+ *
+ * @example
+ * ```typescript
+ * clearPH("hello_world_test", "_"); // "helloworldtest"
+ * clearPH("user___name", "_"); // "username"
+ * clearPH("test***end", "*"); // "testend"
+ * clearPH("email@domain.com", /@/); // "emaildomain.com"
+ * ```
  */
 export declare const clearPH: (str?: string, placeholder?: string | RegExp) => string;
 /**
- * Приводит первый символ слова к верхнему регистру
+ * Приводит первый символ строки к верхнему регистру, остальные оставляет без изменений.
+ *
+ * @param word - Строка для капитализации
+ * @returns Строка с заглавной первой буквой
+ *
+ * @example
+ * ```typescript
+ * toCapital("hello"); // "Hello"
+ * toCapital("world"); // "World"
+ * toCapital(""); // ""
+ * toCapital("a"); // "A"
+ * ```
  */
 export declare const toCapital: (word?: string) => string;
 /**
- * Приводит первый символ каждого слова к верхнему регистру
+ * Приводит первый символ каждого слова к верхнему регистру (Title Case).
+ * Разделяет строку по пробелам и применяет капитализацию к каждому слову.
+ *
+ * @param str - Строка для преобразования в Title Case
+ * @returns Строка с заглавными первыми буквами каждого слова
+ *
+ * @example
+ * ```typescript
+ * toCapitalMap("hello world"); // "Hello World"
+ * toCapitalMap("javascript programming"); // "Javascript Programming"
+ * toCapitalMap(""); // ""
+ * toCapitalMap("single"); // "Single"
+ * ```
  */
 export declare const toCapitalMap: (str?: string) => string;
 /**
- * Повторяет строку указанное количество раз с разделителем
+ * Повторяет строку указанное количество раз с разделителем между повторениями.
  *
- * @param {string} str - Исходная строка
- * @param {number} length - Количество повторений
- * @param {string} [separator=""] - Разделитель между повторениями (по умолчанию пустая строка)
+ * @param str - Исходная строка для повторения
+ * @param length - Количество повторений (должно быть неотрицательным)
+ * @param separator - Разделитель между повторениями (по умолчанию пустая строка)
+ * @returns Результирующая строка из повторений
+ *
+ * @example
+ * ```typescript
+ * repeat("abc", 3); // "abcabcabc"
+ * repeat("hello", 2, " "); // "hello hello"
+ * repeat("x", 5, "-"); // "x-x-x-x-x"
+ * repeat("test", 0); // ""
+ * repeat("", 3, ","); // ",,"
+ * ```
  */
 export declare const repeat: (str: string, length: number, separator?: string) => string;
 /**
- * Приводит всё к нижнему регистру и корректирует пробелы
+ * Приводит строку к нижнему регистру и нормализует пробелы.
+ * Комбинация методов toLowerCase() и spaceClean().
+ *
+ * @param str - Строка для нормализации
+ * @returns Строка в нижнем регистре с нормализованными пробелами
+ *
+ * @example
+ * ```typescript
+ * toFlat("  Hello    World  "); // "hello world"
+ * toFlat("CamelCase String"); // "camelcase string"
+ * toFlat(""); // ""
+ * ```
  */
 export declare const toFlat: (str?: string) => string;
 /**
- * Готовая {@link Map} для перевода кириллицы нижнего регистра в латиницу
+ * Карта для транслитерации кириллических символов в латинские.
+ * Содержит соответствия для всех букв русского алфавита в нижнем регистре.
+ * Используется в функции {@link toSlug} для создания URL-friendly строк.
+ *
+ * @example
+ * ```typescript
+ * cyrillicToLatinMap.get('а'); // "a"
+ * cyrillicToLatinMap.get('ё'); // "yo"
+ * cyrillicToLatinMap.get('ъ'); // ""
+ * ```
  */
 export declare const cyrillicToLatinMap: Map<string, string>;
 /**
- * Функция для создания *slug* (фрагмента URL) сущности
+ * Создает URL-friendly slug из текста.
+ * Конвертирует кириллицу в латиницу, удаляет специальные символы,
+ * нормализует пробелы и заменяет их на разделитель.
+ *
+ * @param text - Исходный текст для преобразования в slug
+ * @param separator - Разделитель для замены пробелов (по умолчанию "-")
+ * @returns URL-friendly строка
+ *
+ * @example
+ * ```typescript
+ * toSlug("Привет, мир!"); // "privet-mir"
+ * toSlug("JavaScript Programming"); // "javascript-programming"
+ * toSlug("Café & Restaurant", "_"); // "cafe_restaurant"
+ * toSlug("Специальные символы!!!", "."); // "specialnye-simvoly"
+ * ```
  */
 export declare const toSlug: (text: string, separator?: string) => string;

package/dist/string.js

@@ -1,49 +1,137 @@
 /**
- * Регулярное выражение для захвата всех нецифровых символов из строки
+ * Регулярное выражение для захвата всех нецифровых символов из строки.
+ * Используется для удаления всех символов, кроме цифр 0-9.
  */
 export const oDigitRegExp = /\D/g;
 /**
- * Чистка строки от всего, кроме цифр
+ * Удаляет все символы из строки, кроме цифр 0-9.
+ *
+ * @param v - Входная строка для очистки
+ * @returns Строка, содержащая только цифры
+ *
+ * @example
+ * ```typescript
+ * oDigitClean("abc123def456"); // "123456"
+ * oDigitClean("+7 (999) 123-45-67"); // "79991234567"
+ * oDigitClean(""); // ""
+ * ```
  */
 export const oDigitClean = (v = "") => v.replace(oDigitRegExp, "");
 //...
 /**
- * Регулярное выражение для захвата пробелов
+ * Регулярное выражение для захвата одного или более пробельных символов подряд.
+ * Включает пробелы, табуляции, переносы строк и другие пробельные символы.
  */
 export const spaceRegExp = /\s+/g;
 /**
- * Заменяет все двойные, тройные и т. д. пробелы на один
+ * Нормализует пробелы в строке: заменяет множественные пробелы на один и удаляет пробелы в начале и конце.
+ *
+ * @param v - Входная строка для нормализации
+ * @returns Строка с нормализованными пробелами
+ *
+ * @example
+ * ```typescript
+ * spaceClean("  hello    world  "); // "hello world"
+ * spaceClean("multiple\n\n\nspaces"); // "multiple spaces"
+ * spaceClean("tab\t\tseparated"); // "tab separated"
+ * ```
  */
 export const spaceClean = (v = "") => v.replace(spaceRegExp, " ").trim();
 /**
- * Очистка от плейсхолдеров
+ * Удаляет все вхождения плейсхолдера из строки.
+ *
+ * @param str - Входная строка
+ * @param placeholder - Строка или регулярное выражение для удаления (по умолчанию "_")
+ * @returns Строка без плейсхолдеров
+ *
+ * @example
+ * ```typescript
+ * clearPH("hello_world_test", "_"); // "helloworldtest"
+ * clearPH("user___name", "_"); // "username"
+ * clearPH("test***end", "*"); // "testend"
+ * clearPH("email@domain.com", /@/); // "emaildomain.com"
+ * ```
  */
 export const clearPH = (str = "", placeholder = "_") => str.replaceAll(placeholder, "");
 //...
 /**
- * Приводит первый символ слова к верхнему регистру
+ * Приводит первый символ строки к верхнему регистру, остальные оставляет без изменений.
+ *
+ * @param word - Строка для капитализации
+ * @returns Строка с заглавной первой буквой
+ *
+ * @example
+ * ```typescript
+ * toCapital("hello"); // "Hello"
+ * toCapital("world"); // "World"
+ * toCapital(""); // ""
+ * toCapital("a"); // "A"
+ * ```
  */
 export const toCapital = (word = "") => word.charAt(0).toUpperCase() + word.slice(1);
 /**
- * Приводит первый символ каждого слова к верхнему регистру
+ * Приводит первый символ каждого слова к верхнему регистру (Title Case).
+ * Разделяет строку по пробелам и применяет капитализацию к каждому слову.
+ *
+ * @param str - Строка для преобразования в Title Case
+ * @returns Строка с заглавными первыми буквами каждого слова
+ *
+ * @example
+ * ```typescript
+ * toCapitalMap("hello world"); // "Hello World"
+ * toCapitalMap("javascript programming"); // "Javascript Programming"
+ * toCapitalMap(""); // ""
+ * toCapitalMap("single"); // "Single"
+ * ```
  */
 export const toCapitalMap = (str = "") => str.split(" ").map(toCapital).join(" ");
 //...
 /**
- * Повторяет строку указанное количество раз с разделителем
+ * Повторяет строку указанное количество раз с разделителем между повторениями.
+ *
+ * @param str - Исходная строка для повторения
+ * @param length - Количество повторений (должно быть неотрицательным)
+ * @param separator - Разделитель между повторениями (по умолчанию пустая строка)
+ * @returns Результирующая строка из повторений
  *
- * @param {string} str - Исходная строка
- * @param {number} length - Количество повторений
- * @param {string} [separator=""] - Разделитель между повторениями (по умолчанию пустая строка)
+ * @example
+ * ```typescript
+ * repeat("abc", 3); // "abcabcabc"
+ * repeat("hello", 2, " "); // "hello hello"
+ * repeat("x", 5, "-"); // "x-x-x-x-x"
+ * repeat("test", 0); // ""
+ * repeat("", 3, ","); // ",,"
+ * ```
  */
 export const repeat = (str, length, separator = "") => Array.from({ length }).fill(str).join(separator);
 //...
 /**
- * Приводит всё к нижнему регистру и корректирует пробелы
+ * Приводит строку к нижнему регистру и нормализует пробелы.
+ * Комбинация методов toLowerCase() и spaceClean().
+ *
+ * @param str - Строка для нормализации
+ * @returns Строка в нижнем регистре с нормализованными пробелами
+ *
+ * @example
+ * ```typescript
+ * toFlat("  Hello    World  "); // "hello world"
+ * toFlat("CamelCase String"); // "camelcase string"
+ * toFlat(""); // ""
+ * ```
  */
 export const toFlat = (str = "") => spaceClean(str.toLowerCase());
+//...
 /**
- * Готовая {@link Map} для перевода кириллицы нижнего регистра в латиницу
+ * Карта для транслитерации кириллических символов в латинские.
+ * Содержит соответствия для всех букв русского алфавита в нижнем регистре.
+ * Используется в функции {@link toSlug} для создания URL-friendly строк.
+ *
+ * @example
+ * ```typescript
+ * cyrillicToLatinMap.get('а'); // "a"
+ * cyrillicToLatinMap.get('ё'); // "yo"
+ * cyrillicToLatinMap.get('ъ'); // ""
+ * ```
  */
 export const cyrillicToLatinMap = new Map([
     ["а", "a"],
@@ -81,7 +169,21 @@ export const cyrillicToLatinMap = new Map([
     ["я", "ya"],
 ]);
 /**
- * Функция для создания *slug* (фрагмента URL) сущности
+ * Создает URL-friendly slug из текста.
+ * Конвертирует кириллицу в латиницу, удаляет специальные символы,
+ * нормализует пробелы и заменяет их на разделитель.
+ *
+ * @param text - Исходный текст для преобразования в slug
+ * @param separator - Разделитель для замены пробелов (по умолчанию "-")
+ * @returns URL-friendly строка
+ *
+ * @example
+ * ```typescript
+ * toSlug("Привет, мир!"); // "privet-mir"
+ * toSlug("JavaScript Programming"); // "javascript-programming"
+ * toSlug("Café & Restaurant", "_"); // "cafe_restaurant"
+ * toSlug("Специальные символы!!!", "."); // "specialnye-simvoly"
+ * ```
  */
 export const toSlug = (text, separator = "-") => {
     const buf = [];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nemigo/helpers",
-	"version": "0.9.1",
+	"version": "0.11.0",
 	"private": false,
 	"author": {
 		"name": "Vlad Logvin",
@@ -91,6 +91,10 @@
 			"types": "./dist/omitter.d.ts",
 			"default": "./dist/omitter.js"
 		},
+		"./path": {
+			"types": "./dist/path.d.ts",
+			"default": "./dist/path.js"
+		},
 		"./phymath": {
 			"types": "./dist/phymath/index.d.ts",
 			"default": "./dist/phymath/index.js"
@@ -137,18 +141,20 @@
 		}
 	},
 	"peerDependencies": {
+		"@std/msgpack": "jsr:^1.0.0",
 		"zod": ">=4.0.0"
 	},
 	"peerDependenciesMeta": {
+		"@std/msgpack": {
+			"optional": true
+		},
 		"zod": {
 			"optional": true
 		}
 	},
-	"dependencies": {
-		"@std/msgpack": "jsr:^1.0.0"
-	},
 	"devDependencies": {
 		"@nemigo/configs": "workspace:*",
+		"@std/msgpack": "jsr:1.0.3",
 		"zod": "4.1.5"
 	}
 }