@dxtmisha/functional-basic 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.8.0] - 2026-07-25
+
+### Added
+- **domContentLoaded**: Introduced `domContentLoaded` DOM helper function to safely execute callbacks once the DOM is loaded, with comprehensive unit tests (`domContentLoaded.test.ts`).
+- **toNumberPositive**: Introduced `toNumberPositive` utility function to convert inputs to positive finite numbers (`> 0`) or return a default fallback (`0`), with unit tests (`toNumberPositive.test.ts`).
+- **sortList**: Introduced `sortList` standalone utility function for multi-column array sorting by property paths, directions (`'asc'`, `'desc'`), or custom comparison functions using locale-aware `Intl.Collator`.
+- **sortTypes**: Added `SortDir`, `SortColumnItem`, and `SortFunction` type definitions, extending `SortColumnItem` to allow optional `dir` and `column` properties for 3-state sorting cycles (`asc` -> `desc` -> `undefined`).
+- **getRandomItem**: Introduced a new `getRandomItem` utility function to safely retrieve a random element from arrays, objects, or primitive values, returning `undefined` when empty or missing, with full bilingual JSDocs.
+- **Tests**: Added unit test suites for `sortList` (`sortList.test.ts`), `getRandomItem` (`getRandomItem.test.ts`), `domContentLoaded` (`domContentLoaded.test.ts`), and `toNumberPositive` (`toNumberPositive.test.ts`).
+
 ## [1.7.1] - 2026-07-14
 
 ### Changed

package/README.md

@@ -81,3 +81,5 @@ Full API reference, examples, and guides:
 ## License
 
 [MIT](LICENSE)
+
+

package/ai-description.md

@@ -1,19 +1,7 @@
-### Core Purpose
-The library provides an isomorphic utility framework for managing high-level application concerns in JavaScript/TypeScript environments (SSR and DOM). It includes robust abstractions for API communication (REST/Fetch), structured state management, DOM-safe event handling, internationalization, and reactive data storage.
+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.
 
-### Key Expositions
-*   **API & Networking**: `Api` (singleton interface), `ApiInstance` (core requester), `ApiCache` (request memoization), `ApiError` (centralized error handling), `ApiHydration` (SSR data serialization), and `ApiHeaders`.
-*   **State & Storage**: `DataStorage` (persistent storage with prefixes/expiration), `ServerStorage` (SSR-safe context isolation), `CookieStorage` (isomorphic cookie management), `Query`/`Hash` (URL-state management), and `Global` (app-wide data).
-*   **UI & Events**: `EventItem` (DOM-safe, optimized event management with `ResizeObserver` and `scroll-sync`), `LoadingInstance` (global loading state), and `ScrollbarWidth` (layout utility).
-*   **Localization & Formatting**: `Geo` (locale/timezone management), `GeoIntl` (Intl API wrapper), `GeoUnit` (metric/imperial conversion), `Translate` (i18n), and `Formatters` (currency, number, date, and pluralization utility).
-*   **Utilities & Data**: `Formatters`, `SearchList` (search matching/caching), `ResumableTimer`, and a suite of functional utilities for object cloning, string/date manipulation, and DOM operations.
+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.
 
-### Triggers for Studying ai-types.md
-Review `ai-types.md` whenever the following requirements arise:
-1.  **API Integration**: You need to implement new request methods, custom error handling for specific HTTP status codes, or configure global API middleware (`wrapper`/`preparation`).
-2.  **I18n/Formatting**: You are dealing with complex localization rules, unit conversions (Geo/Units), or pluralization requirements.
-3.  **SSR Consistency**: You are implementing features that must function identically on both the server and client (Hydration, `ServerStorage`, or `Datetime` formatting).
-4.  **Complex State**: You need to map or query data structures in memory using `SearchList` or utilize `BroadcastChannel` for cross-context messaging.
+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).
 
