@dxtmisha/wiki 0.39.7 → 0.56.0

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

@@ -0,0 +1,178 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Classes/CookieStorage - Хранилище Cookie'/>
+
+# Класс CookieStorage
+
+Класс для управления хранением cookie с поддержкой пользовательских слушателей. Предоставляет низкоуровневый интерфейс для работы с cookie в различных окружениях (DOM, SSR) с автоматическим парсингом типов и безопасной обработкой данных.
+
+Включает тесную интеграцию с `CookieBlock` для контроля доступа и поддерживает декодирование URL-encoded значений.
+
+## Ключевые особенности
+
+- **Гибкое хранение** — поддержка памяти процесса и внешних механизмов хранения через слушатели
+- **Автоматическое преобразование** — интеллектуальное преобразование строковых значений в соответствующие типы данных
+- **Интеграция с блокировкой** — уважает глобальную блокировку записи через `CookieBlock`
+- **Безопасность окружения** — автоматическое определение DOM окружения и адаптация поведения
+- **URL-декодирование** — автоматическое декодирование имен и значений при чтении из DOM
+
+## Статические методы
+
+### Действие
+
+#### `get`
+
+Получает значение cookie по имени с автоматическим преобразованием типов. Если значение не существует и указано значение по умолчанию, оно будет установлено и сохранено.
+
+**Параметры:**
+- `name: string` — имя cookie
+- `defaultValue?: T | (() => T)` — значение по умолчанию или функция, возвращающая значение
+
+**Возвращает:** `T | undefined` — преобразованное значение cookie или значение по умолчанию
+
+#### `set`
+
+Сохраняет значение cookie с указанными параметрами и автоматическим обновлением в памяти и DOM. Если активна блокировка через `CookieBlock`, значение сохраняется только в памяти.
+
+**Параметры:**
+- `name: string` — имя cookie
+- `value: T | (() => T)` — значение или функция, возвращающая значение
+- `options?: CookieOptions` — дополнительные параметры cookie
+
+**Возвращает:** `T` — сохраненное значение
+
+#### `remove`
+
+Удаляет cookie, устанавливая пустое значение и отрицательный срок действия. Эквивалентно вызову `set(name, '', { age: -1 })`.
+
+**Параметры:**
+- `name: string` — имя cookie
+
+### Конфигурация
+
+- `init(getListener?, getListenerRaw?, setListener?)` — Инициализирует хранилище с пользовательскими слушателями для чтения и записи данных. Слушатель записи `setListener` принимает 4 аргумента: `(key, value, cookie, options)`.
+- `reset()` — Сбрасывает хранилище, очищая все элементы в памяти и удаляя слушатели
+
+### Вспомогательные
+
+- `update()` — Обновляет данные в памяти, парся значения из `document.cookie`
+
+## Типы
+
+### `CookieOptions`
+
+Объект конфигурации для параметров cookie:
+
+- `age?: number` — время жизни в секундах (атрибут max-age)
+- `sameSite?: 'strict' | 'lax'` — политика SameSite
+- `path?: string` — путь для cookie (по умолчанию `/`)
+- `domain?: string` — домен для cookie
+- `secure?: boolean` — если true, добавляет атрибут Secure
+- `httpOnly?: boolean` — если true, добавляет атрибут HttpOnly (только для серверных слушателей)
+- `partitioned?: boolean` — если true, добавляет атрибут Partitioned (CHIPS)
+- `arguments?: string[] | Record<string, any>` — дополнительные директивы для строки cookie
+
+## Встроенное преобразование типов
+
+`CookieStorage` автоматически преобразует строковые значения при чтении:
+
+- `'undefined'` → `undefined`
+- `'null'` → `null`
+- `'true'` → `true`
+- `'false'` → `false`
+- `'123'` → `123` (число)
+- `'{"key":"value"}'` → `{key: 'value'}` (объект JSON)
+
+## Примеры
+
+### Базовое использование
+
+```typescript
+import { CookieStorage } from '@dxtmisha/functional-basic'
+
+// Получение значения с дефолтным значением
+const theme = CookieStorage.get<string>('theme', 'dark')
+
+// Сохранение значения
+CookieStorage.set('user', 'john', {
+  age: 3600,
+  sameSite: 'lax'
+})
+
+// Удаление
+CookieStorage.remove('user')
+```
+
+### Инициализация с внешним хранилищем
+
+```typescript
+import { CookieStorage } from '@dxtmisha/functional-basic'
+
+CookieStorage.init(
+  (key) => myStorage.get(key),
+  undefined,
+  (key, value, cookie, options) => {
+    // cookie - это уже отформатированная строка типа "key=value; max-age=..."
+    myStorage.set(key, value, cookie, options)
+  }
+)
+```
+
+### Инициализация для SSR (Raw)
+
+```typescript
+import { CookieStorage } from '@dxtmisha/functional-basic'
+
+// Для SSR получаем все куки в виде сырой строки
+CookieStorage.init(
+  undefined,
+  () => request.headers.cookie
+)
+```
+
+### Обновление и сброс
+
+```typescript
+import { CookieStorage } from '@dxtmisha/functional-basic'
+
+// Обновить данные в памяти из document.cookie
+// Полезно, когда куки были установлены внешне
+CookieStorage.update()
+
+// Сбросить хранилище (очистить слушатели и данные в памяти)
+// Полезно для тестирования или очистки
+CookieStorage.reset()
+```
+
+### Полный рабочий процесс
+
+```typescript
+import { CookieStorage } from '@dxtmisha/functional-basic'
+
+// Инициализация с пользовательским хранилищем
+CookieStorage.init(
+  (key) => redis.get(key),
+  undefined,
+  (key, value, cookie, options) => redis.set(key, value, cookie, options)
+)
+
+// Установка значения с параметрами
+CookieStorage.set('user', 'john', {
+  age: 3600,           // 1 час
+  sameSite: 'lax',     // Политика SameSite
+  path: '/',           // Путь
+  secure: true,        // Только HTTPS
+  httpOnly: true,      // Защита от XSS (для SSR)
+  arguments: ['Priority=High'] // Дополнительные директивы
+})
+
+// Получение значения с преобразованием типа
+const user = CookieStorage.get<string>('user')
+
+// Обновление из внешнего источника
+CookieStorage.update()
+
+// Очистка
+CookieStorage.remove('user')
+CookieStorage.reset()
+```

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

