@mirta/basics 0.3.5 → 0.4.1

package/dist/array/index.d.mts

@@ -0,0 +1,61 @@
+/**
+ * Преобразует входное значение в массив.
+ *
+ * Если входное значение уже является массивом, возвращает его копию.
+ * В противном случае оборачивает значение в массив и возвращает результат.
+ *
+ * @template TItem - Тип элемента или массива элементов.
+ * @param input - Входное значение, которое может быть одиночным элементом или массивом элементов.
+ * @returns Массив, содержащий один элемент (если входной — не массив) или копию входного массива.
+ *
+ * @example
+ * ```ts
+ * ensureArray('hello') // → ['hello']
+ * ```
+ * @example
+ * ```ts
+ * ensureArray([1, 2, 3]) // → [1, 2, 3]
+ * ```
+ * @example
+ * ```ts
+ * ensureArray(null) // → [null]
+ * ```
+ * @since 0.4.0
+ *
+ **/
+declare function ensureArray<TItem>(input: TItem | TItem[]): TItem[];
+
+/**
+ * Преобразует входные данные в массив, исключая все "ложные" значения.
+ *
+ * К ложным значениям относятся: `0`, `''`, `false`, `null`, `undefined`, `NaN`.
+ *
+ * @template TItem - Тип допустимых значений.
+ * @param input - Вход: значение или массив с возможными `false`, `null`, `undefined`.
+ * @returns Массив истинных значений типа `TItem[]`. Если вход пустой — возвращает `[]`.
+ *
+ * @example
+ *
+ * ```ts
+ * ensureCompactArray([1, null, 2, '']) // → [1, 2]
+ *
+ * ```
+ * @example
+ *
+ * ```ts
+ * ensureCompactArray('hello') // → ['hello']
+ *
+ * ```
+ * @example
+ *
+ * ```ts
+ * ensureCompactArray(undefined) // → []
+ *
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function ensureCompactArray<TItem>(input: TItem | false | null | undefined | (TItem | false | null | undefined)[]): TItem[];
+
+export { ensureArray, ensureCompactArray };

package/dist/array/index.mjs

@@ -0,0 +1,67 @@
+/**
+ * Преобразует входное значение в массив.
+ *
+ * Если входное значение уже является массивом, возвращает его копию.
+ * В противном случае оборачивает значение в массив и возвращает результат.
+ *
+ * @template TItem - Тип элемента или массива элементов.
+ * @param input - Входное значение, которое может быть одиночным элементом или массивом элементов.
+ * @returns Массив, содержащий один элемент (если входной — не массив) или копию входного массива.
+ *
+ * @example
+ * ```ts
+ * ensureArray('hello') // → ['hello']
+ * ```
+ * @example
+ * ```ts
+ * ensureArray([1, 2, 3]) // → [1, 2, 3]
+ * ```
+ * @example
+ * ```ts
+ * ensureArray(null) // → [null]
+ * ```
+ * @since 0.4.0
+ *
+ **/
+function ensureArray(input) {
+    return Array.isArray(input) ? [...input] : [input];
+}
+
+/**
+ * Преобразует входные данные в массив, исключая все "ложные" значения.
+ *
+ * К ложным значениям относятся: `0`, `''`, `false`, `null`, `undefined`, `NaN`.
+ *
+ * @template TItem - Тип допустимых значений.
+ * @param input - Вход: значение или массив с возможными `false`, `null`, `undefined`.
+ * @returns Массив истинных значений типа `TItem[]`. Если вход пустой — возвращает `[]`.
+ *
+ * @example
+ *
+ * ```ts
+ * ensureCompactArray([1, null, 2, '']) // → [1, 2]
+ *
+ * ```
+ * @example
+ *
+ * ```ts
+ * ensureCompactArray('hello') // → ['hello']
+ *
+ * ```
+ * @example
+ *
+ * ```ts
+ * ensureCompactArray(undefined) // → []
+ *
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+function ensureCompactArray(input) {
+    if (Array.isArray(input))
+        return input.filter(Boolean);
+    return input ? [input] : [];
+}
+
+export { ensureArray, ensureCompactArray };

package/dist/fuzzy/index.d.mts

@@ -0,0 +1,170 @@
+/**
+ * Универсальный результат вычисления расстояния редактирования между двумя строками.
+ *
+ * Интерфейс предназначен для стандартизации выходных данных различных алгоритмов
+ * нечёткого сравнения строк, таких как Левенштейн и Дамерау-Левенштейн.
+ *
+ * Позволяет единообразно работать с метриками схожести в системах подсказок,
+ * нечёткого поиска и обработки опечаток.
+ *
+ * @example
+ * ```ts
+ * const result: DistanceResult = damerauLevenshtein("команда", "команда");
+ * log(result.steps);      // 0
+ * log(result.relative);   // 0
+ * log(result.similarity); // 1
+ * ```
+ * @since 0.4.0
+ *
+ **/
+interface DistanceResult {
+    /**
+     * Количество операций редактирования, необходимых для преобразования
+     * одной строки в другую. Конкретный набор операций зависит от реализации алгоритма:
+     *
+     * - Алгоритм Левенштейна: вставка, удаление, замена
+     * - Алгоритм Дамерау-Левенштейна: + транспозиция соседних символов
+     * - Другие алгоритмы: могут использовать свои метрики (например, блоковые перестановки)
+     *
+     * @example
+     * Для алгоритма Дамерау-Левенштейна:
+     * ```txt
+     * "релиз" → "релзи" = 1 (транспозиция 'и' и 'з')
+     * ```
+     * Для алгоритма Левенштейна:
+     * ```txt
+     * "релиз" → "релзи" = 2 (удаление + вставка)
+     * ```
+     **/
+    readonly steps: number;
+    /**
+     * Относительное расстояние — нормализованная метрика, рассчитываемая как отношение
+     * количества операций к максимальной длине сравниваемых строк.
+     *
+     * Позволяет сравнивать строки разной длины на одной шкале.
+     *
+     * Указывается в диапазоне от 0 (полное совпадение) до 1 (максимальное различие).
+     *
+     * @example
+     * Для строк "текст" (5) и "тест" (4) при steps = 1:
+     * ```txt
+     * relative = 1 / max(5, 4) = 1 / 5 = 0.2
+     * ```
+     **/
+    readonly relative: number;
+    /**
+     * Степень схожести строк — величина, обратная относительному расстоянию.
+     *
+     * Используется для ранжирования результатов в системах нечёткого поиска и подсказок.
+     * Чем выше значение, тем больше вероятность, что строки семантически близки.
+     *
+     * Указывается в диапазоне от 0 (максимальное различие) до 1 (полное совпадение)
+     *
+     * @example
+     * ```txt
+     * similarity = 1 - relative
+     * relative = 0.2 → similarity = 0.8
+     * ```
+     **/
+    readonly similarity: number;
+}
+
+/**
+ * Вычисляет расстояние Дамерау-Левенштейна между двумя строками.
+ *
+ * Сложность: `O(n × m)` 💥 Экспоненциальный рост.
+ *
+ * @param from Первая строка
+ * @param to Вторая строка
+ * @param maxDistance Максимальное расстояние для расчёта.
+ *                    Если превышено, расстояние возвращается как `Infinity`.
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function damerauLevenshtein(from: string, to: string, maxDistance?: number): DistanceResult;
+
+/**
+ * Тип для фонетического кода — строка, гарантированно содержащая 6 цифр.
+ *
+ * Используется для маркировки результата функции `daitchMokotoffLite`,
+ * чтобы отличать обычные строки от валидных фонетических кодов.
+ *
+ * @example
+ * ```ts
+ * '550000' as PhoneticCode
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+type PhoneticCode = Branded<string, 'PhoneticCode'>;
+
+/**
+ * Упрощённая реализация алгоритма Daitch-Mokotoff для фонетического кодирования.
+ *
+ * Сложность: `O(n)` — один проход по строке.
+ *
+ * Преобразует строки в 6-значные коды, устойчивые к опечаткам, транслитерации и диалектным различиям.
+ * Поддерживает кириллицу через транслитерацию.
+ *
+ * @param input - Входная строка (может быть `null` / `undefined`)
+ * @returns 6-значный фонетический код
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function daitchMokotoffLite(input: string | null | undefined): PhoneticCode;
+
+/**
+ * Параметры для работы с функцией {@link suggestClosest} — нечёткого поиска
+ * наиболее подходящего значения на основе ввода пользователя.
+ *
+ * Используется для настройки чувствительности и поведения при сравнении строк.
+ *
+ * @since 0.4.0
+ *
+ **/
+interface SuggestOptions {
+    /**
+     * Максимальное расстояние Дамерау-Левенштейна, при котором значение
+     * считается допустимым кандидатом для подсказки. По умолчанию — `2`.
+     *
+     * Чем меньше значение, тем строже сравнение.
+     *
+     **/
+    maxDistance?: number;
+    /**
+     * Веса для комбинированного ранжира.
+     * Сумма не обязана быть 1 — нормализуется внутри.
+     */
+    weights?: {
+        phonetic?: number;
+        trigram?: number;
+        levenshtein?: number;
+    };
+}
+/**
+ * Предлагает наиболее близкое значение из списка допустимых,
+ * используя алгоритм Дамерау-Левенштейна для учёта опечаток.
+ *
+ * Функция предназначена для реализации подсказок вроде:
+ * "Вы имели в виду 'release'?", когда пользователь ввёл 'releas'.
+ *
+ * @param input Введённая пользователем строка, возможно, с опечаткой
+ * @param targetValues Список корректных, допустимых значений (например, команды, флаги)
+ * @param options Настройки нечёткого поиска
+ * @returns Наиболее близкое значение из `knownValues` или `undefined`, если совпадений нет
+ *
+ * @example
+ * ```ts
+ * suggestClosest('releas', ['release', 'publish']) // → 'release'
+ * suggestClosest('релиз', ['release', 'publish'])  // → 'release'
+ * ```
+ * @since 0.4.0
+ *
+ **/
+declare function suggestClosest(input: string, targetValues: readonly string[], options?: SuggestOptions): string | undefined;
+
+export { daitchMokotoffLite, damerauLevenshtein, suggestClosest };
+export type { DistanceResult, PhoneticCode, SuggestOptions };