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

<Meta title='@dxtmisha/ru/functional-basic/Classes/ApiPreparation - Подготовка запросов API'/>

# Класс ApiPreparation

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

> `ApiPreparation` является **вспомогательным классом**, предназначенным для управления жизненным циклом запросов. В большинстве случаев рекомендуется взаимодействовать с хуками через методы `setPreparation` и `setEnd` основного инстанса `Api`.

## Ключевые особенности

- **Последовательное выполнение** — гарантирует, что хуки подготовки выполняются по одному, предотвращая коллизии при параллельных операциях (например, дублирование запросов на обновление токена).
- **Глобальный перехват** — предоставляет единую точку входа и выхода для всего сетевого трафика, инициируемого родительским менеджером.
- **Повтор запроса** — хуки после запроса могут сигнализировать системе о необходимости автоматического повтора запроса после изменения состояния.

## Методы

### Действие

#### `make`

Выполняет зарегистрированный коллбэк подготовки. Если другая подготовка уже выполняется, метод ожидает её завершения.

**Параметры:**
- `active: boolean` — Активен ли хук для текущего запроса.
- `apiFetch: ApiFetch` — Конфигурация предстоящего запроса.

**Возвращает:** `Promise<void>`

#### `makeEnd`

Выполняет зарегистрированный коллбэк анализа после завершения запроса.

**Параметры:**
- `active: boolean` — Активен ли хук для текущего запроса.
- `query: Response` — Нативный объект ответа Fetch API.
- `apiFetch: ApiFetch` — Конфигурация, использованная для запроса.

**Возвращает:** `Promise<ApiPreparationEnd>` — Объект, управляющий дальнейшими шагами (например, сброс или подмена данных).

### Конфигурация

- `set(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Регистрирует функцию для запуска перед каждым включенным запросом.
- `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Регистрирует функцию для запуска после каждого включенного ответа.

## Типы

#### `ApiPreparationEnd`
Результат выполнения хука анализа.
- `reset?: boolean` — Если true, запрос будет прерван и перезапущен.
- `data?: any` — Произвольные данные.

## Руководство: Механика хуков

Следующие правила и условия определяют, как система подготовки синхронизирует и управляет хуками жизненного цикла:

- **Синхронизация** — система использует механизм опроса (интервал 160 мс), чтобы гарантировать, что одновременно выполняется только один хук `setPreparation`. Если одновременно запускаются несколько запросов, последующие вызовы будут ждать до 32 попыток опроса (~5 секунд), пока первый не завершится.
- **Инъекция контекста** — объект `apiFetch` передается в хук по ссылке. Изменение его свойств (таких как заголовки или тело запроса) внутри `setPreparation` напрямую влияет на последующий сетевой вызов.
- **Управление потоком (Reset)** — хук `setEnd` может вернуть `{ reset: true }`. Когда этот флаг обнаружен, `ApiInstance` прервет текущую цепочку запроса и немедленно перезапустит её с фазы подготовки. Это в основном используется для прозрачного автоматического обновления токенов.
- **Область выполнения** — хуки запускаются только в том случае, если они явно включены в конфигурации запроса. По умолчанию `globalPreparation` и `globalEnd` в `ApiFetch` установлены в true.
