@dxtmisha/wiki 0.39.1 → 0.39.2

package/src/media/functional/functional-basic/classes/ApiDefault/ApiDefault.en.mdx

@@ -0,0 +1,48 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/ApiDefault - Default API Request Data'/>
+
+# ApiDefault Class
+
+A class for managing default data for API requests. It allows setting base parameters that should be included in every request, supporting both standard objects and `FormData`.
+
+## Key Features
+
+- **Centralized Defaults** — define common parameters (like tokens or locale) once for all API calls.
+- **Support for Multiple Formats** — works seamlessly with both plain JavaScript objects and `FormData`.
+- **Intelligent Merging** — merges defaults with request-specific data, prioritizing the actual request data if keys overlap.
+- **Easy Checks** — simple methods to check if any default data is currently set.
+
+## Initialization
+
+To initialize the object, call the `ApiDefault()` constructor.
+
+```typescript
+import { ApiDefault } from '@dxtmisha/functional'
+
+// 1. Simple initialization
+const apiDefault = new ApiDefault()
+
+// 2. Setting default data
+apiDefault.set({ lang: 'en', version: 'v1' })
+
+// 3. Example usage with a request object
+const requestData = { user_id: 5 }
+const mergedRequest = apiDefault.request(requestData)
+// Result: { lang: 'en', version: 'v1', user_id: 5 }
+
+// 4. Example usage with FormData
+const fd = new FormData()
+fd.append('photo', fileBlob)
+apiDefault.request(fd)
+// Result: fd now contains 'lang' and 'version' if they were missing
+```
+
+## Methods
+
+- `is(): boolean` — Checks if any default data has been set.
+- `get(): ApiDefaultValue` — Returns the current default data.
+- `request(request: ApiFetch['request']): ApiFetch['request']` — Merges the stored default data into a provided request object or `FormData` instance.
+- `set(request: ApiDefaultValue)` — Sets the default data object for requests.
+
+

package/src/media/functional/functional-basic/classes/ApiDefault/ApiDefault.ru.mdx

@@ -0,0 +1,48 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/ApiDefault - Данные API по умолчанию'/>
+
+# Класс ApiDefault
+
+Класс для управления данными по умолчанию для API-запросов. Он позволяет устанавливать базовые параметры, которые должны быть включены в каждый запрос, поддерживая как стандартные объекты, так и `FormData`.
+
+## Ключевые особенности
+
+- **Централизованные значения** — определите общие параметры (например, токены или локаль) один раз для всех вызовов API.
+- **Поддержка различных форматов** — бесшовно работает как с обычными объектами JavaScript, так и с `FormData`.
+- **Интеллектуальное слияние** — объединяет значения по умолчанию с данными конкретного запроса, отдавая приоритет данным запроса при совпадении ключей.
+- **Простые проверки** — удобные методы для проверки наличия установленных данных по умолчанию.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `ApiDefault()`.
+
+```typescript
+import { ApiDefault } from '@dxtmisha/functional'
+
+// 1. Простая инициализация
+const apiDefault = new ApiDefault()
+
+// 2. Установка данных по умолчанию
+apiDefault.set({ lang: 'ru', version: 'v1' })
+
+// 3. Пример использования с объектом запроса
+const requestData = { user_id: 5 }
+const mergedRequest = apiDefault.request(requestData)
+// Результат: { lang: 'ru', version: 'v1', user_id: 5 }
+
+// 4. Пример использования с FormData
+const fd = new FormData()
+fd.append('photo', fileBlob)
+apiDefault.request(fd)
+// Результат: fd теперь содержит 'lang' и 'version', если они отсутствовали
+```
+
+## Методы
+
+- `is(): boolean` — Проверяет, были ли установлены какие-либо данные по умолчанию.
+- `get(): ApiDefaultValue` — Возвращает текущие данные по умолчанию.
+- `request(request: ApiFetch['request']): ApiFetch['request']` — Объединяет сохраненные данные по умолчанию с предоставленным объектом запроса или экземпляром `FormData`.
+- `set(request: ApiDefaultValue)` — Устанавливает объект данных по умолчанию для всех запросов.
+
+

