@nemigo/helpers 0.13.3 → 1.5.0

package/dist/string.d.ts

@@ -1,95 +1,95 @@
+/**
+ * Удаляет все вхождения плейсхолдеров из строки через {@link String.replaceAll}
+ *
+ * @param [str=""] - Входная строка
+ * @param [placeholder="_"] - Строка или регулярное выражение для удаления
+ *
+ * @remarks Если используется `RegExp`, он **должен содержать флаг `g`**
+ *
+ * @example
+ * ```typescript
+ * clearPH("user___name"); // "username"
+ * ```
+ */
+export declare const clearPH: (str?: string, placeholder?: string | RegExp) => string;
 /**
  * Регулярное выражение для захвата всех нецифровых символов из строки.
- * Используется для удаления всех символов, кроме цифр 0-9.
+ * Используется для удаления всех символов, кроме цифр 0-9
  */
 export declare const oDigitRegExp: RegExp;
 /**
- * Удаляет все символы из строки, кроме цифр 0-9.
+ * Удаляет все символы из строки, кроме цифр 0-9
  *
- * @param v - Входная строка для очистки
- * @returns Строка, содержащая только цифры
+ * @param [str=""] - Входная строка для очистки
  *
  * @example
  * ```typescript
  * oDigitClean("abc123def456"); // "123456"
  * oDigitClean("+7 (999) 123-45-67"); // "79991234567"
- * oDigitClean(""); // ""
  * ```
  */
-export declare const oDigitClean: (v?: string) => string;
+export declare const oDigitClean: (str?: string) => string;
 /**
- * Регулярное выражение для захвата одного или более пробельных символов подряд.
- * Включает пробелы, табуляции, переносы строк и другие пробельные символы.
+ * Регулярное выражение для захвата одного или более пробельных символов подряд
  */
-export declare const spaceRegExp: RegExp;
+export declare const oSpaceRegExp: RegExp;
 /**
- * Нормализует пробелы в строке: заменяет множественные пробелы на один и удаляет пробелы в начале и конце.
+ * Нормализует пробелы в строке: заменяет множественные пробелы на один и удаляет пробелы в начале и конце
  *
- * @param v - Входная строка для нормализации
- * @returns Строка с нормализованными пробелами
+ * @param [str=""] - Входная строка для нормализации
  *
  * @example
  * ```typescript
- * spaceClean("  hello    world  "); // "hello world"
- * spaceClean("multiple\n\n\nspaces"); // "multiple spaces"
- * spaceClean("tab\t\tseparated"); // "tab separated"
+ * oSpaceClean("  hello    world  "); // "hello world"
+ * oSpaceClean("multiple\n\n\nspaces"); // "multiple spaces"
+ * oSpaceClean("tab\t\tseparated"); // "tab separated"
  * ```
  */
-export declare const spaceClean: (v?: string) => string;
+export declare const oSpaceClean: (str?: string) => string;
 /**
- * Удаляет все вхождения плейсхолдера из строки.
+ * Приводит строку к нижнему регистру и нормализует пробелы.
+ * Комбинация методов {@link String.toLowerCase} и {@link oSpaceClean}
  *
- * @param str - Входная строка
- * @param placeholder - Строка или регулярное выражение для удаления (по умолчанию "_")
- * @returns Строка без плейсхолдеров
+ * @param [str=""] - Строка для нормализации
  *
  * @example
  * ```typescript
- * clearPH("hello_world_test", "_"); // "helloworldtest"
- * clearPH("user___name", "_"); // "username"
- * clearPH("test***end", "*"); // "testend"
- * clearPH("email@domain.com", /@/); // "emaildomain.com"
+ * toFlat("  Hello    World  "); // "hello world"
+ * toFlat("CamelCase String"); // "camelcase string"
+ * toFlat(""); // ""
  * ```
  */
