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

<Meta title='@dxtmisha/ru/functional-basic/Classes/ApiResponse - Эмуляция ответов API'/>

# Класс ApiResponse

Класс-менеджер для перехвата, кэширования и эмуляции ответов API. Он позволяет перехватывать исходящие API-запросы и возвращать предопределенные мок-данные вместо выполнения реального сетевого трафика.

> `ApiResponse` является **вспомогательным классом**, предназначенным для эмуляции и мокирования API. В большинстве случаев рекомендуется регистрировать мок-ответы через параметр `response` в глобальной конфигурации `Api`.

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

- **Перехват запросов** — интеллектуально сопоставляет исходящие запросы на основе пути, HTTP-метода и объекта данных.
- **Динамические возможности** — поддерживает как статические объекты, так и выполнение динамических функций-коллбэков для обработки контекста запроса.
- **Симуляция задержки сети** — встроенная система для имитации сетевых задержек с помощью рандомизированных таймеров.
- **Режим разработчика** — выводит полезную отладочную информацию в консоль браузера, показывая, какие данные сопоставились с конкретным моком.

## Инициализация

Для инициализации объекта вызовите конструктор `ApiResponse(requestDefault)`.

**Параметры:**
- `requestDefault: ApiDefault` — класс запросов по умолчанию, используемый для конфигурации и хранения.

```typescript
import { ApiResponse } from '@dxtmisha/functional-basic'

const apiResponse = new ApiResponse(myApiDefault)
```

## Методы

### Действие

#### `emulator`

Основной цикл движка, который проверяет конфигурации запросов и выполняет соответствующие эмулированные ответы. Этот метод работает только в среде DOM.

**Параметры:**
- `apiFetch: ApiFetch` — Свойства запроса для эмуляции.

**Возвращает:** `Promise<T | undefined>` — Данные эмулированного ответа.

#### `emulatorAsync`

Синхронная версия эмулятора. Возвращает мок-ответ немедленно, без задержек и состояния загрузки. Этот метод работает только в среде DOM.

**Параметры:**
- `apiFetch: ApiFetch` — Свойства запроса для эмуляции.

**Возвращает:** `T | undefined` — Данные эмулированного ответа.

### Проверка

- `get(path: string, method: ApiMethod, request?: ApiFetch['request'], devMode?: boolean): ApiResponseItem | undefined` — Синхронно проверяет наличие подходящего мок-запроса в кэше.
- `getList(): (ApiResponseItem & Record<string, any>)[]` — Возвращает список всех зарегистрированных конфигураций эмулятора.

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

- `add(response: ApiResponseItem | ApiResponseItem[]): this` — Добавляет объекты мок-ответов в локальный реестр.
- `setDevMode(devMode: boolean): this` — Включает или выключает режим отладочного вывода в консоль.

## Типы

#### `ApiResponseItem`
Объект, определяющий конфигурацию мок-ответа.
- `path: string | RegExp` — Путь или шаблон URL.
- `method: ApiMethod` — HTTP-метод (GET, POST и т.д.).
- `response: any | ((request?: any) => any)` — Данные мока или функция для их генерации.
- `request?: ApiFetch['request'] | '*any'` — Опциональные данные запроса для сопоставления.
- `lag?: boolean` — Нужно ли имитировать задержку сети.
- `disable?: any` — Условие для отключения мока (boolean или функция).
- `isForGlobal?: boolean` — Пометить как глобальный мок (скрыт из getList).

## Руководство: Эмуляция API

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

- **Регистрация моков** — ответы, добавленные через `add()`, имеют приоритет и проверяются перед выполнением любого реального сетевого вызова.
- **Критерии сопоставления** — мок срабатывает только в том случае, если путь (строка или RegExp), HTTP-метод и тело запроса полностью соответствуют конфигурации.
- **Wildcard для тела** — использование значения `*any` для запроса позволяет моку соответствовать любой полезной нагрузке, пропуская глубокое сравнение объектов.
- **Динамические данные** — свойство `response` может быть функцией, что позволяет генерировать динамические данные мока на основе входящих параметров запроса.
- **Симуляция задержки** — установка `lag: true` добавляет случайную задержку (0–2000 мс) и активирует общее состояние загрузки (класс `d-response-loading` на body).
- **Повторные срабатывания** — по умолчанию конфигурация эмулятора срабатывает только один раз, если не включен `devMode`, что предотвращает дублирование моков для одного и того же состояния.
