@dxtmisha/wiki 0.39.7 → 0.39.8

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.
+- `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 удален)
+```

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

@@ -0,0 +1,97 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Classes/StorageCallback - Storage Callbacks'/>
+
+# Lớp StorageCallback
+
+Một lớp tiện ích để quản lý các nhóm hàm callback liên kết với các khóa lưu trữ cụ thể. Nó cho phép nhiều thành phần hoặc chức năng phản hồi các thay đổi hoặc kích hoạt lưu trữ một cách phối hợp, bất đồng bộ.
+
+## Các đặc điểm chính
+
+- **Các thực thể có tên** — thực hiện mô hình singleton, trong đó các thực thể được truy xuất theo tên và nhóm, đảm bảo rằng các phần khác nhau của ứng dụng chia sẻ cùng một danh sách callback cho cùng một tài nguyên.
+- **Phân tách theo nhóm** — cho phép tách biệt các danh sách callback theo nhóm (ví dụ: 'main', 'global', 'local'), ngăn chặn xung đột tên giữa các mô-đun khác nhau.
+- **Thực thi bất đồng bộ** — hỗ trợ các callback dựa trên `Promise` và thực thi chúng theo trình tự trong quá trình `run`.
+- **Theo dõi trạng thái tải** — cung cấp cờ `loading` có sẵn, được quản lý tự động trong giai đoạn thực thi callback.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm tạo `StorageCallback(name, group)` hoặc sử dụng phương thức tĩnh `getInstance(name, group)`.
+
+### Các ràng buộc Generic
+
+Để đảm bảo kiểu dữ liệu nghiêm ngặt, lớp hỗ trợ các generic sau:
+- `T = any` — Kiểu dữ liệu được truyền cho các callback.
+- `Callback = (value: T) => void | Promise<void>` — Cấu trúc hàm callback.
+
+**Tham số:**
+- `name: string` — định danh duy nhất cho mục nhập lưu trữ.
+- `group: string = 'main'` — phân loại tùy chọn để ngăn chặn xung đột tên.
+
+```typescript
+import { StorageCallback } from '@dxtmisha/functional-basic'
+
+// 1. Khởi tạo đơn giản (nhóm mặc định là 'main')
+const storage = new StorageCallback('user-data')
+
+// 2. Sử dụng phương thức tĩnh getInstance
+const sharedStorage = StorageCallback.getInstance('settings', 'global')
+
+// 3. Sử dụng generic để kiểm soát kiểu dữ liệu
+const numberStorage = new StorageCallback<number>('counter')
+numberStorage.addCallback((val) => console.log(val + 1))
+```
+
+## Các phương thức
+
+### Thông tin
+
+- `getName(): string` — trả về tên của thực thể lưu trữ.
+- `isLoading(): boolean` — trả về trạng thái tải hiện tại.
+- `getLoading(): boolean` — trả về trạng thái tải hiện tại (tương tự `isLoading`).
+
+### Quản lý
+
+- `addCallback(callback: Callback, isOnce?: boolean): this` — thêm một callback mới vào danh sách thực thi. Nếu `isOnce: true`, callback sẽ bị xóa sau lần thực thi đầu tiên.
+- `removeCallback(callback: Callback): this` — xóa một callback cụ thể khỏi danh sách.
+
+### Điều khiển (Control)
+
+- `preparation(): this` — chuẩn bị trạng thái trước khi thực thi (đặt `loading` thành `true`). Được sử dụng thủ công khi bắt đầu các hoạt động bất đồng bộ.
+- `run(value: T): Promise<this>` — thực thi tất cả các callback theo trình tự với giá trị được cung cấp. Đặt `loading` về `false` khi bắt đầu thực thi.
+
+## Ví dụ sử dụng
+
+### Quản lý trạng thái tải thủ công
+
+Khi dữ liệu được lấy bất đồng bộ từ nguồn bên ngoài (ví dụ: Figma storage), bạn có thể quản lý trạng thái `loading` thủ công để điều phối nhiều yêu cầu.
+
+```typescript
+const storage = new StorageCallback('figma-data')
+
+// 1. Kiểm tra nếu không phải đang tải
+if (!storage.isLoading()) {
+  // 2. Thiết lập trạng thái đang tải
+  storage.preparation()
+  
+  // 3. Yêu cầu dữ liệu
+  fetchFromFigma((data) => {
+    // 4. Thực thi callback (run sẽ đưa loading về false)
+    storage.run(data)
+  })
+}
+```
+
+### Callback một lần
+
+Nếu bạn chỉ cần một hàm kích hoạt một lần (ví dụ: để nạp dữ liệu ban đầu), hãy sử dụng cờ `isOnce`.
+
+```typescript
+const storage = new StorageCallback('initial-data')
+
+storage.addCallback((data) => {
+  console.log('Đã thực thi một lần:', data)
+}, true)
+
+await storage.run('update 1') // 'Đã thực thi một lần: update 1'
+await storage.run('update 2') // (không có đầu ra, callback đã bị xóa)
+```