@@ -0,0 +1,178 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/CookieStorage - Lưu trữ Cookie'/>
+
+# Lớp CookieStorage
+
+Lớp quản lý lưu trữ cookie với hỗ trợ người nghe tùy chỉnh. Cung cấp giao diện cấp thấp để làm việc với cookie trong các môi trường khác nhau (DOM, SSR) với phân tích tự động kiểu và xử lý dữ liệu an toàn.
+
+Bao gồm tích hợp chặt chẽ với `CookieBlock` để kiểm soát truy cập và hỗ trợ giải mã các giá trị đã được mã hóa URL.
+
+## Các tính năng chính
+
+- **Lưu trữ linh hoạt** — hỗ trợ bộ nhớ quy trình và cơ chế lưu trữ bên ngoài thông qua người nghe
+- **Phân tích tự động** — chuyển đổi thông minh các giá trị chuỗi thành các loại dữ liệu tương ứng
+- **Tích hợp chặn** — tôn trọng chặn ghi toàn cầu qua `CookieBlock`
+- **Nhận thức môi trường** — tự động phát hiện môi trường DOM và thích ứng hành vi
+- **Giải mã URL** — tự động giải mã tên và giá trị khi đọc từ DOM
+
+## Phương thức tĩnh
+
+### Hành động
+
+#### `get`
+
+Lấy giá trị cookie theo tên với chuyển đổi kiểu tự động. Nếu giá trị không tồn tại và có chỉ định giá trị mặc định, nó sẽ được thiết lập và lưu trữ.
+
+**Tham số:**
+- `name: string` — tên cookie
+- `defaultValue?: T | (() => T)` — giá trị mặc định hoặc hàm trả về giá trị
+
+**Trả về:** `T | undefined` — giá trị cookie đã chuyển đổi hoặc giá trị mặc định
+
+#### `set`
+
+Lưu giá trị cookie với các tham số được chỉ định và cập nhật tự động trong bộ nhớ và DOM. Nếu chặn đang hoạt động qua `CookieBlock`, giá trị chỉ được lưu trong bộ nhớ.
+
+**Tham số:**
+- `name: string` — tên cookie
+- `value: T | (() => T)` — giá trị hoặc hàm trả về giá trị
+- `options?: CookieOptions` — tham số cookie bổ sung
+
+**Trả về:** `T` — giá trị đã lưu
+
+#### `remove`
+
+Xóa cookie bằng cách đặt giá trị rỗng và thời hạn hết hạn âm. Tương đương với việc gọi `set(name, '', { age: -1 })`.
+
+**Tham số:**
+- `name: string` — tên cookie
+
+### Cấu hình
+
+- `init(getListener?, getListenerRaw?, setListener?)` — Khởi tạo bộ nhớ với các trình lắng nghe tùy chỉnh để đọc và ghi dữ liệu. Trình lắng nghe ghi `setListener` chấp nhận 4 đối số: `(key, value, cookie, options)`.
+- `reset()` — Đặt lại lưu trữ bằng cách xóa tất cả phần tử trong bộ nhớ và xóa người nghe
+
+### Hỗ trợ
+
+- `update()` — Cập nhật dữ liệu trong bộ nhớ bằng cách phân tích giá trị từ `document.cookie`
+
+## Các loại
+
+### `CookieOptions`
+
+Đối tượng cấu hình cho tham số cookie:
+
+- `age?: number` — thời gian tồn tại tính bằng giây (thuộc tính max-age)
+- `sameSite?: 'strict' | 'lax'` — chính sách SameSite
+- `path?: string` — đường dẫn cho cookie (mặc định là `/`)
+- `domain?: string` — tên miền cho cookie
+- `secure?: boolean` — nếu đúng, thêm thuộc tính Secure
+- `httpOnly?: boolean` — nếu đúng, thêm thuộc tính HttpOnly (chỉ dành cho trình lắng nghe phía máy chủ)
+- `partitioned?: boolean` — nếu đúng, thêm thuộc tính Partitioned (CHIPS)
+- `arguments?: string[] | Record<string, any>` — các chỉ thị bổ sung cho chuỗi cookie
+
+## Chuyển đổi loại tích hợp
+
+`CookieStorage` tự động chuyển đổi các giá trị chuỗi khi đọc:
+
+- `'undefined'` → `undefined`
+- `'null'` → `null`
+- `'true'` → `true`
+- `'false'` → `false`
+- `'123'` → `123` (số)
+- `'{"key":"value"}'` → `{key: 'value'}` (đối tượng JSON)
+
+## Ví dụ
+
+### Sử dụng cơ bản
+
+```typescript
+import { CookieStorage } from '@dxtmisha/functional-basic'
+
+// Lấy với giá trị mặc định
+const theme = CookieStorage.get<string>('theme', 'dark')
+
+// Lưu giá trị
+CookieStorage.set('user', 'john', {
+  age: 3600,
+  sameSite: 'lax'
+})
+
+// Xóa
+CookieStorage.remove('user')
+```
+
+### Khởi tạo với lưu trữ bên ngoài
+
+```typescript
+import { CookieStorage } from '@dxtmisha/functional-basic'
+
+CookieStorage.init(
+  (key) => myStorage.get(key),
+  undefined,
+  (key, value, cookie, options) => {
+    // cookie là chuỗi đã được định dạng như "key=value; max-age=..."
+    myStorage.set(key, value, cookie, options)
+  }
+)
+```
+
+### Khởi tạo cho SSR (Raw)
+
+```typescript
+import { CookieStorage } from '@dxtmisha/functional-basic'
+
+// Đối với SSR, lấy tất cả cookie dưới dạng chuỗi thô
+CookieStorage.init(
+  undefined,
+  () => request.headers.cookie
+)
+```
+
+### Cập nhật và đặt lại
+
+```typescript
+import { CookieStorage } from '@dxtmisha/functional-basic'
+
+// Cập nhật dữ liệu trong bộ nhớ từ document.cookie
+// Hữu ích khi cookie được đặt từ bên ngoài
+CookieStorage.update()
+
+// Đặt lại lưu trữ (xóa người nghe và dữ liệu trong bộ nhớ)
+// Hữu ích cho kiểm thử hoặc dọn dẹp
+CookieStorage.reset()
+```
+
+### Quy trình làm việc hoàn chỉnh
+
+```typescript
+import { CookieStorage } from '@dxtmisha/functional-basic'
+
+// Khởi tạo với lưu trữ tùy chỉnh
+CookieStorage.init(
+  (key) => redis.get(key),
+  undefined,
+  (key, value, cookie, options) => redis.set(key, value, cookie, options)
+)
+
+// Đặt giá trị với các tùy chọn
+CookieStorage.set('user', 'john', {
+  age: 3600,           // 1 giờ
+  sameSite: 'lax',     // Chính sách SameSite
+  path: '/',           // Đường dẫn
+  secure: true,        // Chỉ HTTPS
+  httpOnly: true,      // Bảo vệ XSS (cho SSR)
+  arguments: ['Priority=High'] // Các chỉ thị bổ sung
+})
+
+// Nhận giá trị với chuyển đổi loại
+const user = CookieStorage.get<string>('user')
+
+// Cập nhật từ nguồn bên ngoài
+CookieStorage.update()
+
+// Dọn dẹp
+CookieStorage.remove('user')
+CookieStorage.reset()
+```

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

