@dxtmisha/wiki 0.39.7 → 0.56.0

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

@@ -0,0 +1,131 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/ServerStorage - Data Isolation in SSR'/>
+
+# ServerStorage Class
+
+`ServerStorage` is a mechanism for managing **isolated global state** in applications with SSR (Server-Side Rendering) support.
+
+The class allows you to work with data as easily as with static variables, but ensures that user data on the server does not intermingle between parallel requests.
+
+## Key Features
+
+- **Request Isolation** — data on the server is bound to the context of the current human or machine request.
+- **Hydration** — ability to automatically transfer state from the server to the client via JSON.
+- **Security** — automatic XSS escaping during data transfer.
+
+```typescript
+import { ServerStorage } from '@dxtmisha/functional-basic'
+
+// Save data with a hydration flag (will be available on the client)
+ServerStorage.set('theme', () => 'dark', true)
+
+// Retrieve data
+const theme = ServerStorage.get('theme') // 'dark'
+```
+
+## Data Access Methods
+
+### `get`
+
+Retrieves a value by key. If it doesn't exist, creates it using the default value factory.
+
+**Parameters:**
+- `key: string` — unique storage key.
+- `defaultValue?: () => T` — function that returns the default value if not found.
+- `hydration: boolean` — if `true`, the value will be included in the JSON for the client (default: `false`).
+
+**Returns:** `T`
+
+### `set`
+
+Saves a value to the storage.
+
+**Parameters:**
+- `key: string` — unique storage key.
+- `value: () => T` — function that returns the value to save.
+- `hydration: boolean` — if `true`, the value will be included in the JSON for the client (default: `false`).
+
+**Returns:** `T`
+
+## Utility & Lifecycle Methods
+
+- `init(listener: () => Record<string, any>): typeof ServerStorage` — Initializes the storage with a context listener. On the server, this listener should return an object unique to each request.
+- `has(key: string): boolean` — Checks for the existence of a key in the current context.
+- `remove(key: string): void` — Removes a value by key from the storage.
+- `setErrorStatus(hide: boolean): void` — Sets whether to hide context missing errors in the console/error center.
+- `reset(): void` — Resets the storage, clearing all stored data and the listener. Useful for performing cleanup.
+- `toString(): string` — Generates an HTML `<script type="application/json">` tag containing all data marked for hydration.
+
+## Isolation in SSR
+
+In standard client-side applications, global state belongs to a single user. However, in an SSR environment, one Node.js process handles many concurrent requests simultaneously. To prevent user data from "leaking" between these requests (State Pollution), `ServerStorage` must be correctly isolated.
+
+To achieve this, you must initialize `ServerStorage` with the `init` method. This method accepts a listener function that returns a data object unique to the current request context.
+
+> Important: Correct isolation is critical for security. If not configured, data from one user could be served to another.
+
+### Node.js (AsyncLocalStorage)
+
+The recommended way for Node.js is to use `AsyncLocalStorage` to store context throughout an asynchronous request.
+
+```typescript
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { ServerStorage } from '@dxtmisha/functional-basic'
+
+const als = new AsyncLocalStorage<Record<string, any>>()
+
+// Initialization
+ServerStorage.init(() => als.getStore() || {})
+
+// Usage in server
+http.createServer((req, res) => {
+  als.run({}, () => {
+    // All calls to ServerStorage inside this block will be isolated
+    ServerStorage.set('requestId', () => req.id)
+  })
+})
+```
+
+### Nuxt / Nitro
+
+In Nuxt/Nitro, isolation is managed via the `h3` event context using `useEvent()` within a server plugin.
+
+```typescript
+// server/plugins/server-storage.ts
+import { ServerStorage } from '@dxtmisha/functional-basic'
+
+export default defineNitroPlugin(() => {
+  ServerStorage.init(() => {
+    try {
+      return useEvent().context
+    } catch {
+      return {}
+    }
+  })
+})
+```
+
+## Hydration (Transferring Data to Client)
+
+Hydration is the process of transferring the application state set on the server to the client. This allows the browser to pick up where the server left off, ensuring consistency and preventing redundant data fetching or "flickering" during page load.
+
+### 1. Identify Data for Hydration
+
+When using `set()` or `get()`, pass `true` as the third parameter (`hydration`). Only values marked this way will be transferred to the client.
+
+```typescript
+// Set on server
+ServerStorage.set('userSettings', () => ({ fontSize: 16 }), true)
+```
+
+### 2. Injecting State into HTML
+
+On the server, you must call `ServerStorage.toString()` and insert its result into your page template (usually at the very end of the `<body>` tag, before your application scripts).
+
+This method generates a special script tag:
+```html
+<script id="__ui:server:storage:id__" type="application/json">
+  {"userSettings":{"fontSize":16}}
+</script>
+```

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