-export declare const clearPH: (str?: string, placeholder?: string | RegExp) => string;
+export declare const toFlat: (str?: string) => string;
 /**
- * Приводит первый символ строки к верхнему регистру, остальные оставляет без изменений.
+ * Приводит первый символ строки к верхнему регистру, остальные оставляет без изменений
  *
- * @param word - Строка для капитализации
- * @returns Строка с заглавной первой буквой
+ * @param [word=""] - Слово для капитализации
  *
  * @example
  * ```typescript
- * toCapital("hello"); // "Hello"
- * toCapital("world"); // "World"
- * toCapital(""); // ""
- * toCapital("a"); // "A"
+ * toCapitalCase("hello"); // "Hello"
  * ```
  */
-export declare const toCapital: (word?: string) => string;
+export declare const toCapitalCase: (word?: string) => string;
 /**
- * Приводит первый символ каждого слова к верхнему регистру (Title Case).
- * Разделяет строку по пробелам и применяет капитализацию к каждому слову.
+ * Разделяет строку по пробелам и приводит первый символ каждого слова к верхнему регистру ({@link toCapitalCase})
  *
- * @param str - Строка для преобразования в Title Case
- * @returns Строка с заглавными первыми буквами каждого слова
+ * @param [str=""] - Строка для преобразования в Title Case
  *
  * @example
  * ```typescript
- * toCapitalMap("hello world"); // "Hello World"
- * toCapitalMap("javascript programming"); // "Javascript Programming"
- * toCapitalMap(""); // ""
- * toCapitalMap("single"); // "Single"
+ * toCapitalCaseMap("hello world"); // "Hello World"
+ * toCapitalCaseMap(""); // ""
+ * toCapitalCaseMap("single"); // "Single"
  * ```
  */
-export declare const toCapitalMap: (str?: string) => string;
+export declare const toCapitalCaseMap: (str?: string) => string;
 /**
- * Повторяет строку указанное количество раз с разделителем между повторениями.
+ * Повторяет строку указанное количество раз с разделителем между повторениями
  *
  * @param str - Исходная строка для повторения
- * @param length - Количество повторений (должно быть неотрицательным)
- * @param separator - Разделитель между повторениями (по умолчанию пустая строка)
- * @returns Результирующая строка из повторений
+ * @param length - Количество повторений (**должно быть ≥ 0**)
+ * @param [separator=""] - Разделитель между повторениями
  *
  * @example
  * ```typescript
@@ -101,49 +101,3 @@ export declare const toCapitalMap: (str?: string) => string;
  * ```
  */
 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 toSlug} для создания URL-friendly строк.
- *
- * @example
- * ```typescript
- * cyrillicToLatinMap.get('а'); // "a"
- * cyrillicToLatinMap.get('ё'); // "yo"
- * cyrillicToLatinMap.get('ъ'); // ""
- * ```
- */
-export declare const cyrillicToLatinMap: Map<string, string>;
-/**
- * Создает 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,98 +1,95 @@
+/**
+ * Удаляет все вхождения плейсхолдеров из строки через {@link String.replaceAll}
+ *
+ * @param [str=""] - Входная строка
+ * @param [placeholder="_"] - Строка или регулярное выражение для удаления
+ *
+ * @remarks Если используется `RegExp`, он **должен содержать флаг `g`**
+ *
+ * @example
+ * ```typescript
+ * clearPH("user___name"); // "username"
+ * ```
+ */
+export const clearPH = (str = "", placeholder = "_") => str.replaceAll(placeholder, "");
 /**
  * Регулярное выражение для захвата всех нецифровых символов из строки.
- * Используется для удаления всех символов, кроме цифр 0-9.
+ * Используется для удаления всех символов, кроме цифр 0-9
  */
 export const oDigitRegExp = /\D/g;
 /**
- * Удаляет все символы из строки, кроме цифр 0-9.
+ * Удаляет все символы из строки, кроме цифр 0-9
  *
- * @param v - Входная строка для очистки
- * @returns Строка, содержащая только цифры
+ * @param [str=""] - Входная строка для очистки
  *
  * @example
  * ```typescript
  * oDigitClean("abc123def456"); // "123456"
  * oDigitClean("+7 (999) 123-45-67"); // "79991234567"
- * oDigitClean(""); // ""
  * ```
  */
