import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/functional/! О библиотеке'/>

# [@dxtmisha/functional](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional)

`@dxtmisha/functional` — это библиотека утилит, базовых классов и composables для сложной веб-разработки на Vue 3. 

Современные фронтенд-приложения требуют управления десятками асинхронных процессов: получением данных по API, синхронизацией вкладок, работой с локальными хранилищами, форматированием дат и адаптацией под локаль пользователя. Часто разработчики решают эти задачи локально внутри компонентов, что приводит к дублированию кода, "разбуханию" файлов `.vue` и ошибкам при очистке подписок или таймеров. Пакет работает на базе [@dxtmisha/functional-basic](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional) и предоставляет реактивные обертки и архитектурные решения, специально созданные для решения этих проблем в экосистеме Vue (Composition API).

## Установка

```bash
npm i @dxtmisha/functional
```

## Зачем нужна эта библиотека?

Основная идея пакета — вынести типовую бизнес-логику и работу с побочными эффектами за пределы компонентов, сделав этот процесс строго типизированным и реактивным по умолчанию.

Вам больше не нужно вручную синхронизировать HTTP-запросы с локальным состоянием экрана, писать обертки для реактивного кеширования данных или изобретать решения для работы с LocalStorage внутри компонентов. Библиотека предоставляет готовые реактивные абстракции, которые берут эту работу на себя. Вы просто вызываете нужный composable или класс, а под капотом библиотека сама управляет реактивными ссылками (`ref`), следит за жизненным циклом Vue, очищает сборщики мусора при размонтировании компонента и сохраняет строгую типизацию TypeScript. 

## Особенности и подход к разработке

**Полная интеграция с Composition API**
Каждая утилита в библиотеке спроектирована с учетом работы реактивности Vue 3. Данные из хранилищ, ответы от API или системная локаль всегда возвращаются в виде реактивных объектов. Если конфигурация меняется, все зависящие от нее компоненты обновляются автоматически.

**Архитектурное разделение (Separation of Concerns)**
Пакет идеологически подталкивает разработчика писать "тонкие" компоненты. Вся логика валидации, управления сложными состояниями (`loading`, `error`, `success`), подготовки данных и кеширования вынесена в специализированные классы и composables. В `.vue` файле остается только декларативная привязка переменных к шаблону.

**Безопасность типов**
Благодаря мощным TypeScript-интерфейсам, пакет обеспечивает 100% покрытие типов между API, хранилищами и UI. Дженерики и умное выведение типов защищают от опечаток и ошибок рефакторинга. IDE всегда знает, какие поля вернул запрос и какие методы можно вызвать у класса.

**Предсказуемое управление ресурсами**
Библиотека берет на себя безопасное управление подписками и освобождение памяти. Если компонент, вызвавший запрос к API или слушающий глобальное событие, был уничтожен (unmounted), связанные с ним задачи и watcher-ы будут корректно завершены, предотвращая утечки памяти в приложении.

## Что она умеет?

Библиотека закрывает все ключевые потребности при разработке сложного фронтенда:

**Сетевые запросы (API)** 
Набор composables (`useApiGet`, `useApiPost`, `useApiPut`, `useApiDelete`, `useApiRequest`), инкапсулирующих логику работы с сервером. При вызове они возвращают объект со встроенными полями: текущим состоянием загрузки (`loading`), зафиксированными ошибками и полученными данными (`item`, `list`). Они из коробки умеют кешировать ответы, автоматически отменять устаревшие предыдущие запросы (особенно важно для живого поиска) и легко настраиваются через заголовки.

**Хранилища состояния** 
Реактивные хуки `useStorageRef`, `useSessionRef`, `useCookieRef` и `useHashRef`. Позволяют напрямую привязать реактивную переменную к LocalStorage, SessionStorage, URL-хешу или cookie-файлу. Вы просто работаете с этой переменной как с обычным `ref` в коде, а библиотека сама синхронизирует ее с постоянным хранилищем браузера, моментально распространяя изменения даже на другие открытые вкладки пользователя.

**Интернационализация и форматирование** 
Инструменты `useTranslateRef`, `useGeoIntlRef`, `DatetimeRef` и `GeoFlagRef` — это функции, которые на лету реагируют на изменение параметров среды (смена языка, выбор другой валюты или региона). Они автоматически перестраивают форматы дат, адаптируют валюты и переводят тексты. Обновление компонентов происходит самостоятельно, без написания дополнительных слушателей событий.

**Инженерия UI-компонентов**
Система базовых классов `DesignAbstract`, `DesignComp`, `DesignChanged`, `DesignAsyncAbstract`. Позволяет разработчикам инкапсулировать внутреннюю логику нестандартных UI-элементов (кастомные селекторы, сложные формы, модальные окна со стейтами) в независимые классы. Это делает бизнес-логику отделяемой от верстки, легкой для тестирования и позволяет переиспользовать функционал в других проектах.

**Вспомогательные утилиты**
Пакет включает множество точечных реактивных решений:
- `useMeta` для реактивного манипулирования SEO-тегами в зависимости от состояния страницы;
- `useBroadcastValueRef` для установки канала обмена данными между окнами браузера в реальном времени;
- `useLoadingRef` для централизованного контроля за индикаторами загрузки;
- Функции `computedAsync` и `toComputed` для элегантного выполнения асинхронных операций внутри Vue 3.

## Для кого это?

Пакет предназначен для разработчиков, строящих многостраничные бизнес-приложения, сложные панели управления (dashboards) или собственные UI-фреймворки на технологиях Vue 3. Он радикально сокращает количество шаблонного (boilerplate) кода, предлагая взамен проверенные и безопасные паттерны разработки.

## Git

[https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional)
