@reforgium/internal 1.1.0 → 1.1.1

package/fesm2022/reforgium-internal.mjs

@@ -76,12 +76,12 @@ const VALIDATION_MESSAGES = new InjectionToken('RE_VALIDATION_MESSAGES', {
 });
 
 /**
- * Загружает файл из объекта Blob и предлагает пользователю сохранить его.
+ * Downloads a file from a Blob object and prompts the user to save it.
  *
- * @param {Blob} blob - Объект Blob, представляющий файл для загрузки.
- * @param {string} [fileName] - Опционально. Имя для загружаемого файла.
- * Если не указано, в качестве имени файла будет использоваться текущая метка времени.
- * @return {void} Не возвращает значение.
+ * @param {Blob} blob - Blob object representing the file to download.
+ * @param {string} [fileName] - Optional. Name for the downloaded file.
+ * If not specified, the current timestamp will be used as the filename.
+ * @return {void} Does not return a value.
  */
 function downloadByBlob(blob, fileName) {
     const win = window;
@@ -95,12 +95,12 @@ function downloadByBlob(blob, fileName) {
     }
 }
 /**
- * Инициирует загрузку файла по-указанному URL. Опционально можно указать пользовательское имя файла.
+ * Initiates a file download for the given URL. Optionally, a custom filename can be specified.
  *
- * @param {string} url - URL файла для загрузки.
- * @param {string} [filename] - Желаемое имя для загружаемого файла.
- * Если не указано, будет использовано имя на основе временной метки.
- * @return {void} Функция не возвращает значение.
+ * @param {string} url - URL of the file to download.
+ * @param {string} [filename] - Desired name for the downloaded file.
+ * If not specified, a timestamp-based name will be used.
+ * @return {void} The function does not return a value.
  */
 function downloadByUrl(url, filename) {
     const win = window;
@@ -114,12 +114,12 @@ function downloadByUrl(url, filename) {
     win.document.body.removeChild(a);
 }
 /**
- * Копирует указанный текст в буфер обмена. Использует Clipboard API, если доступен,
- * в противном случае использует `document.execCommand` в качестве запасного метода.
+ * Copies the specified text to the clipboard. Uses the Clipboard API if available,
+ * otherwise falls back to `document.execCommand`.
  *
- * @param {string} text - Текст, который необходимо скопировать в буфер обмена.
- * @return {Promise<boolean>} Промис, который резолвится в boolean, указывающий, было ли
- * копирование текста успешным.
+ * @param {string} text - The text to copy to the clipboard.
+ * @return {Promise<boolean>} A promise that resolves to a boolean indicating whether
+ * the text copying was successful.
  */
 async function copyText(text) {
     const win = window;
@@ -145,13 +145,13 @@ async function copyText(text) {
     return ok;
 }
 /**
- * Преобразует строку в формате Base64 в объект Blob.
+ * Converts a Base64 encoded string to a Blob object.
  *
- * @param {string} base64 - Строка в формате Base64. Может опционально включать MIME-тип
- * в формате `data:<mimeType>;base64,<data>`.
- * @param {string} [mimeType=''] - MIME-тип данных. Необязательный параметр, будет переопределен,
- * если `base64` включает MIME-тип.
- * @return {Blob} Объект Blob, созданный из строки в формате Base64.
+ * @param {string} base64 - Base64 encoded string. Can optionally include a MIME type
+ * in the format `data:<mimeType>;base64,<data>`.
+ * @param {string} [mimeType=''] - MIME type of the data. Optional parameter, will be overridden
+ * if the `base64` string includes a MIME type.
+ * @return {Blob} A Blob object created from the Base64 string.
  */
 function base64ToBlob(base64, mimeType = '') {
     const matches = base64.match(/^data:(.+);base64,(.*)$/);
@@ -166,6 +166,27 @@ function base64ToBlob(base64, mimeType = '') {
     return new Blob([byteArray], { type: mime });
 }
 
+/**
+ * Creates a debounced signal that delays updates from the source signal.
+ * The output signal will only update after the specified delay has passed without new values.
+ *
+ * @template T - The type of the signal value
+ * @param {Signal<T>} src - The source signal to debounce
+ * @param {number} [ms=150] - The debounce delay in milliseconds (default: 150ms)
+ * @param {Object} [opts] - Optional configuration
+ * @param {Injector} [opts.injector] - Optional injector for the effect context
+ * @returns {Signal<T>} A readonly signal that emits debounced values from the source
+ *
+ * @example
+ * ```typescript
+ * const searchQuery = signal('');
+ * const debouncedQuery = debounceSignal(searchQuery, 300);
+ *
+ * effect(() => {
+ *   console.log('Debounced value:', debouncedQuery());
+ * });
+ * ```
+ */
 const debounceSignal = (src, ms = 150, opts) => {
     const out = signal(src(), ...(ngDevMode ? [{ debugName: "out" }] : []));
     let timeoutRef;
@@ -182,6 +203,29 @@ const debounceSignal = (src, ms = 150, opts) => {
     }, { injector: opts?.injector });
     return out.asReadonly();
 };
+/**
+ * Creates a throttled signal that limits the rate of updates from the source signal.
+ * The output signal will emit the first value immediately, then wait for the specified delay
+ * before allowing subsequent updates. If values are emitted during the waiting period,
+ * the last value will be queued and emitted after the delay.
+ *
+ * @template T - The type of the signal value
+ * @param {Signal<T>} src - The source signal to throttle
+ * @param {number} [ms=100] - The throttle delay in milliseconds (default: 100ms)
+ * @param {Object} [opts] - Optional configuration
+ * @param {Injector} [opts.injector] - Optional injector for the effect context
+ * @returns {Signal<T>} A readonly signal that emits throttled values from the source
+ *
+ * @example
+ * ```typescript
+ * const scrollPosition = signal(0);
+ * const throttledPosition = throttleSignal(scrollPosition, 200);
+ *
+ * effect(() => {
+ *   console.log('Throttled position:', throttledPosition());
+ * });
+ * ```
+ */
 const throttleSignal = (src, ms = 100, opts) => {
     const out = signal(src(), ...(ngDevMode ? [{ debugName: "out" }] : []));
     let last = 0;
@@ -227,19 +271,19 @@ const throttleSignal = (src, ms = 100, opts) => {
 
 const pad = (n) => n.toString().padStart(2, '0');
 /**
- * Форматирует объект даты в строку заданного формата.
+ * Formats a Date object into a string of the given format.
  *
- * @param {Date} date - Объект даты для форматирования.
- * @param {string} [format='yyyy-MM-dd'] - Строковый формат для применения. По умолчанию 'yyyy-MM-dd'.
- * Поддерживаемые токены в строке формата:
- * - yyyy: Полный год (например, 2023)
- * - MM: Месяц с ведущим нулем (01-12)
- * - dd: День месяца с ведущим нулем (01-31)
- * - HH: Час в 24-часовом формате с ведущим нулем (00-23)
- * - mm: Минуты с ведущим нулем (00-59)
- * - ss: Секунды с ведущим нулем (00-59)
+ * @param {Date} date - Date object to format.
+ * @param {string} [format='yyyy-MM-dd'] - String format to apply. Defaults to 'yyyy-MM-dd'.
+ * Supported tokens in the format string:
+ * - yyyy: Full year (e.g., 2023)
+ * - MM: Month with leading zero (01-12)
+ * - dd: Day of the month with leading zero (01-31)
+ * - HH: Hour in 24-hour format with leading zero (00-23)
+ * - mm: Minutes with leading zero (00-59)
+ * - ss: Seconds with leading zero (00-59)
  *
- * @returns {string} Отформатированная строка даты. Возвращает пустую строку, если входная дата некорректна.
+ * @returns {string} Formatted date string. Returns an empty string if the input date is invalid.
  */
 const formatDate = (date, format = 'yyyy-MM-dd') => {
     if (isNaN(date['getTime']?.())) {
@@ -260,11 +304,11 @@ const formatDate = (date, format = 'yyyy-MM-dd') => {
     return formatted;
 };
 /**
- * Форматирует заданную дату в локализованную строковую репрезентацию в формате 'день месяц год'.
- * Месяц локализован для 'ru-RU' локали и сокращен.
+ * Formats the given date into a localized string representation in the format 'day month year'.
+ * The month is localized for 'ru-RU' locale and abbreviated.
  *
- * @param {Date} date - Объект даты для форматирования.
- * @return {string} Строка, представляющая отформатированную дату в формате 'день месяц год'.
+ * @param {Date} date - Date object to format.
+ * @return {string} A string representing the formatted date in the format 'day month year'.
  */
 function formatToLocaledDate(date) {
     const day = date.getDate();
@@ -273,12 +317,12 @@ function formatToLocaledDate(date) {
     return `${day} ${month} ${year}`;
 }
 /**
- * Парсит дату из строки по заданной маске.
- * Поддерживает dd, MM, yyyy, HH, mm, ss.
- * Разделители любые: '.', '/', '-',' '.
+ * Parses a date from a string based on the given mask.
+ * Supports dd, MM, yyyy, HH, mm, ss.
+ * Any delimiters: '.', '/', '-', ' '.
  *
- * @param {string} value - исходная строка с датой
- * @param {string} format - маска, например "dd.MM.yyyy"
+ * @param {string} value - source date string
+ * @param {string} format - mask, e.g., "dd.MM.yyyy"
  * @returns {Date|null}
  */
 const parseToDate = (value, format = 'dd.MM.yyyy') => {
@@ -307,19 +351,19 @@ const parseToDate = (value, format = 'dd.MM.yyyy') => {
     return date;
 };
 /**
- * Парсит строковое представление двух дат в кортеж объектов `Date` или значений `null`.
+ * Parses a string representation of two dates into a tuple of `Date` objects or `null` values.
  *
- * Эта функция пытается извлечь и разобрать два значения даты из входной строки
- * на основе предоставленного формата даты. Если парсинг неуспешен, возвращаемый кортеж будет
- * состоять из значений `null`. По умолчанию ожидаемый формат даты - `dd.MM.yyyy`, но он
- * может быть изменен.
+ * This function attempts to extract and parse two date values from the input string
+ * based on the provided date format. If parsing is unsuccessful, the returned tuple will
+ * consist of `null` values. The default expected date format is `dd.MM.yyyy`, but it
+ * can be changed.
  *
- * @param {string | null} value - Строка, содержащая представления дат для разбора.
- * Если `null`, функция вернет `[null, null]`.
- * @param {string} [format='dd.MM.yyyy'] - Формат даты, используемый для парсинга.
- * Поддерживает `yyyy`, `MM`, `dd`, `HH`, `mm` и `ss`.
- * @returns {[Date | null, Date | null]} Кортеж, где первый элемент - разобранная начальная дата
- * и второй элемент - разобранная конечная дата. Если парсинг не удался, оба элемента будут `null`.
+ * @param {string | null} value - String containing date representations to parse.
+ * If `null`, the function will return `[null, null]`.
+ * @param {string} [format='dd.MM.yyyy'] - Date format used for parsing.
+ * Supports `yyyy`, `MM`, `dd`, `HH`, `mm`, and `ss`.
+ * @returns {[Date | null, Date | null]} A tuple where the first element is the parsed start date
+ * and the second element is the parsed end date. If parsing fails, both elements will be `null`.
  */
 const parseToDatePeriod = (value, format = 'dd.MM.yyyy') => {
     if (typeof value !== 'string' || !format) {
@@ -344,21 +388,21 @@ const parseToDatePeriod = (value, format = 'dd.MM.yyyy') => {
     }
 };
 /**
- * Определяет, является ли переданное значение периодом дат.
+ * Determines if the given value is a date period.
  *
- * Период дат представляется в виде массива, содержащего ровно два экземпляра Date.
- * Оба элемента массива должны быть корректными объектами Date (т.е. не `Invalid Date`).
+ * A date period is represented as an array containing exactly two Date instances.
+ * Both elements of the array must be valid Date objects (i.e., not `Invalid Date`).
  *
- * @param {unknown} value - Значение для проверки.
- * @returns {value is [Date, Date]} - Возвращает `true`, если значение является корректным периодом дат, иначе `false`.
+ * @param {unknown} value - Value to check.
+ * @returns {value is [Date, Date]} - Returns `true` if the value is a valid date period, otherwise `false`.
  */
 const isDatePeriod = (value) => Array.isArray(value) && value.length === 2 && value.every((it) => it instanceof Date && !isNaN(it.getTime()));
 /**
- * Преобразует различные типы данных в объект Date.
+ * Converts various data types to a Date object.
  *
- * @param {unknown} v - Значение для преобразования. Может быть объектом Date,
- * числом (timestamp) или строкой, содержащей корректную дату.
- * @returns {Date} Объект Date. Если преобразование невозможно, возвращает Invalid Date.
+ * @param {unknown} v - Value to convert. Can be a Date object,
+ * a number (timestamp), or a string containing a valid date.
+ * @returns {Date} Date object. If conversion is impossible, returns Invalid Date.
  */
 const toDate = (v) => {
     if (v instanceof Date)
@@ -370,8 +414,8 @@ const toDate = (v) => {
     return new Date(NaN);
 };
 /**
- * Переводит строку даты из заданного формата в ISO (UTC).
- * Пример:
+ * Converts a date string from a given format to ISO (UTC).
+ * Example:
  *   reformatDateToISO("24.11.2025", "dd.MM.yyyy")
  *   → "2025-11-24T00:00:00.000Z"
  */
@@ -421,27 +465,27 @@ function reformatDateToISO(dateStr, mask) {
 }
 
 /**
- * Определяет, является ли переданное значение null или undefined, опционально учитывая
- * пустые строки как null-подобные значения.
+ * Determines if the given value is null or undefined, optionally considering
+ * empty strings as null-like values.
  *
- * @param {unknown} value - Значение для проверки на null или undefined.
- * @param {boolean} [withEmptyString=false] - Если true, пустые строки также считаются
- *     null-подобными значениями в дополнение к null и undefined.
- * @returns {value is null | undefined} Возвращает `true`, если значение равно null, undefined,
- *     или (если `withEmptyString` равно true) пустой строке. В противном случае возвращает `false`.
+ * @param {unknown} value - Value to check for null or undefined.
+ * @param {boolean} [withEmptyString=false] - If true, empty strings are also considered
+ *     null-like values in addition to null and undefined.
+ * @returns {value is null | undefined} Returns `true` if the value is null, undefined,
+ *     or (if `withEmptyString` is true) an empty string. Otherwise returns `false`.
  */
 const isNullable = (value, withEmptyString = false) => value === null || value === undefined || (withEmptyString ? value === '' : false);
 /**
- * Проверяет, является ли переданное значение числом или может быть преобразовано в корректное число.
+ * Checks if the given value is a number or can be converted to a valid number.
  *
- * Эта функция проверяет, является ли входное значение числовым. Если входное значение
- * имеет тип number, проверяется, что оно является конечным числом и не NaN. Если входное
- * значение является строкой, проверяется возможность преобразования этой строки в корректное число.
+ * This function checks if the input value is numeric. If the input value
+ * is of type number, it is verified to be a finite number and not NaN. If the input
+ * value is a string, it checks if this string can be converted to a valid number.
  *
- * @param {unknown} value - Значение для проверки.
- * @param {boolean} [fromString=false] - Если true, строковые значения будут пытаться преобразоваться в число.
- * @returns {value is number} `true` если значение является числом или строкой,
- * которую можно преобразовать в число; иначе `false`.
+ * @param {unknown} value - Value to check.
+ * @param {boolean} [fromString=false] - If true, string values will attempt to be converted to a number.
+ * @returns {value is number} `true` if the value is a number or a string
+ * that can be converted to a number; otherwise `false`.
  */
 const isNumber = (value, fromString = false) => {
     if (typeof value === 'number') {
@@ -531,12 +575,12 @@ const concatArray = (value, mode, key) => {
 };
 
 /**
- * Форматирует число или строку, содержащую число, добавляя пробелы в качестве разделителей тысяч.
+ * Formats a number or a string containing a number by adding spaces as thousands separators.
  *
- * @param {number|string} num - Число или строка для форматирования.
- * Если входное значение null, undefined или недопустимое число, возвращается пустая строка.
- * @return {string} Отформатированная строка с пробелами в качестве разделителей тысяч или пустая строка,
- * если входные данные недопустимы.
+ * @param {number|string} num - The number or string to format.
+ * If the input value is null, undefined, or an invalid number, an empty string is returned.
+ * @return {string} Formatted string with spaces as thousands separators, or an empty string
+ * if the input is invalid.
  */
 function formatToSpacedNumber(num) {
     const stringed = String(num).replaceAll(' ', '');
@@ -547,13 +591,13 @@ function formatToSpacedNumber(num) {
     return str.replace(/\B(?=(\d{3})+(?!\d))/g, ' ');
 }
 /**
- * Обрезает строку до указанного количества символов и добавляет многоточие ('…'),
- * если строка превышает лимит.
+ * Truncates a string to the specified number of characters and adds an ellipsis ('…')
+ * if the string exceeds the limit.
  *
- * @param {string} text - Текст для обрезки.
- * @param {number} limit - Максимально допустимая длина строки.
- * @returns {string} Обрезанная строка с многоточием, если длина превышает лимит,
- * или исходная строка, если нет.
+ * @param {string} text - The text to truncate.
+ * @param {number} limit - Maximum allowed string length.
+ * @returns {string} Truncated string with an ellipsis if length exceeds the limit,
+ * or the original string otherwise.
  */
 const truncate = (text, limit) => {
     return text.length > limit ? text.slice(0, limit) + '…' : text;
@@ -614,12 +658,12 @@ const getDirMap = (directions) => {
 };
 
 /**
- * Вычисляет доступное вертикальное пространство под заданным элементом в области просмотра.
+ * Calculates the available vertical space below the given element in the viewport.
  *
- * @param {Element} el - DOM элемент, для которого необходимо вычислить доступную высоту снизу.
- * @param {number} [margin=20] - Опциональное поле, вычитаемое из вычисленной доступной высоты.
- * @return {number} Доступная высота в пикселях под элементом с учетом поля.
- * Возвращает 0, если нет доступного пространства.
+ * @param {Element} el - DOM element for which to calculate the available height below.
+ * @param {number} [margin=20] - Optional margin subtracted from the calculated available height.
+ * @return {number} Available height in pixels below the element, taking margin into account.
+ * Returns 0 if there is no available space.
  */
 function getAvailableHeight(el, margin = 20) {
     const rect = el.getBoundingClientRect();
@@ -630,12 +674,12 @@ function getAvailableHeight(el, margin = 20) {
 }
 
 /**
- * Извлекает значение по вложенному пути внутри объекта или массива.
- * Путь указывается в виде строки с разделителями-точками.
+ * Retrieves a value by a nested path within an object or array.
+ * The path is specified as a dot-delimited string.
  *
- * @param obj Объект или массив для обхода.
- * @param path Строка с разделителями-точками, указывающая путь для извлечения значения.
- * @return Значение, найденное по указанному пути, или undefined, если путь не существует или недействителен.
+ * @param obj The object or array to traverse.
+ * @param path A dot-delimited string specifying the path to retrieve the value.
+ * @return The value found at the specified path, or undefined if the path does not exist or is invalid.
  */
 function getChainedValue(obj, path) {
     if (!obj) {
@@ -657,11 +701,11 @@ function getChainedValue(obj, path) {
 }
 
 /**
- * Нормализует заданный URL, удаляя избыточные слеши, разрешая сегменты с точками
- * и обеспечивая отсутствие завершающих слешей в конце URL.
+ * Normalizes a given URL by removing redundant slashes, resolving dot segments,
+ * and ensuring there are no trailing slashes at the end of the URL.
  *
- * @param {string} url - Строка URL для нормализации.
- * @return {string} - Нормализованная строка URL.
+ * @param {string} url - The URL string to normalize.
+ * @return {string} - The normalized URL string.
  */
 function normalizeUrl(url) {
     const [protocol, rest] = url.split('://');
@@ -672,14 +716,14 @@ function normalizeUrl(url) {
     return rest ? `${protocol}://${cleaned}` : cleaned;
 }
 /**
- * Заменяет заполнители в предоставленном URL-шаблоне соответствующими значениями из объекта params.
- * Заполнители определяются как `:key` в строке шаблона.
+ * Replaces placeholders in the provided URL template with corresponding values from the params object.
+ * Placeholders are defined as `:key` in the template string.
  *
- * @param {string} template URL-шаблон, содержащий заполнители для замены.
- * @param {AnyDict} [params] Опциональный словарь, содержащий пары ключ-значение.
- * Ключи соответствуют заполнителям в шаблоне, а значения заменят их.
- * @return {string} URL с заполнителями, замененными соответствующими значениями из объекта params.
- * По умолчанию возвращает исходный шаблон, если params не предоставлен.
+ * @param {string} template URL template containing placeholders to replace.
+ * @param {AnyDict} [params] Optional dictionary containing key-value pairs.
+ * Keys correspond to placeholders in the template, and values will replace them.
+ * @return {string} URL with placeholders replaced by corresponding values from the params object.
+ * Defaults to the original template if params is not provided.
  */
 function fillUrlWithParams(template, params) {
     if (!params) {
@@ -688,12 +732,12 @@ function fillUrlWithParams(template, params) {
     return template.replace(/:([a-zA-Z0-9_]+)/g, (_, k) => encodeURIComponent(params[k] ?? ''));
 }
 /**
- * Добавляет параметры запроса к указанному URL.
+ * Appends query parameters to the specified URL.
  *
- * @param {string} url Базовый URL, к которому будут добавлены параметры запроса.
- * @param {Record<string, unknown>} [params] Опциональный объект, содержащий пары ключ-значение параметров запроса.
- * Ключи со значениями null или undefined будут проигнорированы.
- * @return {string} URL с добавленными параметрами запроса.
+ * @param {string} url Base URL to which query parameters will be added.
+ * @param {Record<string, unknown>} [params] Optional object containing query parameter key-value pairs.
+ * Keys with null or undefined values will be ignored.
+ * @return {string} URL with appended query parameters.
  */
 function appendQueryParams(url, params) {
     if (!params || !Object.keys(params).length)
@@ -708,11 +752,11 @@ function appendQueryParams(url, params) {
     return `${base}?${searchParams.toString()}`;
 }
 /**
- * Разбирает строку запроса в объект, содержащий пары ключ-значение.
+ * Parses a query string into an object containing key-value pairs.
  *
- * @param {string} query - Строка запроса для разбора. Может начинаться с '?'.
- * @return {Record<string, string>} Объект, где каждый ключ - это имя параметра запроса,
- * а значение - соответствующее значение.
+ * @param {string} query - The query string to parse. May start with '?'.
+ * @return {Record<string, string>} An object where each key is a query parameter name,
+ * and the value is the corresponding value.
  */
 function parseQueryParams(query) {
     const search = query.startsWith('?') ? query.slice(1) : query;
@@ -727,13 +771,13 @@ function parseQueryParams(query) {
 /**
  * Constructs a query string from a given object and concatenation type.
  *
- * @param {Record<string, any>} object - Объект с парами ключ-значение для преобразования в строку запроса.
- * Ключи представляют имена параметров, а значения - значения параметров.
- * @param {'comma' | 'json' | 'multi'} concatType - Метод обработки значений массива:
- *   - 'comma': Объединяет элементы массива через запятую.
- *   - 'json': Сериализует массив как JSON строку.
- *   - 'multi': Создает несколько записей для элементов массива, где каждый связан с одним и тем же ключом.
- * @returns {string} - Сформированная строка запроса с закодированными как URI компоненты ключами и значениями.
+ * @param {Record<string, any>} object - Object with key-value pairs to convert into a query string.
+ * Keys represent parameter names, and values represent parameter values.
+ * @param {'comma' | 'json' | 'multi'} concatType - Method for handling array values:
+ *   - 'comma': Joins array elements with a comma.
+ *   - 'json': Serializes the array as a JSON string.
+ *   - 'multi': Creates multiple entries for array elements, each associated with the same key.
+ * @returns {string} - Formed query string with keys and values encoded as URI components.
  */
 const makeQuery = (object, concatType) => {
     return Object.entries(object)
@@ -748,16 +792,16 @@ const makeQuery = (object, concatType) => {
         .join('&');
 };
 /**
- * Сравнивает два маршрута, чтобы определить, совпадает ли фактический маршрут с шаблоном маршрута.
- * Поддерживает статическое и динамическое сопоставление маршрутов с опциональным учетом подмаршрутов.
+ * Compares two routes to determine if the actual route matches the route template.
+ * Supports static and dynamic route matching with optional subroute consideration.
  *
- * @param {string} actualRoute - Фактический путь маршрута для сравнения.
- * @param {string} pureRoute - Шаблонный путь маршрута для сопоставления, который может включать заполнители
- * (например, `:id`).
- * @param {boolean} [withSubroute=false] - Определяет, разрешать ли сопоставление подмаршрутов. Если true,
- * actualRoute должен начинаться с заполненного pureRoute.
- * @return {boolean} Возвращает true, если фактический маршрут соответствует шаблонному
- * маршруту (и опциональному условию подмаршрута, если включено), в противном случае false.
+ * @param {string} actualRoute - Actual route path to compare.
+ * @param {string} pureRoute - Template route path to match, which may include placeholders
+ * (e.g., `:id`).
+ * @param {boolean} [withSubroute=false] - Determines whether to allow subroute matching. If true,
+ * actualRoute must start with the filled pureRoute.
+ * @return {boolean} Returns true if the actual route matches the template
+ * route (and optional subroute condition if enabled), otherwise false.
  */
 const compareRoutes = (actualRoute, pureRoute, withSubroute = false) => {
     if (!pureRoute.includes(':')) {
@@ -769,12 +813,12 @@ const compareRoutes = (actualRoute, pureRoute, withSubroute = false) => {
     }
 };
 /**
- * Обрабатывает и материализует путь маршрута путем декодирования и при необходимости замены параметров маршрута.
+ * Processes and materializes a route path by decoding and, if necessary, replacing route parameters.
  *
- * @param {string} actualRoute - Фактический путь маршрута, обычно предоставляемый
- * в качестве источника значений динамических параметров.
- * @param {string} pureRoute - Шаблон пути маршрута, может включать динамические сегменты, обозначенные `:`.
- * @returns {string} Полностью материализованный и декодированный путь маршрута.
+ * @param {string} actualRoute - Actual route path, usually provided
+ * as a source for dynamic parameter values.
+ * @param {string} pureRoute - Route path template, may include dynamic segments denoted by `:`.
+ * @returns {string} Fully materialized and decoded route path.
  */
 const materializeRoutePath = (actualRoute, pureRoute) => {
     if (!pureRoute.includes(':')) {
@@ -798,14 +842,14 @@ const fillRouteTemplate = (actualRoute, pureRoute) => {
 };
 
 /**
- * Рекурсивно проверяет равенство двух объектов, включая вложенные структуры и особые случаи,
- * такие как массивы, наборы, карты, даты и NaN.
+ * Recursively checks the equality of two objects, including nested structures and special cases
+ * such as arrays, sets, maps, dates, and NaN.
  *
- * @param {AnyType} a - Первый объект для сравнения.
- * @param {AnyType} b - Второй объект для сравнения.
- * @param {Map} [seen=new Map()] - Карта, используемая для обнаружения циклических ссылок
- * при глубокой проверке равенства.
- * @return {boolean} - Возвращает true, если объекты полностью равны, иначе возвращает false.
+ * @param {AnyType} a - The first object to compare.
+ * @param {AnyType} b - The second object to compare.
+ * @param {Map} [seen=new Map()] - A map used to detect cyclic references
+ * during deep equality check.
+ * @return {boolean} - Returns true if the objects are deeply equal, otherwise returns false.
  */
 function deepEqual(a, b, seen = new Map()) {
     if (a === b) {