@front-utils/utils

Коллекция вспомогательных TypeScript/JavaScript утилит для повседневных задач фронтенд-разработки.

Установка

npm install @front-utils/utils
# или
yarn add @front-utils/utils
# или
bun add @front-utils/utils

Содержание

• Base Утилиты
• Проверки (Check)
• Работа с датами (Date)
• Инструменты для работы с файлами (File)
• Работа с изображениями (Image)
• Сетевые утилиты (Net)
• Работа с числами (Number)

Base Утилиты

uuid()

Генерирует стандартный UUID (v4) с использованием API crypto.

Пример использования:

import { uuid } from '@front-utils/utils';
const id = uuid();

Результат: '550e8400-e29b-41d4-a716-446655440000' (пример)

declOfNum(number, decls)

Возвращает правильное склонение существительного в зависимости от переданного числа (русский язык).

Пример использования:

import { declOfNum } from '@front-utils/utils';
const text = declOfNum(5, ['яблоко', 'яблока', 'яблок']);

Результат: 'яблок'

iteratorToList(iterable)

Преобразует IterableIterator в стандартный массив. Полезно для работы с результатами Map.keys(), Map.values() и т.д.

Пример использования:

import { iteratorToList } from '@front-utils/utils';
const map = new Map([['a', 1], ['b', 2]]);
const keys = iteratorToList(map.keys());

Результат: ['a', 'b']

createObserver()

Создает экземпляр паттерна "Наблюдатель" (Observer) для управления подписками.

Пример использования:

import { createObserver } from '@front-utils/utils';
const observer = createObserver<string>();
const unsubscribe = observer.subscribe((data) => console.log(data));
observer.notify('Hello');
unsubscribe();

Результат: Вывод 'Hello' в консоль.

randomIntMinMax({ min, max })

Генерирует случайное целое число в заданном диапазоне (включительно).

Пример использования:

import { randomIntMinMax } from '@front-utils/utils';
const random = randomIntMinMax({ min: 1, max: 5 });

Результат: 3 (случайное число от 1 до 5)

replaceSearchMatch(regex, value)

Оборачивает совпадения по регулярному выражению в тег <b>.

Пример использования:

import { replaceSearchMatch } from '@front-utils/utils';
const html = replaceSearchMatch(/(мир)/gi, 'Привет, Мир!');

Результат: 'Привет, <b>Мир</b>!'

createSafetyRegString(str)

Экранирует спецсимволы в строке для безопасного создания RegExp.

Пример использования:

import { createSafetyRegString } from '@front-utils/utils';
const safe = createSafetyRegString('test.js*');

Результат: 'test\\.js\\*'

safeHandleDecorate(fn)

Обертка для синхронных функций, возвращающая [error, result].

Пример использования:

import { safeHandleDecorate } from '@front-utils/utils';
const safeParse = safeHandleDecorate(JSON.parse);
const [err, res] = safeParse('{"ok": true}');

Результат: [null, { ok: true }]

safeHandleDecorateAsync(fn)

Обертка для асинхронных функций, возвращающая Promise<[error, result]>.

Пример использования:

import { safeHandleDecorateAsync } from '@front-utils/utils';
const safeFetch = safeHandleDecorateAsync(fetch);
const [err, res] = await safeFetch('...');

shallowCompare(objA, objB)

Поверхностное сравнение двух объектов.

Пример использования:

import { shallowCompare } from '@front-utils/utils';
const equal = shallowCompare({ x: 1 }, { x: 1 });

Результат: true

Проверки (Check)