@@ -6,23 +6,31 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 A versatile class for interacting with the browser's `localStorage` and `sessionStorage`. It features built-in prefixes, cache expiration, memory caching for active instances, and automatic JSON serialization.
 
+> `DataStorage` is an **auxiliary class**, designed for low-level interaction with browser storage. In most cases, it is recommended to use higher-level classes like `Cookie` or `Api` for specific data needs.
+
 ## Key Features
 
 - **Automatic Serialization** — seamlessly handles JSON parsing and stringifying for stored configurations and objects.
 - **Time-based Caching** — allows saving objects with timestamps and respects age constraints during data retrieval.
 - **Prefix Management** — supports global and instance-specific prefixes to isolate and group keys within `localStorage`.
 - **Memory Efficiency** — creates singletons for identical keys, avoiding duplicate reads from disk.
+- **SSR Ready** — uses request-specific isolation during server-side rendering to prevent data leaks between parallel requests.
 
 ## Initialization
 
 To initialize the object, call the `DataStorage(name, isSession)` constructor.
 
+### Generic Constraints
+
+The class supports the following generic to ensure strict typing of the stored value:
+- `T` — The type of the value being stored.
+
 **Parameters:**
 - `name: string` — the name of the storage key.
 - `isSession: boolean = false` — whether to use `sessionStorage` (defaults to `localStorage`).
 
 ```typescript
-import { DataStorage } from '@dxtmisha/functional'
+import { DataStorage } from '@dxtmisha/functional-basic'
 
 // 1. Create an instance for localStorage
 const settings = new DataStorage('settings')
@@ -31,23 +39,31 @@ const settings = new DataStorage('settings')
 const session = new DataStorage('user_session', true)
 ```
 
