@dxtmisha/wiki 0.39.6 → 0.39.8

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

@@ -0,0 +1,153 @@
+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, setListener)` — Инициализирует хранилище с пользовательскими слушателями для чтения и записи данных
+- `reset()` — Сбрасывает хранилище, очищая все элементы в памяти и удаляя слушатели
+
+### Вспомогательные
+
+- `update()` — Обновляет данные в памяти, парся значения из `document.cookie`
+
+## Типы
+
+### `CookieOptions`
+
+Объект конфигурации для параметров cookie:
+
+- `age?: number` — время жизни в секундах (атрибут Max-Age)
+- `sameSite?: 'strict' | 'lax'` — политика SameSite
+- `arguments?: string[]` — дополнительные директивы для строки 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),
+  (key, value, options) => myStorage.set(key, value, options)
+)
+```
+
+### Обновление и сброс
+
+```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),
+  (key, value, options) => redis.set(key, value, options)
+)
+
+// Установка значения с параметрами
+CookieStorage.set('user', 'john', {
+  age: 3600,           // 1 час
+  sameSite: 'lax',     // Политика SameSite
+  arguments: ['Secure', 'Path=/'] // Дополнительные директивы
+})
+
+// Получение значения с преобразованием типа
+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,153 @@
+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, setListener)` — Khởi tạo lưu trữ với người nghe tùy chỉnh để đọc và ghi dữ liệu
+- `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
+- `arguments?: string[]` — 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),
+  (key, value, options) => myStorage.set(key, value, options)
+)
+```
+
+### 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),
+  (key, value, options) => redis.set(key, value, 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
+  arguments: ['Secure', 'Path=/'] // 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())
+```

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

@@ -6,23 +6,31 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 Một lớp linh hoạt để tương tác với `localStorage` và `sessionStorage` của trình duyệt. Nó bao gồm các tiền tố được tích hợp sẵn, thời gian hết hạn bộ đệm (cache), lưu vào bộ nhớ đệm (memory caching) cho các bản sao hoạt động và chuyển đổi JSON tự động.
 
+> `DataStorage` là một **lớp phụ trợ**, được thiết kế để tương tác cấp thấp với bộ nhớ trình duyệt. Trong hầu hết các trường hợp, bạn nên sử dụng các lớp cấp cao hơn như `Cookie` hoặc `Api` cho các nhu cầu dữ liệu cụ thể.
+
 ## Tính năng chính
 
 - **Chuyển đổi Tự động** — tự động xử lý phân tích và chuyển đổi chuỗi JSON cho các cấu hình và đối tượng được lưu trữ.
 - **Bộ nhớ đệm Dựa trên Thời gian** — cho phép lưu các đối tượng cùng với mốc thời gian và tôn trọng các ràng buộc về tuổi đời (age) của dữ liệu trong quá trình truy xuất.
 - **Quản lý Tiền tố** — hỗ trợ cả tiền tố toàn cục và riêng biệt để cách ly cũng như gom nhóm các khóa trong `localStorage`.
-- **Tối ưu Bô nhớ** — tạo ra các singleton cho những khóa giống nhau nhằm tránh các thao tác đọc đĩa bị lặp lại.
+- **Tối ưu Bộ nhớ** — tạo ra các singleton cho những khóa giống nhau nhằm tránh các thao tác đọc đĩa bị lặp lại.
+- **Hỗ trợ SSR** — sử dụng cơ chế cách ly theo từng request trong quá trình render phía server để ngăn chặn rò rỉ dữ liệu giữa các phiên làm việc song song.
 
 ## Khởi tạo
 
 Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `DataStorage(name, isSession)`.
 
+### Ràng buộc Generic (Generic Constraints)
+
+Lớp hỗ trợ generic sau để đảm bảo kiểm soát kiểu dữ liệu nghiêm ngặt cho giá trị được lưu trữ:
+- `T` — Kiểu dữ liệu của giá trị được lưu trữ.
+
 **Tham số:**
 - `name: string` — tên của khóa lưu trữ.
 - `isSession: boolean = false` — có sử dụng `sessionStorage` hay không (mặc định là `localStorage`).
 
 ```typescript
-import { DataStorage } from '@dxtmisha/functional'
+import { DataStorage } from '@dxtmisha/functional-basic'
 
 // 1. Tạo một thực thể cho localStorage
 const settings = new DataStorage('settings')
@@ -31,25 +39,31 @@ const settings = new DataStorage('settings')
 const session = new DataStorage('user_session', true)
 ```
 
-## Cách sử dụng Cơ bản
+## Các phương thức
 
-## Cấu hình toàn cục
+### Truy cập Bộ lưu trữ
 
-- `setPrefix(newPrefix: string): void` (static) — Thay đổi tên tiền tố toàn cục áp dụng cho những instance mới đang định dùng môi trường `localStorage`. Giá trị tiền tố mặc định là `ui-storage`.
+- `get(defaultValue?: T | (() => T), cache?: number): T | undefined` — Truy xuất giá trị hiện được lưu trữ. Nếu thời gian cache được cung cấp, nó sẽ trả về `undefined` nếu dữ liệu đã quá hạn.
+- `set(value?: T | (() => T)): T | undefined` — Thiết lập hoặc cập nhật giá trị trong cơ chế lưu trữ. Truyền `undefined` sẽ xóa mục đó.
+- `remove(): this` — Xóa khóa tương ứng khỏi môi trường lưu trữ và thực thể trong bộ nhớ.
+- `update(): this` — Buộc thực thể bộ nhớ phải đồng bộ hóa với dữ liệu thô hiện tại bên trong các Storage API vật lý.
 
-## Quản lý dữ liệu
+### Cấu hình
 
-### `get`
+- `static setPrefix(newPrefix: string): void` — Thay đổi tiền tố toàn cục áp dụng cho các thực thể mới. Tiền tố mặc định là `ui-storage`.
 
-Truy xuất cấu hình đã phân tích hiện tại được lưu lại từ trước.
+## SSR và Hydration
 
-**Tham số:**
-- `defaultValue?: T | (() => T)` — giá trị dự phòng được trả về nếu bên trong bộ lưu trữ trống rỗng.
-- `cache?: number` — độ tuổi tối đa cho phép (tính bằng giây). Nếu dữ liệu đã cũ hơn mức này, nó sẽ cư xử như thể không có gì được lưu trữ.
+Lớp `DataStorage` hoàn toàn tương thích với Server-Side Rendering (SSR). Nó sử dụng một registry đặc biệt để cách ly các instance giữa các HTTP request khác nhau trên server.
 
-**Trả về:** `T | undefined` — giá trị được lưu trữ hoặc `undefined`.
+> Để tránh lỗi hydration (khi HTML render từ server khác với client), bạn nên gọi phương thức `get()` bên trong `useEffect` hoặc các hook chỉ chạy ở client. Trên server, `get()` sẽ luôn trả về `undefined` (hoặc `defaultValue`) vì `localStorage` không khả dụng.
 
+## Ví dụ
+
+### Sử dụng Giá trị Mặc định và Cache
 ```javascript
+const settings = new DataStorage('user_settings')
+
 // Lấy dữ liệu, trả về object rỗng nếu không tìm thấy
 const currentSettings = settings.get({})
 
@@ -57,20 +71,11 @@ const currentSettings = settings.get({})
 const cachedItem = settings.get(undefined, 60)
 ```
 
-### `set`
-
-Thiết lập hoặc cập nhật một giá trị trong cơ chế lưu trữ.
-
-**Tham số:**
-- `value?: T | (() => T)` — giá trị muốn lưu. Việc truyền `undefined` sẽ loại bỏ mục đó khỏi kho lưu trữ.
-
-**Trả về:** `T | undefined` — giá trị được lưu trữ.
-
+### Đồng bộ hóa Thủ công
 ```javascript
-settings.set({ theme: 'dark', notifications: true })
-```
-
-## Các phương thức bổ sung
+const storage = new DataStorage('shared_data')
 
-- `remove(): this` — Xóa bỏ chính xác khóa lưu trữ tương ứng từ phần môi trường phần mềm `localStorage` hoặc `sessionStorage`, đồng thời lập tức dọn sạch dữ liệu khối nhớ hiện tại.
-- `update(): this` — Buộc bộ đệm đối tượng trong bộ nhớ tự đồng bộ lại thật khít so với dữ liệu rỗng hiện hành bên trong các hàm Storage API vật lý.
+// ... dữ liệu có thể đã thay đổi trong một tab khác hoặc phần khác của ứng dụng
+storage.update() // Đồng bộ hóa bộ nhớ với ổ đĩa
+console.log(storage.get())
+```