@astral/utils

Утилиты и функции общего назначения.

Table of contents

• Installation
• base
  • zeroPad
  • debounce
  • uniqBy
  • prop
  • mergeDeep
• date
  • addHours
  • addDays
  • addMonths
  • addYears
  • isDate
• declension
  • declensionOfWords
  • declensionDay
  • declensionMonth
  • declensionYear
• file
  • formatFileSizeToView
  • formatFileTypeToView
  • getAllFileExtensions
  • getFileExtension
  • getFileType
• phone
  • formatPhoneToView
  • normalizePhone
  • checkPhone
• email
  • checkProbablyEmail
• number
  • formatNumberToCurrency

Installation

npm i --save @astral/utils

yarn add @astral/utils

Imports

Импорты утилит осуществляются не через корневой index файл, а через конкретные пути.

✅ Valid

import { zeroPad } from '@astral/utils/base/zeroPad';

❌ Invalid

import { zeroPad } from '@astral/utils';

Мотивация: позволяет при росте пакета не замедлять dev инструменты (ts, сборщики...).

base

base utils - Общие утилиты и функции

zeroPad

Утилита для генерации строковых чисел с заданным количеством символов, если число символов числа меньше необходимого.

import { zeroPad } from '@astral/utils/zeroPad';

// 001
zeroPad(1,3);

// 007
zeroPad(7,3);

// 111
zeroPad(111,3);

debounce

import { debounce } from '@astral/utils/debounce';

// Функция будет вызываться по истечению 300мс с момент последнего вызова
const debouncedFunc = debounce(() => { ... }, 300);
debouncedFunc();

// isPending
const debouncedFunc = debounce(() => { ... }, 300);
debouncedFunc.isPending // false
debouncedFunc();
debouncedFunc.isPending // true

// Отмена запланированного выполнения
const debouncedFunc = debounce(() => { ... }, 300);
debouncedFunc();
debouncedFunc.clear(); // отмена выполнения

Подробнее

uniqBy

import { uniqBy } from '@astral/utils/uniqBy';

Функция возвращает массив, содержащий только одну копию каждого элемента исходного списка. Подробнее

prop

import { prop } from '@astral/utils/prop';

Функция получает значение указанного свойства Подробнее

mergeDeep

import { mergeDeep } from '@astral/utils/mergeDeep';

Функция для объединения исходного объекта с целевым Подробнее

isPlainObject

Проверяет является ли объект "простым" объектом (plain object).

import { isPlainObject } from '@astral/utils/isPlainObject';

isPlainObject({}); // true
isPlainObject({ foo: 'bar' }); // true
isPlainObject(Object.create(null)); // true
isPlainObject(new Foo()); // false
isPlainObject([1, 2, 3]); // false

date

Утилиты и функции работы с датами

addHours

Утилита добавляющая к дате указанное количество часов

import { addHours } from '@astral/utils/date/addHours';

// 2024-01-01T05:00:00 - функция добавит 5 часов
addHours(new Date('2024-01-01T00:00:00'), 5);

addDays

Утилита добавляющая к дате указанное количество дней

import { addDays } from '@astral/utils/date/addDays';

// 01.10.2024 - функция добавит 10 дней
addDays(new Date('01.01.2024'), 10);

addMonths

Утилита добавляющая к дате указанное количество месяцев

import { addMonths } from '@astral/utils/date/addMonths';

// 04.01.2024 - функция добавит 4 месяца
addMonths(new Date('01.01.2024'), 4);

addYears

Утилита добавляющая к дате указанное количество лет

import { addYears } from '@astral/utils/date/addYears';

// 01.01.2024 - функция добавит 4 года
addYears(new Date('01.01.2020'), 4);

isDate

Утилита проверки значения на валидность даты

import { isDate } from '@astral/utils/date/isDate';

// true
isDate(new Date('01.01.2020'));

// true
isDate('01.01.2020');


// true
isDate(2024);


// false
isDate(undefined);

// false
isDate(null);

// false
isDate('some string');

declension

Утилиты и функции для работы со склонениями слов

declensionOfWords

Базовая утилита для работы со склонениями

import { declensionOfWords } from '@astral/utils/declension/declensionOfWords';

// Возвращает функцию для склонения слова 'документ'
const declensionDocument = declensionOfWords(['документ', 'документа', 'документов']);

declensionDay

Утилита для склонения дней

import { declensionDay } from '@astral/utils/declension/declensionDay';

// вернет 'день'
declensionDay(1); 

// вернет 'дня'
declensionDay(2); 

