@dxtmisha/wiki 0.39.1 → 0.39.2

package/src/media/functional/functional/functions/computedByLanguage/computedByLanguage.vi.mdx

@@ -0,0 +1,46 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Functions/computedByLanguage - Thuộc tính computed theo ngôn ngữ'/>
+
+# `computedByLanguage`
+
+Tạo một thuộc tính computed phản ứng tự động tính toán lại khi ngôn ngữ hiện tại hoặc các phụ thuộc bên trong getter thay đổi.
+
+### Cách thức hoạt động
+
+Hàm thực hiện các kiểm tra theo thứ tự sau:
+1. **Kiểm tra ngôn ngữ**: Xác minh rằng ngôn ngữ đã được thiết lập thông qua `GeoRef.get().value`.
+2. **Kiểm tra điều kiện**: Nếu tham số `conditions` được cung cấp, nó sẽ được gọi để kiểm tra bổ sung (ví dụ: kiểm tra quyền truy cập hoặc trạng thái tải dữ liệu).
+3. **Thực thi Getter chính**: Nếu cả hai kiểm tra trên đều vượt qua, `getter` sẽ được gọi. Nếu nó trả về một giá trị (không phải `undefined`), giá trị đó sẽ trở thành kết quả.
+4. **Tùy chọn dự phòng**: Nếu bất kỳ kiểm tra nào thất bại hoặc `getter` trả về `undefined`, `getterNone` sẽ được thực thi/trả về.
+
+**Tham số:**
+- `getter: ComputedGetter<R>` — Logic chính để lấy giá trị. Chỉ được gọi nếu ngôn ngữ đã thiết lập và các điều kiện được thỏa mãn.
+- `getterNone: R | (() => R)` — Giá trị dự phòng hoặc hàm trả về giá trị đó. Đóng vai trò là "Phương án B". Mặc định: `() => undefined`.
+- `conditions?: () => boolean` — Một hàm điều kiện. Đóng vai trò là "người gác cổng" (gatekeeper): nếu nó trả về `false`, `getter` chính thậm chí sẽ không được kích hoạt.
+- `debugOptions?: DebuggerOptions` — Tùy chọn dùng để gỡ lỗi các phép tính phản ứng, được hỗ trợ bởi Vue.js.
+
+**Trả về:**
+`ComputedRef<R>` — Thuộc tính computed phản ứng.
+
+```typescript
+import { computedByLanguage } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+// Sử dụng cơ bản
+const label = computedByLanguage(() => translateKey('hello'))
+
+// Với giá trị dự phòng
+const title = computedByLanguage(
+  () => translateKey('page.title'),
+  () => 'Untitled'
+)
+
+// Với điều kiện bổ sung
+const isReady = ref(true)
+const content = computedByLanguage(
+  () => translateKey('content'),
+  () => 'Loading...',
+  () => isReady.value
+)
+```

package/src/media/functional/functional/functions/computedEternity/computedEternity.en.mdx

@@ -0,0 +1,31 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Functions/computedEternity - Persistent computed property'/>
+
+# `computedEternity`
+
+Creates a computed property that is computed on demand and cached. The value is updated automatically when dependencies change, but only if it has been accessed at least once. The watcher remains active throughout the application's lifecycle. This is particularly useful for properties that should persist globally after the first access.
+
+**Parameters:**
+- `getter: () => Promise<T> | T` — A function that returns the value to be computed (can be synchronous or asynchronous).
+
+**Returns:**
+`CustomRef<T>` — A reactive custom ref containing the resolved result of the getter.
+
+```typescript
+import { computedEternity } from '@dxtmisha/functional'
+
+// Async getter - will only be called when 'data.value' is first accessed
+const data = computedEternity(async () => {
+  const response = await fetch('/api/data')
+  return response.json()
+})
+
+// Sync getter
+const i = ref(0)
+const double = computedEternity(() => i.value * 2)
+
+console.log(double.value) // 0
+i.value = 5
+// double.value will be 10 on next access
+```

