@foxford/foxford-utils 1.0.1 → 1.1.0

package/index.js.flow

@@ -0,0 +1,654 @@
+
+/**
+ * Генерирует уникальный идентификатор (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: { [key: string]: mixed, ... }>(
+  obj: T,
+  filterFunc: (
+    key: { ...$Keys<T>, ...string },
+    value: $ElementType<T, $Keys<T>>
+  ) => boolean
+): $Rest<T, { ... }>;
+declare type ToggleEventLike = {
+  currentTarget: EventTarget | null,
+  ...
+};
+declare class Collapse {
+  onClickHandler: (e: ToggleEventLike) => boolean;
+  constructor(): this;
+  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: (...args: any[]) => any>(
+  f: T,
+  ms: number
+): (
+  ...args: $ReadOnlyArray<mixed>
+) => $Call<<R>((...args: any[]) => R) => R, typeof setTimeout>;
+
+/**
+ * Преобразует массив элементов в объект, где ключ — строковый id элемента.
+ *
+ * Пример:
+ *   [{ id: 1, name: 'item 1' }] -> { "1": { id: 1, name: 'item 1' } }
+ */
+declare function indexById<
+  T: {
+    id: string | number | symbol,
+    ...
+  }
+>(
+  items: $ReadOnlyArray<T>
+): { [key: string]: T, ... };
+
+/**
+ * Русская форма множественного числа.
+ * @docs http://localization-guide.readthedocs.io/en/latest/l10n/pluralforms.html
+ * @example pluralize(1, ['штука', 'штуки', 'штук'])
+ */
+declare type PluralForms<T> = [T, T, T];
+declare function pluralize<T>(counter: number, forms: PluralForms<T>): T;
+
+/**
+ * Возвращает объект, пригодный для React-свойства `dangerouslySetInnerHTML`.
+ * @example <div dangerouslySetInnerHTML={rawMarkup("<b>text</b>")} />
+ */
+declare type DangerousHTML = {
+  __html: string,
+  ...
+};
+declare function rawMarkup(text: string): DangerousHTML;
+
+/**
+ * Делает первую букву строки заглавной
+ * @param str - входная строка
+ * @returns строка с первой заглавной буквой
+ */
+declare function capitalize(str: string): string;
+declare type FileLike = {
+  size: number,
+  ...
+};
+/**
+ * getFilesSize — суммирует size у переданных файлов/вложений
+ * Совместимо с File/Blob (у них тоже есть поле size).
+ */
+declare function getFilesSize(
+  attachments: $ReadOnlyArray<FileLike>,
+  files: $ReadOnlyArray<FileLike>
+): number;
+declare type MimeEntry = {
+  mime: string,
+  extensions: string[],
+  ...
+};
+declare type MimeFiles = $ReadOnlyArray<MimeEntry>;
+/**
+ * Возвращает массив MIME-типов из массива файлов
+ */
+declare function getMimeTypes(files: MimeFiles): string[];
+
+/**
+ * Возвращает случайное целое число между min (включительно) и max (не включая max)
+ */
+declare function getRandomInt(min: number, max: number): number;
+declare type HasGroupId = {
+  group: {
+    id: string | number,
+    ...
+  },
+  ...
+};
+/**
+ * Превращает массив элементов с group.id в объект,
+ * где ключ — String(group.id), значение — сам элемент.
+ *
+ * Последний элемент с одинаковым group.id перезапишет предыдущий.
+ */
+declare function indexByGroupId<T: HasGroupId>(items: $ReadOnlyArray<T>): {
+  [key: string]: T,
+  ...
+};
+
+/**
+ * Прокручивает окно к верхней границе первого элемента, соответствующего селектору.
+ * Возвращает `false`, если элемент не найден; иначе возвращает `undefined`.
+ */
+declare function scrollToElement(selector: string): false | void;
+declare var TYPES: {
+  +days: ["день", "дня", "дней"],
+  +exercises: ["занятие", "занятия", "занятий"],
+  +hours: ["час", "часа", "часов"],
+  +members: ["участник", "участника", "участников"],
+  +minutes: ["минута", "минуты", "минут"],
+  +points: ["балл", "балла", "баллов"],
+  +remains: ["остался", "осталось", "осталось"],
+  +seconds: ["секунда", "секунды", "секунд"],
+  +students: ["ученик", "ученика", "учеников"],
+  +studentsParentalCase: ["ученика", "учеников", "учеников"],
+  +tasks: ["задача", "задачи", "задач"],
+  ...
+};
+declare type PluralizeType = $Keys<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[];
+declare interface SourceOption {
+  id: string | number;
+  name: string;
+  image_url?: string | null;
+}
+declare 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 var transformOptionsForSelect: <T: SourceOption>(
+  options?: $ReadOnlyArray<T>
+) => SelectOption[];
+declare type AnyRecord = { [key: string | number | Symbol]: mixed, ... };
+/**
+ * Глубокий мерж объектов «как в оригинале»:
+ * - мутирует **target** и не мутирует **source**
+ * - если по ключу и в target, и в source лежат объекты — сливаем рекурсивно
+ * - иначе просто присваиваем ссылку из source в target
+ */
+declare function merge<T: AnyRecord, S: AnyRecord>(
+  target: T,
+  source: S
+): { ...T, ...S };
+
+/**
+ * Определяет Internet Explorer (<=11) или старый Edge (движок EdgeHTML).
+ * @returns false, если это не IE/EdgeHTML; иначе — номер основной версии.
+ */
+declare function detectIE(ua?: string): number | false;
+declare type SerializedField = {
+  name: string,
+  value: string,
+  ...
+};
+/**
+ * Сериализует поля формы аналогично jQuery.serializeArray()
+ */
+declare function serializeArray(form: mixed): SerializedField[];
+
+/**
+ * Возвращает внешнюю высоту элемента (offsetHeight + вертикальные отступы).
+ */
+declare function outerHeight(el: HTMLElement): number;
+
+/**
+ * Проверяет, полностью ли элемент находится в текущей области видимости (viewport).
+ */
+declare function isElementInViewport(el: Element): boolean;
+declare type StringMap = { [key: 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: { [key: string]: mixed, ... }, K: $Keys<T>>(
+  arr1?: T[],
+  arr2?: T[],
+  key?: K
+): T[];
+
+/**
+ * Функция принимает Ф.И.О, возвращает Ф.И.
+ *
+ * Примеры:
+ *  - "Иванов Иван Иванович" -> "Иван Иванов"
+ *  - "Иванов Иван" -> "Иван Иванов"
+ *  - "Иванов" -> "Иванов"
+ */
+declare var makeShortNameFromFull: (fullName?: string) => string;
+/**
+ * Извлекает все цифры из строки
+ *
+ * Если вход не строка — вернёт пустую строку.
+ */
+declare var extractDigits: (input?: mixed) => string;
+/**
+ * Карта ISO-кодов -> символ валюты.
+ */
+declare var CURRENCY_DIRECTORY: {
+  +AFN: "؋",
+  +ALL: "Lek",
+  +ANG: "ƒ",
+  +ARS: "$",
+  +AUD: "$",
+  +AWG: "ƒ",
+  +AZN: "₼",
+  +BAM: "KM",
+  +BBD: "$",
+  +BGN: "лв",
+  +BMD: "$",
+  +BND: "$",
+  +BOB: "$b",
+  +BRL: "R$",
+  +BSD: "$",
+  +BWP: "P",
+  +BYR: "Br",
+  +BZD: "BZ$",
+  +CAD: "C$",
+  +CHF: "CHF",
+  +CLP: "$",
+  +CNY: "¥",
+  +COP: "$",
+  +CRC: "₡",
+  +CUP: "₱",
+  +CZK: "Kč",
+  +DKK: "kr",
+  +DOP: "RD$",
+  +EEK: "kr",
+  +EGP: "£",
+  +EUR: "€",
+  +FJD: "$",
+  +FKP: "£",
+  +FRF: "₣",
+  +GBP: "£",
+  +GGP: "£",
+  +GHC: "¢",
+  +GIP: "£",
+  +GTQ: "Q",
+  +GYD: "$",
+  +HKD: "$",
+  +HNL: "L",
+  +HRK: "kn",
+  +HUF: "Ft",
+  +IDR: "Rp",
+  +ILS: "₪",
+  +IMP: "£",
+  +INR: "₨",
+  +IRR: "﷼",
+  +ISK: "kr",
+  +JEP: "£",
+  +JMD: "J$",
+  +JPY: "¥",
+  +KGS: "KGS",
+  +KHR: "៛",
+  +KPW: "₩",
+  +KRW: "₩",
+  +KYD: "$",
+  +KZT: "₸",
+  +LAK: "₭",
+  +LBP: "£",
+  +LKR: "₨",
+  +LRD: "$",
+  +LTL: "Lt",
+  +LVL: "Ls",
+  +MKD: "ден",
+  +MNT: "₮",
+  +MUR: "₨",
+  +MXN: "$",
+  +MYR: "RM",
+  +MZN: "MT",
+  +NAD: "$",
+  +NGN: "₦",
+  +NIO: "C$",
+  +NOK: "kr",
+  +NPR: "₨",
+  +NZD: "$",
+  +OMR: "﷼",
+  +PAB: "B/.",
+  +PEN: "S/.",
+  +PHP: "₱",
+  +PKR: "₨",
+  +PLN: "zł",
+  +PYG: "Gs",
+  +QAR: "﷼",
+  +RON: "lei",
+  +RSD: "Дин.",
+  +RUR: "₽",
+  +SAR: "﷼",
+  +SBD: "$",
+  +SCR: "₨",
+  +SEK: "kr",
+  +SGD: "$",
+  +SHP: "£",
+  +SOS: "S",
+  +SRD: "$",
+  +SVC: "$",
+  +SYP: "£",
+  +THB: "฿",
+  +TRL: "₤",
+  +TRY: "₤",
+  +TTD: "TT$",
+  +TVD: "$",
+  +TWD: "NT$",
+  +UAH: "₴",
+  +USD: "$",
+  +UYU: "$U",
+  +UZS: "лв",
+  +VEF: "Bs",
+  +VND: "₫",
+  +XCD: "$",
+  +YER: "﷼",
+  +ZAR: "R",
+  +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?: {
+    [key: string]:
+      | string
+      | number
+      | boolean
+      | null
+      | void
+      | Array<string | number | boolean | null | void>,
+    ...
+  }
+): string;
+
+/**
+ * Хэлпер для парсинга строки запроса (location.search)
+ * @example parseQueryString('?id=1')  // => { id: '1' }
+ */
+declare function parseQueryString(query: string): { [string]: string | $ReadOnlyArray<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?: {
+  [key: string]: string | number | boolean | null | void,
+  ...
+}): string;
+declare var mimeImages: () => string[];
+declare var mimeFiles: () => string[];
+declare var mimeAudio: () => string[];
+declare var acceptFileTypes: () => string[];
+declare var acceptAllTypes: () => string[];
+declare var acceptImagesExtensions: () => string[];
+declare var acceptFilesExtensions: () => string[];
+declare var acceptAudioExtensions: () => string[];
+declare var 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 var matchesId: <
+  T: {
+    id: mixed,
+    ...
+  }
+>(
+  idToMatch: mixed
+) => (obj: T) => boolean;
+/**
+ * Минимальная форма события для детекции клавиши Enter.
+ */
+declare type KeyLikeEvent =
+  | {
+      which?: number,
+      keyCode?: number,
+      ...
+    }
+  | { which?: number, keyCode?: number, ... };
+/**
+ * Определяет, была ли нажата клавиша Enter.
+ */
+declare function detectEnterKey(e: KeyLikeEvent): boolean;
+
+/**
+ * Собирает объект опции или возвращает `undefined`, если `value` — ложное значение.
+ * Примечание: сохраняет исходное поведение — `0`, пустая строка, false → `undefined`.
+ */
+declare function makeOption<T>(
+  value: T,
+  label: string
+): {
+  value: T,
+  label: string,
+  ...
+} | void;
+
+/**
+ * Создаёт загрузчик для асинхронных опций селекта.
+ *
+ * `func(args)` должен вернуть Promise с массивом опций или null/undefined.
+ * Если возвращается Promise, разрешённый `{ options }` объединяется с `extras`.
+ * Если возвращается null/undefined, используется `{ options: defaultOptions }` (плюс `extras`).
+ *
+ * `extras` сохраняет обратную совместимость со старым распространением (spread) значений по умолчанию.
+ */
+declare function makeLoadOptionsFunc<O: { [key: string]: any }, A>(
+  func: (args: A) => Promise<O[]> | void | null,
+  args: A,
+  defaultOptions: O[],
+  extras?: { [key: string]: mixed, ... }
+): Promise<{
+  ...{
+    options: O[],
+    ...
+  },
+  ...{ [key: string]: mixed, ... },
+}>;
+export type {
+  AnyRecord,
+  DangerousHTML,
+  FileLike,
+  HasGroupId,
+  MimeFiles,
+  PluralForms,
+  PluralizeType,
+  SelectOption,
+  SerializedField,
+  SourceOption,
+  StringMap,
+};
+declare export {
+  Collapse,
+  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,
+};