package/src/media/functional/functional-basic/classes/ApiDefault/ApiDefault.vi.mdx

@@ -0,0 +1,48 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/ApiDefault - Dữ liệu API mặc định'/>
+
+# Lớp ApiDefault
+
+Một lớp để quản lý dữ liệu mặc định cho các yêu cầu API. Nó cho phép thiết lập các tham số cơ bản cần được bao gồm trong mọi yêu cầu, hỗ trợ cả đối tượng thông thường và `FormData`.
+
+## Các tính năng chính
+
+- **Mặc định hóa tập trung** — định nghĩa các tham số chung (như token hoặc ngôn ngữ) một lần cho tất cả các cuộc gọi API.
+- **Hỗ trợ nhiều định dạng** — hoạt động mượt mà với cả đối tượng JavaScript thuần túy và `FormData`.
+- **Gộp dữ liệu thông minh** — gộp các giá trị mặc định với dữ liệu cụ thể của yêu cầu, ưu tiên dữ liệu yêu cầu thực tế nếu có sự trùng lặp khóa.
+- **Kiểm tra dễ dàng** — các phương thức đơn giản để kiểm tra xem dữ liệu mặc định đã được thiết lập hay chưa.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `ApiDefault()`.
+
+```typescript
+import { ApiDefault } from '@dxtmisha/functional'
+
+// 1. Khởi tạo đơn giản
+const apiDefault = new ApiDefault()
+
+// 2. Thiết lập dữ liệu mặc định
+apiDefault.set({ lang: 'vi', version: 'v1' })
+
+// 3. Ví dụ sử dụng với một đối tượng yêu cầu
+const requestData = { user_id: 5 }
+const mergedRequest = apiDefault.request(requestData)
+// Kết quả: { lang: 'vi', version: 'v1', user_id: 5 }
+
+// 4. Ví dụ sử dụng với FormData
+const fd = new FormData()
+fd.append('photo', fileBlob)
+apiDefault.request(fd)
+// Kết quả: fd bây giờ chứa 'lang' và 'version' nếu chúng bị thiếu
+```
+
+## Các phương thức
+
+- `is(): boolean` — Kiểm tra xem dữ liệu mặc định đã được thiết lập chưa.
+- `get(): ApiDefaultValue` — Trả về dữ liệu mặc định hiện tại.
+- `request(request: ApiFetch['request']): ApiFetch['request']` — Gộp dữ liệu mặc định đã lưu vào một đối tượng yêu cầu hoặc biến biểu mẫu `FormData` được cung cấp.
+- `set(request: ApiDefaultValue)` — Thiết lập dữ liệu mặc định cho các yêu cầu.
+
+

package/src/media/functional/functional-basic/classes/ApiHeaders/ApiHeaders.en.mdx

@@ -0,0 +1,37 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/ApiHeaders - API Request Headers'/>
+
+# ApiHeaders Class
+
+A class for managing and merging HTTP request headers. It handles default application-wide headers, custom headers for specific requests, and default `Content-Type` assignment.
+
+## Key Features
+
+- **Default Headers** — set global headers like `Authorization` or `X-App-Version` once.
+- **Dynamic Content-Type** — automatically manages the `Content-Type` header (defaults to `application/json;charset=UTF-8`).
+- **Safe Merging** — merges multiple header sources without mutating the original objects.
+- **Validation** — ensures only valid objects are processed as headers.
+
+## Initialization
+
+To initialize the object, call the `ApiHeaders()` constructor.
+
+```typescript
+import { ApiHeaders } from '@dxtmisha/functional'
+
+// 1. Simple initialization
+const apiHeaders = new ApiHeaders()
+
+// 2. Setting default headers
+apiHeaders.set({ 'X-App-Platform': 'web' })
+
+// 3. Getting headers for a request
+const headers = apiHeaders.get({ 'Authorization': 'Bearer token123' })
+// Result: { 'X-App-Platform': 'web', 'Authorization': 'Bearer token123', 'Content-Type': 'application/json;charset=UTF-8' }
+```
+
+## Methods
+
+- `get(value?: Record<string, string> | null, type = 'application/json;charset=UTF-8'): Record<string, string> | undefined` — Intersects default headers with custom ones and injects `Content-Type`.
+- `set(headers: Record<string, string>): this` — Sets or updates the default headers object.

