@dxtmisha/functional-basic 1.10.1 → 1.11.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 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
+- **Configuration Types**:
+  - Added `DesignUiConfigPackagePrompt`, `promptInclude`, and `promptPackageOnly` type definitions to `src/types/basicTypes.ts`.
+  - Added AI resource documentation for `design-config.md` with prompt exclusion rules.
+
+### Changed
+- **Dependencies**:
+  - Updated workspace package dependencies to explicit `>=` semver ranges (`@dxtmisha/media >= 0.7.3`).
+- **AI Documentation**:
+  - Refined descriptions and updated MD5 hashes in `ai-types-list/resources/` for `design-config.json` and `error-center.json`.
+
 ## [1.10.1] - 2026-08-30
 
 ### Added

package/ai-description.md

@@ -1,13 +1,8 @@
-### Package Description
-A comprehensive isomorphic utility framework providing client/SSR HTTP client management, locale-aware internationalization, data caching, storage abstraction, DOM event handling, search filtering, and SEO metadata orchestration.
+This package provides a comprehensive isomorphic utility foundation for web applications, delivering tools for HTTP communication, client-server state hydration, cross-tab messaging, and storage isolation. It includes complete systems for internationalization, localized date and number formatting, geographic metadata, translation handling, SEO meta tags, and URL state synchronization. An AI assistant should study "ai-types.md" when implementing localized data formatting, isomorphic HTTP requests, browser storage persistence, URL query manipulation, or multi-field list searching in web projects.
 
-### Triggers for Studying ai-types.md
-Study `ai-types.md` when configuring or executing HTTP requests, handling SSR hydration, setting up request/response interceptors or mock emulators (`Api`, `ApiFetch`, `ApiResponse`, `ApiPreparation`, `ApiHeaders`), managing persistent and session storage across DOM and server runtimes (`CookieStorage`, `DataStorage`, `ServerStorage`), implementing localized formatting for dates, currencies, numbers, units, or phone numbers (`Geo`, `GeoIntl`, `GeoUnit`, `GeoPhone`, `Datetime`), configuring i18n translation batching or file loaders (`Translate`, `TranslateFile`), setting up centralized error handling (`ErrorCenter`), binding resilient DOM listeners or resize/scroll observers (`EventItem`), building regex-based searchable lists and highlighted match views (`SearchList`, `Formatters`), managing Open Graph and Twitter Card SEO tags (`Meta`, `MetaOg`, `MetaTwitter`), or synchronizing state with URL hash and query parameters (`Query`, `Hash`, `UrlItem`).
-
-### Key Capabilities
-HTTP Client Integration, API Response Caching, SSR State Hydration, Isomorphic Cookie Storage, Web Storage Abstraction, Locale Internationalization, Datetime Manipulation, Multi Unit Conversion, Phone Number Masking, I18n Translation Management, Centralized Error Handling, DOM Event Management, Search Filtering, Match Highlighting, URL State Synchronization, SEO Meta Management, Cross Tab Messaging, Global Loading Tracking
+Key Capabilities: HTTP Client, API Hydration, SSR Storage Isolation, Cookie Management, In-Memory Caching, Date Time Localization, Internationalization Formatting, Unit Conversion, Country Flags, Phone Mask Parsing, Translation Management, SEO Meta Tags, Open Graph Metadata, URL Parameter Handling, Hash State Routing, DOM Event Handling, Cross-Tab Messaging, List Search Filtering, Search Text Highlighting, Clipboard Integration, Web Share API, Resumable Timers, Scrollbar Width Calculation
 ## 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': Comprehensive API reference and code examples for the @dxtmisha/functional-basic utility package. Covers HTTP networking, client/server storage, internationalization, DOM utilities, and general helper functions. Streamlines common frontend and SSR development tasks including state persistence, API integration, and formatting.
-- 'node_modules/@dxtmisha/functional-basic/ai-resources/design-config.md': Specification and configuration reference for design.config.json across DXT UI packages and monorepo roots. Defines rules for configuration inheritance, TypeScript declaration scanning, AI provider integrations, and documentation generation. Standardizes build parameters and toolchain automation across packages.
-- 'node_modules/@dxtmisha/functional-basic/ai-resources/error-center.md': Defines mandatory error management standards and API rules using ErrorCenter in @dxtmisha/functional-basic. Prohibits direct console logging and enforces structured error dispatching across all application domains. Guides error registration, custom group handlers, and external telemetry integration.
+- '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-doc.md