@@ -0,0 +1,131 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/ServerStorage - Изоляция данных в SSR'/>
+
+# Класс ServerStorage
+
+`ServerStorage` — это механизм для управления **изолированным глобальным состоянием** в приложениях с поддержкой SSR (Server-Side Rendering).
+
+Класс позволяет работать с данными так же просто, как со статическими переменными, но гарантирует, что на сервере данные разных пользователей не будут смешиваться.
+
+## Основные возможности
+
+- **Изоляция запросов** — на сервере данные привязываются к контексту текущего HTTP-запроса.
+- **Гидратация** — возможность автоматически передавать состояние с сервера на клиент через JSON.
+- **Безопасность** — автоматическое экранирование XSS при передаче данных.
+
+```typescript
+import { ServerStorage } from '@dxtmisha/functional-basic'
+
+// Сохранение данных с флагом гидратации (будут доступны на клиенте)
+ServerStorage.set('theme', () => 'dark', true)
+
+// Получение данных
+const theme = ServerStorage.get('theme') // 'dark'
+```
+
+## Методы доступа к данным
+
+### `get`
+
+Извлекает значение по ключу. Если оно не существует, создает его с помощью фабрики значений по умолчанию.
+
+**Параметры:**
+- `key: string` — уникальный ключ хранилища.
+- `defaultValue?: () => T` — функция, возвращающая значение по умолчанию, если оно не найдено.
+- `hydration: boolean` — если `true`, значение будет включено в JSON для передачи на клиент (по умолчанию: `false`).
+
+**Возвращает:** `T`
+
+### `set`
+
+Записывает значение в хранилище.
+
+**Параметры:**
+- `key: string` — уникальный ключ хранилища.
+- `value: () => T` — функция, возвращающая значение для сохранения.
+- `hydration: boolean` — если `true`, значение будет включено в JSON для передачи на клиент (по умолчанию: `false`).
+
+**Возвращает:** `T`
+
+## Вспомогательные методы и жизненный цикл
+
+- `init(listener: () => Record<string, any>): typeof ServerStorage` — Инициализирует хранилище слушателем контекста. На сервере этот слушатель должен возвращать объект, уникальный для каждого запроса.
+- `has(key: string): boolean` — Проверяет наличие ключа в текущем контексте.
+- `remove(key: string): void` — Удаляет значение по ключу из хранилища.
+- `setErrorStatus(hide: boolean): void` — Устанавливает, нужно ли скрывать ошибки отсутствия контекста в консоли/центре ошибок.
+- `reset(): void` — Сбрасывает хранилище, очищая все сохраненные данные и слушателя. Полезно для выполнения очистки.
+- `toString(): string` — Генерирует HTML-тег `<script type="application/json">` со всеми данными, помеченными для гидратации.
+
+## Изоляция в SSR
+
+В обычных клиентских приложениях глобальное состояние принадлежит одному пользователю. Однако в среде SSR один процесс Node.js обрабатывает множество одновременных запросов. Чтобы данные пользователей не смешивались между собой (Загрязнение состояния), `ServerStorage` должен быть правильно изолирован.
+
+Для этого необходимо инициализировать `ServerStorage` с помощью метода `init`. Он принимает функцию-слушатель, которая возвращает объект данных, уникальный для контекста текущего запроса.
+
+> Важно: Правильная изоляция критична для безопасности. Без нее данные одного пользователя могут быть по ошибке переданы другому.
+
+### Node.js (AsyncLocalStorage)
+
+Рекомендуемый способ для Node.js — использование `AsyncLocalStorage` для сохранения контекста на протяжении асинхронного запроса.
+
+```typescript
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { ServerStorage } from '@dxtmisha/functional-basic'
+
+const als = new AsyncLocalStorage<Record<string, any>>()
+
+// Инициализация
+ServerStorage.init(() => als.getStore() || {})
+
+// Использование на сервере
+http.createServer((req, res) => {
+  als.run({}, () => {
+    // Внутри этого блока все вызовы ServerStorage будут изолированы
+    ServerStorage.set('requestId', () => req.id)
+  })
+})
+```
+
+### Nuxt / Nitro
+
+В Nuxt/Nitro изоляция управляется через контекст события `h3` с помощью `useEvent()` внутри серверного плагина.
+
+```typescript
+// server/plugins/server-storage.ts
+import { ServerStorage } from '@dxtmisha/functional-basic'
+
+export default defineNitroPlugin(() => {
+  ServerStorage.init(() => {
+    try {
+      return useEvent().context
+    } catch {
+      return {}
+    }
+  })
+})
+```
+
+## Гидратация (Передача данных клиенту)
+
+Гидратация — это процесс передачи состояния приложения, установленного на сервере, клиенту. Это позволяет браузеру «подхватить» данные там, где закончил сервер, обеспечивая согласованность и предотвращая повторные запросы данных или «мерцание» страницы при загрузке.
+
+### 1. Пометка данных для гидратации
+
+При использовании `set()` или `get()` передайте `true` третьим параметром (`hydration`). Только значения, помеченные таким образом, будут переданы на клиент.
+
+```typescript
+// Установка на сервере
+ServerStorage.set('userSettings', () => ({ fontSize: 16 }), true)
+```
+
+### 2. Вставка состояния в HTML
+
+На сервере необходимо вызвать `ServerStorage.toString()` и вставить результат в шаблон страницы (обычно в самый конец тега `<body>`, перед скриптами приложения).
+
+Этот метод генерирует специальный тег script:
+```html
+<script id="__ui:server:storage:id__" type="application/json">
+  {"userSettings":{"fontSize":16}}
+</script>
+```

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