-### Integration Context
-The library acts as a foundational service layer between the application logic and the runtime environment. It is designed to be framework-agnostic but is particularly optimized for SSR-heavy environments (like Vue/React) where hydration of state (via `ServerStorage`) and safe access to global browser objects (via `isDomRuntime`) are critical. It wraps native `fetch`, `localStorage`, `sessionStorage`, `BroadcastChannel`, and `Intl` APIs into structured, type-safe, and singleton-accessible services.
+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.

package/ai-doc.md

@@ -2,140 +2,61 @@
 
 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.
 
-## Coding Standards & Class Structure
+## 2. API Reference & Examples
 
-### 1. Class Member Order
-1. **Properties/Variables**: Top of class, ordered by visibility (`public` -> `protected` -> `private`). Initialize inline if possible.
-2. **Constructor**: Follows properties. Parameter properties (e.g. `protected url: string`) allowed.
-3. **Public Methods**:
-   1. Getters, checkers, status methods (`is*`, `get*`).
-   2. Setters & configuration (`set*`).
-   3. Core executors & actions (`request()`, `fetch()`, `show()`).
-4. **Protected Methods**: Internal helpers for subclasses.
-5. **Private Methods**: Internal helper logic at the very bottom.
-
-### 2. Style & Type Conventions
-- **Naming**: Classes = `PascalCase`, Methods/Properties = `camelCase`, Constants = `UPPER_SNAKE_CASE`.
-- **TypeScript**: No `any` (use `unknown`/generics). Explicit return types on ALL methods (including `void`). Export all types/interfaces. Suffix type files with `Types` (e.g., `*Types.ts`). Use `@effect/schema` for API schemas if present.
-- **SSR Safety**: Isomorphic code. Do not store request-specific state in static/global variables. Use `isDomRuntime()` before accessing `window`/`document`/`location`. Use `ServerStorage.get(key, () => new Instance())` for request-isolated singletons.
-
----
-
-## API Reference & Examples
-
-### 1. HTTP Client (`Api`, `ApiInstance`, `ApiCache`)
+### HTTP Client & Caching
 ```typescript
 import { Api, ApiCache } from '@dxtmisha/functional-basic';
-
-// Config
-Api.setOrigin('https://api.example.com');
-Api.setUrl('/api/v1');
-Api.setRequestDefault({ client: 'web' });
+Api.setOrigin('https://api.example.com'); Api.setUrl('/api/v1'); Api.setRequestDefault({ client: 'web' });
 Api.setHeaders(() => ({ Authorization: `Bearer ${localStorage.getItem('token') || ''}` }));
-
-// Interceptors
-Api.setPreparation(async (fetchOpts) => { if (fetchOpts.auth) fetchOpts.headers['X-Auth'] = '1'; });
-Api.setEnd(async (res, fetchOpts) => res.status === 401 ? { reset: true } : {});
-
-// Requests
-const users = await Api.request<User[]>('users'); // default GET
-const profile = await Api.get<User>({ path: 'profile' });
+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' } });
-
-// Cache
-await ApiCache.set('key', { data: 1 }, 60000); // ms age
-const cached = await ApiCache.get<{ data: number }>('key');
+await ApiCache.set('k', { a: 1 }, 60000); const cache = await ApiCache.get<{a: number}>('k');
 ```
 
-### 2. State & Storage Management
+### Storage & State
 ```typescript
 import { DataStorage, CookieStorage, Cookie, ServerStorage } from '@dxtmisha/functional-basic';
-
-// DataStorage (localStorage/sessionStorage)
-DataStorage.setPrefix('my_app_');
-const userStorage = new DataStorage<{ id: string }>('user_session', false); // true for sessionStorage
-userStorage.set({ id: '123' });
-const user = userStorage.get({ id: 'guest' }); // fallback default
-userStorage.remove();
-
-// Cookies
-CookieStorage.set('theme', 'dark', { age: 31536000, secure: true, sameSite: 'lax' });
-const theme = CookieStorage.get<string>('theme', 'light');
-CookieStorage.remove('theme');
-
-const tokenCookie = new Cookie<string>('auth_token');
-tokenCookie.set('xyz123', { secure: true });
-const token = tokenCookie.get();
-
-// SSR Request-Isolated Storage
-const myService = ServerStorage.get('myService', () => new MyService());
+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
 ```
 