package/src/media/functional/functional-basic/classes/ApiHeaders/ApiHeaders.ru.mdx

@@ -0,0 +1,37 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/ApiHeaders - Заголовки API-запросов'/>
+
+# Класс ApiHeaders
+
+Класс для управления и слияния заголовков HTTP-запросов. Он обрабатывает заголовки по умолчанию, пользовательские заголовки для конкретных запросов и автоматическое назначение `Content-Type`.
+
+## Ключевые особенности
+
+- **Заголовки по умолчанию** — установите глобальные заголовки, такие как `Authorization` или `X-App-Version`, один раз.
+- **Динамический Content-Type** — автоматически управляет заголовком `Content-Type` (по умолчанию `application/json;charset=UTF-8`).
+- **Безопасное слияние** — объединяет несколько источников заголовков без изменения исходных объектов.
+- **Валидация ввода** — гарантирует, что для заголовков используются только допустимые объекты.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `ApiHeaders()`.
+
+```typescript
+import { ApiHeaders } from '@dxtmisha/functional'
+
+// 1. Простая инициализация
+const apiHeaders = new ApiHeaders()
+
+// 2. Установка заголовков по умолчанию
+apiHeaders.set({ 'X-App-Platform': 'web' })
+
+// 3. Получение заголовков для запроса
+const headers = apiHeaders.get({ 'Authorization': 'Bearer token123' })
+// Результат: { 'X-App-Platform': 'web', 'Authorization': 'Bearer token123', 'Content-Type': 'application/json;charset=UTF-8' }
+```
+
+## Методы
+
+- `get(value?: Record<string, string> | null, type = 'application/json;charset=UTF-8'): Record<string, string> | undefined` — Объединяет заголовки по умолчанию с пользовательскими и добавляет `Content-Type`.
+- `set(headers: Record<string, string>): this` — Устанавливает или обновляет заголовки по умолчанию.

package/src/media/functional/functional-basic/classes/ApiHeaders/ApiHeaders.vi.mdx

@@ -0,0 +1,37 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/ApiHeaders - Tiêu đề yêu cầu API'/>
+
+# Lớp ApiHeaders
+
+Một lớp để quản lý và gộp các tiêu đề (headers) yêu cầu HTTP. Nó xử lý các tiêu đề mặc định cho toàn bộ ứng dụng, tiêu đề tùy chỉnh cho các yêu cầu cụ thể và việc tự động gán `Content-Type`.
+
+## Các tính năng chính
+
+- **Tiêu đề mặc định** — thiết lập các tiêu đề chung một lần duy nhất, ví dụ như `Authorization` hoặc `X-App-Version`.
+- **Content-Type Động** — tự động quản lý tiêu đề `Content-Type` (mặc định là `application/json;charset=UTF-8`).
+- **Gộp an toàn** — gộp nhiều nguồn tiêu đề khác nhau mà không làm thay đổi các đối tượng gốc.
+- **Xác thực đầu vào** — đảm bảo chỉ các đối tượng hợp lệ mới được xử lý dưới dạng tiêu đề.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `ApiHeaders()`.
+
+```typescript
+import { ApiHeaders } from '@dxtmisha/functional'
+
+// 1. Khởi tạo đơn giản
+const apiHeaders = new ApiHeaders()
+
+// 2. Thiết lập các tiêu đề mặc định
+apiHeaders.set({ 'X-App-Platform': 'web' })
+
+// 3. Lấy các tiêu đề cho yêu cầu
+const headers = apiHeaders.get({ 'Authorization': 'Bearer token123' })
+// Kết quả: { 'X-App-Platform': 'web', 'Authorization': 'Bearer token123', 'Content-Type': 'application/json;charset=UTF-8' }
+```
+
+## Các phương thức
+
+- `get(value?: Record<string, string> | null, type = 'application/json;charset=UTF-8'): Record<string, string> | undefined` — Giao thoa tiêu đề mặc định với những tiêu đề tùy chỉnh được truyền vào và tiêm `Content-Type`.
+- `set(headers: Record<string, string>): this` — Thiết lập hoặc cập nhật mảng đối tượng tiêu đề mặc định.