package/src/media/functional/functional/functions/computedEternity/computedEternity.ru.mdx

@@ -0,0 +1,31 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Functions/computedEternity - Постоянное вычисляемое свойство'/>
+
+# `computedEternity`
+
+Создаёт вычисляемое свойство, которое вычисляется по требованию и кешируется. Значение обновляется автоматически при изменении зависимостей, но только если к нему был осуществлён доступ хотя бы один раз. Вотчер остаётся активным на протяжении всей работы приложения. Это полезно для свойств, которые должны сохраняться глобально после первого обращения.
+
+**Параметры:**
+- `getter: () => Promise<T> | T` — Функция, которая возвращает вычисляемое значение (может быть синхронной или асинхронной).
+
+**Возвращает:**
+`CustomRef<T>` — Реактивное вычисляемое свойство с результатом выполнения геттера.
+
+```typescript
+import { computedEternity } from '@dxtmisha/functional'
+
+// Асинхронный геттер - будет вызван только при первом обращении к 'data.value'
+const data = computedEternity(async () => {
+  const response = await fetch('/api/data')
+  return response.json()
+})
+
+// Синхронный геттер
+const i = ref(0)
+const double = computedEternity(() => i.value * 2)
+
+console.log(double.value) // 0
+i.value = 5
+// double.value будет 10 при следующем обращении
+```

package/src/media/functional/functional/functions/computedEternity/computedEternity.vi.mdx

@@ -0,0 +1,31 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Functions/computedEternity - Thuộc tính tính toán vĩnh cửu'/>
+
+# `computedEternity`
+
+Tạo một thuộc tính tính toán được tính toán theo yêu cầu và được lưu vào bộ nhớ đệm. Giá trị được cập nhật tự động khi các phụ thuộc thay đổi, nhưng chỉ khi nó đã được truy cập ít nhất một lần. Watcher vẫn hoạt động trong suốt vòng đời của ứng dụng. Điều này đặc biệt hữu ích cho các thuộc tính cần tồn tại trên toàn cầu sau lần truy cập đầu tiên.
+
+**Các tham số:**
+- `getter: () => Promise<T> | T` — Một hàm trả về giá trị cần tính toán (có thể là đồng bộ hoặc bất đồng bộ).
+
+**Trả về:**
+`CustomRef<T>` — Một ref tùy chỉnh phản ứng chứa kết quả đã giải quyết của getter.
+
+```typescript
+import { computedEternity } from '@dxtmisha/functional'
+
+// Getter bất đồng bộ - sẽ chỉ được gọi khi 'data.value' được truy cập lần đầu tiên
+const data = computedEternity(async () => {
+  const response = await fetch('/api/data')
+  return response.json()
+})
+
+// Getter đồng bộ
+const i = ref(0)
+const double = computedEternity(() => i.value * 2)
+
+console.log(double.value) // 0
+i.value = 5
+// double.value sẽ là 10 trong lần truy cập tiếp theo
+```

package/src/media/functional/functional/functions/dxtFunctionalPlugin/dxtFunctionalPlugin.en.mdx

