@dxtmisha/functional-basic 1.11.0 → 1.11.2

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.11.1] - 2026-10-04
+
+### Changed
+- **`ErrorCenter`**:
+  - Implemented lazy singleton initialization for `ErrorCenter.getItem()`, avoiding premature top-level module instantiation of `ErrorCenterInstance` and improving tree-shaking and SSR execution safety.
+- **Tree-Shaking & Top-Level Purity**:
+  - Replaced dynamic regular expressions (`new RegExp(...)`) with static regex literals in `addTagHighlightMatch` (`/___HIGHLIGHT_START___|___HIGHLIGHT_END___/g`) and `applyTemplate` (`/%(d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s|t|u|v)/g`) to eliminate module initialization side effects.
+  - Replaced dynamic `random()`-based tag generation in `addTagHighlightMatch` with static tags (`___HIGHLIGHT_START___` / `___HIGHLIGHT_END___`).
+  - Simplified `Icons.getUrlGlobal()` by removing unused `Api` import and redundant localhost ternary check.
+  - Extracted `API_CACHE_DEFAULT_STEP_AGE_CLEAR_OLD` constant in `ApiCache` for cache cleanup intervals.
+- **AI Type Definitions**:
+  - Applied `// ai-none` annotations across secondary class files to optimize AI context window and documentation size.
+
 ## [1.11.0] - 2026-09-07
 
 ### Added

package/ai-description.md

@@ -1,8 +1,8 @@
-This package provides a comprehensive isomorphic toolkit containing core services, state managers, and utilities for both browser and server-side runtimes. It includes integrated modules for HTTP requests with SSR hydration and caching, geographic localization, date and measurement unit formatting, dictionary translations, persistent storage, and URL state synchronization. An AI assistant should consult this package when implementing API integration layers, configuring SEO and social metadata, managing multi-locale formatting, or coordinating client-server storage and DOM utilities.
+This package provides a comprehensive isomorphic foundational toolkit containing utilities for API communication, request lifecycle handling, storage management, and DOM manipulation. It includes robust internationalization and localization systems for date-time calculations, units, currencies, phone masks, and multi-language translations, alongside SEO meta tag generation and URL state synchronization. An AI assistant should study this package when implementing client-server data fetching with SSR hydration, browser storage persistence, localized data formatting, text search matching, or DOM event lifecycle control.
 
-Key Capabilities: API Client, Request Caching, SSR Hydration, API Mocking, Error Management, Geographic Localization, Locale Formatting, Translation Management, Phone Masking, Unit Conversion, DateTime Localization, Cookie Management, Server Storage, Browser Storage, URL State Sync, Broadcast Messaging, SEO Meta Management, Open Graph Metadata, Twitter Card Management, DOM Event Handling, Search List Filtering, Text Highlighting, Clipboard Utilities, Global Loading State
+Key Capabilities: HTTP Client, SSR Hydration, API Caching, Request Interceptors, Cross-Tab Messaging, Cookie Management, Local Storage, Session Storage, In-Memory Caching, Date Manipulation, Locale Formatting, Currency Formatting, Unit Conversion, Phone Number Masking, Flag Icons, Translation Management, Meta Tag Management, Open Graph SEO, Twitter Cards, URL Query Management, URL Hash Routing, Search Highlighting, List Sorting, DOM Event Management, Global Loading State, Resumable Timer, Clipboard Utilities, Image Resizing, Scroll Control, Type Checking Utilities
 ## Mandatory Rules
 You MUST evaluate whether your task relates to any of the following topics (even if not working directly with this package). If related material is present, you are strictly obligated to read and study the corresponding file before proceeding:
-- 'node_modules/@dxtmisha/functional-basic/ai-resources/api-reference.md': API reference and code examples for HTTP client, storage, localization, DOM, and utility functions.
+- 'node_modules/@dxtmisha/functional-basic/ai-resources/api-reference.md': Provides usage guidelines and API references for HTTP requests, caching, storage, localization, and DOM utility functions.
 - 'node_modules/@dxtmisha/functional-basic/ai-resources/design-config.md': Rules and schema for configuring design systems, TypeScript declaration scanning, AI generation, and package settings.
 - 'node_modules/@dxtmisha/functional-basic/ai-resources/error-center.md': Standards and APIs for centralized error handling, routing exceptions via ErrorCenter without direct console logging.

package/ai-mcp-resources.json

