@dxtmisha/functional 1.13.5 → 1.14.0

package/dist/src/classes/ref/GeoRef.d.ts

@@ -43,6 +43,27 @@ export declare class GeoRef {
      * реактивная строка, представляющая первый день недели
      */
     static getFirstDay(): ComputedRef<string>;
+    /**
+     * Current location string.
+     *
+     * Текущее местоположение.
+     * @returns reactive string with the current location/ реактивная строка с текущим местоположением
+     */
+    static getLocation(): ComputedRef<string>;
+    /**
+     * Current country code from the location.
+     *
+     * Текущий код страны из местоположения.
+     * @returns reactive string with the current country code from location/ реактивная строка с кодом текущей страны из местоположения
+     */
+    static getLocationCountry(): ComputedRef<string>;
+    /**
+     * Current language code from the location.
+     *
+     * Текущий код языка из местоположения.
+     * @returns reactive string with the current language code from location/ реактивная строка с кодом текущего языка из местоположения
+     */
+    static getLocationLanguage(): ComputedRef<string>;
     /**
      * Changes the data by the full code.
      *

package/dist/src/composables/ref/useQueryRef.d.ts

@@ -0,0 +1,9 @@
+import { ShallowRef } from 'vue';
+/**
+ * Creates a reactive variable to manage URL query parameters.
+ *
+ * Создает реактивную переменную для управления query-параметрами URL.
+ * @param name value name / название значения
+ * @param defaultValue default value / значение по умолчанию
+ */
+export declare function useQueryRef<T>(name: string, defaultValue?: T | (() => T)): ShallowRef<T>;

package/dist/src/library.d.ts

@@ -31,6 +31,7 @@ export * from './composables/ref/useLazyItemByMarginRef';
 export * from './composables/ref/useLazyRef';
 export * from './composables/ref/useLoadingRef';
 export * from './composables/ref/useMeta';
+export * from './composables/ref/useQueryRef';
 export * from './composables/ref/useRouterList';
 export * from './composables/ref/useSearchRef';
 export * from './composables/ref/useSearchValueRef';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/functional",
   "private": false,
-  "version": "1.13.5",
+  "version": "1.14.0",
   "type": "module",
   "description": "A comprehensive library of utilities, base classes, and Vue 3 composables for reactive web development. Extends @dxtmisha/functional-basic with Composition API.",
   "keywords": [
@@ -46,10 +46,9 @@
   },
   "files": [
     "dist",
-    "ai-description.txt",
-    "ai-doc.ru.txt",
-    "ai-doc.txt",
-    "ai-types.txt",
+    "ai-description.md",
+    "ai-doc.md",
+    "ai-types.md",
     "CHANGELOG.md",
     "LICENSE",
     "package.json",

package/ai-description.txt

@@ -1,18 +0,0 @@
-This library is a collection of Vue 3-based utility classes and composables designed for building complex, reactive, and SSR-ready interfaces. It provides a standardized framework for API management, component state, geographic/localization data, and dynamic rendering.
-
-1. Core Purpose:
-An infrastructure-level toolkit for Vue 3 that abstracts asynchronous data fetching, state management, and UI rendering logic. It provides structured classes and composables to handle API lifecycle (GET/POST/PUT/DELETE), reactive data transformations, internationalization (Intl), and component orchestration.
-
-2. Usage Scenarios:
-- API Orchestration: When building complex forms, data tables, or dashboards requiring integrated state, validation (via @effect/schema compatibility), and SSR support. Use `useApiManagementRef` for unified CRUD handling or `useApiRef` for individual requests.
-- Reactive Data Management: When you need synchronized data across browser tabs (`useBroadcastValueRef`) or persistence across reloads (`useStorageRef`, `useCookieRef`).
-- Localization & Formatting: When the application needs to dynamically handle geographic data, currency formatting, file sizes, or date manipulation via `GeoIntlRef` and `useGeoIntlRef`.
-- Component Design System: When building modular UI components that require consistent prop-to-style/class mapping (`DesignConstructorAbstract`, `DesignComponents`).
-- Lifecycle & DOM Utilities: When implementing lazy loading (`useLazyRef`) or global state management using `executeUse` for singletons.
-
-3. Integration Context:
-- Vue 3 Core: Heavily leverages `Ref`, `ComputedRef`, and `provide/inject`.
-- Data Fetching: Acts as a high-level wrapper over an underlying `functional-basic` library.
-- Routing: Integrates with `vue-router` via `RouterItemRef` and `useRouterList`.
-- SSR: Provides specific `Async` variants (e.g., `useApiAsyncRef`) for server-side pre-fetching.
-- Schema Validation: Designed to work with `@effect/schema` for robust API contract validation.

package/ai-doc.ru.txt

@@ -1,45 +0,0 @@
-Это главная функциональная библиотека для среды Vue (@dxtmisha/functional). Здесь собраны утилиты, composables и реактивные классы, заточенные под Vue.
-
-ПРАВИЛА ИСПОЛЬЗОВАНИЯ:
-1. При разработке на Vue всегда отдавайте приоритет этой библиотеке для работы с логикой и composables, а не `@dxtmisha/functional-basic`.
-2. Библиотека оборачивает базовую нереактивную логику в систему реактивности Vue. Если нужная функция или класс есть здесь, они имеют абсолютный приоритет.
-3. Импортируйте утилиты из `@dxtmisha/functional` для реактивного поведения UI, composables и управления состоянием.
-
-РАБОТА С API И СОСТОЯНИЕМ (useApi / executeUse):
-Для работы с сетевыми запросами в библиотеке предусмотрен набор хуков: `useApiGet`, `useApiPost`, `useApiPut`, `useApiDelete`, `useApiRequest`, `useApiRef`, `useApiAsyncRef`, `useApiManagementRef`, `useApiManagementAsyncRef`.
-Строго соблюдайте следующие правила их применения:
-
-1. НЕ ВЫЗЫВАЙТЕ эти хуки напрямую в компонентах (SFC).
-2. Выносите всю настройку и вызовы `useApi*` в ОТДЕЛЬНЫЕ ФАЙЛЫ (сервисы / хранилища).
-3. Оборачивайте настройку API в фабрику `executeUse` (а именно: `executeUseGlobal`, `executeUseProvide` или `executeUseLocal` из `src/functions/executeUse.ts`). Это гарантирует создание синглтонов (одна точка доступа) и предотвращает создание дубликатов запросов и хранилищ состояния.
-4. Выполняйте любую дополнительную обработку запросов (например: маппинг данных, подготовка структуры для отображения скелетона перед загрузкой формы) в этом же файле, внутри коллбэка `executeUse`, а наружу возвращайте уже полностью готовый набор данных и методов.
-   *Пример правильного использования:*
-   ```ts
-   import { executeUseGlobal } from '@dxtmisha/functional';
-   import { useApiManagementRef } from '@dxtmisha/functional';
-
-   export const useUserManagement = executeUseGlobal(() => {
-     return useApiManagementRef(
-       { path: '/api/users' },                 // GET setup
-       { date: (v) => new Date(v).toLocaleString() }, // Formatters
-       { columns: ['name', 'email'] },         // Search
-       { path: '/api/users' },                 // POST
-       { path: (o) => `/api/users/${o.id}` },  // PUT
-       { path: (o) => `/api/users/${o.id}` }   // DELETE
-     );
-     // Здесь же можно добавить логику подготовки скелетонов, форматирования и т.д.
-     // и затем вернуть расширенный объект
-   });
-   ```
-5. В самом Vue-компоненте просто импортируйте и вызывайте созданный синглтон-хук: `const { list, loading, sendPost } = useUserManagement();`
-
-ВЫБОР СТРАТЕГИИ executeUse:
-1. `executeUseLocal` (ПРЕДПОЧТИТЕЛЬНО):
-   - Когда использовать: Для большинства API-запросов и сервисов.
-   - Особенности: Работает «лениво» (lazy) — инициализируется только в момент первого вызова. Экземпляр сохраняется до конца сессии. Это позволяет не перегружать старт приложения лишними запросами.
-2. `executeUseGlobal`:
-   - Когда использовать: Когда данные или сервис должны быть загружены/инициализированы СРАЗУ при старте приложения (например: критические настройки, SDK).
-   - Особенности: Создает один экземпляр на всё приложение. Все глобальные синглтоны инициализируются принудительно через `executeUseGlobalInit()`.
-3. `executeUseProvide`:
-   - Когда использовать: Для состояния, разделяемого между родителем и группой дочерних компонентов (например: табы, сложные формы с подкомпонентами).
-   - Особенности: Использует provide/inject. Первый компонент в дереве, вызвавший хук, становится «провайдером», остальные — потребителями.

package/ai-doc.txt

@@ -1,45 +0,0 @@
-This is the main functional library for the Vue environment (@dxtmisha/functional). It contains Vue-specific utilities, composables, and reactive classes.
-
-USAGE RULES:
-1. When developing in Vue, always use this library for functionality, logic, and composables instead of `@dxtmisha/functional-basic` whenever possible.
-2. It wraps basic non-reactive logic into Vue's reactivity system. If the required function or composable exists here, it has absolute priority.
-3. Import utilities from `@dxtmisha/functional` for reactive UI behavior, composables, and state management.
-
-WORKING WITH API AND STATE (useApi / executeUse):
-A set of composables is provided for network requests: `useApiGet`, `useApiPost`, `useApiPut`, `useApiDelete`, `useApiRequest`, `useApiRef`, `useApiAsyncRef`, `useApiManagementRef`, `useApiManagementAsyncRef`.
-Strictly follow these rules for their application:
-
-1. DO NOT call these composables directly in the Vue components (SFC).
-2. Move all API configurations and `useApi*` calls into SEPARATE FILES (services/stores).
-3. Wrap the API configurations inside the `executeUse` factory (specifically: `executeUseGlobal`, `executeUseProvide`, or `executeUseLocal` from `src/functions/executeUse.ts`). This guarantees the creation of managed singletons (single access point) and prevents duplicated requests and reactive states.
-4. Perform any additional request processing (e.g., data mapping, preparing structures for skeletons before loading a form) in the same file, inside the `executeUse` callback, and return a fully prepared set of data and methods.
-   *Example of correct usage:*
-   ```ts
-   import { executeUseGlobal } from '@dxtmisha/functional';
-   import { useApiManagementRef } from '@dxtmisha/functional';
-
-   export const useUserManagement = executeUseGlobal(() => {
-     return useApiManagementRef(
-       { path: '/api/users' },                 // GET setup
-       { date: (v) => new Date(v).toLocaleString() }, // Formatters
-       { columns: ['name', 'email'] },         // Search
-       { path: '/api/users' },                 // POST
-       { path: (o) => `/api/users/${o.id}` },  // PUT
-       { path: (o) => `/api/users/${o.id}` }   // DELETE
-     );
-     // Logic for skeletons, additional formatting, etc., should be added here,
-     // and then return the extended object.
-   });
-   ```
-5. Within the Vue component itself, simply import and call your custom singleton composable: `const { list, loading, sendPost } = useUserManagement();`
-
-CHOOSING THE executeUse STRATEGY:
-1. `executeUseLocal` (PREFERRED):
-   - When to use: For most API requests and services.
-   - Key Features: Works "lazily" (lazy initialization) — initializes only when first called. The instance persists until the end of the session. This prevents overloading the application start with unnecessary requests.
-2. `executeUseGlobal`:
-   - When to use: When data or a service must be loaded/initialized IMMEDIATELY at application start (e.g., critical settings, SDKs).
-   - Key Features: Creates a single instance for the entire application. All global singletons are forcibly initialized via `executeUseGlobalInit()`.
-3. `executeUseProvide`:
-   - When to use: For state shared between a parent and a group of child components (e.g., tabs, complex forms with sub-components).
-   - Key Features: Uses provide/inject. The first component in the tree that calls the hook becomes the "provider", others become consumers.