@@ -0,0 +1,80 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Functions/dxtFunctionalPlugin - Unified Initialization'/>
+
+# `dxtFunctionalPlugin`
+
+`dxtFunctionalPlugin` is a Vue 3 plugin designed to centralize the configuration and initialization of all functional services (`Api`, `Translate`, `Icons`, `Meta`) in your application. It ensures that global singletons are properly set up before the app is mounted.
+
+**Parameters:**
+- `app: App` — The Vue application instance.
+- `options: FunctionalPluginOptions` — Configuration object for functional services.
+
+**Returns:**
+`Plugin` — A Vue plugin object that integrates core functional logic into the application.
+
+## Installation
+
+Add the plugin to your Vue application in `main.ts`:
+
+```typescript
+import { createApp } from 'vue'
+import { dxtFunctionalPlugin } from '@dxtmisha/functional'
+import App from './App.vue'
+import router from './router'
+
+const app = createApp(App)
+
+app.use(dxtFunctionalPlugin, {
+  api: { urlRoot: 'https://api.example.com' },
+  metaSuffix: ' | My Portal',
+  router
+})
+
+app.mount('#app')
+```
+
+## Initialization Flow
+
+When the plugin is installed, it performs the following steps in order:
+
+1.  **Api**: Calls `Api.setConfig()` with the provided `ApiConfig`.
+2.  **Translate**: Calls `Translate.setConfig()` with the provided `TranslateConfig`.
+3.  **Icons**: Calls `Icons.setConfig()` with the provided `IconsConfig`.
+4.  **Meta**: Configures the default title suffix via `useMeta().setSuffix()`.
+5.  **Router**: Registers the router instance in `RouterItemRef`, making it accessible globally.
+6.  **executeUseGlobalInit**: Triggers the batch initialization of all global singletons defined using `executeUseGlobal`.
+
+## Data Types
+
+The plugin uses the following interfaces for configuration:
+
+### `FunctionalPluginOptions`
+
+- `api?: ApiConfig` — Configuration for the global `Api` instance.
+- `translate?: TranslateConfig` — Configuration for the global `Translate` service.
+- `icons?: IconsConfig` — Configuration for the global `Icons` registry.
+- `metaSuffix?: string` — A string that will be appended to all page titles set via `useMeta()`.
+- `router?: Router` — The Vue Router instance. If omitted, the plugin will attempt to extract it from `app.config.globalProperties.$router`.
+
+### `ApiConfig`
+
+Interface for API service configuration:
+- `urlRoot?: string` — Base URL for API requests.
+- `headers?: Record<string, string>` — Default headers for all API requests.
+- `requestDefault?: Record<string, any>` — Default request data to be sent with every request.
+- `preparation?: (apiFetch: ApiFetch) => Promise<void>` — Hook called before every request.
+- `end: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>` — Hook called after every request.
+
+### `TranslateConfig`
+
+Interface for translation service configuration:
+- `url?: string` — URL to the translation data script.
+- `propsName?: string` — Key name in the local storage or state for translations.
+- `readApi?: boolean` — Whether to read translations from the API.
+
+### `IconsConfig`
+
+Interface for icon registry configuration:
+- `url?: string` — Base URL for retrieving icon assets.
+- `list?: Record<string, IconsItem>` — Object mapping icon names to their SVG content or loader.

package/src/media/functional/functional/functions/dxtFunctionalPlugin/dxtFunctionalPlugin.ru.mdx

