@dxtmisha/functional-basic 1.8.3 → 1.8.5

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.8.5] - 2026-08-05
+
+### Changed
+- **AI Documentation**: Updated JSDoc prompt rules, added MCP resource definitions (`ai-mcp.json`), removed redundant prompt files, and updated package metadata (`ai-description.md`, `ai-types.md`).
+
+## [1.8.4] - 2026-08-05
+
+### Changed
+- **AI Documentation**: Modularized package documentation and generated `ai-mcp.json` resource definitions alongside updated `ai-description.md` and `ai-types.md`.
+
+## [1.8.3] - 2026-08-01
+
+### Changed
+- **Documentation**: Updated `ai-doc.md` and `ai-doc.ru.md` with explicit class method sorting order guidelines (`get/set`, `is/has`, `get.../set...`, `add/remove`, `update/reset`, sorted alphabetically within subgroups).
+
+## [1.8.2] - 2026-07-31
+
+### Changed
+- **Package Metadata**: Standardized package exports and AI documentation files (`ai-description.md`, `ai-types.md`).
+
 ## [1.8.1] - 2026-07-31
 
 ### Added

package/ai-description.md

@@ -1,5 +1,4 @@
-This library is an isomorphic utility framework designed for full-stack JavaScript and TypeScript applications, providing unified abstractions for API data fetching, SSR hydration, state persistence, internationalization, DOM event management, and SEO metadata. The API and Network module manages HTTP requests via Fetch with automated retries, hook-based request preparation, response caching, SSR client hydration, error storage matching, and mock response emulation. The Storage module delivers cross-environment persistence across browser cookies, local or session storage, and request-isolated server rendering contexts. The Localization and Formatting module handles locale detection, phone number masking, localized unit conversions, translation retrieval, and date, number, or plural formatting using native Intl APIs. The DOM, Events, and Navigation module offers memory-safe event listening with automatic DOM removal checks, reactive URL query and hash state tracking, inter-tab broadcast messaging, global loading state coordination, and meta tag management for OpenGraph and Twitter cards. The Search and Utilities module facilitates in-memory multi-column searching with match highlighting, centralized error logging, resumable timers, and type-safe array or object transformations. Studying type definitions in ai-types.md is mandatory when constructing strongly typed API fetch parameters, handling custom response wrappers, defining error storage criteria, configuring complex list formatters, or supplying generic type arguments to search, storage, and event handlers. The library connects as a foundational utility layer bridging client-side UI frameworks with server-side rendering environments and REST backend endpoints.
+The library provides an isomorphic suite of client- and server-side utilities designed for web application infrastructure, state management, internationalization, and network communication, serving as a unified foundation for API lifecycle management, SSR hydration, browser storage, and data transformation across JavaScript runtimes. API and network utilities streamline HTTP fetch requests with configurable defaults, automatic retries with jitter, response caching, error classification, and SSR client hydration script generation. Storage and state management modules supply request-isolated SSR storage contexts, type-safe cookie management, synchronized URL query and hash state, local and session storage with age-based expiration, and cross-tab broadcast messaging. Localization and geographic tools provide automated country and language detection, phone number mask matching, metric-to-imperial unit conversion, pluralization, currency formatting, and asynchronous multi-language translation resolution. Search and data handling capabilities enable multi-column list searching, search match highlighting, fuzzy and exact regular expression matching, multi-field array sorting, and recursive object template replacement. UI, DOM, and event helpers deliver DOM element manipulation, ResizeObserver and scroll-sync event listeners, global loading indicators, icon registration, resumable timers, and isomorphic HTML meta tag management for standard SEO, Open Graph, and Twitter Cards. Studying type definitions in ai-types.md is mandatory when typing complex API request or response structures, configuring custom request wrappers, defining criteria for error storage items, specifying search column paths, setting up custom translation dictionaries, or implementing isolated server storage contexts during SSR. This package connects with modern web frameworks and SSR environments by wrapping standard Web APIs, fetch interfaces, and DOM listeners with environment-agnostic abstractions and automated client-side hydration hooks.
 ## Mandatory Rules
-Read the corresponding file if your task relates to:
-- 'node_modules/@dxtmisha/functional-basic/ai-prompts/api-reference.md': HTTP client, caching, storage management, geolocation, localization, DOM events, and general utilities
-- 'node_modules/@dxtmisha/functional-basic/ai-prompts/coding-standards.md': Class structure, naming and typing standards, SSR safety, and primitive helper functions
+Read the corresponding file ONLY when working on a task related to (even if not working directly with this package):
+- 'node_modules/@dxtmisha/functional-basic/ai-prompts/api-reference.md': HTTP client caching, storage management, geolocation localization, and DOM utility helpers

package/ai-doc.md

@@ -1 +1,8 @@
-Framework-agnostic utility library. **Vue developers MUST search `@dxtmisha/functional` first**; use this ONLY if no reactive/Vue-specific analog exists.
+Framework-agnostic utility library. **Vue developers MUST search `@dxtmisha/functional` first**; use this ONLY if no reactive/Vue-specific analog exists.
+
+## Coding Standards & Conventions
+
+- **Class Structure**: Properties/Variables (`public`->`protected`->`private`) -> Constructor -> Public Methods -> Protected Methods -> Private Methods. Within each method group, follow order: 1) `get` / `set` (getters/setters), 2) `is...` / `has...`, 3) `get...` / `set...`, 4) `add...` / `remove...`, 5) `update...` / `reset...`, 6) remaining methods. Within each subgroup, methods are grouped semantically by logical pairs and rules (e.g., `min` / `max`, `width` / `height`, `x` / `y` / `z`), and remaining methods are sorted alphabetically.
+- **Style/Types**: `PascalCase` classes, `camelCase` methods/props, `UPPER_SNAKE_CASE` constants. No `any` (use `unknown`/generics). Explicit return types for ALL methods. Export all interfaces. Type files: `*Types.ts`. Use `@effect/schema` for schemas.
+- **SSR Safety**: Isomorphic code. Do NOT store request state in globals. Use `isDomRuntime()` before `window`/`document`. Use `ServerStorage.get('key', () => new Class())` for request-isolated singletons.
+- **Utility & Primitive Functions**: ALWAYS use primitive helper functions from this package (e.g. `isFunction`, `executeFunction`, `isFilled`, `isObject`, `isString`, `isArray`, etc.) instead of writing custom inline checks or conditions.