package/src/media/functional/functional-basic/functions/addTagHighlightMatch/addTagHighlightMatch.en.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/en/functional-basic/Functions/addTagHighlightMatch - Highlight matches in a string'/>
 
@@ -8,17 +8,20 @@ A utility for highlighting matches in a string by wrapping them in a `<span>` HT
 
 **Parameters:**
 - `value: string` — The initial string to process.
-- `search?: string` — The search string (one or more words separated by spaces).
+- `search?: string | RegExp` — The search string (one or more words separated by spaces) or a regular expression.
 - `className: string = 'sys-highlight-match'` — The CSS class to be added to the `<span>` tag.
+- `shouldEscape: boolean = false` — Whether to escape the string before adding highlighting.
 
 **Returns:**
 `string` — The string with HTML tags added for highlighting.
 
-```typescript
+<Source
+  language='typescript'
+  code={`
 import { addTagHighlightMatch } from '@dxtmisha/functional-basic'
 
 // Highlight a single word
-addTagHighlightMatch('Hello world', 'hello') 
+addTagHighlightMatch('Hello world', 'hello')
 // '<span class="sys-highlight-match">Hello</span> world'
 
 // Highlight multiple words (OR logic)
@@ -28,4 +31,9 @@ addTagHighlightMatch('Apple and Banana', 'apple banana')
 // Custom class
 addTagHighlightMatch('Test', 'test', 'text-red')
 // '<span class="text-red">Test</span>'
-```
+
+// With escaping
+addTagHighlightMatch('<b>bold</b>', 'bold', 'sys-highlight-match', true)
+// '&lt;b&gt;<span class="sys-highlight-match">bold</span>&lt;/b&gt;'
+  `}
+/>

package/src/media/functional/functional-basic/functions/addTagHighlightMatch/addTagHighlightMatch.ru.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/ru/functional-basic/Functions/addTagHighlightMatch - Подсветка совпадений в строке'/>
 
@@ -8,17 +8,20 @@ import { Meta } from '@storybook/addon-docs/blocks'
 
 **Параметры:**
 - `value: string` — Исходная строка для обработки.
-- `search?: string` — Строка поиска (одно или несколько слов через пробел).
+- `search?: string | RegExp` — Строка поиска (одно или несколько слов через пробел) или регулярное выражение.
 - `className: string = 'sys-highlight-match'` — CSS-класс, который будет добавлен к тегу `<span>`.
+- `shouldEscape: boolean = false` — Нужно ли экранировать строку перед добавлением подсветки.
 
 **Возвращает:**
 `string` — Строка с добавленными HTML-тегами для подсветки.
 
-```typescript
+<Source
+  language='typescript'
+  code={`
 import { addTagHighlightMatch } from '@dxtmisha/functional-basic'
 
 // Подсветка одного слова
-addTagHighlightMatch('Hello world', 'hello') 
+addTagHighlightMatch('Hello world', 'hello')
 // '<span class="sys-highlight-match">Hello</span> world'
 
 // Подсветка нескольких слов (OR-логика)
@@ -28,4 +31,9 @@ addTagHighlightMatch('Apple and Banana', 'apple banana')
 // Кастомный класс
 addTagHighlightMatch('Test', 'test', 'text-red')
 // '<span class="text-red">Test</span>'
-```
+
+// С экранированием
+addTagHighlightMatch('<b>bold</b>', 'bold', 'sys-highlight-match', true)
+// '&lt;b&gt;<span class="sys-highlight-match">bold</span>&lt;/b&gt;'
+  `}
+/>

package/src/media/functional/functional-basic/functions/addTagHighlightMatch/addTagHighlightMatch.vi.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/vi/functional-basic/Functions/addTagHighlightMatch - Làm nổi bật các kết quả khớp trong chuỗi'/>
 
@@ -8,17 +8,20 @@ Tiện ích để làm nổi bật các kết quả khớp trong một chuỗi b
 
 **Tham số:**
 - `value: string` — Chuỗi ban đầu để xử lý.
