@dxtmisha/functional-basic 1.8.4 → 1.8.5

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 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

package/ai-description.md

@@ -1,11 +1,4 @@
-This library serves as a comprehensive isomorphic runtime toolkit providing core utility primitives for HTTP networking, state persistence, internationalization, metadata management, DOM manipulation, and data transformation across browser and server-side rendering environments.
-
-Its main capabilities are organized into high-level functional groupings: API and network utilities handle HTTP request orchestration, response caching, structured error normalization, retry strategies, and SSR hydration script generation; storage utilities manage cookies, local and session storage, request-isolated server storage, and inter-tab broadcast messaging; internationalization and localization modules process geographic standards, timezone conversions, localized number/date/unit formatting, phone masking, and pluralization rules; DOM and event helpers provide lifecycle-managed event listeners, smooth scrolling, visibility checks, element creation, and global loading indicators; metadata modules provide a unified interface to generate and manage HTML, Open Graph, and Twitter Card tags; and data processing functions handle string transformations, deep copying, template replacement, fuzzy searching with query highlighting, and list sorting.
-
-It is mandatory to study "ai-types.md" when configuring typed API request payloads and hooks, defining custom error center callbacks, constructing complex localized formatter options, implementing schema-driven search or sorting parameters, or working with environment-specific storage contracts.
-
-The library integrates into modern web application stacks by offering framework-agnostic utilities that safely detect browser versus SSR runtimes while supporting seamless client hydration workflows.
+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, geolocation, localization, formatting, DOM events, and utility helpers
-- 'node_modules/@dxtmisha/functional-basic/ai-prompts/coding-standards.md': Class structure, 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,26 +1,20 @@
 [
   {
     "uri": "@dxtmisha/functional-basic/ai-types.md",
-    "name": "TypeScript Type Definitions",
+    "name": "TypeScript Types Reference (@dxtmisha/functional-basic)",
     "mimeType": "text/markdown",
-    "description": "Comprehensive TypeScript type definitions, enums, class interfaces, and utility function signatures for API request handling, internationalization, and client-side data management."
+    "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-description.md",
-    "name": "Isomorphic Utility Toolkit",
+    "name": "Utility Library Overview (@dxtmisha/functional-basic)",
     "mimeType": "text/markdown",
-    "description": "Provides an architectural overview of the isomorphic runtime toolkit covering HTTP networking, state persistence, i18n, DOM helpers, and metadata management across browser and SSR environments. Details core utility capabilities and outlines mandatory cross-referencing rules for API references, types, and coding standards."
+    "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",
+    "name": "API Reference Guide (@dxtmisha/functional-basic)",
     "mimeType": "text/markdown",
-    "description": "API reference and code usage examples for @dxtmisha/functional-basic, detailing HTTP clients, caching, storage, geolocation, DOM events, and general utilities."
-  },
-  {
-    "uri": "@dxtmisha/functional-basic/ai-prompts/coding-standards.md",
-    "name": "Coding Standards",
-    "mimeType": "text/markdown",
-    "description": "Architectural conventions, class structure rules, SSR safety guidelines, and TypeScript typing standards for code implementation."
+    "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

@@ -535,7 +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 declare const errorCauseList: ErrorCenterCauseList;
 export declare class Api {
     static isLocalhost(): boolean;
     static getItem(): ApiInstance;
@@ -690,34 +689,20 @@ export declare class BroadcastMessage<Message = any> {
     setCallbackError(callbackError: (event: MessageEvent<Message>) => void): this;
     destroy(): this;
 }
-/** @deprecated This class is obsolete and should not be used */
 export declare class Cache {
     get<T>(name: string, callback: () => T, comparison?: any[]): T;
     getAsync<T>(name: string, callback: () => T, comparison?: any[]): Promise<T>;
 }
-/** @deprecated This class is obsolete and should not be used */
 export declare class CacheItem<T> {
     constructor(callback: () => T);
     getCache(comparison: any[]): T;
     getCacheOld(): T | undefined;
     getCacheAsync(comparison: any[]): Promise<T>;
 }
-/** @deprecated This class is obsolete and should not be used */
 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>;
 }
-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 Cookie<T> {
     static getInstance<T>(name: string): Cookie<T>;
     constructor(name: string);
@@ -734,6 +719,17 @@ export declare class CookieBlockInstance {
     get(): boolean;
     set(value: boolean): void;
 }
+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;
@@ -751,9 +747,12 @@ export declare class DataStorage<T> {
     update(): this;
 }
 /**
+ * A class for working with dates and localized date-time operations.
+ *
  * @remarks
- * Creating a `Datetime` instance without a specific date (using current time)
- * in SSR may lead to hydration mismatches.
+ * 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);
@@ -862,6 +861,25 @@ export declare class ErrorCenterInstance {
     setIsConsole(isConsole: ErrorCenterHandlerIsConsole): this;
     on(cause: ErrorCenterCauseItem): this;
 }
+/**
+ * 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);
     isActive(): boolean;
@@ -1025,7 +1043,8 @@ export declare class Hash {
     static removeWatch<T>(name: string, callback: (value: T) => void): void;
     static reload(): void;
 }
-export declare class HashInstance extends UrlInstanceAbstract {}
+export declare class HashInstance extends UrlInstanceAbstract {
+}
 export type IconsItem = string | Promise<string | any> | (() => Promise<string | any>);
 export type IconsConfig = {
     url?: string;
@@ -1176,7 +1195,8 @@ export declare class Query {
     static removeWatch<T>(name: string, callback: (value: T) => void): void;
     static reload(): void;
 }
-export declare class QueryInstance extends UrlInstanceAbstract {}
+export declare class QueryInstance extends UrlInstanceAbstract {
+}
 export declare class ResumableTimer {
     constructor(callback: FunctionVoid, delay?: number, blockStart?: boolean);
     resume(): this;
@@ -1252,7 +1272,7 @@ export declare class ServerStorage {
     static reset(): void;
     static has(key: string): boolean;
     static get<T = any>(key: string, defaultValue?: () => T, hydration?: boolean): T;
-    static set<T = any>(key: string, value: () => T, hydration?: boolean, storageList?: ServerStorageList): T;
+    static set<T = any>(key: string, value: () => T, hydration?: boolean, storageList?: Record<string, any>): T;
     static setErrorStatus(hide: boolean): void;
     static remove(key: string): void;
     static toString(): string;
@@ -1341,15 +1361,19 @@ export declare class UrlItem {
 }
 export declare function addTagHighlightMatch(value: string, search?: string | RegExp, className?: string, shouldEscape?: boolean): string;
 export declare function anyToString<V>(value: V, isArrayString?: boolean, trim?: boolean): string;
-export declare function applyTemplate(text: string, replacement?: Record<string, string | number | boolean> | string[]): string;
+export declare const applyTemplate: (text: string, replacement?: Record<string, string | number | boolean> | string[]) => string;
 export declare function arrFill<T>(value: T, count: number): T[];
 export declare function blobToBase64(blob: Blob, clean?: boolean): Promise<string | undefined>;
 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
- * Always returns `undefined` when running on server.
+ * 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>;
@@ -1369,23 +1393,33 @@ export declare function getAttributes<E extends ElementOrWindow>(element?: Eleme
 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 in SSR may cause hydration mismatches.
+ * 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 in SSR will cause hydration mismatches.
+ * 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;
 /**
- * @warning Initialization mandatory for correct SSR functioning.
+ * Initializes getElementId with a context provider.
+ *
+ * @warning
+ * Mandatory for correct SSR behavior on both server and client.
+ *
  * @example
  * ```typescript
  * import { useId } from 'vue'
- * import { initGetElementId } from '@dxtmisha/functional-basic'
  * initGetElementId(() => useId())
  * ```
  */
@@ -1456,7 +1490,7 @@ export declare function removeCommonPrefix(mainStr: string, prefix: string): str
 export declare const replaceComponentName: (text: string | undefined, name: string, componentName: string) => string | undefined;
 export declare function replaceRecursive<I>(array: ObjectItem<I>, replacement?: ObjectOrArray<I>, isMerge?: boolean): ObjectItem<I>;
 export declare function replaceTemplate(value: string, replaces: Record<string, string | FunctionReturn<string>>): string;
-export type ResizeImageByMaxType = 'auto' | 'width' | 'height';
+type ResizeImageByMaxType = 'auto' | 'width' | 'height';
 export declare function resizeImageByMax(image: HTMLImageElement | string, maxSize: number, type?: ResizeImageByMaxType, typeData?: string): string | undefined;
 export declare function secondToTime(second: number | string | undefined, hasHour?: boolean): string;
 export declare function setElementItem<E extends ElementOrWindow, K extends keyof E, V extends E[K] = E[K]>(element: ElementOrString<E>, index: K, value: V | Record<string, V>): E | undefined;
@@ -1476,6 +1510,14 @@ 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;
@@ -1485,4 +1527,5 @@ export declare function toString<T>(value: T): string;
 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.4",
+  "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.