package/ai-mcp.json

@@ -1,14 +1,20 @@
 [
   {
-    "uri": "@dxtmisha/functional-basic/ai-prompts/api-reference.md",
-    "name": "API Reference",
+    "uri": "@dxtmisha/functional-basic/ai-types.md",
+    "name": "TypeScript Types Reference (@dxtmisha/functional-basic)",
     "mimeType": "text/markdown",
-    "description": "Comprehensive API reference and code examples for the functional-basic library, covering HTTP requests, state storage, localization, DOM manipulation, and utility helpers."
+    "description": "Comprehensive TypeScript type definitions, enums, classes, and utility function declarations covering API client interfaces, metadata management, internationalization, and DOM utilities."
   },
   {
-    "uri": "@dxtmisha/functional-basic/ai-prompts/coding-standards.md",
-    "name": "Coding Standards",
+    "uri": "@dxtmisha/functional-basic/ai-description.md",
+    "name": "Utility Library Overview (@dxtmisha/functional-basic)",
+    "mimeType": "text/markdown",
+    "description": "Provides an overview of isomorphic client and server utilities for HTTP networking, state management, localization, data search, DOM handling, and SSR hydration. Outlines architectural conventions and package capabilities across browser and server runtimes."
+  },
+  {
+    "uri": "@dxtmisha/functional-basic/ai-prompts/api-reference.md",
+    "name": "API Reference Guide (@dxtmisha/functional-basic)",
     "mimeType": "text/markdown",
-    "description": "Defines class structure ordering, TypeScript styling and typing conventions, isomorphic SSR safety rules, and standard primitive helper function usage."
+    "description": "Comprehensive API reference and usage examples for the `@dxtmisha/functional-basic` package. Covers HTTP client configurations, caching, state storage, localization, DOM events, and core utility functions."
   }
 ]

package/ai-types.md