@@ -15,7 +15,7 @@
     "uri": "@dxtmisha/functional-basic/ai-resources/api-reference.md",
     "name": "Functional Basic API Reference (@dxtmisha/functional-basic)",
     "mimeType": "text/markdown",
-    "description": "API reference and code examples for HTTP client, storage, localization, DOM, and utility functions."
+    "description": "Provides usage guidelines and API references for HTTP requests, caching, storage, localization, and DOM utility functions."
   },
   {
     "uri": "@dxtmisha/functional-basic/ai-resources/design-config.md",

package/ai-resources/api-reference.md

@@ -12,6 +12,74 @@ 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');
 ```
 
+### Error Responses & Return Types (`ApiData<T>`)
+
+When an error occurs during an API call, `Api` behaves differently depending on whether it is an HTTP response error or a network/runtime failure:
+
+#### 1. HTTP Errors (HTTP status >= 400)
+`Api.request`, `Api.get`, `Api.post`, etc. do **NOT** throw an exception on HTTP errors (e.g. 400, 401, 403, 404, 500). Instead, they return the parsed response wrapped as `ApiData<T>` (`ApiDataItem<T>`), enriched with status and error metadata:
+
+```typescript
+import { Api, ApiError, ApiMethodItem } from '@dxtmisha/functional-basic';
+
+// Optional: register known error patterns in advance
+ApiError.add({
+  url: 'users/login',
+  method: ApiMethodItem.post,
+  code: 'INVALID_CREDENTIALS',
+  message: 'Invalid email or password'
+});
+
+// Response returns ApiDataItem<T> with error metadata attached:
+const response = await Api.get<User>({ path: 'users/999' });
+
+// 1. Response status metadata: `statusObject` (ApiStatusItem)
+response.statusObject?.status;       // number - HTTP status code (e.g. 404, 500)
+response.statusObject?.statusText;   // string - HTTP status text (e.g. "Not Found")
+response.statusObject?.lastStatus;   // ApiStatusType ('error' | 'warning' | 'info' | 'success')
+response.statusObject?.lastCode;     // string | undefined - Server error code
+response.statusObject?.lastMessage;  // string | undefined - Error message or status text
+response.statusObject?.error;        // string | undefined - Error string if exception occurred
+
+// 2. Structured error helper: `errorObject` (ApiErrorItem)
+// Available when `initError: true` (default) and matching error found or response evaluated
+response.errorObject?.getCode();     // string | undefined - Matched error code (e.g. 'INVALID_CREDENTIALS')
+response.errorObject?.getMessage();  // string | undefined - Evaluated error message
+response.errorObject?.getStatus();   // number - HTTP status code (e.g. 404)
+response.errorObject?.getResponse(); // Response - Raw Fetch Response object
+response.errorObject?.getMethod();   // ApiMethodItem - Request HTTP method
+
+// 3. Extracted metadata fields (automatically merged if returned by backend):
+response.success;                    // boolean - false on error
+response.code;                       // string | number - Error code from backend
+response.message;                    // string - Backend error message
+response.error;                      // { code?: string | number, message?: string }
+
+// 4. Global status inspection for the last executed request:
+const status = Api.getStatus();      // ApiStatus instance
+status.getStatus();                  // number (e.g. 404)
+status.getStatusType();              // 'error'
+status.getMessage();                 // Error message string
+```
+
+#### 2. Network & Runtime Errors (Throws Exception)
+Network failures (connection refused, DNS failure, offline mode, timeout via `AbortController`) throw an exception and must be handled with `try / catch`:
+
+```typescript
+try {
+  await Api.get({ path: 'users', timeout: 5000 });
+} catch (error) {
+  // Network failures, TimeoutError, or Offline
+  const lastError = Api.getStatus().getError(); // String error recorded in ApiStatus
+}
+```
+
+#### 3. Error Routing & Options
+- **`ErrorCenter` Integration**: HTTP errors (status >= 400) and network exceptions are automatically dispatched to `ErrorCenter.on(...)` (groups: `'api'`, `'api-server'`).
+- **`hideError?: boolean`**: Set to `true` in `apiFetch` configuration to suppress dispatching errors to `ErrorCenter`.
+- **`initError?: boolean`**: Set to `false` in `apiFetch` configuration to disable extracting `ApiErrorItem` (`errorObject`).
+
+
 ## Storage & State
 ```typescript
 import { DataStorage, CookieStorage, Cookie, ServerStorage } from '@dxtmisha/functional-basic';