@@ -0,0 +1,80 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Functions/dxtFunctionalPlugin - Единая инициализация'/>
+
+# `dxtFunctionalPlugin`
+
+`dxtFunctionalPlugin` — это плагин для Vue 3, предназначенный для централизованной настройки и инициализации всех функциональных сервисов (`Api`, `Translate`, `Icons`, `Meta`) в вашем приложении. Он гарантирует, что глобальные синглтоны будут правильно настроены до монтирования приложения.
+
+**Параметры:**
+- `app: App` — Экземпляр приложения Vue.
+- `options: FunctionalPluginOptions` — Объект конфигурации для функциональных сервисов.
+
+**Возвращает:**
+`Plugin` — Объект плагина Vue, который интегрирует основную функциональную логику в приложение.
+
+## Установка
+
+Добавьте плагин в ваше приложение Vue в `main.ts`:
+
+```typescript
+import { createApp } from 'vue'
+import { dxtFunctionalPlugin } from '@dxtmisha/functional'
+import App from './App.vue'
+import router from './router'
+
+const app = createApp(App)
+
+app.use(dxtFunctionalPlugin, {
+  api: { urlRoot: 'https://api.example.com' },
+  metaSuffix: ' | Мое приложение',
+  router
+})
+
+app.mount('#app')
+```
+
+## Процесс инициализации
+
+При установке плагин выполняет следующие шаги по порядку:
+
+1.  **Api**: Вызывает `Api.setConfig()` с предоставленным `ApiConfig`.
+2.  **Translate**: Вызывает `Translate.setConfig()` с предоставленным `TranslateConfig`.
+3.  **Icons**: Вызывает `Icons.setConfig()` с предоставленным `IconsConfig`.
+4.  **Meta**: Настраивает суффикс заголовка по умолчанию через `useMeta().setSuffix()`.
+5.  **Router**: Регистрирует экземпляр роутера в `RouterItemRef`, делая его доступным глобально.
+6.  **executeUseGlobalInit**: Запускает пакетную инициализацию всех глобальных синглтонов, определенных с помощью `executeUseGlobal`.
+
+## Типы данных
+
+Плагин использует следующие интерфейсы для конфигурации:
+
+### `FunctionalPluginOptions`
+
+- `api?: ApiConfig` — Конфигурация для глобального экземпляра `Api`.
+- `translate?: TranslateConfig` — Конфигурация для глобального сервиса переводов `Translate`.
+- `icons?: IconsConfig` — Конфигурация для глобального реестра иконок `Icons`.
+- `metaSuffix?: string` — Строка, которая будет добавлена ко всем заголовкам страниц, установленным через `useMeta()`.
+- `router?: Router` — Экземпляр Vue Router. Если не указан, плагин попытается извлечь его из `app.config.globalProperties.$router`.
+
+### `ApiConfig`
+
+Интерфейс конфигурации API-сервиса:
+- `urlRoot?: string` — Базовый URL для API-запросов.
+- `headers?: Record<string, string>` — Заголовки по умолчанию для всех API-запросов.
+- `requestDefault?: Record<string, any>` — Данные запроса по умолчанию, отправляемые с каждым запросом.
+- `preparation?: (apiFetch: ApiFetch) => Promise<void>` — Хук, вызываемый перед каждым запросом.
+- `end: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>` — Хук, вызываемый после каждого запроса.
+
+### `TranslateConfig`
+
+Интерфейс конфигурации сервиса переводов:
+- `url?: string` — URL к скрипту с данными переводов.
+- `propsName?: string` — Имя ключа в локальном хранилище или состоянии для переводов.
+- `readApi?: boolean` — Флаг чтения переводов из API.
+
+### `IconsConfig`
+
+Интерфейс конфигурации реестра иконок:
+- `url?: string` — Базовый URL для получения ресурсов иконок.
+- `list?: Record<string, IconsItem>` — Объект, сопоставляющий имена иконок с их SVG-контентом или загрузчиком.

package/src/media/functional/functional/functions/dxtFunctionalPlugin/dxtFunctionalPlugin.vi.mdx