-### 3. Geolocation & Localization
+### Geolocation, Formatting & Localization
 ```typescript
 import { Geo, GeoIntl, GeoFlag, GeoPhone } from '@dxtmisha/functional-basic';
-
-// Geo state
-const country = Geo.getCountry(); // e.g., 'VN'
-const lang = Geo.getLanguage();   // e.g., 'vi'
-Geo.set('en-US');
-
-// Formatters (Intl)
+const country = Geo.getCountry(); const lang = Geo.getLanguage(); Geo.set('en-US');
 const intl = new GeoIntl('en-US');
-intl.number(123456.78);          // '123,456.78'
-intl.currency(99.99, 'USD');      // '$99.99'
-intl.sizeFile(1024 * 1024 * 5);  // '5.00 MB'
-intl.date(new Date(), 'date');    // 'Jun 18, 2026'
-intl.date(new Date(), 'time');    // '10:48 PM'
-intl.relative(new Date(Date.now() - 3600000)); // '1 hour ago'
-intl.plural(3, 'apple|apples');   // '3 apples' ('one|other' or 'one|few|many|other')
-
-// Flags & Phones
+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 phoneInfo = GeoPhone.getByPhone('+84900000000'); // .phone = cleaned string
-const mask = GeoPhone.toMask('84900000000');
+const phone = GeoPhone.getByPhone('+84900000000'); const mask = GeoPhone.toMask('84900000000');
 ```
 
-### 4. DOM, Safe Events & Helpers
+### DOM, Events & Helpers
 ```typescript
-import { EventItem, goScrollSmooth, writeClipboardData, getClipboardData } from '@dxtmisha/functional-basic';
+import { EventItem, goScrollSmooth, writeClipboardData, getClipboardData, SearchList, Formatters, FormattersType, isFilled, isDomRuntime, copyObject, anyToString, sleep } from '@dxtmisha/functional-basic';
 
-// Leak-proof Event management
-const clickListener = new EventItem(window, 'click', (e) => console.log(e), { passive: true });
-clickListener.start();
-clickListener.stop(); // Call on destroy/cleanup!
+// Safe Events (leak-proof)
+const listener = new EventItem(window, 'click', console.log, { passive: true }); listener.start(); listener.stop();
 
 // DOM / Clipboard
-goScrollSmooth(document.getElementById('target'));
-await writeClipboardData('text');
-const text = await getClipboardData();
-```
+goScrollSmooth(document.getElementById('t')); await writeClipboardData('txt'); await getClipboardData();
 
-### 5. Search & Formatting Utilities
-```typescript
-import { SearchList, Formatters, FormattersType } from '@dxtmisha/functional-basic';
-
-// Search List with highlights
-const searcher = new SearchList([{ name: 'John Doe' }], ['name'], 'john');
-const results = searcher.to(); // returns matching items with highlighted markup in matching keys
-
-// Object Formatter
-const formatter = new Formatters({
-  price: { type: FormattersType.currency, options: 'USD' },
-  date: { type: FormattersType.date, options: { month: 'long', year: 'numeric' } }
-}, { price: 12000, date: '2026-06-18' });
-const formatted = formatter.to(); // { price: '$12,000.00', date: 'June 2026' }
-```
-
-### 6. General Helpers
-```typescript
-import { isFilled, isDomRuntime, copyObject, anyToString, sleep } from '@dxtmisha/functional-basic';
+// 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();
 
-isFilled([]); // false (works for strings, arrays, objects, numbers, booleans)
-isDomRuntime(); // true if in browser
-const cloned = copyObject({ a: 1 });
-const str = anyToString(123);
-await sleep(500);
+// General
+isFilled([]); // false (strings, arrays, objects, numbers, booleans)
+isDomRuntime(); const cloned = copyObject({ a: 1 }); const str = anyToString(123); await sleep(500);
 ```