-- `search?: string` — Chuỗi tìm kiếm (một hoặc nhiều từ phân tách bằng dấu cách).
+- `search?: string | RegExp` — Chuỗi tìm kiếm (một hoặc nhiều từ phân tách bằng dấu cách) hoặc biễu thức chính quy.
 - `className: string = 'sys-highlight-match'` — Class CSS sẽ được thêm vào thẻ `<span>`.
+- `shouldEscape: boolean = false` — Có nên thoát chuỗi trước khi thêm làm nổi bật hay không.
 
 **Trả về:**
 `string` — Chuỗi với các thẻ HTML được thêm vào để làm nổi bật.
 
-```typescript
+<Source
+  language='typescript'
+  code={`
 import { addTagHighlightMatch } from '@dxtmisha/functional-basic'
 
 // Làm nổi bật một từ đơn
-addTagHighlightMatch('Hello world', 'hello') 
+addTagHighlightMatch('Hello world', 'hello')
 // '<span class="sys-highlight-match">Hello</span> world'
 
 // Làm nổi bật nhiều từ (logic OR)
@@ -28,4 +31,9 @@ addTagHighlightMatch('Apple and Banana', 'apple banana')
 // Class tùy chỉnh
 addTagHighlightMatch('Test', 'test', 'text-red')
 // '<span class="text-red">Test</span>'
-```
+
+// Với thoát chuỗi (escaping)
+addTagHighlightMatch('<b>bold</b>', 'bold', 'sys-highlight-match', true)
+// '&lt;b&gt;<span class="sys-highlight-match">bold</span>&lt;/b&gt;'
+  `}
+/>

package/src/media/functional/functional-basic/functions/anyToString/anyToString.en.mdx

@@ -1,33 +1,51 @@
-import { Meta } from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
 <Meta title='@dxtmisha/en/functional-basic/Functions/anyToString - Conversion of a value to a string'/>
 
 # `anyToString`
 
-A utility that safely converts any input data into a string type.
-
-This is useful when outputting data to the interface when the variable type (object, array, boolean, or null) is not known in advance.
+A utility for safely converting any input data into a string type.
 
 **Parameters:**
-- `value: V` — Values for conversion.
-- `isArrayString: boolean` (optional, default: `true`) — If `true`, arrays of primitives will be joined by commas. If `false`, they will be stringified as JSON.
+- `value: V` — The value for conversion.
+- `isArrayString: boolean = true` — If `true`, primitive arrays are joined by commas.
+- `trim: boolean = true` — If `true`, trims leading and trailing whitespace (only for strings).
+
+**Conversion Rules:**
+- **Strings**: Returned as is (with `trim` if enabled).
+- **Arrays**: If `isArrayString: true` and no objects are in the array, elements are joined by commas. Otherwise, JSON stringified.
+- **Objects**: Converted to JSON. In case of error (e.g., circular reference), returns standard `toString()`.
+- **Boolean**: `true` converts to `'1'`, `false` to `'0'`.
+- **Other types**: `null` and `undefined` result in an empty string. Others call `toString()`.
 
 **Returns:**
-`string` — The string representation of the provided value.
+`string` — The string representation of the value.
+
+## Examples
 
-```typescript
+<Source
+  language='typescript'
+  code={`
 import { anyToString } from '@dxtmisha/functional-basic'
 
-console.log(anyToString(' test ')) // 'test' (trimmed)
-console.log(anyToString([1, 2, 3])) // '1,2,3' (isArrayString = true)
-console.log(anyToString([1, 2, 3], false)) // '[1,2,3]' (isArrayString = false)
+// 1. Strings
+anyToString('  Hello  ')               // 'Hello'
+anyToString('  Hello  ', true, false)  // '  Hello  '
+
+// 2. Arrays
+anyToString([1, 2, 3])                 // '1,2,3'
+anyToString([1, 2, 3], false)          // '[1,2,3]'
+
+// 3. Objects
+anyToString({ a: 1 })                  // '{"a":1}'
 
-console.log(anyToString([[1], [2]])) // '[[1],[2]]' (nested arrays are stringified as JSON)
-console.log(anyToString([{ a: 1 }, 2])) // '[{"a":1},2]' (arrays with objects are stringified as JSON)
+// 4. Boolean values (1/0 conversion)
+anyToString(true)                      // '1'
+anyToString(false)                     // '0'
 
-console.log(anyToString({ a: 1 })) // '{"a":1}'
-console.log(anyToString(true)) // '1'
-console.log(anyToString(false)) // '0'
-console.log(anyToString(123)) // '123'
-console.log(anyToString(null)) // ''
-```
+// 5. Empty values and types
+anyToString(null)                      // ''
+anyToString(123)                       // '123'
+anyToString(Symbol('test'))            // 'Symbol(test)'
+  `}
+/>