@@ -0,0 +1,80 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Functions/dxtFunctionalPlugin - Khởi tạo thống nhất'/>
+
+# `dxtFunctionalPlugin`
+
+`dxtFunctionalPlugin` là một plugin cho Vue 3 được thiết kế để tập trung hóa cấu hình và khởi tạo cho tất cả các dịch vụ tính năng (`Api`, `Translate`, `Icons`, `Meta`) trong ứng dụng của bạn. Nó đảm bảo các đối tượng đơn lẻ (singleton) được thiết lập đúng cách trước khi gắn kết (mount) ứng dụng.
+
+**Các tham số:**
+- `app: App` — Thực thể ứng dụng Vue.
+- `options: FunctionalPluginOptions` — Đối tượng cấu hình cho các dịch vụ tính năng.
+
+**Trả về:**
+`Plugin` — Một đối tượng plugin Vue tích hợp logic tính năng cốt lõi vào ứng dụng.
+
+## Cài đặt
+
+Thêm plugin vào ứng dụng Vue của bạn trong `main.ts`:
+
+```typescript
+import { createApp } from 'vue'
+import { dxtFunctionalPlugin } from '@dxtmisha/functional'
+import App from './App.vue'
+import router from './router'
+
+const app = createApp(App)
+
+app.use(dxtFunctionalPlugin, {
+  api: { urlRoot: 'https://api.example.com' },
+  metaSuffix: ' | Ứng dụng của tôi',
+  router
+})
+
+app.mount('#app')
+```
+
+## Luồng khởi tạo
+
+Khi plugin được cài đặt, nó thực hiện các bước sau theo thứ tự:
+
+1.  **Api**: Gọi `Api.setConfig()` với `ApiConfig` được cung cấp.
+2.  **Translate**: Gọi `Translate.setConfig()` với `TranslateConfig` được cung cấp.
+3.  **Icons**: Gọi `Icons.setConfig()` với `IconsConfig` được cung cấp.
+4.  **Meta**: Cấu hình hậu tố cho tiêu đề thông qua `useMeta().setSuffix()`.
+5.  **Router**: Đăng ký router vào `RouterItemRef`, giúp có thể truy cập toàn cục.
+6.  **executeUseGlobalInit**: Kích hoạt quá trình khởi tạo hàng loạt cho tất cả các đối tượng đơn lẻ được định nghĩa thông qua `executeUseGlobal`.
+
+## Các kiểu dữ liệu
+
+Plugin sử dụng các giao diện (interface) sau để cấu hình:
+
+### `FunctionalPluginOptions`
+
+- `api?: ApiConfig` — Cấu hình cho phiên bản `Api` toàn cục.
+- `translate?: TranslateConfig` — Cấu hình cho dịch vụ dịch thuật `Translate` toàn cục.
+- `icons?: IconsConfig` — Cấu hình cho cơ sở dữ liệu biểu tượng `Icons` toàn cục.
+- `metaSuffix?: string` — Chuỗi hậu tố sẽ được thêm vào tất cả tiêu đề trang được thiết lập thông qua `useMeta()`.
+- `router?: Router` — Thực thể Vue Router. Nếu bỏ qua, plugin sẽ cố gắng lấy nó từ `app.config.globalProperties.$router`.
+
+### `ApiConfig`
+
+Giao diện cấu hình cho dịch vụ API:
+- `urlRoot?: string` — URL cơ sở cho các yêu cầu API.
+- `headers?: Record<string, string>` — Các tiêu đề mặc định cho tất cả yêu cầu API.
+- `requestDefault?: Record<string, any>` — Dữ liệu yêu cầu mặc định được gửi kèm theo mỗi yêu cầu.
+- `preparation?: (apiFetch: ApiFetch) => Promise<void>` — Hook được gọi trước mỗi yêu cầu.
+- `end: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>` — Hook được gọi sau mỗi yêu cầu.
+
+### `TranslateConfig`
+
+Giao diện cấu hình cho dịch vụ dịch thuật:
+- `url?: string` — URL đến script chứa dữ liệu dịch thuật.
+- `propsName?: string` — Tên khóa trong bộ nhớ cục bộ hoặc trạng thái cho bản dịch.
+- `readApi?: boolean` — Cờ đọc các bản dịch từ API.
+
+### `IconsConfig`
+
+Giao diện cấu hình cho cơ sở dữ liệu biểu tượng:
+- `url?: string` — URL cơ sở để lấy các tài nguyên biểu tượng.
+- `list?: Record<string, IconsItem>` — Đối tượng ánh xạ tên biểu tượng với nội dung SVG hoặc bộ nạp của chúng.

package/src/media/functional/functional/functions/executeUse/executeUse.en.mdx