-## Global Settings
+## Methods
 
-- `setPrefix(newPrefix: string): void` (static) — Changes the global prefix applied to new instances attempting to use `localStorage`. The default prefix is `ui-storage`.
+### Storage Access
 
-## Data Management
+- `get(defaultValue?: T | (() => T), cache?: number): T | undefined` — Retrieves the currently saved value. If a cache time is provided, it returns `undefined` if the data is stale.
+- `set(value?: T | (() => T)): T | undefined` — Sets or updates the value in the storage mechanism. Passing `undefined` deletes the item.
+- `remove(): this` — Clears the corresponding key from the storage environment and the memory instance.
+- `update(): this` — Forces the memory instance to synchronize with the current raw data inside the physical Storage APIs.
 
-### `get`
+### Configuration
 
-Retrieves the currently saved structured configuration.
+- `static setPrefix(newPrefix: string): void` — Changes the global prefix applied to new instances. The default prefix is `ui-storage`.
 
-**Parameters:**
-- `defaultValue?: T | (() => T)` — a fallback value to return if the storage is empty.
-- `cache?: number` — maximum allowed age (in seconds). If the data is older, it behaves as if nothing was stored.
+## SSR and Hydration
 
-**Returns:** `T | undefined` — the stored value or `undefined`.
+The `DataStorage` class is fully compatible with Server-Side Rendering (SSR). It uses a special registry to isolate instances between different HTTP requests on the server.
 
