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

<Meta title='@dxtmisha/en/functional-basic/Classes/ApiPreparation - API Request Preparation'/>

# ApiPreparation Class

A specialized class designed to handle tasks and side effects immediately before and after an API request execution. It serves to intercept requests globally via tracking hooks, enabling state manipulation or triggering of global logic like token refreshes or logging.

> `ApiPreparation` is an **auxiliary class**, designed for managing request lifecycles. In most cases, it is recommended to interact with hooks through the `setPreparation` and `setEnd` methods of the main `Api` instance.

## Key Features

- **Sequential Execution** — ensures that preparation hooks resolve one at a time, preventing collisions during concurrent operations (e.g., duplicate token refreshes).
- **Global Interception** — provides a single point of entry and exit for all network traffic initiated by its parent manager.
- **Request Replay** — post-request hooks can signal the system to automatically retry a request after state changes.

## Methods

### Action

#### `make`

Executes the registered preparation callback. If another preparation is currently in progress, it waits for it to complete.

**Parameters:**
- `active: boolean` — Whether the hook is enabled for the current request.
- `apiFetch: ApiFetch` — The configuration for the upcoming request.

**Returns:** `Promise<void>`

#### `makeEnd`

Executes the registered analysis callback after a request completes.

**Parameters:**
- `active: boolean` — Whether the hook is enabled for the current request.
- `query: Response` — The native Fetch API response object.
- `apiFetch: ApiFetch` — The configuration used for the request.

**Returns:** `Promise<ApiPreparationEnd>` — An object controlling the next steps (e.g., reset, data injection).

### Configuration

- `set(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Registers a function to run before every enabled request.
- `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Registers a function to run after every enabled response.

## Types

#### `ApiPreparationEnd`
Result of the analysis hook execution.
- `reset?: boolean` — If true, the request will be aborted and restarted.
- `data?: any` — Custom data to pass along.

## Guide: Mechanics of Hooks

The following rules and conditions define how the preparation system synchronizes and manages lifecycle hooks:

- **Synchronization** — the system uses a polling mechanism (160ms interval) to ensure that only one `setPreparation` hook executes at a time. If multiple requests start concurrently, subsequent calls will wait up to 32 polling attempts (~5 seconds) for the first one to finish.
- **Context Injection** — the `apiFetch` object is passed to the hooks by reference. Modifying its properties (like headers or request body) inside `setPreparation` directly affects the physical network call that follows.
- **Flow Control (Reset)** — the `setEnd` hook can return `{ reset: true }`. When this flag is detected, the `ApiInstance` will abort the current request chain and immediately restart it from the preparation phase. This is primarily used for silent, automatic token refreshing.
- **Execution Scope** — hooks only run if they are explicitly enabled in the request configuration. By default, `globalPreparation` and `globalEnd` are set to true in `ApiFetch`.
