@dxtmisha/wiki 0.25.1 → 0.39.2

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

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Functions/domQuerySelectorAll - Select DOM elements'/>
+
+# `domQuerySelectorAll`
+
+Finds and returns a list of all HTML elements that match the specified CSS selectors. The returned result is a static (non-live) `NodeList`.
+
+The function checks for the presence of a browser (DOM) environment via `isDomRuntime()`. If executed on the server or in an environment without a DOM, it returns `undefined`.
+
+**Parameters:**
+- `selectors: string` — A string containing one or more selectors to search for.
+
+**Returns:**
+`NodeListOf<E> | undefined` — A collection of matching elements (which could be an empty list if no matches are found), or `undefined` if the DOM is unavailable.
+
+```typescript
+import { domQuerySelectorAll } from '@dxtmisha/functional-basic'
+
+// Find all elements with a specific class
+const items = domQuerySelectorAll('.list-item')
+
+if (items) {
+  items.forEach(item => {
+    item.classList.add('active')
+  })
+}
+```

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

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Functions/domQuerySelectorAll - Выбор элементов в DOM'/>
+
+# `domQuerySelectorAll`
+
+Ищет и возвращает список всех HTML-элементов, соответствующих указанным CSS-селекторам. Возвращаемый результат представляет собой статический (не живой) `NodeList`.
+
+Функция проверяет наличие браузерного (DOM) окружения посредством вызова `isDomRuntime()`. На сервере или в среде без DOM возвращается `undefined`.
+
+**Параметры:**
+- `selectors: string` — Строка, содержащая один или несколько селекторов для поиска.
+
+**Возвращает:**
+`NodeListOf<E> | undefined` — Коллекцию найденных элементов (может быть пустой, если ничего не найдено), либо `undefined`, если DOM недоступен.
+
+```typescript
+import { domQuerySelectorAll } from '@dxtmisha/functional-basic'
+
+// Поиск всех элементов с определенным классом
+const items = domQuerySelectorAll('.list-item')
+
+if (items) {
+  items.forEach(item => {
+    item.classList.add('active')
+  })
+}
+```

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

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Functions/domQuerySelectorAll - Chọn các phần tử DOM'/>
+
+# `domQuerySelectorAll`
+
+Tìm và trả về một danh sách tất cả các phần tử HTML khớp với bộ chọn CSS được chỉ định. Kết quả trả về là một `NodeList` tĩnh (không tự động cập nhật).
+
+Hàm kiểm tra sự tồn tại của môi trường trình duyệt (DOM) thông qua `isDomRuntime()`. Nếu được thực thi trên máy chủ hoặc môi trường không có DOM, hàm sẽ trả về `undefined`.
+
+**Tham số:**
+- `selectors: string` — Một chuỗi chứa một hoặc nhiều bộ chọn để tìm kiếm.
+
+**Trả về:**
+`NodeListOf<E> | undefined` — Một tập hợp các phần tử khớp (có thể là một mảng rỗng nếu không tìm thấy), hoặc `undefined` nếu không có quyền truy cập DOM.
+
+```typescript
+import { domQuerySelectorAll } from '@dxtmisha/functional-basic'
+
+// Tìm tất cả phần tử có class nhất định
+const items = domQuerySelectorAll('.list-item')
+
+if (items) {
+  items.forEach(item => {
+    item.classList.add('active')
+  })
+}
+```

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

@@ -0,0 +1,25 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Functions/encodeAttribute - Encode characters for attributes'/>
+
+# `encodeAttribute`
+
+Encodes special characters in a string (`&`, `<`, `>`, `"`, `'`) into their corresponding HTML entities (`&amp;`, `&lt;`, `&gt;`, `&quot;`, `&#39;`). This is essential for safely inserting user or dynamic text into HTML attributes to prevent XSS attacks.
+
+Additionally, the function trims whitespace from the edges of the string using the `.trim()` method.
+
+**Parameters:**
+- `text: string` — The string to encode.
+
+**Returns:**
+`string` — The encoded string, trimmed of extra edge whitespace.
+
+```typescript
+import { encodeAttribute } from '@dxtmisha/functional-basic'
+
+const unsafeInput = ' <script>alert("XSS")</script> '
+const safeAttr = encodeAttribute(unsafeInput)
+
+console.log(safeAttr)
+// '&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;'
+```

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