+> To avoid hydration mismatches (when the server-rendered HTML differs from the client-rendered one), it is recommended to call `get()` inside `useEffect` or other client-only hooks. On the server, `get()` will return `undefined` (or the `defaultValue`), as `localStorage` is not available.
+
+## Examples
+
+### Using Default Values and Cache
 ```javascript
+const settings = new DataStorage('user_settings')
+
 // Get data, falling back to an empty object if not found
 const currentSettings = settings.get({})
 
@@ -55,20 +71,11 @@ const currentSettings = settings.get({})
 const cachedItem = settings.get(undefined, 60)
 ```
 
-### `set`
-
-Sets or updates the value in the storage mechanism.
-
-**Parameters:**
-- `value?: T | (() => T)` — the value to save. Passing `undefined` will delete the item from storage.
-
-**Returns:** `T | undefined` — the stored value.
-
+### Manual Synchronization
 ```javascript
-settings.set({ theme: 'dark', notifications: true })
-```
-
-## Additional Methods
+const storage = new DataStorage('shared_data')
 
-- `remove(): this` — Clears the corresponding key actively from the `localStorage` or `sessionStorage` environments, and immediately unsets the existing memory instance.
-- `update(): this` — Forces the memory instance to synchronize tightly with the current raw data inside the physical Storage APIs.
+// ... data might be changed in another tab or part of the app
+storage.update() // Sync memory instance with disk
+console.log(storage.get())
+```

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

@@ -6,23 +6,31 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 Универсальный класс для взаимодействия с `localStorage` и `sessionStorage` браузера. Включает в себя автоматическое создание префиксов, ограничение срока действия кэша (возраст), кэширование в памяти для активных экземпляров и автоматическую сериализацию JSON.
 
+> `DataStorage` является **вспомогательным классом**, предназначенным для низкоуровневого взаимодействия с хранилищем браузера. В большинстве случаев рекомендуется использовать специализированные классы, такие как `Cookie` или `Api`, для конкретных задач.
+
 ## Основные возможности
 
 - **Автоматическая сериализация** — легко справляется с разбором и преобразованием в JSON-строку при хранении конфигураций и объектов.
 - **Хранение с учётом времени** — позволяет сохранять объекты с временными метками и учитывать ограничения по возрасту значения во время его извлечения.
 - **Управление префиксами** — поддерживает глобальные и специфичные для каждого экземпляра префиксы, позволяющие изолировать и группировать ключи в рамках `localStorage`.
 - **Эффективная память** — создает паттерн singleton для идентичных ключей, чтобы избежать одновременного чтения непосредственно с диска.
+- **Поддержка SSR** — использует изоляцию на уровне запросов при серверном рендеринге, предотвращая утечку данных между параллельными сессиями.
 
 ## Инициализация
 
 Для инициализации объекта вызовите конструктор `DataStorage(name, isSession)`.
 
+### Ограничения дженериков (Generic Constraints)
+
+Класс поддерживает следующий дженерик для обеспечения строгой типизации сохраняемого значения:
+- `T` — Тип данных, хранящихся в хранилище.
+
 **Параметры:**
 - `name: string` — название ключа в хранилище.
 - `isSession: boolean = false` — нужно ли использовать `sessionStorage` (по умолчанию `localStorage`).
 
 ```typescript