@@ -0,0 +1,131 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/ServerStorage - Cách ly dữ liệu trong SSR'/>
+
+# Lớp ServerStorage
+
+`ServerStorage` là một cơ chế để quản lý **trạng thái toàn cục được cách ly** trong các ứng dụng hỗ trợ SSR (Server-Side Rendering).
+
+Lớp này cho phép bạn làm việc với dữ liệu dễ dàng như với các biến tĩnh (static), nhưng đảm bảo rằng dữ liệu người dùng trên máy chủ không bị trộn lẫn giữa các yêu cầu song song.
+
+## Các tính năng chính
+
+- **Cách ly yêu cầu** — dữ liệu trên máy chủ được liên kết với ngữ cảnh của yêu cầu hiện tại.
+- **Hydration** — khả năng tự động chuyển trạng thái từ máy chủ sang máy khách thông qua JSON.
+- **Bảo mật** — tự động thoát (escape) XSS trong quá trình truyền dữ liệu.
+
+```typescript
+import { ServerStorage } from '@dxtmisha/functional-basic'
+
+// Lưu dữ liệu với cờ hydration (sẽ có sẵn trên máy khách)
+ServerStorage.set('theme', () => 'dark', true)
+
+// Truy xuất dữ liệu
+const theme = ServerStorage.get('theme') // 'dark'
+```
+
+## Các phương thức truy cập dữ liệu
+
+### `get`
+
+Truy xuất giá trị theo khóa. Nếu không tìm thấy, nó sẽ tạo giá trị mới bằng cách sử dụng factory giá trị mặc định.
+
+**Tham số:**
+- `key: string` — khóa lưu trữ duy nhất.
+- `defaultValue?: () => T` — hàm trả về giá trị mặc định nếu không tìm thấy.
+- `hydration: boolean` — nếu là `true`, giá trị sẽ được bao gồm trong JSON cho máy khách (mặc định: `false`).
+
+**Trả về:** `T`
+
+### `set`
+
+Lưu một giá trị vào kho lưu trữ.
+
+**Tham số:**
+- `key: string` — khóa lưu trữ duy nhất.
+- `value: () => T` — hàm trả về giá trị để lưu.
+- `hydration: boolean` — nếu là `true`, giá trị sẽ được bao gồm trong JSON cho máy khách (mặc định: `false`).
+
+**Trả về:** `T`
+
+## Các phương thức tiện ích và vòng đời
+
+- `init(listener: () => Record<string, any>): typeof ServerStorage` — Khởi tạo kho lưu trữ với bộ lắng nghe ngữ cảnh. Trên máy chủ, bộ lắng nghe này sẽ trả về một đối tượng duy nhất cho mỗi yêu cầu.
+- `has(key: string): boolean` — Kiếm tra sự tồn tại của một khóa trong ngữ cảnh hiện tại.
+- `remove(key: string): void` — Xóa một giá trị theo khóa khỏi kho lưu trữ.
+- `setErrorStatus(hide: boolean): void` — Thiết lập việc ẩn lỗi thiếu ngữ cảnh trong bảng điều khiển hoặc trung tâm lỗi.
+- `reset(): void` — Đặt lại kho lưu trữ, xóa tất cả dữ liệu đã lưu và bộ lắng nghe. Hữu ích cho việc dọn dẹp.
+- `toString(): string` — Tạo một thẻ HTML `<script type="application/json">` chứa tất cả dữ liệu được đánh dấu để hydration.
+
+## Cách ly trong SSR
+
+Trong các ứng dụng phía máy khách thông thường, trạng thái toàn cục thuộc về một người dùng duy nhất. Tuy nhiên, trong môi trường SSR, một quy trình Node.js xử lý nhiều yêu cầu đồng thời. Để ngăn chặn dữ liệu của người dùng này "rò rỉ" sang yêu cầu của người dùng khác (Ô nhiễm trạng thái), `ServerStorage` phải được cách ly chính xác.
+
+Để đạt được điều này, bạn phải khởi tạo `ServerStorage` bằng phương thức `init`. Phương thức này chấp nhận một hàm lắng nghe trả về một đối tượng dữ liệu duy nhất cho ngữ cảnh yêu cầu hiện tại.
+
+> Quan trọng: Việc cách ly chính xác là cực kỳ quan trọng đối với bảo mật. Nếu không được cấu hình, dữ liệu từ người dùng này có thể được cung cấp cho người dùng khác.
+
+### Node.js (AsyncLocalStorage)
+
+Cách được khuyến nghị cho Node.js là sử dụng `AsyncLocalStorage` để lưu trữ ngữ cảnh trong suốt một yêu cầu không đồng bộ.
+
+```typescript
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { ServerStorage } from '@dxtmisha/functional-basic'
+
+const als = new AsyncLocalStorage<Record<string, any>>()
+
+// Khởi tạo
+ServerStorage.init(() => als.getStore() || {})
+
+// Sử dụng trong máy chủ
+http.createServer((req, res) => {
+  als.run({}, () => {
+    // Tất cả các lệnh gọi đến ServerStorage bên trong khối này sẽ được cách ly
+    ServerStorage.set('requestId', () => req.id)
+  })
+})
+```
+
+### Nuxt / Nitro
+
+Trong Nuxt/Nitro, việc cách ly được quản lý thông qua ngữ cảnh sự kiện `h3` bằng cách sử dụng `useEvent()` bên trong một plugin máy chủ.
+
+```typescript
+// server/plugins/server-storage.ts
+import { ServerStorage } from '@dxtmisha/functional-basic'
+
+export default defineNitroPlugin(() => {
+  ServerStorage.init(() => {
+    try {
+      return useEvent().context
+    } catch {
+      return {}
+    }
+  })
+})
+```
+
+## Hydration (Chuyển dữ liệu sang máy khách)
+
+Hydration là quá trình chuyển trạng thái ứng dụng được thiết lập trên máy chủ sang máy khách. Điều này cho phép trình duyệt tiếp tục công việc từ nơi máy chủ dừng lại, đảm bảo tính nhất quán và ngăn chặn việc tìm kiếm dữ liệu thừa hoặc hiện tượng "nhấp nháy" (flickering) trong quá trình tải trang.
+
+### 1. Xác định dữ liệu để Hydration
+
+Khi sử dụng `set()` hoặc `get()`, hãy truyền `true` làm tham số thứ ba (`hydration`). Chỉ những giá trị được đánh dấu theo cách này mới được chuyển sang máy khách.
+
+```typescript
+// Thiết lập trên máy chủ
+ServerStorage.set('userSettings', () => ({ fontSize: 16 }), true)
+```
+
+### 2. Chèn trạng thái vào HTML
+
+Trên máy chủ, bạn phải gọi `ServerStorage.toString()` và chèn kết quả của nó vào mẫu trang của bạn (thường ở cuối thẻ `<body>`, trước các tập lệnh ứng dụng của bạn).
+
+Phương thức này tạo ra một thẻ script đặc biệt:
+```html
+<script id="__ui:server:storage:id__" type="application/json">
+  {"userSettings":{"fontSize":16}}
+</script>
+```

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

