@dxtmisha/functional-basic 1.8.1 → 1.8.3

package/ai-description.md

@@ -1,7 +1,5 @@
-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.
-
-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.
-
-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).
-
-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.
+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.
+## 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

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 (Getters -> Setters -> Core actions) -> Protected Methods -> Private Methods.
-- **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,14 @@
+[
+  {
+    "uri": "@dxtmisha/functional-basic/ai-prompts/api-reference.md",
+    "name": "API Reference",
+    "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."
+  },
+  {
+    "uri": "@dxtmisha/functional-basic/ai-prompts/coding-standards.md",
+    "name": "Coding Standards",
+    "mimeType": "text/markdown",
+    "description": "Defines class structure ordering, TypeScript styling and typing conventions, isomorphic SSR safety rules, and standard primitive helper function usage."
+  }
+]

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.