-import { DataStorage } from '@dxtmisha/functional'
+import { DataStorage } from '@dxtmisha/functional-basic'
 
 // 1. Создание экземпляра для localStorage
 const settings = new DataStorage('settings')
@@ -31,23 +39,31 @@ const settings = new DataStorage('settings')
 const session = new DataStorage('user_session', true)
 ```
 
-## Глобальная настройка
+## Методы
 
-- `setPrefix(newPrefix: string): void` (static) — Изменяет глобальный префикс, применяемый ко всем новым экземплярам. Префикс по умолчанию — `ui-storage`.
+### Доступ к хранилищу
 
-## Управление данными
+- `get(defaultValue?: T | (() => T), cache?: number): T | undefined` — Извлекает текущее сохраненное значение. Если указано время кэширования, возвращает `undefined`, если данные устарели.
+- `set(value?: T | (() => T)): T | undefined` — Устанавливает или обновляет значение в хранилище. Передача `undefined` удаляет элемент.
+- `remove(): this` — Удаляет соответствующий ключ из хранилища и очищает экземпляр в памяти.
+- `update(): this` — Принудительно синхронизирует экземпляр памяти с актуальными данными из Storage API.
 
-### `get`
+### Конфигурация
 
-Получает текущую сохранённую структурированную конфигурацию.
+- `static setPrefix(newPrefix: string): void` — Изменяет глобальный префикс, применяемый ко всем новым экземплярам. Префикс по умолчанию — `ui-storage`.
 
-**Параметры:**
-- `defaultValue?: T | (() => T)` — запасное значение, которое будет возвращено, если хранилище пусто.
-- `cache?: number` — максимально допустимый возраст (в секундах). Если данные старше, они считаются не существующими.
+## SSR и Гидратация
 
-**Возвращает:** `T | undefined` — сохраненное значение или `undefined`.
+Класс `DataStorage` полностью совместим с серверным рендерингом (SSR). Он использует специальный реестр для изоляции экземпляров между различными HTTP-запросами на сервере.
 
+> Чтобы избежать ошибок гидратации (когда HTML от сервера не совпадает с клиентским), рекомендуется вызывать метод `get()` внутри `useEffect` или других клиентских хуков. На сервере `get()` всегда будет возвращать `undefined` (или `defaultValue`), так как `localStorage` недоступен.
+
+## Примеры
+
+### Использование значений по умолчанию и кэша
 ```javascript
+const settings = new DataStorage('user_settings')
+
 // Получение данных с откатом к пустому объекту, если они не найдены
 const currentSettings = settings.get({})
 
@@ -55,20 +71,11 @@ const currentSettings = settings.get({})
 const cachedItem = settings.get(undefined, 60)
 ```
 
-### `set`
-
-Устанавливает или обновляет значение в механизме хранения.
-
-**Параметры:**
-- `value?: T | (() => T)` — значение для сохранения. Передача `undefined` удалит элемент из хранилища.
-
-**Возвращает:** `T | undefined` — сохраненное значение.
-
+### Ручная синхронизация
 ```javascript
-settings.set({ theme: 'dark', notifications: true })
-```
-
-## Дополнительные методы
+const storage = new DataStorage('shared_data')
 
-- `remove(): this` — Активно удаляет соответствующий ключ из среды `localStorage` или `sessionStorage`, а также немедленно очищает существующее значение в памяти.
-- `update(): this` — Принудительно синхронизирует экземпляр памяти с текущими данными (raw) внутри физических API Storage.
+// ... данные могли быть изменены в другой вкладке или части приложения
+storage.update() // Синхронизируем память с диском
+console.log(storage.get())
+```