@dxtmisha/functional-basic 1.8.2 → 1.8.4

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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,7 +1,11 @@
-An isomorphic TypeScript utility framework designed to provide core runtime services for web applications across browser and Server-Side Rendering (SSR) environments. Its primary functions include wrapping the Fetch API with request/response caching and hydration, state management isolated by request context, comprehensive internationalization (i18n, unit conversions, phone masking, date/number formatting), SEO meta tag synchronization, reactive URL hash and query parameter tracking, managed DOM event lifecycle handling, in-memory list search with string highlighting, and centralized error handling.
+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.
 
-Api and ApiInstance manage Fetch-based HTTP communication featuring retries, custom headers, preparation hooks, and mock response emulation. ApiCache handles client and server data caching. ServerStorage and DataStorage provide isomorphic request-isolated state retention and browser storage abstraction with SSR hydration support. CookieStorage and Cookie manage client/server cookies consistently. Geo, GeoIntl, GeoPhone, GeoUnit, and Datetime form a localization engine handling Intl formatting, country phone masking, unit conversions, and date calculations. Translate and TranslateInstance manage synchronous and asynchronous translation batching. Query, QueryInstance, Hash, and HashInstance offer reactive, watchable interfaces for URL query strings and hash parameters. EventItem wraps DOM event listeners with ResizeObserver and requestAnimationFrame scroll optimizations. SearchList provides in-memory text search, regex generation, and matching string highlights. Meta, MetaOg, and MetaTwitter manage standard HTML, Open Graph, and Twitter Card metadata tags in the DOM or as HTML strings. ErrorCenter provides centralized error tracking and routing.
+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.
 
-Studying ai-types.md is mandatory when implementing or typing API configurations (ApiFetch, ApiConfig, ApiHydrationItem), setting up application error handling (ErrorCenterCauseItem, ErrorCenterHandlerList), configuring complex list transformations (FormattersOptionsList, FormattersType), managing geographic and phone mask parameters (GeoItem, GeoDate, GeoPhoneValue), defining search parameters (SearchOptions, SearchColumns), configuring SEO meta types (MetaOpenGraphTag, MetaTwitterCard), or working with core generic utility types (ArrayToItem, NormalOrPromise, ObjectOrArray, NumberOrString).
+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 operates as a foundational layer directly above native browser and Node.js runtime APIs (Fetch API, Intl API, DOM Window/Element interfaces, ResizeObserver, BroadcastChannel, Web Storage). It integrates with frontend SSR frameworks (such as Vue, React, Nuxt, or Next.js) by decoupling server-side request state via ServerStorage and generating safe client hydration scripts (getElementSafeScript) to prevent client-server hydration mismatches.
+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.
+## 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

package/ai-doc.md

@@ -1,65 +1 @@
-# @dxtmisha/functional-basic Reference
-
-Framework-agnostic utility library. **Vue developers MUST search `@dxtmisha/functional` first**; use this ONLY if no reactive/Vue-specific analog exists.
-
-## 1. 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.
-
-## 2. API Reference & Examples
-
-### HTTP Client & Caching
-```typescript
-import { Api, ApiCache } from '@dxtmisha/functional-basic';
-Api.setOrigin('https://api.example.com'); Api.setUrl('/api/v1'); Api.setRequestDefault({ client: 'web' });
-Api.setHeaders(() => ({ Authorization: `Bearer ${localStorage.getItem('token') || ''}` }));
-Api.setPreparation(async (opts) => { if (opts.auth) opts.headers['X-Auth'] = '1'; });
-Api.setEnd(async (res) => res.status === 401 ? { reset: true } : {});
-const users = await Api.request<User[]>('users'); // GET
-const updated = await Api.post<User>({ path: 'profile', request: { name: 'New' } });
-await ApiCache.set('k', { a: 1 }, 60000); const cache = await ApiCache.get<{a: number}>('k');
-```
-
-### Storage & State
-```typescript
-import { DataStorage, CookieStorage, Cookie, ServerStorage } from '@dxtmisha/functional-basic';
-DataStorage.setPrefix('app_');
-const ls = new DataStorage<{ id: string }>('user', false); ls.set({ id: '1' }); ls.get({ id: '0' }); ls.remove();
-CookieStorage.set('t', 'dark', { age: 31536000, secure: true }); CookieStorage.get<string>('t', 'light');
-const c = new Cookie<string>('auth'); c.set('xyz', { secure: true }); c.get();
-const srv = ServerStorage.get('svc', () => new Svc()); // SSR isolated
-```
-
-### Geolocation, Formatting & Localization
-```typescript
-import { Geo, GeoIntl, GeoFlag, GeoPhone } from '@dxtmisha/functional-basic';
-const country = Geo.getCountry(); const lang = Geo.getLanguage(); Geo.set('en-US');
-const intl = new GeoIntl('en-US');
-intl.number(1234.5); intl.currency(99, 'USD'); intl.sizeFile(1024*1024); intl.date(new Date(), 'date');
-intl.relative(new Date(Date.now() - 3600000)); intl.plural(3, 'apple|apples');
-const flag = new GeoFlag().getFlag('VN');
-const phone = GeoPhone.getByPhone('+84900000000'); const mask = GeoPhone.toMask('84900000000');
-```
-
-### DOM, Events & Helpers
-```typescript
-import { EventItem, goScrollSmooth, writeClipboardData, getClipboardData, SearchList, Formatters, FormattersType, isFilled, isFunction, executeFunction, isDomRuntime, copyObject, anyToString, sleep } from '@dxtmisha/functional-basic';
-
-// Safe Events (leak-proof)
-const listener = new EventItem(window, 'click', console.log, { passive: true }); listener.start(); listener.stop();
-
-// DOM / Clipboard
-goScrollSmooth(document.getElementById('t')); await writeClipboardData('txt'); await getClipboardData();
-
-// Search & Formatters
-const res = new SearchList([{ n: 'John' }], ['n'], 'jo').to(); // Highlights matches
-const fmt = new Formatters({ p: { type: FormattersType.currency, options: 'USD' } }, { p: 12 }).to();
-
-// General
-isFilled([]); // false (strings, arrays, objects, numbers, booleans)
-executeFunction(callbackOrValue, arg1); // Executes callback if function, or returns value as is
-isFunction(val); // Type-guard for functions
-isDomRuntime(); const cloned = copyObject({ a: 1 }); const str = anyToString(123); await sleep(500);
-```
+Framework-agnostic utility library. **Vue developers MUST search `@dxtmisha/functional` first**; use this ONLY if no reactive/Vue-specific analog exists.