@@ -0,0 +1,97 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Classes/StorageCallback - Storage Callbacks'/>
+
+# StorageCallback Class
+
+A utility class for managing groups of callback functions associated with specific storage keys. It ensures that multiple components or functions can react to storage changes or triggers in a coordinated, asynchronous manner.
+
+## Key Features
+
+- **Named Instances** — facilitates a singleton-like pattern where instances are retrieved by name and group, ensuring different parts of the application share the same callback list for the same resource.
+- **Group Separation** — allows segregating callback lists by group (e.g., 'main', 'global', 'local'), preventing name collisions between different modules.
+- **Asynchronous Execution** — supports `Promise`-based callbacks and executes them sequentially during the `run` process.
+- **Loading State Tracking** — provides a built-in `loading` flag that is automatically managed during the callback execution phase.
+
+## Initialization
+
+To initialize the object, call the `StorageCallback(name, group)` constructor or use the static method `getInstance(name, group)`.
+
+### Generic Constraints
+
+To ensure strict typing, the class supports the following generics:
+- `T = any` — The type of data passed to callbacks.
+- `Callback = (value: T) => void | Promise<void>` — The structure of the callback function.
+
+**Parameters:**
+- `name: string` — a unique identifier for the storage entry.
+- `group: string = 'main'` — optional category to prevent name collisions.
+
+```typescript
+import { StorageCallback } from '@dxtmisha/functional-basic'
+
+// 1. Simple initialization (group defaults to 'main')
+const storage = new StorageCallback('user-data')
+
+// 2. Using the singleton-like getInstance method
+const sharedStorage = StorageCallback.getInstance('settings', 'global')
+
+// 3. Using generics for strict typing
+const numberStorage = new StorageCallback<number>('counter')
+numberStorage.addCallback((val) => console.log(val + 1))
+```
+
+## Methods
+
+### Information
+
+- `getName(): string` — returns the storage instance name.
+- `isLoading(): boolean` — returns the current loading state.
+- `getLoading(): boolean` — returns the current loading state (alias for `isLoading`).
+
+### Management
+
+- `addCallback(callback: Callback, isOnce?: boolean): this` — adds a new callback to the execution list. If `isOnce: true`, the callback will be removed after the first execution.
+- `removeCallback(callback: Callback): this` — removes a specific callback from the list.
+
+### Control
+
+- `preparation(): this` — prepares the state before execution (sets `loading` to `true`). Should be called manually when starting an asynchronous process.
+- `run(value: T): Promise<this>` — executes all callbacks sequentially with the provided value. Sets `loading` back to `false` at the start of execution.
+
+## Usage Examples
+
+### Manual Loading Management
+
+When data is fetched asynchronously from an external source (e.g., Figma storage), you can manage the `loading` state manually to coordinate multiple requests.
+
+```typescript
+const storage = new StorageCallback('figma-data')
+
+// 1. Check if it is not already loading
+if (!storage.isLoading()) {
+  // 2. Set loading state to true
+  storage.preparation()
+  
+  // 3. Request the data
+  fetchFromFigma((data) => {
+    // 4. Run callbacks (run will reset loading to false)
+    storage.run(data)
+  })
+}
+```
+
+### One-time Callback
+
+If you only need a function to trigger once (e.g., for initial data hydration), use the `isOnce` flag.
+
+```typescript
+const storage = new StorageCallback('initial-data')
+
+storage.addCallback((data) => {
+  console.log('Executed once:', data)
+}, true)
+
+await storage.run('update 1') // 'Executed once: update 1'
+await storage.run('update 2') // (no output, callback removed)
+```

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