@@ -1,14 +1,4 @@
-1) All these methods are in the @dxtmisha/functional-basic library.
-2) Everything that is exported can be used.
-3) Use what is in this library if it exists; do not use other libraries if there is an analogue here. Do not create new ones if an analogue already exists here.
-
-The following is the content of "exports" from package.json:
-{
-  ".": {
-    "import": "./dist/library.js",
-    "types": "./dist/library.d.ts"
-  }
-}
+All these methods are in the @dxtmisha/functional-basic library.
 
 export declare enum ApiMethodItem {
     delete = "DELETE",
@@ -545,47 +535,6 @@ export type TranslateDataFileItem = () => Promise<TranslateDataFileList>;
 export type TranslateDataFile = Record<string, TranslateDataFileItem>;
 export declare const TRANSLATE_GLOBAL_PREFIX = "global";
 export declare const TRANSLATE_TIME_OUT = 160;
-export type IconsItem = string | Promise<string | any> | (() => Promise<string | any>);
-export type IconsConfig = {
-    url?: string;
-    list?: Record<string, IconsItem>;
-};
-export type CookieSameSite = 'strict' | 'lax';
-export type CookieOptions = {
-    age?: number;
-    sameSite?: CookieSameSite;
-    path?: string;
-    domain?: string;
-    secure?: boolean;
-    httpOnly?: boolean;
-    partitioned?: boolean;
-    arguments?: string[] | Record<string, string | number | boolean>;
-};
-export type LoadingDetail = {
-    loading: boolean;
-};
-export type LoadingRegistrationItem = {
-    item: EventItem<Window, CustomEvent, LoadingDetail>;
-    listener: EventListenerDetail<CustomEvent, LoadingDetail>;
-    element?: ElementOrString<HTMLElement>;
-};
-export type ApiInstanceOptions = {
-    headersClass?: typeof ApiHeaders;
-    requestDefaultClass?: typeof ApiDefault;
-    statusClass?: typeof ApiStatus;
-    responseClass?: typeof ApiResponse;
-    preparationClass?: typeof ApiPreparation;
-    loadingClass?: LoadingInstance;
-    errorCenterClass?: ErrorCenterInstance;
-    hydrationClass?: typeof ApiHydration;
-    wrapper?: <R>(callback: () => Promise<R>, apiFetch: ApiFetch) => Promise<R>;
-};
-export declare const GEO_FLAG_ICON_NAME = "f";
-export declare const UI_GEO_COOKIE_KEY = "ui-geo-code";
-export declare const errorCauseList: ErrorCenterCauseList;
-/**
- * Utility for making HTTP requests.
- */
 export declare class Api {
     static isLocalhost(): boolean;
     static getItem(): ApiInstance;
@@ -613,9 +562,6 @@ export declare class Api {
     static patch<T>(request: ApiFetch): Promise<T>;
     static delete<T>(request: ApiFetch): Promise<T>;
 }
-/**
- * Class for caching API responses.
- */
 export declare class ApiCache {
     static init(getListener: (key: string) => Promise<ApiCacheItem | undefined>, setListener: (key: string, value: ApiCacheItem) => Promise<boolean>, removeListener: (key: string) => Promise<boolean>, cacheStepAgeClearOld?: number): void;
     static reset(): void;
@@ -625,9 +571,6 @@ export declare class ApiCache {
     static setByFetch<T>(fetch: ApiFetch, value: T): Promise<void>;
     static remove(key: string): Promise<void>;
 }
-/**
- * Class for handling and processing data returned from an API request.
- */
 export declare class ApiDataReturn<T = any> {
     constructor(apiFetch: ApiFetch, query: Response, end: ApiPreparationEnd, error?: ApiErrorItem | undefined);
     init(): Promise<this>;
@@ -635,26 +578,17 @@ export declare class ApiDataReturn<T = any> {
     getAndStatus(status: ApiStatus): ApiData<T>;
     getData(): ApiData<T> | undefined;
 }
-/**
- * Class for working with default API request data.
- */
 export declare class ApiDefault {
     is(): boolean;
     get(): Record<string, any> | undefined;
     request(request: ApiFetch['request']): ApiFetch['request'];
     set(request: ApiDefaultValue): this;
 }
-/**
- * Utility class for managing the API error storage and creating error items.
- */
 export declare class ApiError {
     static getStorage(): ApiErrorStorage;
     static add(item: Partial<ApiErrorStorageItem> | Partial<ApiErrorStorageItem>[], url?: string | RegExp, method?: ApiMethodItem): void;
     static getItem(method: ApiMethodItem, response: Response): Promise<ApiErrorItem>;
 }
-/**
- * Class for managing and extracting data from an API error response.
- */
 export declare class ApiErrorItem {
     constructor(method: ApiMethodItem, response: Response, error: ApiErrorStorageItem);
     getMethod(): ApiMethodItem;
@@ -664,32 +598,31 @@ export declare class ApiErrorItem {
     getMessage(): string | undefined;
     getStatus(): number;
 }
-/**
- * Manager for handling and identifying API error states.
- */
 export declare class ApiErrorStorage {
     find(method: ApiMethodItem, response: Response): Promise<ApiErrorStorageItem>;
     add(item: Partial<ApiErrorStorageItem> | Partial<ApiErrorStorageItem>[], url?: string | RegExp, method?: ApiMethodItem): this;
 }
-/**
- * Class for managing HTTP request headers.
- */
 export declare class ApiHeaders {
     get(value?: Record<string, string> | null, type?: string | undefined | null): Record<string, string> | undefined;
     getByRequest(request: ApiFetch['request'], value?: Record<string, string> | null, type?: string): Record<string, string> | undefined;
     set(headers: ApiHeadersValue): this;
 }
-/**
- * Class for collecting API data for hydration on the client side during SSR.
- */
 export declare class ApiHydration {
     initResponse(response: ApiResponse): void;
     toClient<T>(apiFetch: ApiFetch, response: T): void;
     toString(): string;
 }
-/**
- * Core class for managing HTTP requests using the Fetch API.
- */
+export type ApiInstanceOptions = {
+    headersClass?: typeof ApiHeaders;
+    requestDefaultClass?: typeof ApiDefault;
+    statusClass?: typeof ApiStatus;
+    responseClass?: typeof ApiResponse;
+    preparationClass?: typeof ApiPreparation;
+    loadingClass?: LoadingInstance;
+    errorCenterClass?: ErrorCenterInstance;
+    hydrationClass?: typeof ApiHydration;
+    wrapper?: <R>(callback: () => Promise<R>, apiFetch: ApiFetch) => Promise<R>;
+};
 export declare class ApiInstance {
     constructor(url?: string, options?: ApiInstanceOptions);
     isLocalhost(): boolean;
@@ -716,18 +649,12 @@ export declare class ApiInstance {
     patch<T>(request: ApiFetch): Promise<T>;
     delete<T>(request: ApiFetch): Promise<T>;
 }
-/**
- * Class for preparing requests before and after execution.
- */
 export declare class ApiPreparation {
     make(active: boolean, apiFetch: ApiFetch): Promise<void>;
     makeEnd(active: boolean, query: Response, apiFetch: ApiFetch): Promise<ApiPreparationEnd>;
     set(callback: (apiFetch: ApiFetch) => Promise<void>): this;
     setEnd(callback: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>): this;
 }
-/**
- * Class for working with API responses.
- */
 export declare class ApiResponse {
     constructor(requestDefault: ApiDefault);
     get(path: string | undefined, method: ApiMethod, request?: ApiFetch['request'], devMode?: boolean): ApiResponseItem | undefined;
@@ -737,9 +664,6 @@ export declare class ApiResponse {
     emulator<T>(apiFetch: ApiFetch): Promise<T | undefined>;
     emulatorAsync<T>(apiFetch: ApiFetch): T | undefined;
 }
-/**
- * Class for managing API request status.
- */
 export declare class ApiStatus {
     get(): ApiStatusItem | undefined;
     getStatus(): number | undefined;
@@ -757,9 +681,6 @@ export declare class ApiStatus {
     setLastCode(code?: string): this;
     setLastMessage(message?: string): this;
 }
-/**
- * Class for working with BroadcastChannel messages.
- */
 export declare class BroadcastMessage<Message = any> {
     constructor(name: string, callback?: ((event: MessageEvent<Message>) => void) | undefined, callbackError?: ((event: MessageEvent<Message>) => void) | undefined, errorCenter?: ErrorCenterInstance);
     getChannel(): BroadcastChannel | undefined;
@@ -768,35 +689,20 @@ export declare class BroadcastMessage<Message = any> {
     setCallbackError(callbackError: (event: MessageEvent<Message>) => void): this;
     destroy(): this;
 }
-/**
- * Simple in-memory cache class that stores computed values by key.
- * @deprecated
- */
 export declare class Cache {
     get<T>(name: string, callback: () => T, comparison?: any[]): T;
     getAsync<T>(name: string, callback: () => T, comparison?: any[]): Promise<T>;
 }
-/**
- * Class for managing a single cached value with dependency tracking.
- * @deprecated
- */
 export declare class CacheItem<T> {
     constructor(callback: () => T);
     getCache(comparison: any[]): T;
     getCacheOld(): T | undefined;
     getCacheAsync(comparison: any[]): Promise<T>;
 }
-/**
- * Static cache class that uses ServerStorage for persistent caching across the application.
- * @deprecated
- */
 export declare class CacheStatic {
     static get<T>(name: string, callback: () => T, comparison?: any[]): T;
     static getAsync<T>(name: string, callback: () => T, comparison?: any[]): Promise<T>;
 }
-/**
- * Class for managing browser cookies.
- */
 export declare class Cookie<T> {
     static getInstance<T>(name: string): Cookie<T>;
     constructor(name: string);
@@ -804,24 +710,26 @@ export declare class Cookie<T> {
     set(value?: T | string | (() => (T | string)), options?: CookieOptions): void;
     remove(): void;
 }
-/**
- * Class for changing cookie access status.
- */
 export declare class CookieBlock {
     static getItem(): CookieBlockInstance;
     static get(): boolean;
     static set(value: boolean): void;
 }
-/**
- * Class for changing cookie access status instance.
- */
 export declare class CookieBlockInstance {
     get(): boolean;
     set(value: boolean): void;
 }
-/**
- * Class for managing cookie storage with support for custom listeners.
- */
+export type CookieSameSite = 'strict' | 'lax';
+export type CookieOptions = {
+    age?: number;
+    sameSite?: CookieSameSite;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    partitioned?: boolean;
+    arguments?: string[] | Record<string, string | number | boolean>;
+};
 export declare class CookieStorage {
     static init(getListener?: (key: string) => any | undefined, getListenerRaw?: () => string, setListener?: (key: string, value: any, cookie: string, options?: CookieOptions) => void): void;
     static reset(): void;
@@ -830,9 +738,6 @@ export declare class CookieStorage {
     static remove(name: string): void;
     static update(): void;
 }
-/**
- * Class for working with localStorage and sessionStorage.
- */
 export declare class DataStorage<T> {
     static setPrefix(newPrefix: string): void;
     constructor(name: string, isSession?: boolean, errorCenter?: ErrorCenterInstance);
@@ -842,7 +747,12 @@ export declare class DataStorage<T> {
     update(): this;
 }
 /**
- * Class for date manipulation and formatting.
+ * A class for working with dates and localized date-time operations.
+ *
+ * @remarks
+ * Creating a `Datetime` instance without a specific date (using the current time)
+ * for rendering in SSR may lead to hydration mismatches because the time or time zone
+ * on the server may differ from the time on the client.
  */
 export declare class Datetime {
     constructor(date?: NumberOrStringOrDate, type?: GeoDate, code?: string);
@@ -917,9 +827,6 @@ export declare class Datetime {
     cloneDayNext(): Datetime;
     cloneDayPrevious(): Datetime;
 }
-/**
- * Class for managing application error handling globally.
- */
 export declare class ErrorCenter {
     static getItem(): ErrorCenterInstance;
     static has(code: string, group?: string): boolean;
@@ -932,9 +839,6 @@ export declare class ErrorCenter {
     static setIsConsole(isConsole: ErrorCenterHandlerIsConsole): void;
     static on(cause: ErrorCenterCauseItem): void;
 }
-/**
- * Class for managing and triggering error handlers.
- */
 export declare class ErrorCenterHandler {
     constructor(handlers?: ErrorCenterHandlerList, isConsole?: ErrorCenterHandlerIsConsole);
     has(group: ErrorCenterGroup): boolean;
@@ -945,9 +849,6 @@ export declare class ErrorCenterHandler {
     setIsConsole(isConsole: ErrorCenterHandlerIsConsole): this;
     on(cause: ErrorCenterCauseItem): this;
 }
-/**
- * Class for managing error storage and handling within an instance.
- */
 export declare class ErrorCenterInstance {
     constructor(causes?: ErrorCenterCauseList, handler?: ErrorCenterHandler);
     has(code: string, group?: string): boolean;
@@ -961,7 +862,23 @@ export declare class ErrorCenterInstance {
     on(cause: ErrorCenterCauseItem): this;
 }
 /**
- * Wrapper for managing DOM or window event listeners.
+ * Advanced wrapper for managing event listeners on DOM elements or the `window` object.
+ *
+ * ### Key Features:
+ * - Lifecycle Control: Easily `start`, `stop`, `toggle`, or `reset` event listeners.
+ * - DOM Safety: Automatically halts the event if the target element is removed from the DOM.
+ * - Specialized Optimizations:
+ *   - `resize`: Uses `ResizeObserver` for any HTML element (not limited to `window`).
+ *   - `scroll-sync`: High-performance scroll tracking using `requestAnimationFrame`.
+ * - Dynamic Configuration: Chained setters for target element, event type, listener, and options.
+ * - Custom Event Dispatching: Built-in support for triggering events with custom data via `dispatch`.
+ * - Strict Typing: Generic support for elements, event objects, and custom detail data.
+ *
+ * @example
+ * ```typescript
+ * const clickEvent = new EventItem('.btn', 'click', (e) => console.log('Clicked!'));
+ * clickEvent.start();
+ * ```
  */
 export declare class EventItem<E extends ElementOrWindow, O extends Event, D extends Record<string, any> = Record<string, any>> {
     constructor(elementSelector?: ElementOrString<E>, type?: string | string[], listener?: EventListenerDetail<O, D> | undefined, options?: EventOptions, detail?: D | undefined);
@@ -979,9 +896,6 @@ export declare class EventItem<E extends ElementOrWindow, O extends Event, D ext
     toggle(activity: boolean): this;
     reset(): this;
 }
-/**
- * Class for formatting a list of data based on provided options.
- */
 export declare class Formatters<Options extends FormattersOptionsList = FormattersOptionsList, List extends FormattersListProp = FormattersListProp, Item extends FormattersItemProp<List> = FormattersItemProp<List>> {
     constructor(options: Options, list?: List | undefined);
     is(): boolean;
@@ -994,9 +908,6 @@ export declare class Formatters<Options extends FormattersOptionsList = Formatte
     setList(list?: List): this;
     to(): FormattersReturn<List, Options>;
 }
-/**
- * Static class for working with geographical data.
- */
 export declare class Geo {
     static getObject(): GeoInstance;
     static get(): GeoItemFull;
@@ -1021,9 +932,7 @@ export declare class Geo {
     static setTimezone(timezone: number): void;
     static setValueDefault(code?: string | (() => string)): void;
 }
-/**
- * Class for working with flags and geographic information.
- */
+export declare const GEO_FLAG_ICON_NAME = "f";
 export declare class GeoFlag {
     static flags: Record<string, string>;
     constructor(code?: string);
@@ -1037,9 +946,7 @@ export declare class GeoFlag {
     getNationalLanguage(codes?: string[], sort?: boolean): GeoFlagNational[];
     setCode(code: string): this;
 }
-/**
- * Base class for working with geographic data.
- */
+export declare const UI_GEO_COOKIE_KEY = "ui-geo-code";
 export declare class GeoInstance {
     constructor();
     get(): GeoItemFull;
@@ -1064,9 +971,6 @@ export declare class GeoInstance {
     setTimezone(timezone: number): void;
     setValueDefault(code?: string | (() => string)): void;
 }
-/**
- * Internationalization wrapper for numbers, dates, currencies, and plurals.
- */
 export declare class GeoIntl {
     static isItem(code?: string): boolean;
     static getLocation(code?: string): string;
@@ -1098,9 +1002,6 @@ export declare class GeoIntl {
     time(value: NumberOrStringOrDate): string;
     sort<T>(data: T[], compareFn?: (a: T, b: T) => [string, string]): T[];
 }
-/**
- * Utility for phone number formatting and country phone codes.
- */
 export declare class GeoPhone {
     static get(code: string): GeoPhoneValue | undefined;
     static getByPhone(phone: string): GeoPhoneMapInfo;
@@ -1110,9 +1011,6 @@ export declare class GeoPhone {
     static toMask(phone: string, masks?: string[]): string | undefined;
     static removeZero(phone: string): string;
 }
-/**
- * Class for localized unit formatting and automatic conversions.
- */
 export declare class GeoUnit {
     static getInstance(code?: string): GeoUnit;
     constructor(code?: string);
@@ -1132,17 +1030,11 @@ export declare class GeoUnit {
     kilometerPerHour(value: NumberOrString, options?: Intl.NumberFormatOptions): string;
     format(value: NumberOrString, unit: string, options?: Intl.NumberFormatOptions): string;
 }
-/**
- * Static utility class for global application data.
- */
 export declare class Global {
     static getItem(): Record<string, any>;
     static get<R = any>(name: string): R;
     static add(data: Record<string, any>): void;
 }
-/**
- * Static class for working with URL hash data.
- */
 export declare class Hash {
     static getItem(): HashInstance;
     static get<T>(name: string, defaultValue?: T | (() => T)): T;
@@ -1151,13 +1043,13 @@ export declare class Hash {
     static removeWatch<T>(name: string, callback: (value: T) => void): void;
     static reload(): void;
 }
-/**
- * Instance class for working with URL hash parameters.
- */
-export declare class HashInstance extends UrlInstanceAbstract {}
-/**
- * Class for managing icons.
- */
+export declare class HashInstance extends UrlInstanceAbstract {
+}
+export type IconsItem = string | Promise<string | any> | (() => Promise<string | any>);
+export type IconsConfig = {
+    url?: string;
+    list?: Record<string, IconsItem>;
+};
 export declare class Icons {
     static is(index: string): boolean;
     static get(index: string, url?: string, wait?: number): Promise<string>;
@@ -1171,9 +1063,6 @@ export declare class Icons {
     static setUrl(url: string): void;
     static setConfig(config: IconsConfig): void;
 }
-/**
- * Class for managing global loading state.
- */
 export declare class Loading {
     static is(): boolean;
     static get(): number;
@@ -1183,9 +1072,14 @@ export declare class Loading {
     static registrationEvent(listener: EventListenerDetail<CustomEvent, LoadingDetail>, element?: ElementOrString<HTMLElement>): void;
     static unregistrationEvent(listener: EventListenerDetail<CustomEvent, LoadingDetail>, element?: ElementOrString<HTMLElement>): void;
 }
-/**
- * Instance class for managing loading state.
- */
+export type LoadingDetail = {
+    loading: boolean;
+};
+export type LoadingRegistrationItem = {
+    item: EventItem<Window, CustomEvent, LoadingDetail>;
+    listener: EventListenerDetail<CustomEvent, LoadingDetail>;
+    element?: ElementOrString<HTMLElement>;
+};
 export declare class LoadingInstance {
     constructor(eventName?: string);
     is(): boolean;
@@ -1195,9 +1089,6 @@ export declare class LoadingInstance {
     registrationEvent(listener: EventListenerDetail<CustomEvent, LoadingDetail>, element?: ElementOrString<HTMLElement>): void;
     unregistrationEvent(listener: EventListenerDetail<CustomEvent, LoadingDetail>, element?: ElementOrString<HTMLElement>): void;
 }
-/**
- * Class for managing meta tags.
- */
 export declare class Meta extends MetaManager<MetaTag[]> {
     constructor();
     getOg(): MetaOg;
@@ -1224,9 +1115,9 @@ export declare class Meta extends MetaManager<MetaTag[]> {
     html(): string;
     htmlTitle(): string;
 }
-/**
- * Manager class for meta tags.
- */
+type MetaList<T extends readonly string[]> = {
+    [K in T[number]]?: string;
+};
 export declare class MetaManager<T extends readonly string[], Key extends keyof MetaList<T> = keyof MetaList<T>> {
     constructor(listMeta: T, isProperty?: boolean);
     getListMeta(): T;
@@ -1236,12 +1127,6 @@ export declare class MetaManager<T extends readonly string[], Key extends keyof
     set(name: Key, content: string): this;
     setByList(metaList: MetaList<T>): this;
 }
-type MetaList<T extends readonly string[]> = {
-    [K in T[number]]?: string;
-};
-/**
- * Class for Open Graph meta tags.
- */
 export declare class MetaOg extends MetaManager<MetaOpenGraphTag[]> {
     constructor();
     getTitle(): string;
@@ -1259,9 +1144,6 @@ export declare class MetaOg extends MetaManager<MetaOpenGraphTag[]> {
     setLocale(locale: string): this;
     setSiteName(siteName: string): this;
 }
-/**
- * Static accessor for Meta management.
- */
 export declare class MetaStatic {
     static getItem(): Meta;
     static getOg(): MetaOg;
@@ -1288,9 +1170,6 @@ export declare class MetaStatic {
     static html(): string;
     static htmlTitle(): string;
 }
-/**
- * Class for Twitter Card meta tags.
- */
 export declare class MetaTwitter extends MetaManager<MetaTwitterTag[]> {
     constructor();
     getCard(): MetaTwitterCard;
@@ -1308,9 +1187,6 @@ export declare class MetaTwitter extends MetaManager<MetaTwitterTag[]> {
     setDescription(description: string): this;
     setImage(image: string): this;
 }
-/**
- * Static class for URL query parameter management.
- */
 export declare class Query {
     static getItem(): QueryInstance;
     static get<T>(name: string, defaultValue?: T | (() => T)): T;
@@ -1319,13 +1195,8 @@ export declare class Query {
     static removeWatch<T>(name: string, callback: (value: T) => void): void;
     static reload(): void;
 }
-/**
- * Instance class for URL query parameters.
- */
-export declare class QueryInstance extends UrlInstanceAbstract {}
-/**
- * Class for creating a timer that can be paused and resumed.
- */
+export declare class QueryInstance extends UrlInstanceAbstract {
+}
 export declare class ResumableTimer {
     constructor(callback: FunctionVoid, delay?: number, blockStart?: boolean);
     resume(): this;
@@ -1333,18 +1204,12 @@ export declare class ResumableTimer {
     reset(): this;
     clear(): this;
 }
-/**
- * Utility class for scrollbar calculations.
- */
 export declare class ScrollbarWidth {
     static is(): Promise<boolean>;
     static get(): Promise<number>;
     static getStorage(): DataStorage<number>;
     static getCalculate(): boolean;
 }
-/**
- * Class for managing search lists.
- */
 export declare class SearchList<T extends SearchItem, K extends SearchColumns<T>> {
     constructor(list: SearchListValue<T>, columns?: K, value?: string, options?: SearchOptions);
     getData(): SearchListData<T, K>;
@@ -1359,9 +1224,6 @@ export declare class SearchList<T extends SearchItem, K extends SearchColumns<T>
     setOptions(options: SearchOptions): this;
     to(): SearchFormatList<T, K>;
 }
-/**
- * Data manager for search lists.
- */
 export declare class SearchListData<T extends SearchItem, K extends SearchColumns<T>> {
     constructor(list: SearchListValue<T>, columns: K | undefined, item: SearchListItem, options: SearchListOptions);
     is(): this is this & {
@@ -1379,9 +1241,6 @@ export declare class SearchListData<T extends SearchItem, K extends SearchColumn
     forEach(callback: (item: SearchCacheItem<T>['item'], value: SearchCacheItem<T>['value']) => SearchFormatItem<T, K> | undefined): SearchFormatList<T, K>;
     toFormatItem(item: T, selection: boolean): SearchFormatItem<T, K>;
 }
-/**
- * Search list item wrapper.
- */
 export declare class SearchListItem {
     constructor(value: string | undefined, options: SearchListOptions);
     is(): this is this & {
@@ -1391,9 +1250,6 @@ export declare class SearchListItem {
     get(): string;
     set(value?: string): this;
 }
-/**
- * Matcher for search list evaluation.
- */
 export declare class SearchListMatcher {
     constructor(item: SearchListItem, options: SearchListOptions);
     is(): boolean;
@@ -1401,9 +1257,6 @@ export declare class SearchListMatcher {
     get(): RegExp | undefined;
     update(): void;
 }
-/**
- * Options container for search lists.
- */
 export declare class SearchListOptions {
     constructor(options?: SearchOptions | undefined);
     getOptions(): SearchOptions;
@@ -1414,9 +1267,6 @@ export declare class SearchListOptions {
     getClassName(): string;
     setOptions(options: SearchOptions): this;
 }
-/**
- * Storage manager for Server-Side Rendering context.
- */
 export declare class ServerStorage {
     static init(listener: () => Record<string, any> | undefined): typeof ServerStorage;
     static reset(): void;
@@ -1427,9 +1277,6 @@ export declare class ServerStorage {
     static remove(key: string): void;
     static toString(): string;
 }
-/**
- * Callback queue for storage mechanisms.
- */
 export declare class StorageCallback<T = any, Callback = (value: T) => void | Promise<void>> {
     static getInstance<T>(name: string, group?: string): StorageCallback<T, (value: T) => void | Promise<void>>;
     constructor(name: string, group?: string);
@@ -1441,9 +1288,6 @@ export declare class StorageCallback<T = any, Callback = (value: T) => void | Pr
     preparation(): this;
     run(value: T): Promise<this>;
 }
-/**
- * Utility for translation text retrieval.
- */
 export declare class Translate {
     static get(name: string, replacement?: string[] | Record<string, string | number>): Promise<string>;
     static getItem(): TranslateInstance;
@@ -1460,9 +1304,6 @@ export declare class Translate {
     static setReadApi(value: boolean): void;
     static setConfig(config: TranslateConfig): void;
 }
-/**
- * Translation file provider.
- */
 export declare class TranslateFile {
     constructor(data?: TranslateDataFile, language?: string | (() => string), location?: string | (() => string));
     isFile(): boolean;
@@ -1471,9 +1312,6 @@ export declare class TranslateFile {
     getList(): Promise<TranslateDataFileList | undefined>;
     add(data: TranslateDataFile): void;
 }
-/**
- * Translation engine instance.
- */
 export declare class TranslateInstance {
     constructor(url?: string, propsName?: string, files?: TranslateFile);
     get(name: string, replacement?: string[] | Record<string, string | number>): Promise<string>;
@@ -1489,9 +1327,6 @@ export declare class TranslateInstance {
     setPropsName(name: string): this;
     setReadApi(value: boolean): this;
 }
-/**
- * Abstract class for URL state instances.
- */
 export declare abstract class UrlInstanceAbstract {
     get<T>(name: string, defaultValue?: T | (() => T)): T;
     set<T>(name: string, callback: T | (() => T)): this;
@@ -1499,9 +1334,6 @@ export declare abstract class UrlInstanceAbstract {
     removeWatch<T>(name: string, callback: (value: T) => void): this;
     reload(): this;
 }
-/**
- * Isomorphic utility class for URL management.
- */
 export declare class UrlItem {
     static getInstance(): UrlItem;
     constructor(url?: string | URL);
@@ -1535,6 +1367,14 @@ export declare function blobToBase64(blob: Blob, clean?: boolean): Promise<strin
 export declare function capitalize(value: string, isLocale?: boolean): string;
 export declare function copyObject<T>(value: T): T;
 export declare function copyObjectLite<T, R = T>(value: T, source?: any): R;
+/**
+ * Creates an HTML element with the specified tag name and options.
+ *
+ * @remarks
+ * When running on the server, the function always returns `undefined`.
+ * If you use it within a component's rendering logic, it may lead to hydration mismatches.
+ * It is recommended to call this function only inside lifecycle hooks that run exclusively on the client (e.g., `onMounted` in Vue or `useEffect` in React).
+ */
 export declare function createElement<T extends HTMLElement>(parentElement?: HTMLElement, tagName?: string, options?: Partial<T> | Record<keyof T, T[keyof T]> | ((element: T) => void), referenceElement?: HTMLElement): T | undefined;
 export declare function domContentLoaded<T = void>(callback: () => T | Promise<T>): Promise<T>;
 export declare function domQuerySelector<E extends Element = Element>(selectors: string): E | undefined;
@@ -1552,10 +1392,37 @@ export declare function getArrayHighlightMatch(value: string, search?: string |
 export declare function getAttributes<E extends ElementOrWindow>(element?: ElementOrString<E>): Record<string, string | undefined>;
 export declare function getClipboardData(event?: ClipboardEvent): Promise<string>;
 export declare function getColumn<T, K extends keyof T>(array: ObjectOrArray<T>, column: K): (T[K] | undefined)[];
+/**
+ * Returns the current date in the specified format.
+ *
+ * @remarks
+ * Using this function for rendering in SSR may lead to hydration mismatches
+ * because the time or time zone on the server may differ from the time on the client.
+ * It is recommended to use this function inside client-side hooks only (e.g., `onMounted` in Vue or `useEffect` in React).
+ */
 export declare function getCurrentDate(format?: GeoDate): string;
+/**
+ * Returns the current time in milliseconds.
+ *
+ * @remarks
+ * Using this function for rendering in SSR will almost certainly lead to hydration mismatches
+ * because the timestamp on the server will differ from the timestamp on the client.
+ */
 export declare function getCurrentTime(): number;
 export declare function getElement<E extends ElementOrWindow, R extends Exclude<E, Window>>(element?: ElementOrString<E>): R | undefined;
 export declare function getElementId<E extends ElementOrWindow>(element?: ElementOrString<E>, selector?: string): string;
+/**
+ * Initializes getElementId with a context provider.
+ *
+ * @warning
+ * Mandatory for correct SSR behavior on both server and client.
+ *
+ * @example
+ * ```typescript
+ * import { useId } from 'vue'
+ * initGetElementId(() => useId())
+ * ```
+ */
 export declare function initGetElementId(newListener: () => string | number): void;
 export declare function getElementImage(image: HTMLImageElement | string): HTMLImageElement | undefined;
 export declare function getElementItem<T extends ElementOrWindow, K extends keyof T, D>(element: ElementOrString<T>, index: K | string, defaultValue?: D): T[K] | D | undefined;
@@ -1643,16 +1510,22 @@ export declare function toCamelCase(value: string): string;
 export declare function toCamelCaseFirst(value: string): string;
 export declare function toDate<T extends Date | number | string>(value?: T): (T & Date) | Date;
 export declare function toKebabCase(value: string): string;
+/**
+ * Converts a string or number to a finite floating-point number.
+ *
+ * @example
+ * toNumber("1 234,56") // 1234.56
+ * toNumber("1,234.56") // 1234.56
+ * toNumber("1,234")    // 1.234
+ */
 export declare function toNumber(value?: NumberOrString): number;
 export declare function toNumberByMax(value: string | number, max?: string | number, formatting?: boolean, language?: string): string | number;
 export declare function toNumberPositive(value?: number | string | null, defaultValue?: number): number;
 export declare function toPercent(maxValue: number, value: number): number;
 export declare function toPercentBy100(maxValue: number, value: number): number;
 export declare function toString<T>(value: T): string;
-/**
- * Transforms a string into the corresponding primitive data type or object.
- */
 export declare function transformation(value: any, isFunction?: boolean): any;
 export declare function uint8ArrayToBase64(bytes: Uint8Array): string;
 export declare function uniqueArray<T>(value: T[]): T[];
-export declare function writeClipboardData(text: string): Promise<void>;
+export declare function writeClipboardData(text: string): Promise<void>;
+export declare const errorCauseList: ErrorCenterCauseList;

package/dist/library.js

@@ -160,7 +160,7 @@ function oe(e, t, n) {
 	return i.length === a.length ? i : (i.pop(), [...i, a.slice(n - 1).join(t)]);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.138.0/helpers/esm/typeof.js
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/typeof.js
 function C(e) {
 	"@babel/helpers - typeof";
 	return C = typeof Symbol == "function" && typeof Symbol.iterator == "symbol" ? function(e) {
@@ -170,7 +170,7 @@ function C(e) {
 	}, C(e);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.138.0/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/toPrimitive.js
 function se(e, t) {
 	if (C(e) != "object" || !e) return e;
 	var n = e[Symbol.toPrimitive];
@@ -182,13 +182,13 @@ function se(e, t) {
 	return (t === "string" ? String : Number)(e);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.138.0/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/toPropertyKey.js
 function ce(e) {
 	var t = se(e, "string");
 	return C(t) == "symbol" ? t : t + "";
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.138.0/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/defineProperty.js
 function w(e, t, n) {
 	return (t = ce(t)) in e ? Object.defineProperty(e, t, {
 		value: n,
@@ -671,7 +671,7 @@ var ve = "ui-storage", ye = () => D.get("__ui:data-storage__", () => ({})), O =
 	}
 	get() {
 		var e;
-		return (e = this.storage.get()) == null ? !1 : e;
+		return (e = this.storage.get()) != null && e;
 	}
 	set(e) {
 		this.storage.set(e);
@@ -1204,7 +1204,7 @@ var Me = class {
 		return s() && !n ? !1 : !!t;
 	}
 	static isAge(e) {
-		return e ? e.age ? e.age * 1e3 + e.cacheAge >= Date.now() : !0 : !1;
+		return e ? !e.age || e.age * 1e3 + e.cacheAge >= Date.now() : !1;
 	}
 	static isItem(e) {
 		return e in this.getList();
@@ -4135,7 +4135,7 @@ var qt = class {
 	}
 	getReturnEverything() {
 		var e;
-		return (e = this.getOptions().returnEverything) == null ? !1 : e;
+		return (e = this.getOptions().returnEverything) != null && e;
 	}
 	getDelay() {
 		var e;
@@ -4143,7 +4143,7 @@ var qt = class {
 	}
 	getFindExactMatch() {
 		var e;
-		return (e = this.getOptions().findExactMatch) == null ? !1 : e;
+		return (e = this.getOptions().findExactMatch) != null && e;
 	}
 	getClassName() {
 		var e;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/functional-basic",
   "private": false,
-  "version": "1.8.3",
+  "version": "1.8.5",
   "type": "module",
   "description": "Foundational isomorphic utility library for modern web and SSR development — HTTP client, state storage, i18n localization, SEO metadata, DOM events, formatting, and data utilities. Framework-agnostic, TypeScript-first.",
   "keywords": [

package/ai-prompts/coding-standards.md

@@ -1,6 +0,0 @@
-# Coding Standards & Conventions
-
-- **Class Structure**: Properties/Variables (`public`->`protected`->`private`) -> Constructor -> Public Methods -> Protected Methods -> Private Methods. Within each method group, follow order: 1) `get` / `set` (getters/setters), 2) `is...` / `has...`, 3) `get...` / `set...`, 4) `add...` / `remove...`, 5) `update...` / `reset...`, 6) remaining methods. Within each subgroup, methods are grouped semantically by logical pairs and rules (e.g., `min` / `max`, `width` / `height`, `x` / `y` / `z`), and remaining methods are sorted alphabetically.
-- **Style/Types**: `PascalCase` classes, `camelCase` methods/props, `UPPER_SNAKE_CASE` constants. No `any` (use `unknown`/generics). Explicit return types for ALL methods. Export all interfaces. Type files: `*Types.ts`. Use `@effect/schema` for schemas.
-- **SSR Safety**: Isomorphic code. Do NOT store request state in globals. Use `isDomRuntime()` before `window`/`document`. Use `ServerStorage.get('key', () => new Class())` for request-isolated singletons.
-- **Utility & Primitive Functions**: ALWAYS use primitive helper functions from this package (e.g. `isFunction`, `executeFunction`, `isFilled`, `isObject`, `isString`, `isArray`, etc.) instead of writing custom inline checks or conditions.