package/src/media/functional/functional-basic/classes/ApiInstance/ApiInstance.en.mdx

@@ -0,0 +1,349 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/ApiInstance - Request Management'/>
+
+# ApiInstance Class
+
+A class operating over the Fetch API for efficient network request operations. Provides advanced configuration capabilities, global status handling, response emulation, preparation hooks setup, and automatic data parsing.
+
+It includes tight integration with dependency classes: `ApiStatus`, `ApiResponse`, `ApiPreparation`, `ApiDefault`, and `ApiHeaders`.
+
+## Key Features
+
+- **CRUD Methods** — convenient aliases `get`, `post`, `put`, `delete` for handling HTTP requests
+- **Global Configuration** — setting base URL, default headers, and parameters for all requests
+- **Lifecycle Hooks** — ability to set custom callback functions executed before (`setPreparation`) and after (`setEnd`) each request
+- **Status Tracking** — access to the status and errors of the last request via `ApiStatus`
+- **Caching & Emulation** — managing mock responses and caching via `ApiResponse`
+- **Automatic Parsing** — converting the request body into JSON/FormData and automatically extracting data from JSON responses
+- **Geolocation** — automatic substitution of `{locale}`, `{country}`, `{language}` placeholders into request paths
+
+## Constructor
+
+The `ApiInstance` can be configured during initialization with custom dependency classes or specific instances.
+
+**Parameters:**
+- `url: string` — base path for all requests (default: `'/api/'`).
+- `options: ApiInstanceOptions` — configuration object for dependency injection.
+
+### `ApiInstanceOptions`
+
+- `headersClass?: typeof ApiHeaders` — class for managing headers.
+- `requestDefaultClass?: typeof ApiDefault` — class for global request parameters.
+- `statusClass?: typeof ApiStatus` — class for tracking request status.
+- `responseClass?: typeof ApiResponse` — class for response emulation and caching.
+- `preparationClass?: typeof ApiPreparation` — class for lifecycle hook management.
+- `loadingClass?: LoadingInstance` — instance of the loading indicator manager (defaults to `Loading.getItem()`).
+- `errorCenterClass?: ErrorCenterInstance` — instance of the error center for triggering events (defaults to `ErrorCenter.getItem()`).
+
+## API Calling Methods
+
+### `request`
+
+Core executor sequence method managing pure physical network fetch pipelines. Should a solitary string serve as param context, default `GET` assumptions trigger automatically.
+In case of network failures (e.g., 500 status), the method explicitly throws an exception (`throw e`), allowing errors to be natively intercepted in `try/catch`. If the server returns a JSON object, the system automatically injects a `statusObject` field (instance of request status) to the returned payload.
+
+**Parameters:**
+- `pathRequest: string | ApiFetch` — destination path matching format or root configuration structure object.
+
+**Returns:** `Promise<ApiData<T>>` — decoded endpoint structural response formatted interface (including `data`, `statusObject`, etc., when returning an object payload).
+
+### `get`
+
+Dispatches a basic query through HTTP `GET` methodologies natively optimizing inputs payload onto string search parameters formats automatically.
+
+**Parameters:**
+- `request: ApiFetch` — fetch execution configuration property mapping (`path`, `request` body, and so on).
+
+**Returns:** `Promise<T>`
+
+### `post`
+
+Transfers query packets across standard REST/GraphQL pipelines formatted onto the HTTP `POST` specification.
+
+**Parameters:**
+- `request: ApiFetch` — parameters interface structure container including URL pointing directives.
+
+**Returns:** `Promise<T>`
+
+### `put`
+
+Directs object modifications over target remote points using typical system environment HTTP `PUT`.
+
+**Parameters:**
+- `request: ApiFetch` — query options mapped against backend routing.
+
+**Returns:** `Promise<T>`
+
+### `delete`
+
+Forwards structural clearance/purge request using classic URL targeted HTTP `DELETE`.
+
+**Parameters:**
+- `request: ApiFetch` — arguments package structure wrapper.
+
+**Returns:** `Promise<T>`
+
+## Instance Retrieval Methods
+
+- `isLocalhost(): boolean` — Returns `true` if the code is running on a local development server.
+- `getStatus(): ApiStatus` — Returns the `ApiStatus` manager for tracking the state, errors, and complete response object of the last network request.
+- `getResponse(): ApiResponse` — Returns the responses/emulation manager `ApiResponse` for controlling mock-responses.
+
+## Configuration Methods
+
+Methods to configure the API (support chaining, returning the `ApiInstance` object):
+- `setHeaders(headers: Record<string, string>): this` — Applies universal headers injected automatically toward outbound fetch activities.
+- `setRequestDefault(request: Record<string, any>): this` — Forces parameters recursively sent to network traffic streams.
+- `setUrl(url: string): this` — Overwrites generic target URL configurations prefix points.
+- `setPreparation(callback: (apiFetch: ApiFetch) => Promise<void>): this` — Connects a custom hook function actively running just _before_ execution trigger occurs.
+- `setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this` — Sets the hook triggered exactly _after_ network response returns.
+
+## Request Preparation Methods
+
+- `getUrl(path: string, api?: boolean): string` — Generates the full target URL referencing the script, handling dynamic geography variables.
+- `getBody(request?: ApiFetch['request'], method?: string): string | FormData | undefined` — Creates data to be passed into the request physical body.
+- `getBodyForGet(request: ApiFetch['request'], path?: string, method?: string): string` — Forms query parameters specifically for HTTP arguments assigned into the URL directly used when sending `GET` queries.
+
+## ApiFetch Object
+
+`ApiFetch` is the main configuration object passed to all request methods (`request`, `get`, `post`, `put`, `delete`). All fields are optional:
+
+- `path?: string` — endpoint path relative to the base URL (e.g. `'users/list'`).
+- `pathFull?: string` — full request URL. If provided, overrides `api` and `path`.
+- `api?: boolean` — whether to prepend the base URL before `path`. Default: `true`.
+- `method?: ApiMethod` — HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). Default: `'GET'`.
+- `request?: FormData | Record<string, any> | string` — request body (for POST/PUT) or query parameters (for GET). Serialized as JSON or `FormData`.
+- `headers?: Record<string, string> | null` — additional request headers. Pass `null` to disable all headers.
+- `type?: string` — `Content-Type` header value. Default: `'application/json;charset=UTF-8'`.
+- `auth?: boolean` — include authentication headers.
+- `toData?: boolean` — if `true`, automatically unwraps `data` from a `{ data: ... }` wrapper. Default: `true`.
+- `global?: boolean` — use global response cache.
+- `devMode?: boolean` — enable development logging.
+- `hideError?: boolean` — suppresses `console.error` output on failure. Default: `false`.
+- `globalPreparation?: boolean` — whether to run the global `setPreparation` hook before this request. Default: `true`.
+- `globalEnd?: boolean` — whether to run the global `setEnd` hook after the response. Default: `true`.
+- `queryReturn?: (query: Response) => Promise<any>` — custom response processor instead of the default JSON reader.
+- `init?: RequestInit` — additional options passed directly to native `fetch()` (CORS, cache mode, etc.).
+- `timeout?: number` — request timeout in milliseconds. Default: `16000`ms.
+- `controller?: AbortController` — controller for canceling the request.
+- `retry?: number` — number of retries on failure.
+- `retryDelay?: number` — base delay between retries in milliseconds. Default: `64`ms.
+
+## Response Data Structure
+
+Requests return a `Promise<ApiData<T>>`.
+
+### `ApiData<T>`
+
+The structure of the returned data depends on the type of response:
+- **Array**: If the response is an array, `ApiData<T>` acts as `T[]`.
+- **Object**: If the response is an object, `ApiData<T>` includes fields from `T` and the standard wrapper `ApiDataItem<T>`.
+
+### `ApiDataItem<T>`
+
+The object response contains the following fields:
+
+- `data?: T` — primary payload if the response was wrapped.
+- `success?: boolean` — success flag.
+- `status?: ApiStatusType` — status type (`'success'`, `'error'`, `'warning'`, `'info'`).
+- `message?: string` — response message or error description.
+- `statusObject?: ApiStatusItem` — technical information about the request:
+    - `status?: number` — HTTP status code (e.g., 200, 404).
+    - `statusText?: string` — HTTP status text.
+    - `error?: string` — internal error message if the request failed.
+    - `lastResponse?: any` — data from the last response before parsing.
+    - `lastStatus?: ApiStatusType` — status of the last request.
+    - `lastMessage?: string` — message from the last request.
+
+## Request Cancellation (AbortController)
+
+The API supports out-of-the-box request cancellation. Pass an instance of `AbortController` into the `controller` field of the `ApiFetch` configuration.
+
+```javascript
+const controller = new AbortController()
+
+// Dispatch the request
+api.get({ path: 'users', controller }).catch(e => {
+  if (e.name === 'AbortError') {
+    console.log('Request was cancelled by the user')
+  }
+})
+
+// Cancel the request later (e.g., when the component unmounts)
+controller.abort()
+```
+
+## Lifecycle Hooks
+
+Hooks allow you to inject global logic that will automatically execute for every network request. This is a powerful tool for tasks such as:
+- Dynamically adding authorization tokens.
+- Centralized logging of network activity.
+- Automatically refreshing expired tokens (Refresh Token).
+- Global user notification of errors.
+
+### Request Preparation (`setPreparation`)
+
+The `setPreparation` method sets a callback function that is called immediately before a request is sent to the server (before the native `fetch` is executed).
+
+**Key Features:**
+- **Execution Order**: If multiple requests are started simultaneously, the class ensures that the preparation hook is executed **sequentially**. All subsequent requests will wait for the current hook to finish in wait mode (with a 160ms polling interval). This prevents conflicts, such as when multiple concurrent requests attempt to refresh a token.
+- **Parameters**: Receives the `apiFetch` object, which contains all current request settings. You can modify this object (e.g., adding headers or modifying the request body).
+- **Returns**: `Promise<void>`.
+
+```javascript
+api.setPreparation(async (apiFetch) => {
+  // Example: adding a dynamic header
+  if (apiFetch.auth) {
+    const token = await authStore.getToken()
+    apiFetch.headers = {
+      ...apiFetch.headers,
+      'Authorization': `Bearer ${token}`
+    }
+  }
+  
+  console.log(`[API] Preparing request: ${apiFetch.method} ${apiFetch.path}`)
+})
+```
+
+### Request Completion (`setEnd`)
+
+The `setEnd` method sets a callback function that is called after receiving a response from the server, but before the data is passed to the calling code.
+
+**Parameters:**
+- `query: Response` — the native Fetch API response object.
+- `apiFetch: ApiFetch` — the parameters object with which the request was performed.
+
+**Returns:** `Promise<ApiPreparationEnd>`. The result object can contain the following fields:
+- `reset?: boolean` — if set to `true`, the library will abort the current chain and **execute the request again** (recursively) after a jittered delay (see `retryDelay`). The entire process of preparation and execution will be restarted. This is used for automatic handling of refreshed access rights.
+- `data?: any` — allows you to override the data returned by the API method. If this field is specified, the standard response reading mechanism (JSON/text) will be ignored.
+
+```javascript
+api.setEnd(async (response, apiFetch) => {
+  // Example: automatic Refresh Token update
+  if (response.status === 401) {
+    const isSuccess = await authStore.refresh()
+    
+    if (isSuccess) {
+      // Retry the request with the new token
+      return { reset: true }
+    }
+  }
+
+  // Example: global error notification
+  if (response.status >= 500) {
+    notification.error('Service is temporarily unavailable')
+  }
+
+  return {}
+})
+```
+
+### Disabling Hooks for a Specific Request
+
+You can selectively disable global hooks in the `ApiFetch` object:
+- `globalPreparation: false` — skip the `setPreparation` hook execution.
+- `globalEnd: false` — skip the `setEnd` hook execution.
+
+## Response Emulation (ApiResponse)
+
+The emulator manager `ApiResponse` (accessible via `api.getResponse()`) allows configuring mock responses for specified paths. This is incredibly useful during frontend UI development without a completely ready backend API or for writing test fixtures.
+
+### Registering Mock Responses
+
+The `add` method accepts an `ApiResponseItem` object or an array of such objects.
+
+**Key `ApiResponseItem` fields:**
+- `path` — String (exact match) or Regular Expression (`RegExp`) to intercept the request URL.
+- `method` — HTTP method (`ApiMethodItem.get`, `post`, etc.).
+- `request` — (Optional) Request body filter. You can use the special marker `'*any'` to bypass payload validation and capture all requests to this path.
+- `response` — Static data object _or_ a dynamic factory function `(request) => any` that generates a response based on the incoming request payload.
+- `disable` — (Optional) Disable this mock (boolean or callback).
+- `isForGlobal` — (Optional) Mark as global mock.
+- `lag` — (Optional) Simulates network lag (`boolean`), adding a random `setTimeout` from 0 to 2000ms.
+
+```javascript
+const responseManager = api.getResponse()
+
+// Enable developer mode (prints mock request logs and intercepted requests into the console)
+responseManager.setDevMode(true)
+
+// Example 1: Static response for a GET request
+responseManager.add({
+  path: 'users/profile', // can be a string or RegExp
+  method: 'GET',
+  response: { id: 1, name: 'Admin', role: 'superuser' },
+  lag: true // Add artificial lag to simulate real network ping
+})
+
+// Example 2: Dynamic response with a factory curve (useful for pagination or search simulation)
+responseManager.add({
+  path: /users\/search/, // intercepting using RegExp
+  method: 'GET',
+  // The function receives the original payload object passed via request
+  response: (request) => {
+    return [
+        { id: 1, name: `Results for: ${request.query}` }
+    ]
+  }
+})
+
+// Example 3: Intercept POST request regardless of body payload
+responseManager.add({
+  path: 'users/create',
+  method: 'POST',
+  request: '*any', // the *any marker bypasses request payload checking altogether
+  response: { success: true, message: 'User created successfully (MOCK)' }
+})
+
+// Usage in code (no real network stream is opened, mock resolves instantly or after simulated lag)
+const profile = await api.get({ path: 'users/profile' })
+```
+
+### Mock Prioritization and Fallback
+
+- The emulator intercepts requests **before** the actual `fetch` call is made.
+- If the emulator finds no matching registered mock (due to `path`, `method`, or `request` mismatch), the class automatically falls back to executing a real physical network request to the remote server.
+- You can conditionally disable a specific mock by providing a callback to the `disable: () => true` field. The `add` engine will ignore it.
+
+## Examples
+
+```javascript
+import { ApiInstance } from '@dxtmisha/functional'
+
+const api = new ApiInstance()
+
+// API Configuration
+api.setUrl('https://api.example.com/v1/')
+   .setHeaders({ 'Authorization': 'Bearer token123' })
+   .setRequestDefault({ source: 'webapp' })
+
+// Preparation interceptor hook
+api.setPreparation(async (apiFetch) => {
+    console.log('Initializing request to:', apiFetch.path)
+})
+
+// Standard GET fetch behavior with error handling
+try {
+  const data = await api.get({ path: 'users' })
+  // Extracting inline status payload gracefully:
+  // console.log(data.statusObject.getStatus())
+} catch (e) {
+  console.error('Network transport error while pulling users:', e)
+}
+
+// Extended POST behavior capable of abort termination
+const abortCtrl = new AbortController()
+try {
+  const newUser = await api.post({
+    path: 'users/create',
+    request: { name: 'John Doe', age: 30 },
+    controller: abortCtrl
+  })
+} catch (e) {
+  if (e.name === 'AbortError') console.log('Request safely aborted!')
+}
+
+// Abort when needed
+// abortCtrl.abort()
+```