| Функция | Описание | Пример | Результат | | :--- | :--- | :--- | :--- | | isString(v) | Проверка на строку | isString('a') | true | | isBoolean(v) | Проверка на boolean | isBoolean(0) | false | | isFunction(v) | Проверка на функцию | isFunction(() => {}) | true | | isAsyncFunction(v) | Проверка на асинхронную функцию | isAsyncFunction(async () => {}) | true | | isNumber(v) | Проверка на число | isNumber(123) | true | | isNull(v) | Проверка на null | isNull(null) | true | | isUndefined(v) | Проверка на undefined | isUndefined(undefined) | true | | isNullOrUndefined(v) | Проверка на null или undefined | isNullOrUndefined(0) | false | | isObjectType(v) | Проверка typeof v === 'object' | isObjectType([]) | true | | isObject(v) | Проверка на "чистый" объект | isObject({}) | true |

Работа с датами (Date)

Форматирование (Formatting)

format(date)

Форматирует дату в DD.MM.YYYY.

• Пример: format(new Date(2023, 0, 1))
• Результат: '01.01.2023'

getDateString(date, withoutYear?)

Формат "D MMM [YYYY]".

• Пример: getDateString(new Date(2023, 0, 1))
• Результат: '1 янв. 2023'

getFullDateString(date)

Формат "D MMMM [YYYY]".

• Пример: getFullDateString(new Date(2023, 0, 1))
• Результат: '1 января 2023'

getQuarterString(dateString)

Возвращает строку квартала.

• Пример: getQuarterString('2023-05-20')
• Результат: 'II квартал 2023'

getShortDateRangeString(start, end)

Компактный диапазон дат.

• Пример: getShortDateRangeString('2023-01-01', '2023-01-10')
• Результат: '1 – 10 янв. 2023'

formatDateWithOptions({ date, options })

Форматирует дату с произвольными параметрами Intl.DateTimeFormatOptions.

getDateFullString(date)

Формат "D MMM YYYY" (всегда с годом).

getMonthYearFullString({ monthIndex, year, ... })

Полная строка месяца и года.

getMonthYearFullStringFromDate(dateInfo, skipCurrentYear?)

Полная строка месяца и года из даты.

getLocalDateString(dateString)

Локализованная строка даты.

getDateRangeString(start, end, withoutYear?)

Диапазон дат "Start – End".

getFullDatePeriod(start, end)

Полный период дат с полными названиями месяцев.

formatShortEndDate(date)

Форматирует дату в YYYY-MM-DD.

getQuarterNumber(date)

Возвращает номер квартала римскими цифрами (I, II, III, IV).

getMonthFromDate(dateStr, capitalize?)

Извлекает название месяца из строки даты.

getFormatter(options?)

Возвращает кешированный экземпляр Intl.DateTimeFormat.

getOptionalYear(date)

Возвращает год строкой с ведущим пробелом, если он отличается от текущего.

• Пример: getOptionalYear(new Date(2023, 0, 1)) (если сейчас 2024) -> ' 2023'

Валидация (Validation)

isValidDate(str)

Проверка валидности даты.

• Результат: isValidDate('2023-01-01') -> true, isValidDate('invalid') -> false

isValidDateString(str, { isRuString })

Проверка строки даты, включая формат DD.MM.YYYY (при isRuString: true).

• Пример: isValidDateString('01.01.2023', { isRuString: true })
• Результат: true

getDateParamsFromCalendarFormat(str)

Разбирает строку диапазона дат (например, "01.01.2023 - 10.01.2023") на составляющие.

• Результат: Объект с полями start, end (содержащими year, month, day, isValid) и hasEmptyValue.

createCalendarStringFromISO({ startIsoString, finishIsoString })

Формирует строку диапазона дат для календаря из ISO-строк.

• Пример: createCalendarStringFromISO({ startIsoString: '2023-01-01...', finishIsoString: '2023-01-10...' })
• Результат: '01.01.2023 - 10.01.2023'

Локализация (Localization)

getMonthNameByIndex(index, capitalize?)

Возвращает название месяца по его индексу (0-11).

getMonthNameByIndexGenitiveCase(index)

Возвращает название месяца в родительном падеже.

getMonthNameByIndexPrepositionalCase(index)

Возвращает название месяца в предложном падеже.

