@foxford/foxford-utils 1.0.1 → 1.1.0

package/README.mdx

@@ -0,0 +1,318 @@
+# Foxford Javascript Utils @foxford/foxford-utils
+
+> Набор типизированных утилит, используемых в проектах Фоксфорда. Пакет совместим с **TypeScript** и **Flow** (через `.js.flow`-прокладки).
+> Перенесено с https://github.com/netology-group/foxford-utils-js
+
+## Быстрый старт
+
+```bash
+pnpm add @foxford/foxford-utils
+# или
+npm i @foxford/foxford-utils
+```
+
+ESM:
+
+```ts
+import { qid, pluralize } from '@foxford/foxford-utils'
+```
+
+CJS:
+
+```js
+const { qid, pluralize } = require('@foxford/foxford-utils')
+```
+
+> Пакет публикует ESM и CJS билды, типы `.d.ts`, а также Flow-стабы `.js.flow`.
+
+---
+
+## Содержание
+
+* [Архитектура и билды](#архитектура-и-билды)
+* [Соглашения по коду](#соглашения-по-коду)
+* [Справочник утилит (API Reference)](#справочник-утилит-api-reference)
+
+* [ID/строки](#idстроки)
+* [URL/формы/DOM](#urlформыdom)
+* [Коллекции/объекты](#коллекцииобъекты)
+* [Строки и форматирование](#строки-и-форматирование)
+* [Цвета и градиенты](#цвета-и-градиенты)
+* [Медиатипы/файлы](#медиатипыфайлы)
+* [Разное](#разное)
+* [Совместимость с Flow](#совместимость-с-flow)
+* [Тестирование](#тестирование)
+* [Вклад и релизы](#вклад-и-релизы)
+
+---
+
+## Архитектура и билды
+
+* Монорепо: **Nx** + **pnpm workspaces**.
+* Бандлер: **tsup** (esbuild) → выводит `dist/` с `cjs` и `esm`.
+* Типы: из `*.ts` генерятся `.d.ts`. Для Flow публикуются `.js.flow`.
+* Стили кода: **TypeScript**, **ESLint**, **Prettier**.
+
+Скрипты (пример):
+
+```json
+{
+  "build": "tsup src/index.ts --dts --format cjs,esm",
+  "dev": "tsup --watch",
+  "typecheck": "tsc -p tsconfig.build.json",
+  "test": "vitest"
+}
+```
+
+---
+
+## Соглашения по коду
+
+* Все публичные API имеют TS-типизацию.
+* Функции **не мутируют** входные данные, если не указано обратное.
+* Утилиты маленькие и одноцелевые, покрыты тестами (vitest).
+
+---
+
+## Справочник утилит (API Reference)
+
+### ID/строки
+
+#### `qid(length?: number = 6, number?: boolean = true): string`
+
+Генерирует короткий человекочитаемый ID.
+
+```ts
+import { qid } from '@foxford/foxford-utils'
+const id = qid(8) // "aZ9fK3Lm"
+```
+
+#### `uuid(): string`
+
+Простой UUID-подобный идентификатор (группированный hex).
+
+```ts
+import { uuid } from '@foxford/foxford-utils'
+uuid() // "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+```
+
+### URL/формы/DOM
+
+#### `createPath(url: string, query?: Record<string, unknown>): string`
+
+Строит путь с query-строкой, аккуратно работает с `#hash` и уже существующим `?query`.
+
+```ts
+createPath('/library#top', { id: 1 }) // "/library?id=1#top"
+```
+
+#### `serializeArray(form: HTMLFormElement): Array<{ name: string; value: string }>`
+
+Поведение, близкое к `jQuery.serializeArray()`.
+
+> Из защищённого JS окружения проверяйте, что передан DOM-элемент формы.
+
+```ts
+if (form && typeof form === 'object' && (form as any).nodeName === 'FORM') {
+  const fields = serializeArray(form)
+}
+```
+
+#### `wrapFormFields(wrapper: string, formFieldsString: string, untouchables?: string[]): string`
+
+Оборачивает имена полей формы: `a=1&b=2` → `user[a]=1&user[b]=2`, кроме исключений.
+
+#### `matchesId<T extends { id: string | number }>(idToMatch: T['id']): (x: T) => boolean`
+
+Хелпер для `.find()`/`.some()`.
+
+```ts
+arr.find(matchesId(42))
+```
+
+#### `scrollToElement(selector: string): boolean | void`
+
+Скроллит окно к DOM-элементу. Возвращает `false`, если элемент не найден.
+
+#### `rawMarkup(text: string): { __html: string }`
+
+Удобно для `dangerouslySetInnerHTML` в React.
+
+```tsx
+<div dangerouslySetInnerHTML={rawMarkup('<b>text</b>')} />
+```
+
+### Коллекции/объекты
+
+#### `indexById<T extends { id: string | number }>(items: T[]): Record<string, T>`
+
+Индексирует массив по `id`.
+
+#### `indexByGroupId<T extends { group: { id: string | number } }>(items: T[]): Record<string, T>`
+
+Индексирует по `group.id`.
+
+#### `pickBy<T extends object>(obj: T, filter: (key: keyof T, value: T[keyof T]) => boolean): Partial<T>`
+
+Фильтрует пары ключ/значение по предикату.
+
+#### `merge<T extends object, S extends object>(target: T, source: S): T & S`
+
+**Глубокий** мерж **с мутацией `target` и без мутации `source`**. Совмещает объекты рекурсивно.
+
+```ts
+const out = merge({ a: { x: 1 } }, { a: { y: 2 } }) // { a: { x:1, y:2 } }
+```
+
+### Строки и форматирование
+
+#### `makeShortNameFromFull(fullName?: string): string`
+
+Из `Ф.И.О` делает короткую форму `И.О` (учитывает 2/3 части).
+
+#### `extractDigits(str?: string): string`
+
+Извлекает только цифры из строки.
+
+#### `toCamelCase(obj: Record<string, string>): Record<string, string>`
+
+Конвертирует ключи `snake_case` → `camelCase`.
+
+#### `toUnderscoredCase(obj: Record<string, string>): Record<string, string>`
+
+Конвертирует ключи `camelCase` → `snake_case`.
+
+#### `capitalize(str: string): string`
+
+Делает первую букву заглавной (безопасно для пустых строк).
+
+#### `parseStringListToArray(input?: string): string[]`
+
+Парсит маркированный строковый список (разделители `-`, `—`, `<br>`, `\n`) в массив.
+
+#### `pluralize<N extends number, F extends readonly [string, string, string]>(n: N, forms: F): string`
+
+Русские правила множественного числа.
+
+```ts
+pluralize(1, ['штука', 'штуки', 'штук']) // "штука"
+pluralize(2, ['штука', 'штуки', 'штук']) // "штуки"
+pluralize(5, ['штука', 'штуки', 'штук']) // "штук"
+```
+
+#### `presetPlural(type: 'tasks' | 'exercises' | 'members' | 'hours' | 'seconds' | 'minutes' | 'remains' | 'days' | 'points' | 'students' | 'studentsParentalCase', n: number): string`
+
+Готовые пресеты словоформ на базе `pluralize`.
+
+### Цвета и градиенты
+
+#### `colorLuminance(hex: string, lum?: number): string`
+
+Корректирует яркость hex-цвета (`lum` от -1 до 1).
+
+#### `getGradient(degree: string | number, color: string): string`
+
+Возвращает CSS `linear-gradient` с чуть осветлённой/затемнённой парой одного цвета.
+
+```ts
+getGradient('90deg', '3366ff') // "linear-gradient(90deg, #3a70ff, #2d5ce5)"
+```
+
+### Медиатипы/файлы
+
+#### `getMimeTypes(files: Array<{ extensions: string[]; mime: string }>): string[]`
+
+Извлекает список `mime`.
+
+#### Наборы mime/accept/расширений
+
+```ts
+mimeImages(): string[]
+mimeFiles(): string[]
+mimeAudio(): string[]
+acceptFileTypes(): string[] // images + files
+acceptAllTypes(): string[] // images + files + audio
+acceptImagesExtensions(): string[]
+acceptFilesExtensions(): string[]
+acceptAudioExtensions(): string[]
+```
+
+#### `getFilesSize(attachments: Array<{ size: number }>, files: Array<{ size: number }>): number`
+
+Суммарный размер файлов в байтах.
+
+#### `CURRENCY_DIRECTORY: Record<string, string>`
+
+Соответствие валют → символы/буквы.
+
+### Разное
+
+#### `transformOptionsForSelect<T extends { id: string | number; name: string; image_url?: string }>(options: T[]): Array<{ value: T['id']; label: string; image_url?: string }>`
+
+Готовит данные для `<select>`.
+
+#### `getRandomInt(min: number, max: number): number`
+
+Случайное целое в `[min, max)`.
+
+#### `debounce<T extends (...args: any[]) => any>(fn: T, ms: number): (...args: Parameters<T>) => void`
+
+Декоратор debounce. Сохраняет `this` и аргументы.
+
+---
+
+## Совместимость с Flow
+
+* Для каждого публичного модуля публикуется `.js.flow` с декларациями, чтобы потребители на Flow получали типы «из коробки».
+* При добавлении новой утилиты: создайте `index.ts`, экспортируйте типы; добавьте одноимённый `index.js.flow` с совместимыми аннотациями.
+
+Шаблон `.js.flow`:
+
+```js
+// @flow
+export function qid(length?: number, number?: boolean): string
+```
+
+---
+
+## Тестирование
+
+* Фреймворк: **Vitest**.
+* Покрываем граничные случаи: пустые строки, `null/undefined`, экзотические Unicode (`\u2014` и т.п.), DOM-эмуляция через **jsdom**.
+
+Запуск:
+
+```bash
+pnpm test
+```
+
+Пример теста:
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { pluralize } from '@foxford/foxford-utils'
+
+describe('pluralize', () => {
+  it('ru forms', () => {
+    expect(pluralize(1, ['штука', 'штуки', 'штук'])).toBe('штука')
+    expect(pluralize(2, ['штука', 'штуки', 'штук'])).toBe('штуки')
+    expect(pluralize(5, ['штука', 'штуки', 'штук'])).toBe('штук')
+  })
+})
+```
+
+---
+
+## Вклад и релизы
+
+1. Форк/ветка от `main`.
+2. Добавьте утилиту в `src/`, экспорт в `src/index.ts`.
+3. Напишите тесты (`vitest`), запустите `pnpm typecheck` и `pnpm test`.
+4. Обновите этот `README.mdx` (раздел API).
+5. Повысьте версию по semver, создайте changelog.
+
+---
+
+## Лицензия
+
+MIT © Фоксфорд