@@ -0,0 +1,97 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/StorageCallback - Обратные вызовы хранилища'/>
+
+# Класс StorageCallback
+
+Вспомогательный класс для управления группами функций обратного вызова, связанных с конкретными ключами хранилища. Он позволяет нескольким компонентам или функциям реагировать на изменения или триггеры хранилища согласованно и асинхронно.
+
+## Основные особенности
+
+- **Именованные экземпляры** — реализует паттерн, похожий на синглтон, где экземпляры извлекаются по имени и группе, гарантируя, что разные части приложения используют один и тот же список обратных вызовов для одного и того же ресурса.
+- **Разделение по группам** — позволяет разделять списки обратных вызовов по группам (например, 'main', 'global', 'local'), предотвращая конфликты имен между различными модулями.
+- **Асинхронное выполнение** — поддерживает асинхронные обратные вызовы и выполняет их последовательно в процессе вызова `run`.
+- **Отслеживание состояния загрузки** — предоставляет встроенный флаг `loading`, который автоматически переключается во время фазы выполнения обратных вызовов.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `StorageCallback(name, group)` или используйте статический метод `getInstance(name, group)`.
+
+### Ограничения типов (Generics)
+
+Для обеспечения строгой типизации класс поддерживает следующие параметры:
+- `T = any` — тип данных, передаваемых в обратные вызовы.
+- `Callback = (value: T) => void | Promise<void>` — структура функции обратного вызова.
+
+**Параметры:**
+- `name: string` — уникальный идентификатор для записи в хранилище.
+- `group: string = 'main'` — необязательная категория для предотвращения конфликтов имен.
+
+```typescript
+import { StorageCallback } from '@dxtmisha/functional-basic'
+
+// 1. Простая инициализация (группа по умолчанию 'main')
+const storage = new StorageCallback('user-data')
+
+// 2. Использование статического метода getInstance
+const sharedStorage = StorageCallback.getInstance('settings', 'global')
+
+// 3. Использование generic-типов для строгой типизации
+const numberStorage = new StorageCallback<number>('counter')
+numberStorage.addCallback((val) => console.log(val + 1))
+```
+
+## Методы
+
+### Информация
+
+- `getName(): string` — возвращает имя экземпляра хранилища.
+- `isLoading(): boolean` — возвращает текущее состояние загрузки.
+- `getLoading(): boolean` — возвращает текущее состояние загрузки (аналог `isLoading`).
+
+### Управление
+
+- `addCallback(callback: Callback, isOnce?: boolean): this` — добавляет новый обратный вызов в список выполнения. При `isOnce: true` callback будет удален после первого выполнения.
+- `removeCallback(callback: Callback): this` — удаляет конкретный обратный вызов из списка.
+
+### Управление процессом (Control)
+
+- `preparation(): this` — подготавливает состояние перед выполнением (устанавливает `loading` в `true`). Используется вручную при запуске асинхронных операций.
+- `run(value: T): Promise<this>` — последовательно выполняет все обратные вызовы с переданным значением. В начале выполнения устанавливает `loading` в `false`.
+
+## Примеры использования
+
+### Ручное управление состоянием загрузки
+
+Если данные загружаются асинхронно из внешнего источника (например, Figma storage), вы можете управлять состоянием `loading` вручную.
+
+```typescript
+const storage = new StorageCallback('figma-data')
+
+// 1. Проверяем, не идет ли уже загрузка
+if (!storage.isLoading()) {
+  // 2. Устанавливаем состояние загрузки
+  storage.preparation()
+  
+  // 3. Запрашиваем данные
+  fetchFromFigma((data) => {
+    // 4. Выполняем колбэки (run сбросит loading в false)
+    storage.run(data)
+  })
+}
+```
+
+### Одноразовый обратный вызов
+
+Если вам нужно, чтобы функция сработала только один раз (например, для начальной загрузки данных), используйте флаг `isOnce`.
+
+```typescript
+const storage = new StorageCallback('initial-data')
+
+storage.addCallback((data) => {
+  console.log('Выполнено один раз:', data)
+}, true)
+
+await storage.run('update 1') // 'Выполнено один раз: update 1'
+await storage.run('update 2') // (ничего не выводится, callback удален)
+```