package/ai-mcp.json

@@ -0,0 +1,26 @@
+[
+  {
+    "uri": "@dxtmisha/functional-basic/ai-types.md",
+    "name": "TypeScript Type Definitions",
+    "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."
+  },
+  {
+    "uri": "@dxtmisha/functional-basic/ai-description.md",
+    "name": "Isomorphic Utility Toolkit",
+    "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."
+  },
+  {
+    "uri": "@dxtmisha/functional-basic/ai-prompts/api-reference.md",
+    "name": "API Reference Guide",
+    "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."
+  }
+]

package/ai-prompts/api-reference.md

@@ -0,0 +1,55 @@
+# API Reference & Examples
+
+## HTTP Client & Caching
+```typescript
+import { Api, ApiCache } from '@dxtmisha/functional-basic';
+Api.setOrigin('https://api.example.com'); Api.setUrl('/api/v1'); Api.setRequestDefault({ client: 'web' });
+Api.setHeaders(() => ({ Authorization: `Bearer ${localStorage.getItem('token') || ''}` }));
+Api.setPreparation(async (opts) => { if (opts.auth) opts.headers['X-Auth'] = '1'; });
+Api.setEnd(async (res) => res.status === 401 ? { reset: true } : {});
+const users = await Api.request<User[]>('users'); // GET
+const updated = await Api.post<User>({ path: 'profile', request: { name: 'New' } });
+await ApiCache.set('k', { a: 1 }, 60000); const cache = await ApiCache.get<{a: number}>('k');
+```
+
+## Storage & State
+```typescript
+import { DataStorage, CookieStorage, Cookie, ServerStorage } from '@dxtmisha/functional-basic';
+DataStorage.setPrefix('app_');
+const ls = new DataStorage<{ id: string }>('user', false); ls.set({ id: '1' }); ls.get({ id: '0' }); ls.remove();
+CookieStorage.set('t', 'dark', { age: 31536000, secure: true }); CookieStorage.get<string>('t', 'light');
+const c = new Cookie<string>('auth'); c.set('xyz', { secure: true }); c.get();
+const srv = ServerStorage.get('svc', () => new Svc()); // SSR isolated
+```
+
+## Geolocation, Formatting & Localization
+```typescript
+import { Geo, GeoIntl, GeoFlag, GeoPhone } from '@dxtmisha/functional-basic';
+const country = Geo.getCountry(); const lang = Geo.getLanguage(); Geo.set('en-US');
+const intl = new GeoIntl('en-US');
+intl.number(1234.5); intl.currency(99, 'USD'); intl.sizeFile(1024*1024); intl.date(new Date(), 'date');
+intl.relative(new Date(Date.now() - 3600000)); intl.plural(3, 'apple|apples');
+const flag = new GeoFlag().getFlag('VN');
+const phone = GeoPhone.getByPhone('+84900000000'); const mask = GeoPhone.toMask('84900000000');
+```
+
+## DOM, Events & Helpers
+```typescript
+import { EventItem, goScrollSmooth, writeClipboardData, getClipboardData, SearchList, Formatters, FormattersType, isFilled, isFunction, executeFunction, isDomRuntime, copyObject, anyToString, sleep } from '@dxtmisha/functional-basic';
+
+// Safe Events (leak-proof)
+const listener = new EventItem(window, 'click', console.log, { passive: true }); listener.start(); listener.stop();
+
+// DOM / Clipboard
+goScrollSmooth(document.getElementById('t')); await writeClipboardData('txt'); await getClipboardData();
+
+// Search & Formatters
+const res = new SearchList([{ n: 'John' }], ['n'], 'jo').to(); // Highlights matches
+const fmt = new Formatters({ p: { type: FormattersType.currency, options: 'USD' } }, { p: 12 }).to();
+
+// General
+isFilled([]); // false (strings, arrays, objects, numbers, booleans)
+executeFunction(callbackOrValue, arg1); // Executes callback if function, or returns value as is
+isFunction(val); // Type-guard for functions
+isDomRuntime(); const cloned = copyObject({ a: 1 }); const str = anyToString(123); await sleep(500);
+```

package/ai-prompts/coding-standards.md

@@ -0,0 +1,6 @@
+# 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.