@foxford/foxford-utils 1.0.1 → 1.1.0

package/index.d.cts

@@ -0,0 +1,516 @@
+import qs from 'query-string';
+
+/**
+ * Генерирует уникальный идентификатор (qid)
+ * @param length - длина уникального идентификатора
+ * @param number - включает ли цифры в алфавит
+ * @return строка
+ */
+declare function qid(length?: number, number?: boolean): string;
+
+/**
+ * Генерирует уникальный сгруппированный идентификатор (псевдо-UUID в стиле v4).
+ * Формат: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (hex)
+ */
+declare function uuid(): string;
+
+/**
+ * Фильтрует поля объекта
+ * @param obj - исходный объект
+ * @param filterFunc - предикат, принимающий (key, value)
+ * @returns новый объект с отфильтрованными полями
+ */
+declare function pickBy<T extends Record<string, unknown>>(obj: T, filterFunc: (key: keyof T & string, value: T[keyof T]) => boolean): Partial<T>;
+
+type ToggleEventLike = {
+    currentTarget: EventTarget | null;
+};
+declare class Collapse {
+    onClickHandler: (e: ToggleEventLike) => boolean;
+    private _onClickEventListener;
+    private _boundMakeCollapse;
+    private _collapses;
+    constructor();
+    makeCollapse(collapse: HTMLElement): boolean;
+    init(): void;
+    destroy(): void;
+    reinit(): void;
+}
+
+/**
+ * Декоратор для функции, добавляющий debounce (задержку выполнения).
+ *
+ * @export
+ * @param {function} f - исходная функция
+ * @param {number} ms - задержка в миллисекундах
+ * @returns {function} - функция-декоратор с debounce
+ */
+declare function debounce<T extends (...args: any[]) => any>(f: T, ms: number): (this: ThisParameterType<T>, ...args: Parameters<T>) => ReturnType<typeof setTimeout>;
+
+/**
+ * Преобразует массив элементов в объект, где ключ — строковый id элемента.
+ *
+ * Пример:
+ *   [{ id: 1, name: 'item 1' }] -> { "1": { id: 1, name: 'item 1' } }
+ */
+declare function indexById<T extends {
+    id: PropertyKey;
+}>(items: readonly T[]): Record<string, T>;
+
+/**
+ * Русская форма множественного числа.
+ * @docs http://localization-guide.readthedocs.io/en/latest/l10n/pluralforms.html
+ * @example pluralize(1, ['штука', 'штуки', 'штук'])
+ */
+type PluralForms<T> = readonly [T, T, T];
+declare function pluralize<T>(counter: number, forms: PluralForms<T>): T;
+
+/**
+ * Возвращает объект, пригодный для React-свойства `dangerouslySetInnerHTML`.
+ *
+ * @example
+ * <div dangerouslySetInnerHTML={rawMarkup("<b>text</b>")} />
+ */
+type DangerousHTML = {
+    __html: string;
+};
+declare function rawMarkup(text: string): DangerousHTML;
+
+/**
+ * Делает первую букву строки заглавной
+ * @param str - входная строка
+ * @returns строка с первой заглавной буквой
+ */
+declare function capitalize(str: string): string;
+
+type FileLike = {
+    size: number;
+};
+/**
+ * getFilesSize — суммирует size у переданных файлов/вложений
+ * Совместимо с File/Blob (у них тоже есть поле size).
+ */
+declare function getFilesSize(attachments: ReadonlyArray<FileLike>, files: ReadonlyArray<FileLike>): number;
+
+type MimeEntry = {
+  mime: string
+  extensions: string[]
+}
+
+type MimeFiles = ReadonlyArray<MimeEntry>;
+/**
+ * Возвращает массив MIME-типов из массива файлов
+ */
+declare function getMimeTypes(files: MimeFiles): string[];
+
+/**
+ * Возвращает случайное целое число между min (включительно) и max (не включая max)
+ */
+declare function getRandomInt(min: number, max: number): number;
+
+type HasGroupId = {
+    group: {
+        id: string | number;
+    };
+};
+/**
+ * Превращает массив элементов с group.id в объект,
+ * где ключ — String(group.id), значение — сам элемент.
+ *
+ * Последний элемент с одинаковым group.id перезапишет предыдущий.
+ */
+declare function indexByGroupId<T extends HasGroupId>(items: ReadonlyArray<T>): Record<string, T>;
+
+/**
+ * Прокручивает окно к верхней границе первого элемента, соответствующего селектору.
+ * Возвращает `false`, если элемент не найден; иначе возвращает `undefined`.
+ */
+declare function scrollToElement(selector: string): false | undefined;
+
+declare const TYPES: {
+    readonly days: readonly ["день", "дня", "дней"];
+    readonly exercises: readonly ["занятие", "занятия", "занятий"];
+    readonly hours: readonly ["час", "часа", "часов"];
+    readonly members: readonly ["участник", "участника", "участников"];
+    readonly minutes: readonly ["минута", "минуты", "минут"];
+    readonly points: readonly ["балл", "балла", "баллов"];
+    readonly remains: readonly ["остался", "осталось", "осталось"];
+    readonly seconds: readonly ["секунда", "секунды", "секунд"];
+    readonly students: readonly ["ученик", "ученика", "учеников"];
+    readonly studentsParentalCase: readonly ["ученика", "учеников", "учеников"];
+    readonly tasks: readonly ["задача", "задачи", "задач"];
+};
+type PluralizeType = keyof typeof TYPES;
+/**
+ * Возвращает строку во множественном числе для заданного типа
+ *
+ * @param counter — число, по которому выбирается форма
+ * @param type — один из предопределённых ключей типов
+ */
+declare function pluralizeByType(counter: number, type: PluralizeType): string;
+
+/**
+ * Конвертирует строку base64 в ArrayBuffer.
+ */
+declare function base64ToArrayBuffer(base64: string): ArrayBuffer;
+
+/**
+ * Парсит строку-список вида:
+ * "— Преподаватель кафедры ... <br>
+ *  — Старший преподаватель ..."
+ * в массив элементов без начальных тире/дефисов и пробелов.
+ *
+ * Поддерживаемые разделители между пунктами:
+ *   - начало строки
+ *   - <br>, <br/>, <br /> (в любом регистре)
+ *   - перевод строки \n
+ *
+ * Поддерживаемые маркеры пункта:
+ *   - дефис '-' и множество вариантов тире:
+ *     U+2010..U+2015, U+FE58, U+FE63, U+FF0D
+ */
+declare function parseStringListToArray(input?: string): string[];
+
+interface SourceOption {
+    id: string | number;
+    name: string;
+    image_url?: string | null;
+}
+interface SelectOption {
+    value: string | number;
+    label: string;
+    image_url?: string | null;
+}
+/**
+ * Преобразует массив опций (например, уровней/классов) в формат для select.
+ * @example
+ * transformOptionsForSelect([{ id: 1, name: 'A', image_url: 'x.png' }])
+ * // => [{ value: 1, label: 'A', image_url: 'x.png' }]
+ */
+declare const transformOptionsForSelect: <T extends SourceOption>(options?: readonly T[]) => SelectOption[];
+
+type AnyRecord = Record<string | number | symbol, unknown>;
+/**
+ * Глубокий мерж объектов «как в оригинале»:
+ * - мутирует **target** и не мутирует **source**
+ * - если по ключу и в target, и в source лежат объекты — сливаем рекурсивно
+ * - иначе просто присваиваем ссылку из source в target
+ */
+declare function merge<T extends AnyRecord, S extends AnyRecord>(target: T, source: S): T & S;
+
+/**
+ * Определяет Internet Explorer (<=11) или старый Edge (движок EdgeHTML).
+ * @returns false, если это не IE/EdgeHTML; иначе — номер основной версии.
+ */
+declare function detectIE(ua?: string): number | false;
+
+type SerializedField = {
+    name: string;
+    value: string;
+};
+/**
+ * Сериализует поля формы аналогично jQuery.serializeArray()
+ */
+declare function serializeArray(form: unknown): SerializedField[];
+/**
+ * Возвращает внешнюю высоту элемента (offsetHeight + вертикальные отступы).
+ */
+declare function outerHeight(el: HTMLElement): number;
+/**
+ * Проверяет, полностью ли элемент находится в текущей области видимости (viewport).
+ */
+declare function isElementInViewport(el: Element): boolean;
+
+type StringMap = Record<string, string>;
+/**
+ * Преобразует ключи объекта в camelCase
+ */
+declare function toCamelCase(obj: StringMap): StringMap;
+/**
+ * Преобразует ключи объекта из camelCase в under_scored
+ */
+declare function toUnderscoredCase(obj: StringMap): StringMap;
+
+/**
+ * Разбивает массив на чанки (подмассивы) указанного размера.
+ *
+ * @param limit - Максимальный размер каждого чанка
+ * @param arr - Исходный массив
+ * @returns Массив чанков
+ */
+declare function splitEvery<T>(limit?: number, arr?: T[]): T[][];
+/**
+ * Удаляет дубликаты элементов из массива.
+ *
+ * @param arrArg - Массив для дедупликации
+ * @returns Новый массив без дубликатов
+ */
+declare function uniq<T>(arrArg: T[]): T[];
+/**
+ * Удаляет элемент массива по индексу.
+ *
+ * @param arr - Исходный массив
+ * @param index - Индекс удаляемого элемента
+ * @returns Новый массив без этого элемента
+ */
+declare function removeElFromArr<T>(arr: T[], index: number): T[];
+/**
+ * Сливает два массива объектов по общему ключу.
+ *
+ * Если объект с тем же значением ключа есть в обоих массивах,
+ * объекты объединяются, при этом свойства из `arr2` имеют приоритет.
+ *
+ * @param arr1 - Первый массив объектов
+ * @param arr2 - Второй массив объектов
+ * @param key - Ключевое поле для сравнения (по умолчанию: 'id')
+ * @returns Объединённый массив
+ */
+declare function mergeByKey<T extends Record<string, unknown>, K extends keyof T = 'id' extends keyof T ? 'id' : keyof T>(arr1?: T[], arr2?: T[], key?: K): T[];
+
+/**
+ * Функция принимает Ф.И.О, возвращает Ф.И.
+ *
+ * Примеры:
+ *  - "Иванов Иван Иванович" -> "Иван Иванов"
+ *  - "Иванов Иван" -> "Иван Иванов"
+ *  - "Иванов" -> "Иванов"
+ */
+declare const makeShortNameFromFull: (fullName?: string) => string;
+/**
+ * Извлекает все цифры из строки
+ *
+ * Если вход не строка — вернёт пустую строку.
+ */
+declare const extractDigits: (input?: unknown) => string;
+
+/** Карта ISO-кодов -> символ валюты. */
+declare const CURRENCY_DIRECTORY: {
+    readonly AFN: "؋";
+    readonly ALL: "Lek";
+    readonly ANG: "ƒ";
+    readonly ARS: "$";
+    readonly AUD: "$";
+    readonly AWG: "ƒ";
+    readonly AZN: "₼";
+    readonly BAM: "KM";
+    readonly BBD: "$";
+    readonly BGN: "лв";
+    readonly BMD: "$";
+    readonly BND: "$";
+    readonly BOB: "$b";
+    readonly BRL: "R$";
+    readonly BSD: "$";
+    readonly BWP: "P";
+    readonly BYR: "Br";
+    readonly BZD: "BZ$";
+    readonly CAD: "C$";
+    readonly CHF: "CHF";
+    readonly CLP: "$";
+    readonly CNY: "¥";
+    readonly COP: "$";
+    readonly CRC: "₡";
+    readonly CUP: "₱";
+    readonly CZK: "Kč";
+    readonly DKK: "kr";
+    readonly DOP: "RD$";
+    readonly EEK: "kr";
+    readonly EGP: "£";
+    readonly EUR: "€";
+    readonly FJD: "$";
+    readonly FKP: "£";
+    readonly FRF: "₣";
+    readonly GBP: "£";
+    readonly GGP: "£";
+    readonly GHC: "¢";
+    readonly GIP: "£";
+    readonly GTQ: "Q";
+    readonly GYD: "$";
+    readonly HKD: "$";
+    readonly HNL: "L";
+    readonly HRK: "kn";
+    readonly HUF: "Ft";
+    readonly IDR: "Rp";
+    readonly ILS: "₪";
+    readonly IMP: "£";
+    readonly INR: "₨";
+    readonly IRR: "﷼";
+    readonly ISK: "kr";
+    readonly JEP: "£";
+    readonly JMD: "J$";
+    readonly JPY: "¥";
+    readonly KGS: "KGS";
+    readonly KHR: "៛";
+    readonly KPW: "₩";
+    readonly KRW: "₩";
+    readonly KYD: "$";
+    readonly KZT: "₸";
+    readonly LAK: "₭";
+    readonly LBP: "£";
+    readonly LKR: "₨";
+    readonly LRD: "$";
+    readonly LTL: "Lt";
+    readonly LVL: "Ls";
+    readonly MKD: "ден";
+    readonly MNT: "₮";
+    readonly MUR: "₨";
+    readonly MXN: "$";
+    readonly MYR: "RM";
+    readonly MZN: "MT";
+    readonly NAD: "$";
+    readonly NGN: "₦";
+    readonly NIO: "C$";
+    readonly NOK: "kr";
+    readonly NPR: "₨";
+    readonly NZD: "$";
+    readonly OMR: "﷼";
+    readonly PAB: "B/.";
+    readonly PEN: "S/.";
+    readonly PHP: "₱";
+    readonly PKR: "₨";
+    readonly PLN: "zł";
+    readonly PYG: "Gs";
+    readonly QAR: "﷼";
+    readonly RON: "lei";
+    readonly RSD: "Дин.";
+    readonly RUR: "₽";
+    readonly SAR: "﷼";
+    readonly SBD: "$";
+    readonly SCR: "₨";
+    readonly SEK: "kr";
+    readonly SGD: "$";
+    readonly SHP: "£";
+    readonly SOS: "S";
+    readonly SRD: "$";
+    readonly SVC: "$";
+    readonly SYP: "£";
+    readonly THB: "฿";
+    readonly TRL: "₤";
+    readonly TRY: "₤";
+    readonly TTD: "TT$";
+    readonly TVD: "$";
+    readonly TWD: "NT$";
+    readonly UAH: "₴";
+    readonly USD: "$";
+    readonly UYU: "$U";
+    readonly UZS: "лв";
+    readonly VEF: "Bs";
+    readonly VND: "₫";
+    readonly XCD: "$";
+    readonly YER: "﷼";
+    readonly ZAR: "R";
+    readonly ZWD: "Z$";
+};
+/**
+ * Возвращает символ валюты по ISO-коду.
+ *
+ * Если код неизвестен — вернёт сам переданный код без изменений.
+ */
+declare function getCurrencySymbol(currencyCode: string): string;
+
+/**
+ * Регулирует яркость (осветляет/затемняет) шестнадцатеричного цвета.
+ * Принимает 3- или 6-символьный hex (с решёткой '#' или без неё).
+ */
+declare function colorLuminance(rawHex: string, lum?: number): string;
+/**
+ * Собирает linear-gradient, используя чуть более светлый и тёмный оттенки цвета.
+ * @param degree CSS-угол, например "90deg"
+ * @param color hex-строка БЕЗ '#', например "6699cc"
+ */
+declare function getGradient(degree: string, color: string): string;
+/**
+ * Детерминированный выбор цвета по строке.
+ * @param str произвольная строка
+ * @param colors массив CSS-цветов
+ * @returns один из цветов или null, если colors не передан
+ */
+declare function getColorByString(str: string, colors?: string[]): string | null;
+
+/**
+ * Хэлпер для создания строки URL адреса
+ * @example
+ * createPath('/library', { id: 1 })  // => /library?id=1
+ */
+declare function createPath(u: string, query?: Record<string, string | number | boolean | null | undefined | Array<string | number | boolean | null | undefined>>): string;
+/**
+ * Хэлпер для парсинга строки запроса (location.search)
+ * @example
+ * parseQueryString('?id=1')  // => { id: '1' }
+ */
+declare function parseQueryString(query: string): qs.ParsedQuery<string>;
+/**
+ * Извлекает URL следующей страницы из HTTP заголовка Link
+ * @example
+ * getNextPageURLFromLinkHeader("<http://x/api?page=2>; rel='next'") // => 'http://x/api?page=2'
+ */
+declare function getNextPageURLFromLinkHeader(link?: string): string;
+/**
+ * Извлекает номер следующей страницы из HTTP заголовка Link
+ * @example
+ * getNextPageFromLinkHeader("<http://x/api?page=2>; rel='next'") // => 2
+ */
+declare function getNextPageFromLinkHeader(link?: string): number | null;
+/**
+ * Генерирует query-строку из объекта
+ */
+declare function makeParamString(object?: Record<string, string | number | boolean | null | undefined>): string;
+
+declare const mimeImages: () => string[];
+declare const mimeFiles: () => string[];
+declare const mimeAudio: () => string[];
+declare const acceptFileTypes: () => string[];
+declare const acceptAllTypes: () => string[];
+declare const acceptImagesExtensions: () => string[];
+declare const acceptFilesExtensions: () => string[];
+declare const acceptAudioExtensions: () => string[];
+declare const acceptAllExtensions: () => string[];
+
+/**
+ * Оборачивает все имена полей query-строки в `wrapper[<field>]`, пропуская поля из `untouchables`.
+ *
+ * Пример:
+ *  wrapFormFields('user', 'name=Alex&age=30', ['age'])
+ *  -> 'user[name]=Alex&age=30'
+ */
+declare function wrapFormFields(wrapper: string, formFieldsString: string, untouchables?: string[]): string;
+/**
+ * Возвращает предикат, проверяющий, совпадает ли `id` объекта с `idToMatch`.
+ *
+ * Использование: arr.find(matchesId(id))
+ */
+declare const matchesId: <T extends {
+    id: unknown;
+}>(idToMatch: unknown) => (obj: T) => boolean;
+/**
+ * Минимальная форма события для детекции клавиши Enter.
+ */
+type KeyLikeEvent = {
+    which?: number;
+    keyCode?: number;
+} | Pick<KeyboardEvent, 'which' | 'keyCode'>;
+/**
+ * Определяет, была ли нажата клавиша Enter.
+ */
+declare function detectEnterKey(e: KeyLikeEvent): boolean;
+/**
+ * Собирает объект опции или возвращает `undefined`, если `value` — ложное значение.
+ * Примечание: сохраняет исходное поведение — `0`, пустая строка, false → `undefined`.
+ */
+declare function makeOption<T>(value: T, label: string): {
+    value: T;
+    label: string;
+} | undefined;
+/**
+ * Создаёт загрузчик для асинхронных опций селекта.
+ *
+ * `func(args)` должен вернуть Promise с массивом опций или null/undefined.
+ * Если возвращается Promise, разрешённый `{ options }` объединяется с `extras`.
+ * Если возвращается null/undefined, используется `{ options: defaultOptions }` (плюс `extras`).
+ *
+ * `extras` сохраняет обратную совместимость со старым распространением (spread) значений по умолчанию.
+ */
+declare function makeLoadOptionsFunc<O extends object, A = unknown>(func: (args: A) => Promise<O[]> | undefined | null, args: A, defaultOptions: O[], extras?: Record<string, unknown>): Promise<{
+    options: O[];
+} & Record<string, unknown>>;
+
+export { type AnyRecord, Collapse, type DangerousHTML, type FileLike, type HasGroupId, type MimeFiles, type PluralForms, type PluralizeType, type SelectOption, type SerializedField, type SourceOption, type StringMap, TYPES, acceptAllExtensions, acceptAllTypes, acceptAudioExtensions, acceptFileTypes, acceptFilesExtensions, acceptImagesExtensions, base64ToArrayBuffer, capitalize, colorLuminance, createPath, CURRENCY_DIRECTORY as currencyDirectory, debounce, detectEnterKey, detectIE, extractDigits, getColorByString, getCurrencySymbol, getFilesSize, getGradient, getMimeTypes, getNextPageFromLinkHeader, getNextPageURLFromLinkHeader, getRandomInt, indexByGroupId, indexById, isElementInViewport, makeLoadOptionsFunc, makeOption, makeParamString, makeShortNameFromFull, matchesId, merge, mergeByKey, mimeAudio, mimeFiles, mimeImages, outerHeight, parseQueryString, parseStringListToArray, pickBy, pluralize, pluralizeByType, qid, rawMarkup, removeElFromArr, scrollToElement, serializeArray, splitEvery, toCamelCase, toUnderscoredCase, transformOptionsForSelect, uniq, uuid, wrapFormFields };