@@ -2,7 +2,7 @@ Framework-agnostic utility library. **Vue developers MUST search `@dxtmisha/func
 
 ## 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.
+- **Class Structure**: Properties/Variables (`public`->`protected`->`private`) -> Constructor -> Public Methods -> Protected Methods -> Private Methods. Within each method group, follow order: 1) `get` (getters), 2) `set` (setters), 3) `is...`, 4) `has...`, 5) `get...`, 6) `set...`, 7) `add...`, 8) `remove...`, 9) `update...`, 10) `reset...`, 11) 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-resources.json

@@ -15,18 +15,18 @@
     "uri": "@dxtmisha/functional-basic/ai-resources/api-reference.md",
     "name": "Functional Basic API Reference (@dxtmisha/functional-basic)",
     "mimeType": "text/markdown",
-    "description": "Comprehensive API reference and code examples for the @dxtmisha/functional-basic utility package. Covers HTTP networking, client/server storage, internationalization, DOM utilities, and general helper functions. Streamlines common frontend and SSR development tasks including state persistence, API integration, and formatting."
+    "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",
-    "name": "Design Config Guide (@dxtmisha/functional-basic)",
+    "name": "Design System Configuration Guide (@dxtmisha/functional-basic)",
     "mimeType": "text/markdown",
-    "description": "Specification and configuration reference for design.config.json across DXT UI packages and monorepo roots. Defines rules for configuration inheritance, TypeScript declaration scanning, AI provider integrations, and documentation generation. Standardizes build parameters and toolchain automation across packages."
+    "description": "Rules and schema for configuring design systems, TypeScript declaration scanning, AI generation, and package settings."
   },
   {
     "uri": "@dxtmisha/functional-basic/ai-resources/error-center.md",
-    "name": "Centralized Error Handling Guide (@dxtmisha/functional-basic)",
+    "name": "ErrorCenter Handling Guide (@dxtmisha/functional-basic)",
     "mimeType": "text/markdown",
-    "description": "Defines mandatory error management standards and API rules using ErrorCenter in @dxtmisha/functional-basic. Prohibits direct console logging and enforces structured error dispatching across all application domains. Guides error registration, custom group handlers, and external telemetry integration."
+    "description": "Standards and APIs for centralized error handling, routing exceptions via ErrorCenter without direct console logging."
   }
 ]

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';

package/ai-resources/design-config.md

@@ -28,6 +28,9 @@ Configuration specification for DXT UI packages and monorepo root.
 - `distDir` (`string`, default: `'dist'`): Output directory path for compiled JavaScript files.
 - `aiResourcesDir` (`string`, default: `'ai-resources'`): Directory path containing AI resource and prompt files.
 - `promptScanDepth` (`number`, default: `6`): Maximum directory scan depth for collecting AI prompt packages.
+- `promptExclude` (`string | string[]`): List of library names to exclude from the `ai-prompt.md` file (e.g. `["@dxtmisha/styles"]`).
+- `promptInclude` (`string | string[]`): Whitelist of library names to include in the `ai-prompt.md` file; if specified, only these libraries will be included (e.g. `["@dxtmisha/d1", "@dxtmisha/constructor"]`).
+- `promptPackageOnly` (`boolean`, default: `false`): When `true`, restricts `ai-prompt.md` package discovery to only libraries defined in the root `package.json` (`dependencies`, `devDependencies`, etc.).
 - `separator` (`string`, default: `'/'`): Token path delimiter used when splitting design tokens into sub-branches.
 - `separatorBasicName` (`string`): Base token name stripped during branch segmentation.
 - `separatorLimit` (`number`): Maximum recursion depth for token key splitting.
@@ -73,6 +76,9 @@ Complete `design.config.json` incorporating all available configuration properti
   "distDir": "dist",
   "aiResourcesDir": "ai-resources",
   "promptScanDepth": 6,
+  "promptExclude": [
+    "@dxtmisha/styles"
+  ],
   "separator": "/",
   "separatorBasicName": "basic",
   "separatorLimit": 3,
@@ -101,4 +107,5 @@ Complete `design.config.json` incorporating all available configuration properti
    import { PropertiesConfig } from '../Properties/PropertiesConfig'
    const isExcluded = PropertiesConfig.getTypesExclude()
    const skipVue = PropertiesConfig.isTypesWithoutVue()
+   const promptExcluded = PropertiesConfig.getPromptExclude()
    ```