@@ -0,0 +1,25 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Functions/encodeAttribute - Кодирование символов для атрибутов'/>
+
+# `encodeAttribute`
+
+Кодирует специальные символы в строке (`&`, `<`, `>`, `"`, `'`) в соответствующие HTML-сущности (`&amp;`, `&lt;`, `&gt;`, `&quot;`, `&#39;`). Это необходимо для безопасной вставки пользовательского или динамического текста в HTML-атрибуты для предотвращения XSS-атак.
+
+Кроме того, функция удаляет пробельные символы по краям строки с помощью метода `.trim()`.
+
+**Параметры:**
+- `text: string` — Строка, которую необходимо закодировать.
+
+**Возвращает:**
+`string` — Закодированная и очищенная от лишних пробелов по краям строка.
+
+```typescript
+import { encodeAttribute } from '@dxtmisha/functional-basic'
+
+const unsafeInput = ' <script>alert("XSS")</script> '
+const safeAttr = encodeAttribute(unsafeInput)
+
+console.log(safeAttr)
+// '&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;'
+```

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

@@ -0,0 +1,25 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Functions/encodeAttribute - Mã hóa ký tự cho thuộc tính'/>
+
+# `encodeAttribute`
+
+Mã hóa các ký tự đặc biệt trong chuỗi (`&`, `<`, `>`, `"`, `'`) thành các thực thể HTML tương ứng (`&amp;`, `&lt;`, `&gt;`, `&quot;`, `&#39;`). Điều này là cần thiết để chèn văn bản người dùng hoặc văn bản động vào thuộc tính HTML một cách an toàn nhằm phòng chống tấn công XSS.
+
+Hơn nữa, hàm cũng loại bỏ các khoảng trắng ở hai đầu chuỗi bằng phương thức `.trim()`.
+
+**Tham số:**
+- `text: string` — Chuỗi cần được mã hóa.
+
+**Trả về:**
+`string` — Chuỗi đã được mã hóa và xóa khoảng trắng dư thừa ở hai đầu.
+
+```typescript
+import { encodeAttribute } from '@dxtmisha/functional-basic'
+
+const unsafeInput = ' <script>alert("XSS")</script> '
+const safeAttr = encodeAttribute(unsafeInput)
+
+console.log(safeAttr)
+// '&lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;'
+```

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

@@ -0,0 +1,26 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Functions/ensureMaxSize - Resize image to fit maximum size'/>
+
+# `ensureMaxSize`
+
+Ensures that an image does not exceed the maximum size by resizing it if needed. It returns the image as a Base64 string.
+
+This function is useful for optimizing images before uploading them to a server, reducing bandwidth usage and storage requirements.
+
+**Parameters:**
+- `file: Uint8Array` — The image file as a `Uint8Array`.
+- `compress: number` (optional, default: `0.56`) — The maximum size as a fraction of the original size.
+- `type: string` (optional, default: `'image/jpeg'`) — The MIME type of the output image.
+
+**Returns:**
+`Promise<string>` — Returns a promise that resolves with the Base64 string of the resized image.
+
+```typescript
+import { ensureMaxSize } from '@dxtmisha/functional-basic'
+
+async function processImage(u8array: Uint8Array) {
+  const base64 = await ensureMaxSize(u8array, 0.8, 'image/webp')
+  console.log(base64) // 'data:image/webp;base64,...'
+}
+```

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

@@ -0,0 +1,26 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Functions/ensureMaxSize - Изменение размера изображения до максимального'/>
+
+# `ensureMaxSize`
+
+Гарантирует, что изображение не превышает максимальный размер, изменяя его при необходимости. Функция возвращает изображение в формате строки Base64.
+
+Эта функция полезна для оптимизации изображений перед их отправкой на сервер, что позволяет сократить использование трафика и объем занимаемой памяти.
+
+**Параметры:**
+- `file: Uint8Array` — Файл изображения в виде `Uint8Array`.
+- `compress: number` (необязательно, по умолчанию: `0.56`) — Максимальный размер в виде доли от оригинального размера.
+- `type: string` (необязательно, по умолчанию: `'image/jpeg'`) — MIME-тип выходного изображения.
+
+**Возвращает:**
+`Promise<string>` — Возвращает промис, который разрешается в строку Base64 измененного изображения.
+
+```typescript
+import { ensureMaxSize } from '@dxtmisha/functional-basic'
+
+async function processImage(u8array: Uint8Array) {
+  const base64 = await ensureMaxSize(u8array, 0.8, 'image/webp')
+  console.log(base64) // 'data:image/webp;base64,...'
+}
+```

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