-export const oDigitClean = (v = "") => v.replace(oDigitRegExp, "");
-//...
+export const oDigitClean = (str = "") => str.replace(oDigitRegExp, "");
 /**
- * Регулярное выражение для захвата одного или более пробельных символов подряд.
- * Включает пробелы, табуляции, переносы строк и другие пробельные символы.
+ * Регулярное выражение для захвата одного или более пробельных символов подряд
  */
-export const spaceRegExp = /\s+/g;
+export const oSpaceRegExp = /\s+/g;
 /**
- * Нормализует пробелы в строке: заменяет множественные пробелы на один и удаляет пробелы в начале и конце.
+ * Нормализует пробелы в строке: заменяет множественные пробелы на один и удаляет пробелы в начале и конце
  *
- * @param v - Входная строка для нормализации
- * @returns Строка с нормализованными пробелами
+ * @param [str=""] - Входная строка для нормализации
  *
  * @example
  * ```typescript
- * spaceClean("  hello    world  "); // "hello world"
- * spaceClean("multiple\n\n\nspaces"); // "multiple spaces"
- * spaceClean("tab\t\tseparated"); // "tab separated"
+ * oSpaceClean("  hello    world  "); // "hello world"
+ * oSpaceClean("multiple\n\n\nspaces"); // "multiple spaces"
+ * oSpaceClean("tab\t\tseparated"); // "tab separated"
  * ```
  */
-export const spaceClean = (v = "") => v.replace(spaceRegExp, " ").trim();
+export const oSpaceClean = (str = "") => str.replace(oSpaceRegExp, " ").trim();
 /**
- * Удаляет все вхождения плейсхолдера из строки.
+ * Приводит строку к нижнему регистру и нормализует пробелы.
+ * Комбинация методов {@link String.toLowerCase} и {@link oSpaceClean}
  *
- * @param str - Входная строка
- * @param placeholder - Строка или регулярное выражение для удаления (по умолчанию "_")
- * @returns Строка без плейсхолдеров
+ * @param [str=""] - Строка для нормализации
  *
  * @example
  * ```typescript
- * clearPH("hello_world_test", "_"); // "helloworldtest"
- * clearPH("user___name", "_"); // "username"
- * clearPH("test***end", "*"); // "testend"
- * clearPH("email@domain.com", /@/); // "emaildomain.com"
+ * toFlat("  Hello    World  "); // "hello world"
+ * toFlat("CamelCase String"); // "camelcase string"
+ * toFlat(""); // ""
  * ```
  */
-export const clearPH = (str = "", placeholder = "_") => str.replaceAll(placeholder, "");
-//...
+export const toFlat = (str = "") => oSpaceClean(str.toLowerCase());
 /**
- * Приводит первый символ строки к верхнему регистру, остальные оставляет без изменений.
+ * Приводит первый символ строки к верхнему регистру, остальные оставляет без изменений
  *
- * @param word - Строка для капитализации
- * @returns Строка с заглавной первой буквой
+ * @param [word=""] - Слово для капитализации
  *
  * @example
  * ```typescript
- * toCapital("hello"); // "Hello"
- * toCapital("world"); // "World"
- * toCapital(""); // ""
- * toCapital("a"); // "A"
+ * toCapitalCase("hello"); // "Hello"
  * ```
  */
-export const toCapital = (word = "") => word.charAt(0).toUpperCase() + word.slice(1);
+export const toCapitalCase = (word = "") => word.charAt(0).toUpperCase() + word.slice(1);
 /**
- * Приводит первый символ каждого слова к верхнему регистру (Title Case).
- * Разделяет строку по пробелам и применяет капитализацию к каждому слову.
+ * Разделяет строку по пробелам и приводит первый символ каждого слова к верхнему регистру ({@link toCapitalCase})
  *
- * @param str - Строка для преобразования в Title Case
- * @returns Строка с заглавными первыми буквами каждого слова
+ * @param [str=""] - Строка для преобразования в Title Case
  *
  * @example
  * ```typescript
- * toCapitalMap("hello world"); // "Hello World"
- * toCapitalMap("javascript programming"); // "Javascript Programming"
- * toCapitalMap(""); // ""
- * toCapitalMap("single"); // "Single"
+ * toCapitalCaseMap("hello world"); // "Hello World"
+ * toCapitalCaseMap(""); // ""
+ * toCapitalCaseMap("single"); // "Single"
  * ```
  */