get3digitMonthName(date)

Возвращает краткое (3 буквы) название месяца.

Манипуляции (Manipulation)

addDays(date, count)

Добавляет указанное количество дней к дате.

• Пример: addDays(new Date(2023, 0, 1), 5)
• Результат: 2023-01-06

toLocalTimeString(date)

Возвращает дату в формате ISO без смещения временной зоны.

• Пример: toLocalTimeString(new Date(2023, 0, 1, 12, 0))
• Результат: '2023-01-01T12:00:00'

addMilliseconds(date, ms)

Добавляет миллисекунды к дате.

addMinutes(date, minutes)

Добавляет минуты к дате.

addHours(date, hours)

Добавляет часы к дате.

addMonth(date, months)

Добавляет месяцы к дате.

getMaxTimeEndDate(dateString)

Возвращает дату, соответствующую концу дня (23:59:59).

getEnDateStringFromRu(dateString)

Конвертирует "DD.MM.YYYY" в "MM.DD.YYYY" (для парсинга).

getIsoStringWithoutTime(date)

Возвращает только дату в формате ISO (YYYY-MM-DD).

compareDates(date1, date2)

Сравнивает две даты. Возвращает объект { isEqual, isFirstLess, isInvalid }.

• Пример: compareDates('2023-01-01', '2023-01-02')
• Результат: { isEqual: false, isFirstLess: true, isInvalid: false }

getWeekRangeDates(date)

Возвращает объект со стартом и концом недели для указанной даты.

getWeekRange(date)

Возвращает строку диапазона недели (например, '2 – 8 янв. 2023').

getCurrentWeekStartDate(date, firstDayOfWeekIndex?)

Возвращает дату начала недели.

Периоды (Periods)

getNextWeekPeriod(isoDate)

Возвращает { start, end } следующей недели.

getNextMonthPeriodDates(isoDate)

Возвращает { start, end } следующего месяца.

Инструменты для работы с файлами (File)

fileToBase64(file)

Конвертирует File в base64 строку (с префиксом).

• Результат: { result: 'data:image/png;base64,...', error: null }

getBase64BodyFromFile(file)

Получает только тело base64 без мета-данных.

• Результат: 'iVBORw0KG...'

base64ToFile({ base64File, type, name })

Создает объект File из base64 строки.

isEqual2Files(file1, file2)

Сравнивает два файла (по имени, размеру и типу).

base64ToBytesBuffer(base64)

Конвертирует base64 в ArrayBuffer.

getBodyFromBase64(base64String)

Отрезает префикс data:...;base64, от строки.

Работа с изображениями (Image)

getImageMeta(url)

Получает naturalHeight и naturalWidth изображения по URL.

• Результат: { naturalHeight: 600, naturalWidth: 800 }

getImageMetaFromFile(file)

Получает meta-данные изображения из объекта File.

Сетевые утилиты (Net)

encodeQueryParams(params)

Преобразует объект в строку запроса (query string).

• Пример: encodeQueryParams({ id: 1, tags: ['a', 'b'] })
• Результат: URLSearchParams { 'id' => '1', 'tags' => 'a,b' }

downloadByUrl(filename, url)

Скачивает файл по ссылке.

• Пример: downloadByUrl('doc.pdf', 'https://example.com/doc.pdf')

downloadLocalFile(filename, file)

Скачивает локальный объект File.

Работа с числами (Number)

numberTo2SignString(num)

Дополняет число ведущим нулем (до 2 знаков).

• Пример: numberTo2SignString(5) -> '05', numberTo2SignString(-5) -> '-05'

numberWithSpaces(value, separator?)

Разделяет тысячи.

• Пример: numberWithSpaces(1500000) -> '1 500 000'

getNumberFromStringWithSpaces(str)

Преобразует строку с пробелами обратно в число.

• Пример: getNumberFromStringWithSpaces('1 500 000') -> 1500000