@dxtmisha/functional-basic 1.3.13 → 1.4.0

package/dist/src/classes/Geo.d.ts

@@ -57,6 +57,20 @@ export declare class Geo {
      * @returns location string / строка местоположения
      */
     static getLocation(): string;
+    /**
+     * Returns the country code extracted from the location string.
+     *
+     * Возвращает код страны, извлеченный из строки местоположения.
+     * @returns country code / код страны
+     */
+    static getLocationCountry(): string;
+    /**
+     * Returns the language code extracted from the location string.
+     *
+     * Возвращает код языка, извлеченный из строки местоположения.
+     * @returns language code / код языка
+     */
+    static getLocationLanguage(): string;
     /**
      * Returns fully processed geo data updated with the current language.
      *

package/dist/src/classes/GeoInstance.d.ts

@@ -92,6 +92,20 @@ export declare class GeoInstance {
      * @returns location string / строка местоположения
      */
     getLocation(): string;
+    /**
+     * Getting the country code from the location.
+     *
+     * Получение кода страны из местоположения.
+     * @returns country code / код страны
+     */
+    getLocationCountry(): string;
+    /**
+     * Getting the language code from the location.
+     *
+     * Получение кода языка из местоположения.
+     * @returns language code / код языка
+     */
+    getLocationLanguage(): string;
     /**
      * Getting processed data including the current language.
      *
@@ -167,7 +181,7 @@ export declare class GeoInstance {
      * @param item geo item data / данные гео-объекта
      * @returns standard code string / строка стандартного кода
      */
-    toStandard(item: GeoItem): string;
+    toStandard(item: GeoItem, language?: string): string;
     /**
      * Updates the current location and related data.
      *
@@ -242,6 +256,7 @@ export declare class GeoInstance {
      *
      * Внутренний метод для заполнения отсутствующих полей в гео-объекте.
      * @param item basic geo item / базовый гео-объект
+     * @param code country code, full form language-country or one of them / код страны, полный вид язык-страна или один из них
      * @returns full geo item data / полные данные гео-объекта
      */
     private toFull;

package/dist/src/classes/HashInstance.d.ts

@@ -1,95 +1,29 @@
+import { UrlInstanceAbstract } from './UrlInstanceAbstract';
 /**
  * Class for working with data stored in the URL hash.
  *
  * Класс для работы с данными, сохранёнными в хеше URL.
  */
-export declare class HashInstance {
-    private hash?;
-    private watch;
-    private block;
-    private time?;
+export declare class HashInstance extends UrlInstanceAbstract {
     /**
-     * Get data from hash.
-     *
-     * Получение данных из хэша.
-     * @param name variable name / название переменной
-     * @param defaultValue value or function to change data / значение или функция для изменения данных
-     * @returns stored value / сохранённое значение
-     */
-    get<T>(name: string, defaultValue?: T | (() => T)): T;
-    /**
-     * Change data in hash.
-     *
-     * Изменение данных в хэше.
-     * @param name variable name / название переменной
-     * @param callback value or function to change data / значение или функция для изменения данных
-     * @returns this instance / текущий экземпляр
-     */
-    set<T>(name: string, callback: T | (() => T)): this;
-    /**
-     * Adding an event when data is changed.
-     *
-     * Добавление события при изменении данных.
-     * @param name variable name / название переменной
-     * @param callback the function is called when the data is changed / функция вызывается при изменении данных
-     * @returns this instance / текущий экземпляр
-     */
-    addWatch<T>(name: string, callback: (value: T) => void): this;
-    /**
-     * Removing an event when data is changed.
-     *
-     * Удаление события при изменении данных.
-     * @param name variable name / название переменной
-     * @param callback the function is called when the data is changed / функция вызывается при изменении данных
-     * @returns this instance / текущий экземпляр
-     */
-    removeWatch<T>(name: string, callback: (value: T) => void): this;
-    /**
-     * Update hash variable from URL string.
+     * Initializes hash data and registers the hashchange listener.
      *
-     * Обновление переменной хэша из строки URL.
+     * Инициализирует данные хэша и регистрирует слушатель hashchange.
      * @returns this instance / текущий экземпляр
      */
-    reload(): this;
+    protected init(): this;
     /**
      * Obtaining data from the URL string.
      *
      * Получение данных из строки URL.
      * @returns Record<string, any> hash data / данные хэша
      */
-    private getLocation;
-    /**
-     * Returns the hash object, initializing if needed.
-     *
-     * Возвращает объект хэша, инициализируя при необходимости.
-     * @returns Record<string, any> hash object / объект хэша
-     */
-    private getHash;
-    /**
-     * Initializes hash data and registers the hashchange listener.
-     *
-     * Инициализирует данные хэша и регистрирует слушатель hashchange.
-     * @returns this instance / текущий экземпляр
-     */
-    private init;
-    /**
-     * Reads hash data from the URL and triggers watchers.
-     *
-     * Считывает данные хэша из URL и вызывает наблюдателей.
-     * @returns this instance / текущий экземпляр
-     */
-    private initData;
+    protected getLocation(): Record<string, any>;
     /**
      * Update hash string in URL.
      *
      * Обновление строки хэша в URL.
+     * @returns this instance / текущий экземпляр
      */
-    private update;
-    /**
-     * Calling all functions whose data has changed.
-     *
-     * Вызов всех функций, у которых были изменены данные.
-     * @param location fresh data / свежие данные
-     */
-    private makeWatch;
+    protected update(): this;
 }

package/dist/src/classes/Query.d.ts

@@ -0,0 +1,57 @@
+import { QueryInstance } from './QueryInstance';
+/**
+ * Static class for working with data stored in the URL query parameters.
+ * Provides a centralized interface delegating to QueryInstance.
+ *
+ * Статический класс для работы с данными, сохранёнными в query-параметрах URL.
+ * Предоставляет централизованный интерфейс, делегируя вызовы QueryInstance.
+ */
+export declare class Query {
+    /**
+     * Returns a request-isolated instance of QueryInstance.
+     *
+     * Возвращает изолированный в рамках запроса экземпляр QueryInstance.
+     * @returns QueryInstance instance / экземпляр QueryInstance
+     */
+    static getItem(): QueryInstance;
+    /**
+     * Get data from query.
+     *
+     * Получение данных из query-параметров.
+     * @param name variable name / название переменной
+     * @param defaultValue value or function to change data / значение или функция для изменения данных
+     * @returns stored value / сохранённое значение
+     */
+    static get<T>(name: string, defaultValue?: T | (() => T)): T;
+    /**
+     * Change data in query.
+     *
+     * Изменение данных в query-параметрах.
+     * @param name variable name / название переменной
+     * @param callback value or function to change data / значение или функция для изменения данных
+     */
+    static set<T>(name: string, callback: T | (() => T)): void;
+    /**
+     * Adding an event when data is changed.
+     *
+     * Добавление события при изменении данных.
+     * @param name variable name / название переменной
+     * @param callback the function is called when the data is changed / функция вызывается при изменении данных
+     */
+    static addWatch<T>(name: string, callback: (value: T) => void): void;
+    /**
+     * Removing an event when data is changed.
+     *
+     * Удаление события при изменении данных.
+     * @param name variable name / название переменной
+     * @param callback the function is called when the data is changed / функция вызывается при изменении данных
+     */
+    static removeWatch<T>(name: string, callback: (value: T) => void): void;
+    /**
+     * Update query variables from URL string.
+     *
+     * Обновление переменных query-параметров из строки URL.
+     * @returns void
+     */
+    static reload(): void;
+}

package/dist/src/classes/QueryInstance.d.ts

@@ -0,0 +1,29 @@
+import { UrlInstanceAbstract } from './UrlInstanceAbstract';
+/**
+ * Class for working with data stored in the URL query parameters.
+ *
+ * Класс для работы с данными, сохранёнными в query-параметрах URL.
+ */
+export declare class QueryInstance extends UrlInstanceAbstract {
+    /**
+     * Initializes query data and registers the popstate listener.
+     *
+     * Инициализирует данные query-параметров и регистрирует слушатель popstate.
+     * @returns this instance / текущий экземпляр
+     */
+    protected init(): this;
+    /**
+     * Obtaining data from the URL string.
+     *
+     * Получение данных из строки URL.
+     * @returns Record<string, any> query data / данные query-параметров
+     */
+    protected getLocation(): Record<string, any>;
+    /**
+     * Update query string in URL.
+     *
+     * Обновление строки query-параметров в URL.
+     * @returns this instance / текущий экземпляр
+     */
+    protected update(): this;
+}

package/dist/src/classes/UrlInstanceAbstract.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Base abstract class for working with URL-based states (Hash, Query).
+ *
+ * Базовый абстрактный класс для работы с состояниями на основе URL (Hash, Query).
+ */
+export declare abstract class UrlInstanceAbstract {
+    protected data?: Record<string, any>;
+    protected watch: Record<string, ((value: any) => void)[]>;
+    protected block: boolean;
+    protected time?: any;
+    /**
+     * Get data.
+     *
+     * Получение данных.
+     * @param name variable name / название переменной
+     * @param defaultValue value or function to change data / значение или функция для изменения данных
+     * @returns stored value / сохранённое значение
+     */
+    get<T>(name: string, defaultValue?: T | (() => T)): T;
+    /**
+     * Change data.
+     *
+     * Изменение данных.
+     * @param name variable name / название переменной
+     * @param callback value or function to change data / значение или функция для изменения данных
+     * @returns this instance / текущий экземпляр
+     */
+    set<T>(name: string, callback: T | (() => T)): this;
+    /**
+     * Adding an event when data is changed.
+     *
+     * Добавление события при изменении данных.
+     * @param name variable name / название переменной
+     * @param callback the function is called when the data is changed / функция вызывается при изменении данных
+     * @returns this instance / текущий экземпляр
+     */
+    addWatch<T>(name: string, callback: (value: T) => void): this;
+    /**
+     * Removing an event when data is changed.
+     *
+     * Удаление события при изменении данных.
+     * @param name variable name / название переменной
+     * @param callback the function is called when the data is changed / функция вызывается при изменении данных
+     * @returns this instance / текущий экземпляр
+     */
+    removeWatch<T>(name: string, callback: (value: T) => void): this;
+    /**
+     * Update variables from URL string.
+     *
+     * Обновление переменных из строки URL.
+     * @returns this instance / текущий экземпляр
+     */
+    reload(): this;
+    /**
+     * Returns the query/hash data object, initializing if needed.
+     *
+     * Возвращает объект данных, инициализируя при необходимости.
+     * @returns Record<string, any> data object / объект данных
+     */
+    protected getData(): Record<string, any>;
+    /**
+     * Reads data from the URL and triggers watchers.
+     *
+     * Считывает данные из URL и вызывает наблюдателей.
+     * @returns this instance / текущий экземпляр
+     */
+    protected initData(): this;
+    /**
+     * Calling all functions whose data has changed.
+     *
+     * Вызов всех функций, у которых были изменены данные.
+     * @param location fresh data / свежие данные
+     * @returns this instance / текущий экземпляр
+     */
+    protected makeWatch(location: Record<string, any>): this;
+    /**
+     * Initializes data and event listeners.
+     *
+     * Инициализирует данные и слушатели событий.
+     */
+    protected abstract init(): this;
+    /**
+     * Obtaining data from the URL string.
+     *
+     * Получение данных из строки URL.
+     */
+    protected abstract getLocation(): Record<string, any>;
+    /**
+     * Update string in URL.
+     *
+     * Обновление строки в URL.
+     */
+    protected abstract update(): this;
+}

package/dist/src/classes/UrlItem.d.ts

@@ -46,6 +46,29 @@ export declare class UrlItem {
     get hash(): string;
     /** Origin of the URL (readonly) / Источник URL (только для чтения) */
     get origin(): string;
+    /**
+     * Checks if the specified query parameter exists.
+     *
+     * Проверяет, существует ли указанный параметр запроса.
+     * @param name parameter name / имя параметра
+     * @returns check result / результат проверки
+     */
+    hasParam(name: string): boolean;
+    /**
+     * Returns the value of a query parameter.
+     *
+     * Возвращает значение параметра запроса.
+     * @param name parameter name / имя параметра
+     * @returns parameter value or undefined if not found / значение параметра или undefined, если не найдено
+     */
+    getParam(name: string): string | undefined;
+    /**
+     * Returns all query parameters as an object with transformed types.
+     *
+     * Возвращает все параметры запроса в виде объекта с преобразованными типами.
+     * @returns Record<string, any> object of parameters / объект параметров
+     */
+    getParams(): Record<string, any>;
     /**
      * Updates the URL value.
      *
@@ -54,6 +77,31 @@ export declare class UrlItem {
      * @returns this Url instance / текущий экземпляр Url
      */
     set(url?: string | URL): this;
+    /**
+     * Sets the value of a query parameter.
+     *
+     * Устанавливает значение параметра запроса.
+     * @param name parameter name / имя параметра
+     * @param value parameter value / значение параметра
+     * @returns this UrlItem instance / текущий экземпляр UrlItem
+     */
+    setParam(name: string, value: string): this;
+    /**
+     * Replaces all query parameters with the specified object.
+     *
+     * Заменяет все параметры запроса на указанный объект.
+     * @param params parameters to set / параметры для установки
+     * @returns this UrlItem instance / текущий экземпляр UrlItem
+     */
+    setParams(params: Record<string, any>): this;
+    /**
+     * Deletes a query parameter.
+     *
+     * Удаляет параметр запроса.
+     * @param name parameter name / имя параметра
+     * @returns this UrlItem instance / текущий экземпляр UrlItem
+     */
+    deleteParam(name: string): this;
     /**
      * Converts the Url instance to its string representation.
      *

package/dist/src/library.d.ts

@@ -42,6 +42,8 @@ export * from './classes/MetaManager';
 export * from './classes/MetaOg';
 export * from './classes/MetaStatic';
 export * from './classes/MetaTwitter';
+export * from './classes/Query';
+export * from './classes/QueryInstance';
 export * from './classes/ResumableTimer';
 export * from './classes/ScrollbarWidth';
 export * from './classes/SearchList';
@@ -54,6 +56,7 @@ export * from './classes/StorageCallback';
 export * from './classes/Translate';
 export * from './classes/TranslateFile';
 export * from './classes/TranslateInstance';
+export * from './classes/UrlInstanceAbstract';
 export * from './classes/UrlItem';
 export * from './functions/addTagHighlightMatch';
 export * from './functions/anyToString';

package/dist/src/types/geoTypes.d.ts

@@ -38,6 +38,12 @@ export interface GeoItemFull extends Omit<GeoItem, 'firstDay'> {
     standard: string;
     /** First day of week (required)/ Первый день недели (обязательный) */
     firstDay: string;
+    /** Current location string/ Строка текущего местоположения */
+    location: string;
+    /** Current country code from location/ Текущий код страны из местоположения */
+    locationCountry: string;
+    /** Current language code from location/ Текущий код языка из местоположения */
+    locationLanguage: string;
 }
 /** Geographic flag item for country flag display/ Элемент географического флага для отображения флага страны */
 export interface GeoFlagItem {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/functional-basic",
   "private": false,
-  "version": "1.3.13",
+  "version": "1.4.0",
   "type": "module",
   "description": "Foundational utility library for modern web development — HTTP client, geolocation, i18n, SEO meta tags, caching, storage, DOM utilities, and more. Framework-agnostic, zero dependencies, TypeScript-first.",
   "keywords": [
@@ -59,9 +59,9 @@
   },
   "files": [
     "dist",
-    "ai-description.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 comprehensive, isomorphic utility toolkit for TypeScript applications, focusing on data management, HTTP communication, internationalization, and DOM manipulation. 
-
-1. Core Purpose:
-The library acts as a centralized foundation for common application tasks. It provides a robust HTTP client (Fetch wrapper with built-in retries, caching, and hydration support), state management (localized storage, cookie handling, URL hash synchronization), internationalization (translation management, date/time/currency formatting), and DOM utility functions (event listeners, scroll management, meta tag management).
-
-2. Usage Scenarios:
-- API Orchestration: Use the Api/ApiInstance classes for unified fetch requests, centralized error handling (ErrorCenter), and automatic response caching.
-- State Synchronization: Essential for SSR-compliant state management (ServerStorage) and syncing application state with URL hashes or Cookies.
-- Localization: Indispensable for applications requiring multi-language support (Translate), dynamic date/time formatting (GeoIntl, Datetime), and locale-aware number/currency formatting.
-- DOM & Event Management: Use EventItem for lifecycle-safe event listeners (with automatic cleanup) and scroll/resize optimizations; use Meta and its derivatives for SEO and social media metadata management.
-- Data Processing: Highly useful for search-as-you-type implementations (SearchList) and complex data transformations (Formatters).
-
-3. Integration Context:
-- SSR & Hydration: The library includes specialized handlers (ApiHydration, ServerStorage, getHydrationData) designed to bridge the gap between server-rendered state and client-side execution, preventing hydration mismatches.
-- Architecture: It follows a singleton-friendly patterns (e.g., Api.getItem(), Geo.getObject()) that facilitate global access to state and configurations across disparate modules without tight coupling.
-- Type Safety: Extensively typed (TypeScript), providing full autocompletion and structural validation for search, API, translation, and formatting configurations.
-
-An AI assistant should study this library when tasked with building enterprise-grade, localized web applications that require standardized API communication, cross-browser DOM event management, or robust SSR data state serialization.

package/ai-doc.txt

@@ -1,54 +0,0 @@
-This is the basic functional library (@dxtmisha/functional-basic). It contains framework-agnostic algorithms, utilities, and classes.
-
-ATTENTION FOR VUE ENVIRONMENT:
-If you are developing in Vue, ALWAYS look for the required functionality (composables, reactive wrappers) inside the `@dxtmisha/functional` library FIRST.
-And ONLY if there is no reactive or Vue-specific analog there, you may use the functionality directly from this library (@dxtmisha/functional-basic).
-
-=============================================================================
-CLASS STRUCTURE & CODING STANDARDS (RULES FOR AI)
-=============================================================================
-
-To maintain consistency and high industrial quality across the dxt-ui codebase, all TypeScript classes inside `@dxtmisha/functional-basic` must strictly adhere to the following rules regarding structure, member ordering, and styles.
-
-1. ORDER OF MEMBERS WITHIN A CLASS
-Members in every class MUST be ordered in the following sequence:
-
-   A. Class Properties / Member Variables:
-      - Placed at the very top of the class body.
-      - Ordered by visibility: Public first, then Protected, and Private last.
-      - Within each visibility level, group by logical connection or alphabetically.
-      - Initialize default values directly on declaration when possible.
-
-   B. Constructor:
-      - Placed immediately after all property declarations.
-      - Parameter properties (e.g., `protected url: string`) are allowed to simplify declaration.
-
-   C. Public Methods:
-      - Placed after the constructor.
-      - Grouped logically:
-        1. Getters, checkers, and status-check methods (e.g., `is*`, `get*`).
-        2. Setters and configuration methods (e.g., `set*`).
-        3. Core executors and action methods (e.g., `request()`, `fetch()`, `show()`).
-
-   D. Protected Methods:
-      - Placed after all public methods.
-      - Contain internal utility and helper logic accessible to subclasses.
-
-   E. Private Methods:
-      - Placed at the very end of the class.
-      - Strict encapsulation of internal logic.
-
-2. CODING & STYLE CONVENTIONS
-   - Naming:
-     * Classes: PascalCase (e.g., `LoadingInstance`).
-     * Methods & Properties: camelCase (e.g., `registrationEvent`, `registrationList`).
-     * Constants inside files: UPPER_SNAKE_CASE (e.g., `LOADING_EVENT_NAME`).
-   - TypeScript Safety:
-     * Never use `any`. Use generic parameters or `unknown` if the type is dynamic/undefined.
-     * Explicitly declare return types for ALL public, protected, and private methods (including `void`).
-     * Use interfaces/types to define structural contracts for complex inputs and outputs.
-   - SSR Isolation (Server-Side Rendering):
-     * The library must be fully isomorphic and safe for SSR.
-     * Avoid storing request-specific state in global/static class properties directly.
-     * Use `ServerStorage.get('key', () => new Instance())` for request-isolated singletons.
-     * Use `isDomRuntime()` checks before accessing browser-only APIs like `window`, `document`, or `location`.