-export const toCapitalMap = (str = "") => str.split(" ").map(toCapital).join(" ");
-//...
+export const toCapitalCaseMap = (str = "") => str.split(" ").map(toCapitalCase).join(" ");
 /**
- * Повторяет строку указанное количество раз с разделителем между повторениями.
+ * Повторяет строку указанное количество раз с разделителем между повторениями
  *
  * @param str - Исходная строка для повторения
- * @param length - Количество повторений (должно быть неотрицательным)
- * @param separator - Разделитель между повторениями (по умолчанию пустая строка)
- * @returns Результирующая строка из повторений
+ * @param length - Количество повторений (**должно быть ≥ 0**)
+ * @param [separator=""] - Разделитель между повторениями
  *
  * @example
  * ```typescript
@@ -104,125 +101,3 @@ export const toCapitalMap = (str = "") => str.split(" ").map(toCapital).join(" "
  * ```
  */
 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 toSlug} для создания URL-friendly строк.
- *
- * @example
- * ```typescript
- * cyrillicToLatinMap.get('а'); // "a"
- * cyrillicToLatinMap.get('ё'); // "yo"
- * cyrillicToLatinMap.get('ъ'); // ""
- * ```
- */
-export const cyrillicToLatinMap = new Map([
-    ["а", "a"],
-    ["б", "b"],
-    ["в", "v"],
-    ["г", "g"],
-    ["д", "d"],
-    ["е", "e"],
-    ["ё", "yo"],
-    ["ж", "zh"],
-    ["з", "z"],
-    ["и", "i"],
-    ["й", "y"],
-    ["к", "k"],
-    ["л", "l"],
-    ["м", "m"],
-    ["н", "n"],
-    ["о", "o"],
-    ["п", "p"],
-    ["р", "r"],
-    ["с", "s"],
-    ["т", "t"],
-    ["у", "u"],
-    ["ф", "f"],
-    ["х", "h"],
-    ["ц", "ts"],
-    ["ч", "ch"],
-    ["ш", "sh"],
-    ["щ", "sch"],
-    ["ъ", ""],
-    ["ы", "y"],
-    ["ь", ""],
-    ["э", "e"],
-    ["ю", "yu"],
-    ["я", "ya"],
-]);
-/**
- * Создает 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 = [];
-    let wasSpace = false;
-    for (const _char of text) {
-        const char = _char.toLowerCase();
-        const code = char.charCodeAt(0);
-        // Кириллица (а-я, ё)
-        if ((code >= 1072 && code <= 1103) || code === 1105) {
-            buf.push(cyrillicToLatinMap.get(char) ?? char);
-            wasSpace = false;
-        }
-        // Цифры (0-9)
-        else if (code >= 48 && code <= 57) {
-            buf.push(char);
-            wasSpace = false;
-        }
-        // Латиница (a-z)
-        else if (code >= 97 && code <= 122) {
-            buf.push(char);
-            wasSpace = false;
-        }
-        // Пробуем нормализовать символы с диакритиками в латиницу (é -> e)
-        else {
-            const normalized = char.normalize("NFD").replace(/[\u0300-\u036f]/g, "");
-            const nCode = normalized.charCodeAt(0);
-            if (normalized.length === 1 && nCode >= 97 && nCode <= 122) {
-                buf.push(normalized);
-                wasSpace = false;
-            }
-            else {
-                if (!wasSpace && buf.length > 0) {
-                    buf.push(separator);
-                    wasSpace = true;
-                }
-            }
-        }
-    }
-    // Убираем завершающий separator (с учётом многосимвольного separator)
-    const acc = buf.join("");
-    return separator && acc.endsWith(separator) ? acc.slice(0, -separator.length) : acc;
-};