@@ -0,0 +1,26 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Functions/ensureMaxSize - Thay đổi kích thước ảnh theo kích thước tối đa'/>
+
+# `ensureMaxSize`
+
+Đảm bảo rằng hình ảnh không vượt quá kích thước tối đa bằng cách thay đổi kích thước nếu cần thiết. Hàm trả về ảnh dưới dạng chuỗi Base64.
+
+Hàm này hữu ích cho việc tối ưu hóa hình ảnh trước khi tải chúng lên máy chủ, giúp giảm việc sử dụng băng thông và yêu cầu lưu trữ.
+
+**Tham số:**
+- `file: Uint8Array` — Tệp ảnh dưới dạng `Uint8Array`.
+- `compress: number` (không bắt buộc, mặc định: `0.56`) — Kích thước tối đa theo tỷ lệ với kích thước gốc.
+- `type: string` (không bắt buộc, mặc định: `'image/jpeg'`) — Định dạng MIME cho ảnh đầu ra.
+
+**Trả về:**
+`Promise<string>` — Trả về một promise được hoàn thành với chuỗi Base64 của ảnh đã thay đổi kích thước.
+
+```typescript
+import { ensureMaxSize } from '@dxtmisha/functional-basic'
+
+async function processImage(u8array: Uint8Array) {
+  const base64 = await ensureMaxSize(u8array, 0.8, 'image/webp')
+  console.log(base64) // 'data:image/webp;base64,...'
+}
+```

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

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Functions/escapeExp - Escape special RegExp characters'/>
+
+# `escapeExp`
+
+A utility that escapes all special regular expression characters in a string (`.` `*` `+` `?` `^` `$` `{` `}` `(` `)` `|` `[` `]` `\` `/`), so it can be safely used inside a `RegExp`.
+
+Useful when a string comes from user input or an external source and may contain characters that have special meaning in regular expressions.
+
+**Parameters:**
+- `value: string` — The string to escape.
+
+**Returns:**
+`string` — A string with all special regex characters escaped, safe to use inside a `RegExp`.
+
+```typescript
+import { escapeExp } from '@dxtmisha/functional-basic'
+
+// Escaping characters
+console.log(escapeExp('user.name[0]')) // 'user\\.name\\[0\\]'
+console.log(escapeExp('price $10.00')) // 'price \\$10\\.00'
+
+// Safe usage inside RegExp
+const regex = new RegExp(escapeExp('user.name[0]'))
+regex.test('user.name[0]') // true
+regex.test('userXname0')   // false
+```

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

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Functions/escapeExp - Экранирование специальных символов RegExp'/>
+
+# `escapeExp`
+
+Утилита, экранирующая все специальные символы регулярных выражений в строке (`.` `*` `+` `?` `^` `$` `{` `}` `(` `)` `|` `[` `]` `\` `/`), чтобы её можно было безопасно использовать внутри `RegExp`.
+
+Используется, когда строка поступает от пользователя или из внешнего источника и может содержать символы, имеющие специальное значение в регулярных выражениях.
+
+**Параметры:**
+- `value: string` — Строка, которую нужно экранировать.
+
+**Возвращает:**
+`string` — Строка с экранированными специальными символами, безопасная для использования в `RegExp`.
+
+```typescript
+import { escapeExp } from '@dxtmisha/functional-basic'
+
+// Экранирование символов
+console.log(escapeExp('user.name[0]')) // 'user\\.name\\[0\\]'
+console.log(escapeExp('price $10.00')) // 'price \\$10\\.00'
+
+// Безопасное использование в RegExp
+const regex = new RegExp(escapeExp('user.name[0]'))
+regex.test('user.name[0]') // true
+regex.test('userXname0')   // false
+```

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

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Functions/escapeExp - Thoát các ký tự đặc biệt trong RegExp'/>
+
+# `escapeExp`
+
+Tiện ích thực hiện \"thoát\" (escape) tất cả các ký tự đặc biệt của biểu thức chính quy trong một chuỗi (`.` `*` `+` `?` `^` `$` `{` `}` `(` `)` `|` `[` `]` `\` `/`), để chuỗi đó có thể được sử dụng an toàn bên trong `RegExp`.
+
+Hữu ích khi chuỗi đến từ người dùng hoặc nguồn bên ngoài và có thể chứa các ký tự mang ý nghĩa đặc biệt trong biểu thức chính quy.
+
+**Tham số:**
+- `value: string` — Chuỗi cần escape.
+
+**Trả về:**
+`string` — Chuỗi đã được escape tất cả các ký tự đặc biệt, an toàn để dùng trong `RegExp`.
+
+```typescript
+import { escapeExp } from '@dxtmisha/functional-basic'
+
+// Escape các ký tự đặc biệt
+console.log(escapeExp('user.name[0]')) // 'user\\.name\\[0\\]'
+console.log(escapeExp('price $10.00')) // 'price \\$10\\.00'
+
+// Sử dụng an toàn trong RegExp
+const regex = new RegExp(escapeExp('user.name[0]'))
+regex.test('user.name[0]') // true
+regex.test('userXname0')   // false
+```

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

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Functions/eventStopPropagation - Stop event propagation'/>
+
+# `eventStopPropagation`
+
+Stops the further propagation of an event in the DOM tree (bubbling / capturing) and cancels the browser's default default action.
+
+The function is a convenient wrapper around calling both `event.preventDefault()` and `event.stopPropagation()`.
+
+**Parameters:**
+- `event: Event` — The DOM event instance to stop.
+
+**Returns:**
+`void`
+
+```typescript
+import { eventStopPropagation } from '@dxtmisha/functional-basic'
+
+const link = document.createElement('a')
+link.href = 'https://example.com'
+link.onclick = (e) => {
+  // Will cancel the navigation to the link and stop the click from bubbling to parents
+  eventStopPropagation(e)
+  console.log('Click intercepted!')
+}
+```

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

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Functions/eventStopPropagation - Остановка всплытия события'/>
+
+# `eventStopPropagation`
+
+Останавливает дальнейшее распространение события в DOM-дереве (всплытие / перехват) и отменяет стандартное действие браузера по умолчанию.
+
+Функция является удобной обёрткой над вызовами `event.preventDefault()` и `event.stopPropagation()`.
+
+**Параметры:**
+- `event: Event` — Экземпляр события DOM, который необходимо остановить.
+
+**Возвращает:**
+`void`
+
+```typescript
+import { eventStopPropagation } from '@dxtmisha/functional-basic'
+
+const link = document.createElement('a')
+link.href = 'https://example.com'
+link.onclick = (e) => {
+  // Отменит переход по ссылке и остановит всплытие клика к родителям
+  eventStopPropagation(e)
+  console.log('Клик перехвачен!')
+}
+```

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

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Functions/eventStopPropagation - Dừng lan truyền sự kiện'/>
+
+# `eventStopPropagation`
+
+Dừng việc lan truyền tiếp theo của một sự kiện trong cây DOM (giai đoạn nổi lên / bắt giữ) và hủy bỏ hành động mặc định của trình duyệt.
+
+Hàm này là một trình bao bọc (wrapper) tiện lợi gọi cả hai phương thức `event.preventDefault()` và `event.stopPropagation()`.
+
+**Tham số:**
+- `event: Event` — Phiên bản sự kiện DOM cần dừng.
+
+**Trả về:**
+`void`
+
+```typescript
+import { eventStopPropagation } from '@dxtmisha/functional-basic'
+
+const link = document.createElement('a')
+link.href = 'https://example.com'
+link.onclick = (e) => {
+  // Sẽ hủy bỏ việc điều hướng đến liên kết và ngăn chặn cú nhấp chuột lan truyền lên các phần tử cha
+  eventStopPropagation(e)
+  console.log('Cú nhấp chuột bị chặn!')
+}
+```

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

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Functions/executeFunction - Execute function or return value'/>
+
+# `executeFunction`
+
+A utility that checks the provided argument. If the argument is a function, it executes the function and returns its result. Otherwise, it simply returns the provided argument as is.
+
+This is extremely useful for handling arguments that can flexibly be either a static value or a function that calculates the value on demand (such as lazy evaluation or dynamic defaults).
+
+**Parameters:**
+- `callback: T | FunctionArgs<any, T>` — A value of any type, or a function that returns a value of type `T`.
+
+**Returns:**
+`T` — The result of the function execution, or the raw value provided.
+
+```typescript
+import { executeFunction } from '@dxtmisha/functional-basic'
+
+// Passing a static value
+console.log(executeFunction('Hello')) // 'Hello'
+
+// Passing a function
+const lazyValue = () => {
+  return 'Loaded lazily'
+}
+console.log(executeFunction(lazyValue)) // 'Loaded lazily'
+```

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

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Functions/executeFunction - Выполнение функции или возврат значения'/>
+
+# `executeFunction`
+
+Утилита, которая проверяет переданный аргумент. Если аргумент является функцией, он выполняется, и функция возвращает результат этого выполнения. В противном случае, переданный аргумент возвращается как есть (без изменений).
+
+Это полезно для параметров, которые могут быть как статическим значением, так и функцией, вычисляющей это значение по требованию (например, для ленивых вычислений или значений по умолчанию).
+
+**Параметры:**
+- `callback: T | FunctionArgs<any, T>` — Значение любого типа или функция, возвращающая значение типа `T`.
+
+**Возвращает:**
+`T` — Результат выполнения функции или переданное значение.
+
+```typescript
+import { executeFunction } from '@dxtmisha/functional-basic'
+
+// Передаем статическое значение
+console.log(executeFunction('Привет')) // 'Привет'
+
+// Передаем функцию
+const lazyValue = () => {
+  return 'Загружено лениво'
+}
+console.log(executeFunction(lazyValue)) // 'Загружено лениво'
+```

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

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Functions/executeFunction - Thực thi hàm hoặc trả về giá trị'/>
+
+# `executeFunction`
+
+Tiện ích kiểm tra đối số được cung cấp. Nếu đối số đó là một hàm, nó sẽ thực thi hàm và trả về kết quả của hàm đó. Trong trường hợp ngược lại, nó đơn giản trả về đối số đầu vào (giữ nguyên).
+
+Điều này rất hữu ích cho các tham số có thể linh hoạt chấp nhận một giá trị tĩnh hoặc một hàm tính toán giá trị đó theo yêu cầu (ví dụ như khởi tạo chậm/lazy evaluation hoặc giá trị mặc định động).
+
+**Tham số:**
+- `callback: T | FunctionArgs<any, T>` — Giá trị của bất kỳ loại nào, hoặc một hàm trả về giá trị kiểu `T`.
+
+**Trả về:**
+`T` — Kết quả của việc thực thi hàm hoặc chính giá trị ban đầu.
+
+```typescript
+import { executeFunction } from '@dxtmisha/functional-basic'
+
+// Truyền một giá trị tĩnh
+console.log(executeFunction('Xin chào')) // 'Xin chào'
+
+// Truyền một hàm
+const lazyValue = () => {
+  return 'Được tải lazy'
+}
+console.log(executeFunction(lazyValue)) // 'Được tải lazy'
+```

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

@@ -0,0 +1,32 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Functions/executePromise - Execute Promise or function'/>
+
+# `executePromise`
+
+A utility that safely executes a function and/or awaits the resolution of an asynchronous result (Promise).
+
+Under the hood, it uses the `executeFunction` utility. If passed a function returning a Promise, `executePromise` executes it and waits for the `Promise` to resolve. If a synchronous value or a regular function returning a synchronous value is passed, the utility immediately returns that result.
+
+**Parameters:**
+- `callback: (() => Promise<T>) | (() => T) | T` — A value, a `Promise`, or a function capable of returning a `Promise` or a plain value.
+
+**Returns:**
+`Promise<T>` — A promise resolving to the provided or computed value.
+
+```typescript
+import { executePromise } from '@dxtmisha/functional-basic'
+
+// With an async function
+const fetchData = async () => {
+  return await fetch('/api/data').then(res => res.json())
+}
+const result1 = await executePromise(fetchData)
+
+// With a synchronous function
+const staticData = () => 'Sync data'
+const result2 = await executePromise(staticData)
+
+// With a static value
+const result3 = await executePromise('Data')
+```

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

@@ -0,0 +1,32 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional-basic/Functions/executePromise - Выполнение Promise или функции'/>
+
+# `executePromise`
+
+Утилита, которая безопасно выполняет функцию и/или дожидается разрешения асинхронного результата (Promise).
+
+Внутри используется функция `executeFunction`. Если передан аргумент в виде функции возвращающей промис, `executePromise` выполнит эту функцию и дождётся выполнения `Promise`. Если будет передано синхронное значение или обычная функция, возвращающая синхронное значение, утилита сразу вернёт этот результат.
+
+**Параметры:**
+- `callback: (() => Promise<T>) | (() => T) | T` — Значение, `Promise` или функция, способная вернуть `Promise` или обычное значение.
+
+**Возвращает:**
+`Promise<T>` — Промис, разрешающийся в переданное или вычисленное значение.
+
+```typescript
+import { executePromise } from '@dxtmisha/functional-basic'
+
+// С асинхронной функцией
+const fetchData = async () => {
+  return await fetch('/api/data').then(res => res.json())
+}
+const result1 = await executePromise(fetchData)
+
+// С обычной функцией
+const staticData = () => 'Синхронные данные'
+const result2 = await executePromise(staticData)
+
+// Со статическим значением
+const result3 = await executePromise('Данные')
+```

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

@@ -0,0 +1,32 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional-basic/Functions/executePromise - Thực thi Promise hoặc hàm'/>
+
+# `executePromise`
+
+Một tiện ích thực thi an toàn một hàm và/hoặc chờ đợi kết quả bất đồng bộ (Promise) được hoàn thành.
+
+Bản chất bên trong, nó sử dụng tiện ích `executeFunction`. Nếu truyền vào một hàm trả về một Promise, `executePromise` sẽ thực thi hàm đó và đợi `Promise` hoàn thành. Nếu truyền vào một giá trị đồng bộ hoặc một hàm thông thường trả về giá trị đồng bộ, tiện ích sẽ trả về ngay kết quả đó.
+
+**Tham số:**
+- `callback: (() => Promise<T>) | (() => T) | T` — Một giá trị, một `Promise`, hoặc một hàm có thể trả về một `Promise` hoặc một giá trị thông thường.
+
+**Trả về:**
+`Promise<T>` — Một promise sẽ được hoàn thành với giá trị được cung cấp hoặc được tính toán.
+
+```typescript
+import { executePromise } from '@dxtmisha/functional-basic'
+
+// Với hàm async
+const fetchData = async () => {
+  return await fetch('/api/data').then(res => res.json())
+}
+const result1 = await executePromise(fetchData)
+
+// Với hàm đồng bộ
+const staticData = () => 'Dữ liệu đồng bộ'
+const result2 = await executePromise(staticData)
+
+// Với giá trị tĩnh
+const result3 = await executePromise('Dữ liệu')
+```

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

@@ -0,0 +1,39 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional-basic/Functions/forEach - Iterate over an object or array'/>
+
+# `forEach`
+
+The function performs the specified function once for each element in the object. And returns an array with the results of executing the function.
+
+**Parameters:**
+- `data: D` — object for iteration.
+- `callback: (item: T, key: K, dataMain: typeof data) => R` — a function to execute for each element in the array.
+- `saveUndefined?: boolean` — if `true`, the function returns an array including `undefined` values (filtered by default).
+
+**Returns:**
+`R[]` — an array with the results of executing the function.
+
+## How it works
+
+The function is a universal tool for iterating over various data structures and collecting results into an array.
+
+**Features:**
+- **Type Support** — works with `Array`, `Map`, and standard `Object`.
+- **Result Collection** — unlike the standard `forEach`, this function collects the values returned from the `callback` into a new array.
+- **Undefined Filtering** — by default, all `undefined` values (e.g., if the callback returned nothing for an element) are filtered out of the resulting array.
+- **saveUndefined Parameter** — if `true` is passed as the third argument, the array will preserve all results, including `undefined`.
+
+## Example
+
+```typescript
+import { forEach } from '@dxtmisha/functional-basic'
+
+const data = [1, 2, 3]
+
+// Undefined values are filtered by default
+forEach(data, (item) => item % 2 === 0 ? item : undefined) // [2]
+
+// With saveUndefined: true
+forEach(data, (item) => item % 2 === 0 ? item : undefined, true) // [undefined, 2, undefined]
+```