@dxtmisha/functional 1.11.6 → 1.11.8

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.11.6] - 2026-05-01
+
+### Added
+- **useApiAsyncRef**: Introduced `useApiAsyncRef` for asynchronous API initialization within Vue async setup components.
+- **useApiRef**: Added support for synchronous cache recovery via `recovery()`.
+- **useApiRef**: Added support for server prefetching via `initSsr()` and Vue's `onServerPrefetch`.
+- **getInject**: Moved utility to `@dxtmisha/functional` for wider availability and easier dependency injection.
+
+### Changed / Improved
+- **useApiRef**: Enhanced with response contract validation and improved initialization logic.
+- **useApiRef**: Optimized internals with new helpers like `isConditions` and `getApiFetch`.
+- **SSR & Hydration**: Improved hydration stability by ensuring API data is available immediately upon client mount, preventing flickering and mismatches.
+
+## [1.1.5] - 2026-04-26
+
+### Added
+- **Api**: Added `setOrigin()` and `getOrigin()` methods for managing the protocol and domain of the base URL.
+- **Api**: Added `setConfig()` method for bulk configuration of API settings.
+- **Api**: Added support for `endResetLimit` in `ApiFetch` to control recursive retries via `setEnd`.
+- **Api**: Added support for jittered retry delays to prevent request thundering herds.
+- **ServerStorage**: Added `remove()` method for deleting items from storage.
+- **ServerStorage**: Added `setErrorStatus()` method to toggle visibility of context-missing errors.
+
+## [1.1.4] - 2026-04-25
+
+### Added
+- **Meta**: Added `htmlTitle()` method to `Meta`, `MetaStatic`, and `MetaManager` classes for generating HTML-safe title strings.
+
+### Changed / Improved
+- **MetaManager**: The `toHtml()` method now excludes the `<title>` tag, allowing for more flexible title management via `htmlTitle()`.
+- **Package**: Added `CHANGELOG.md` to the list of files included in the package distribution.
+
+## [1.1.3] - 2026-04-24
+
+### Added
+- **ResumableTimer**: Added a new class for managing timers with pause and resume functionality.
+- **ApiDataReturn**: Implemented a class for standardizing API responses with support for descriptions and texts.
+- **MetaStatic**: Added a class for managing static meta-data.
+- **Datetime**: Added functionality for working with dates and times.
+- **Translate**: Implemented a localization and translation system.
+- **GeoInstance**: Added an instance for advanced geolocation data handling.
+- **ApiHydration**: Added support for API data hydration for SSR.
+- **StorageCallback**: Added a callback mechanism for tracking storage changes.
+- **New Functions**:
+  - `getCurrentTime` — returns the current time.
+  - `getArrayHighlightMatch` — searches for and highlights matches in arrays.
+
+### Changed / Improved
+- **Refactoring**: Major refactoring of the `functional-basic` package to improve architecture.
+- **SSR**: Adapted the API and related modules for full Server-Side Rendering support.
+- **API**:
+  - Improved the core `Api` class.
+  - Refined `ApiCache` and caching systems.
+- **Cookie**:
+  - Completely redesigned the Cookie handling mechanics, including `CookieBlock` and `CookieStorage`.
+  - Added `getListenerRaw` support to `CookieStorage.init()` for initializing from raw cookie strings (essential for SSR).
+  - Extracted cookie parsing and formatting logic into protected `parse()` and `format()` methods.
+  - Expanded `CookieOptions` to support modern attributes: `path`, `domain`, `secure`, `httpOnly`, and `partitioned` (CHIPS).
+  - Updated `setListener` signature to include the fully formatted cookie string as a third parameter, facilitating easier SSR header management.
+- **Function Optimization**:
+  - `getSearchExp` and `getSeparatingSearchExp` — refined search mechanisms.
+  - `getRequestString` — improved query string generation.
+  - `addTagHighlightMatch` — optimized tag highlighting.
+  - `applyTemplate` — expanded template support.
+  - `forEach`, `frame`, `blobToBase64`, `getElementId` — technical improvements and optimization.
+
+### Fixed
+- **Testing**: Fixed and updated all unit tests (`vitest`) for stability and coverage.
+- **Geo**: Fixed logic errors in geolocation functions and their tests.
+- Fixed type definition errors and minor bugs in core functions.
+
+### Documentation
+- **JSDoc**: Completed a full revision and standardization of JSDoc comments for all classes and functions.
+- **ServerStorage**: Added detailed descriptions of methods and operating principles.
+- Updated `ApiDataReturn` documentation.

package/ai-description.txt

@@ -0,0 +1,5 @@
+This library provides a reactive framework for Vue 3 application development, focusing on structured UI component construction, complex data management, and orchestrated API interactions. Its core purpose is to standardize component architecture through abstract base classes like DesignConstructorAbstract and to provide reactive, high-level wrappers for localized formatting (GeoIntlRef), date manipulation (DatetimeRef), and state persistence (useStorageRef, useCookieRef, useBroadcastValueRef).
+
+An AI should study this library when implementing a design system requiring standardized class-based component logic or when building data-intensive interfaces that need integrated searching, filtering, and CRUD operations via useApiManagementRef. It is indispensable for scenarios involving multi-tab state synchronization, SEO management (useMeta), and reactive internationalization (useTranslateRef) where DOM synchronization must be automated.
+
+The library integrates directly with Vue 3 and vue-router, acting as a reactive middleware layer over @dxtmisha/functional-basic. It utilizes a singleton management pattern (executeUse) for global service orchestration and relies heavily on Ref and ComputedRef to maintain its internal state machine and lifecycle hooks.

package/ai-doc.ru.txt

@@ -0,0 +1,34 @@
+Это главная функциональная библиотека для среды 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();`

package/ai-doc.txt

@@ -0,0 +1,34 @@
+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();`