@@ -0,0 +1,267 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Functions/executeUse - Singleton with lifecycle management'/>
+
+# `executeUse`
+
+`executeUse` is a factory that wraps any initializer function and turns its result into a **managed singleton**. The object is created exactly once, frozen (`Object.freeze`), and reused on every subsequent call. Depending on the selected type, the singleton can be component-scoped, global, or local.
+
+To ensure unique identifiers, a combination of an internal global code and the `getElementId()` function is used, guaranteeing no collisions even when used across different modules.
+
+
+
+### Generic Constraints
+
+- `R` — the type of object returned by the initializer function (`callback`).
+- `O extends any[]` — the types of arguments accepted by `callback`.
+- `RI extends ExecuteUseReturn<R>` — the resulting singleton type, including management methods.
+
+```typescript
+function executeUse<R, O extends any[], RI extends ExecuteUseReturn<R>>(
+  callback: (...args: O) => R,
+  type: ExecuteUseType = ExecuteUseType.provide
+): (...args: O) => RI
+
+function executeUseGlobal<R>(callback: () => R): () => ExecuteUseReturn<R>
+function executeUseProvide<R, O extends any[]>(callback: (...args: O) => R): (...args: O) => ExecuteUseReturn<R>
+function executeUseLocal<R, O extends any[]>(callback: (...args: O) => R): (...args: O) => ExecuteUseReturn<R>
+```
+
+**Parameters:**
+- `callback: (...args: O) => R` — The initializer function. Called on the first access and returns an object that will be frozen and cached. Arguments are passed only on the first call.
+- `type: ExecuteUseType` — The type of singleton (default: `ExecuteUseType.provide`).
+
+**Returns:** `ExecuteUseReturn<R>` — a frozen object extending `R` with the following methods:
+- `init(): Readonly<R>` — returns the raw result of `callback` without any management methods (`init`, `destroyExecute`).
+- `destroyExecute?(): void` — only on `local` and `global`. Resets the cache, allowing the object to be re-created on the next call.
+
+### The Initializer Function (`callback`) and its Arguments (`...args: O`)
+
+The main feature of `executeUse` is that the factory function (`callback`) and the arguments passed to it (`...args`) are used **only once** — during actual initialization (the very first call).
+
+- **`callback`**: This is a factory describing the state creation logic. Inside it, you typically declare reactive variables (`ref`, `reactive`), functions to mutate them, and computed values (`computed`). The object returned from `callback` will be "frozen" and cached.
+- **`...args: O`**: You can pass any arguments into your initializer (e.g., initial state, ID of the entity being loaded, or an API client). These arguments will be forwarded into the `callback`.
+
+> **Important note about arguments:** Because `executeUse` strictly caches the result of the first call, any arguments passed during **subsequent** calls of the same hook in other components **will be completely ignored**. The object will not be recreated, and the `callback` function will not run again with new arguments (unless you have previously reset the cache via `destroyExecute()`).
+
+### The `init()` Placeholder Method
+
+The `init` method is simply an empty placeholder function that returns the exact same frozen state object. It exists **purely for code readability and Developer Experience (DX)**.
+
+Its main purpose is to give the developer a way to explicitly and visually highlight in the code the exact place where the actual (first) initialization of the singleton takes place. From a technical perspective, `const state = useTheme()` and `const state = useTheme().init()` do exactly the same thing.
+
+```typescript
+// Somewhere deep in the component tree, we simply get the readied state
+const theme = useTheme()
+
+// And here, in the root component (or main.ts), 
+// we explicitly show other developers: "Initialization happens exactly HERE"
+const theme = useTheme().init()
+```
+## Step-by-Step Guide: How to Create and Use Your Own Service
+
+Creating a managed singleton using `executeUse` typically consists of three simple steps.
+
+### Step 1: Defining the State (Factory)
+First, decide what type of state you need (`global`, `local`, or `provide`). Create a separate file (e.g., `useMyService.ts`). Use one of the factory functions (e.g., `executeUseGlobal`).
+
+Inside the callback function, define all your reactive variables (`ref`, `reactive`), computed properties (`computed`), and functions to mutate the state:
+
+```typescript
+// src/composables/useMyService.ts
+import { ref, computed } from 'vue'
+import { executeUseGlobal } from '@dxtmisha/functional'
+
+// Create the singleton and encapsulate the logic
+const instance = executeUseGlobal(() => {
+  // 1. Reactive state
+  const count = ref(0)
+  
+  // 2. Computed properties
+  const isPositive = computed(() => count.value > 0)
+  
+  // 3. Management methods
+  const increment = () => count.value++
+  const reset = () => { count.value = 0 }
+
+  // Return exactly what should be exposed to the outside
+  return { count, isPositive, increment, reset }
+})
+
+// Export a wrapper function.
+// The () => instance() construct is necessary so that code editors (IDEs)
+// correctly recognize useMyService as a composable function.
+// This ensures proper autocomplete and type inference.
+export const useMyService = () => instance()
+```
+
+### Step 2: Initialization (For `global` only)
+If you chose the `global` mode (like in the example above), you need to tell the application exactly when to instantiate it. This is usually done once at the entry point (`main.ts`):
+
+```typescript
+// src/main.ts
+import { createApp } from 'vue'
+import { executeUseGlobalInit } from '@dxtmisha/functional'
+import App from './App.vue'
+
+// Initialize absolutely all global singletons at once
+executeUseGlobalInit() 
+
+createApp(App).mount('#app')
+```
+
+> **Note:** If your application uses the `dxtFunctionalPlugin`, you **do not need** to call `executeUseGlobalInit()` manually at startup — the plugin handles it automatically under the hood.
+
+### Step 3: Usage in a Component
+Now you can import your `useMyService` function into any Vue component. On the very first logical call, use the `init()` method for clarity.
+
+```vue
+<!-- src/components/MyComponent.vue -->
+<script setup lang="ts">
+import { useMyService } from '@/composables/useMyService'
+
+// We receive the state directly. The init() method indicates
+// that the primary (first) access within this scope is happening here.
+const { count, isPositive, increment } = useMyService().init()
+</script>
+
+<template>
+  <div>
+    <p>Current count: {{ count }}</p>
+    <p>Is positive? {{ isPositive ? 'Yes' : 'No' }}</p>
+    <button @click="increment">Increment</button>
+  </div>
+</template>
+```
+
+If for some reason you need to forcefully reset the state (e.g., upon user logout), simply call the built-in reset method:
+```typescript
+const service = useMyService()
+if (service.destroyExecute) {
+  service.destroyExecute()
+}
+```
+
+## The `ExecuteUseType` Enum
+
+### `provide` (component-scoped singleton, default)
+
+This is a component-oriented singleton that is strictly tied to the lifecycle of a Vue component and its entire subtree. Under the hood, it uses Vue's built-in reactivity and context-passing mechanism (`provide`/`inject`), allowing you to safely pass the very same state instance deep down the component tree without having to drill it through props.
+
+**When to use:** 
+- For sharing state specifically within a defined component subtree (parent -> multiple nesting levels -> child) without polluting the global store.
+- When you need to render multiple independent blocks on the same page (e.g., several complex file uploader widgets), each requiring its own unique state shared only within that widget.
+- If you need automatic garbage collection of the data straight from memory when the "owner" component is unmounted.
+
+**How it works:**
+The first component that calls this function automatically becomes the "owner". The function instantiates the object and immediately calls `provide(id, instance)`. Any nested components that call the same function will not create a new object; instead, they retrieve the previously created one via `inject(id)`. 
+> Note: This type lacks a `destroyExecute()` method because memory is freed automatically by Vue's reactivity system when the owner component is destroyed.
+
+```typescript
+import { executeUseProvide } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+const useTheme = executeUseProvide(() => {
+  const mode = ref<'light' | 'dark'>('light')
+  const toggle = () => { mode.value = mode.value === 'light' ? 'dark' : 'light' }
+  return { mode, toggle }
+})
+
+// In the parent component (owner) — the object is created and provided:
+const theme = useTheme()
+theme.toggle()
+
+// In a deeply nested child component — it receives the same object via inject:
+const theme = useTheme()
+
+// In a completely different, independent component tree — a NEW instance is created:
+const theme2 = useTheme()
+```
+
+### `global` (application-wide singleton)
+
+This is a classic Singleton architectural pattern, existing as a strictly unique instance throughout the entire lifetime of your application (from initialization to closing the browser tab). It provides a global point of access to state from literally anywhere in the code.
+
+**When to use:**
+- For storing global application state: authentication, current user profile, language settings, global shopping cart.
+- When the same data needs to be accessed from completely distinct, unrelated parts of the application (or even outside Vue components, such as in the router).
+- As a lightweight replacement for Vuex / Pinia for simple state management tasks.
+
+**How it works:**
+The initializer function is **not executed when called**. Instead, it is added to a special internal queue (`globalMethods`). Full initialization of all global objects only occurs upon explicitly calling `executeUseGlobalInit()`, which is typically placed in `main.ts` before the app is mounted. Thereafter, all components receive the same cached object from memory.
+
+```typescript
+import { executeUseGlobal, executeUseGlobalInit } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+const useAuth = executeUseGlobal(() => {
+  const user = ref<string | null>(null)
+  const login = (name: string) => { user.value = name }
+  const logout = () => { user.value = null }
+  return { user, login, logout }
+})
+
+// In main.ts — strictly BEFORE mounting the app (app.mount()):
+executeUseGlobalInit()
+
+// In any component, utility, or router:
+const auth = useAuth()
+auth.login('Alice')
+
+// If you need to forcefully reset the state (recreate the state from scratch):
+auth.destroyExecute?.() 
+```
+
+### `local` (closure-cached singleton)
+
+This is an independent singleton that relies on the lexical closure mechanism (`closure caching`) in JavaScript. Instead of using the Vue context or the global scope, it preserves the once-generated result directly inside its own function memory, instantly returning it on all subsequent calls.
+
+**When to use:**
+- For utilities, factories, or services not coupled to Vue (`provide`/`inject` only function inside a component's `setup`).
+- When you need an isolated instance of a heavy class or service only at the exact moment it's actually required (lazy initialization on demand), rather than at app startup.
+- For caching the results of heavy mathematical calculations or configuration transformations.
+
+**How it works:**
+It does not use Vue mechanisms. On the very first call, the initializer function is executed with the provided arguments. The result is strictly frozen (`Object.freeze`) and stored in a variable inside the `executeUse` closure. On all subsequent calls (even if you pass different arguments), the function instantly returns the already saved object from the variable. 
+The `destroyExecute()` method nullifies this internal variable, allowing the initialization algorithm to run again on the next call.
+
+```typescript
+import { executeUseLocal } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+const useHeavyConfig = executeUseLocal((env: string) => {
+  // Heavy configuration calculation operation...
+  const config = ref({ api: `https://${env}.example.com` })
+  return { config }
+})
+
+// First call — initialization
+const devConfig = useHeavyConfig('dev')
+console.log(devConfig.config.value.api) // https://dev.example.com
+
+// Second call in another file — returns the same object, the argument is ignored!
+const sameConfig = useHeavyConfig('prod') 
+console.log(sameConfig.config.value.api) // Still https://dev.example.com
+
+// Forcefully clear the cache
+sameConfig.destroyExecute?.()
+const newConfig = useHeavyConfig('prod') // Initialization will run again
+```
+
+## `executeUseGlobalInit`
+
+```typescript
+function executeUseGlobalInit(): void
+```
+
+Calls all registered global initializers (`ExecuteUseType.global`) and clears the queue. Calling it again does not re-initialize already created singletons. Should be called **once** at app startup — before mounting the root component.
+
+```typescript
+import { createApp } from 'vue'
+import { executeUseGlobalInit } from '@dxtmisha/functional'
+import App from './App.vue'
+
+executeUseGlobalInit()
+createApp(App).mount('#app')
+```
+