// вернет 'дней'
declensionDay(5); 

declensionMonth

Утилита для склонения месяцев

import { declensionMonth } from '@astral/utils/declension/declensionMonth';

// вернет 'месяц'
declensionMonth(1); 

// вернет 'месяца'
declensionMonth(2); 

// вернет 'месяцев'
declensionMonth(5); 

declensionYear

Утилита для склонения лет

import { declensionYear } from '@astral/utils/declension/declensionYear';

// вернет 'год'
declensionYear(1); 

// вернет 'года'
declensionYear(2); 

// вернет 'лет'
declensionYear(5); 

file

Утилиты и функции для работы с файлами

formatFileSizeToView

Функция, которая возвращает размер файла с единицами измерения.

import { formatFileSizeToView } from '@astral/utils/file/formatFileSizeToView';

// 1.00 Б
formatFileSizeToView(1);


// 5.00 Кб
formatFileSizeToView(5 * 1024);


// 5.00 Мб
formatFileSizeToView(5 * 1024 * 1024);

// 0 Б
formatFileSizeToView(0);

formatFileTypeToView

Функция, которая возвращает расширение файла

import { formatFileTypeToView } from '@astral/utils/file/formatFileTypeToView';

// jpeg
formatFileTypeToView('.jpeg');


// pdf
formatFileTypeToView('application/pdf');

getAllFileExtensions

Функция, которая возвращает массив расширений файлов для указанного MIME-типа

import { getAllFileExtensions } from '@astral/utils/file/getAllFileExtensions';

// ['jpg', 'jpeg', 'jpe']
getAllFileExtensions('image/jpeg') 


// ['pdf']
getAllFileExtensions('application/pdf');

getFileExtension

Функция, которая возвращает расширение файла на основе переданного типа

import { getFileExtension } from '@astral/utils/file/getFileExtension';


// jpg
getFileExtension('image/jpeg');


// pdf
getFileExtension('application/pdf');

getFileType

Определяет MIME-тип файла по его расширению

import { getFileType } from '@astral/utils/file/getFileType';

// application/pdf
getFileType('pdf');

phone

Утилиты и функции работы с номерами телефона

formatPhoneToView

Форматирование номера телефона по маске

import { formatPhoneToView } from '@astral/utils/phone/formatPhoneToView';

// +7 (999) 999-99-99
formatPhoneToView('79999999999');


// 8 (999) 999-99-99
formatPhoneToView('79999999999',{
    isStartWithPlus: false,
});


// undefined
formatPhoneToView();

normalizePhone

Нормализует мобильный номер телефона:

• Удаляет все нецифровые символы
• Заменяет первую цифру 8 на 7

import { normalizePhone } from '@astral/utils/phone/normalizePhone';

// 79999999999
normalizePhone('+7 (999) 999-99-99');

// 79999999999
normalizePhone('8/999/999-99-99');

// ''
normalizePhone('');

checkPhone

Возвращает true, если строка является мобильным телефоном. Необходимо передавать нормализованное значение (без маски)

import { checkPhone } from '@astral/utils/phone/checkPhone';

// true
checkPhone('79001234567');


// false
checkPhone('[email protected]');

email

Утилиты и функции работы с email

checkProbablyEmail

Возвращает true, если в строке есть буквы (кириллица или латиница) или символ @

import { checkProbablyEmail } from '@astral/utils/email/checkProbablyEmail';

// true
checkProbablyEmail('привет');
checkProbablyEmail('hello');
checkProbablyEmail('привет@hello');
checkProbablyEmail('@');


// false
checkProbablyEmail('1234567890');

number

Утилиты и функции для работы с числами

formatNumberToCurrency

Форматирование чисел или строк в формат валюты

import { formatNumberToCurrency } from '@astral/utils/number/formatNumberToCurrency';

// "10 000 ₽"
formatNumberToCurrency({ amount: '10000' });

// "100 ₽"
formatNumberToCurrency({ amount: 100 });

// "100,23 ₽"
formatNumberToCurrency({ amount: 100.23 });

// "100,00 ₽"
formatNumberToCurrency({ amount: 100, isShownFractionDigits: true });

// "0 ₽"
formatNumberToCurrency({ amount: 0 });

// "Бесплатно"
formatNumberToCurrency({
  amount: 0,
  isTextInsteadOfZeroFormat: true,
});

// "Даром"
formatNumberToCurrency({
  amount: 0,
  isTextInsteadOfZeroFormat: true,
  zeroSumPlaceholder: "Даром",
});