@dxtmisha/functional-basic 1.14.0 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,155 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.0.0] - 2026-11-03
+
+### Added
+- **`forOwn`**:
+  - Safe object traversal utility skipping prototype pollution keys (`'__proto__'`, `'constructor'`, `'prototype'`) and non-enumerable properties with optional early break return.
+  - Exported in public library exports (`src/library.ts`).
+  - Added comprehensive unit test suite in `src/functions/__tests__/forOwn.test.ts`.
+  - Added trilingual Storybook documentation (EN, RU, VI).
+- **`toGeoItem` / `toGeoItemFull` / `toGeoStandard` / `toLocale`**:
+  - `toGeoItem`: resolves standardized `GeoItem` records from country and language inputs with localized fallbacks.
+  - `toGeoItemFull`: creates comprehensive `GeoItemFull` metadata containing location, language, and country codes.
+  - `toGeoStandard`: transforms raw country and language maps into structured `GeoItem` records.
+  - `toLocale`: creates and formats standard BCP-47 locale tags (`en-US`, `vi-VN`) from country and language codes.
+  - Exported in public library exports (`src/library.ts`).
+  - Added comprehensive unit test suites and trilingual Storybook documentation (EN, RU, VI).
+- **`setElementItemStyle` / `setElementItemAttribute` / `setElementItemProperty`**:
+  - Modular DOM mutation utilities extracted from `setElementItem`.
+  - `setElementItemStyle`: manages CSS style declarations, CSS custom properties (`--*`), kebab-case property normalization, `!important` suffix extraction, and nullish property removal.
+  - `setElementItemAttribute`: manages HTML and ARIA attributes with boolean ARIA serialization (`'true'` / `'false'`), boolean flag toggling, and numeric / BigInt coercion.
+  - `setElementItemProperty`: safely sets element properties and performs deep merges with prototype pollution protection.
+  - Exported in public library exports (`src/library.ts`).
+  - Added unit test suites and trilingual Storybook documentation for each utility.
+- **`GeoLocation` / `GeoList` / `GeoTimezone`**:
+  - Modular decomposition of the monolithic `GeoInstance` class for location resolution, global country database querying, and time zone offset management.
+  - `GeoLocation`: tiered resolution (Cookie -> Storage -> DOM), BCP-47 normalization, and dynamic location synchronization.
+  - `GeoList`: immutable query methods and mutation APIs for country, phone, language, and continent datasets.
+  - `GeoTimezone`: time zone offset parsing, ISO 8601 formatting, and zone normalization.
+  - Exported in public library exports (`src/library.ts`).
+  - Added comprehensive test suites and trilingual Storybook documentation.
+- **`toCountry` / `toLanguage` / `sanitizeLocation`**:
+  - `toCountry`: extracts normalized 2-letter ISO 3166-1 alpha-2 country codes from locale tags or country names, with `isRaw` fallback option.
+  - `toLanguage`: extracts normalized 2-letter ISO 639-1 language codes from locale strings, with `isRaw` fallback option.
+  - `sanitizeLocation`: validates and canonicalizes BCP-47 locale tags using length bounds, regex validation, and `Intl.Locale`.
+  - Exported in public library exports (`src/library.ts`).
+  - Added unit tests and trilingual Storybook documentation.
+- **`removeTag`**:
+  - Utility for stripping HTML/XML tags, comments, DOCTYPE declarations, and CDATA blocks with customizable tag whitelisting/filtering and regex caching.
+  - Exported in public library exports (`src/library.ts`).
+  - Added unit tests and trilingual Storybook documentation.
+- **`getObjectNull`**:
+  - Helper to create clean prototype-less objects (`Object.create(null)`) for safe key-value dictionary storage.
+  - Exported in public library exports (`src/library.ts`).
+  - Added unit tests and trilingual Storybook documentation.
+- **`hasKeys`**:
+  - Zero-allocation property inspection utility checking for the presence of multiple keys on an object.
+  - Exported in public library exports (`src/library.ts`).
+  - Added unit tests and trilingual Storybook documentation.
+- **`isRegExp`**:
+  - Cross-realm `RegExp` type predicate utility.
+  - Exported in public library exports (`src/library.ts`).
+  - Added unit tests and trilingual Storybook documentation.
+- **`domElementsFromPoint`**:
+  - SSR-safe wrapper around `document.elementsFromPoint`.
+  - Exported in public library exports (`src/library.ts`).
+  - Added comprehensive test suite and trilingual Storybook documentation (EN, RU, VI).
+
+### Changed
+- **`Datetime`**:
+  - Refactored `standard()` to construct formatted date-time strings directly from date parts, returning an empty string for invalid dates.
+  - Added `getCode(): string` accessor to retrieve current locale code.
+  - Added `getWeekday(): number` method to get day of the week (0 = Sunday).
+  - Optimized `getMaxDay()` calculation without allocating intermediate cloned date instances.
+  - Clamped days of the month in `setYear()` and `setMonth()` to prevent unintentional month overflow on shorter months.
+  - Introduced `block` flag preventing duplicate watch callbacks during composite operations.
+  - Integrated `ErrorCenter.on` error logging for invalid dates in `setDate()`.
+  - Supported optional parameters in `setDate()`, `setCode()`, and `setWatch()`.
+  - Expanded unit test suite and updated trilingual Storybook documentation.
+- **`Geo` / `GeoInstance`**:
+  - `Geo`: added protected constructor to enforce static utility usage; aligned static facade methods (`get`, `getItem`, `getFirstItem`, `getFlag`, `getFlagList`).
+  - `GeoInstance`: decomposed extraction logic to modular utilities (`toGeoItem`, `toGeoItemFull`, `toGeoStandard`, `toLocale`).
+  - `GeoInstance`: aligned getters with `GeoItemFull` metadata (`getLanguage()` returns `item.language`, `getLocationCountry()` and `getLocationLanguage()` return `item.locationCountry` and `item.locationLanguage`).
+  - `GeoLocation`: delegated country and language extraction to `toCountry` and `toLanguage` with raw fallback support.
+- **`getFirst`**:
+  - Unified implementation and signature symmetry with `getLast` (`readonly T[] | null | undefined`, duck-typed collections).
+  - Optimized object key retrieval via `Object.keys()` without array allocations.
+  - Expanded unit test coverage and updated trilingual Storybook documentation.
+- **`getImageSrc` / `getElementImage` / `resizeImageByMax`**:
+  - `getImageSrc`: widened parameter types to accept `HTMLImageElement | string | Record<string, unknown> | null | undefined`, preventing runtime `TypeError` on non-string primitives using `isObject`.
+  - `getElementImage`: widened source parameter typing to `string | HTMLImageElement | Record<string, unknown> | null | undefined` with duck-typed `HTMLImageElement` checking.
+  - `resizeImageByMax`: refined typing and fallback handling when image is within constraints.
+  - Expanded unit tests and synchronized trilingual Storybook documentation.
+- **`encodeLiteAttribute` / `copyObjectLite`**:
+  - `encodeLiteAttribute`: widened parameter typing to `text?: string | number | null` and added fast-path bypass for strings without special characters via `REGEXP_HAS_SPECIAL_CHARACTERS_LITE`.
+  - `copyObjectLite`: widened parameter typing to optional `source?: unknown` and added prototype isolation tests.
+  - Synchronized trilingual Storybook documentation.
+- **`domQuerySelector` / `domQuerySelectorAll`**:
+  - Added `@template E extends Element = HTMLElement` JSDoc annotations for typed element query narrowing.
+- **`createElement` / `domContentLoaded`**:
+  - Refined SSR guards, promise resolution, and parameter options.
+  - Synchronized trilingual Storybook documentation and expanded unit tests.
+- **`splice`**:
+  - Hardened with `forOwn` traversal protecting against prototype pollution on both target and replacement objects.
+  - Optimized local accumulation with `disableCopy = true`, reducing merging complexity from $O(N^2)$ to $O(N)$.
+  - Added defensive non-object target guard `!isObject(array)` returning `{}` (or a deep clone of `replacement`).
+  - Widened parameter types: `array?: ObjectItem<I> | null`, `replacement?: ObjectItem<I> | I | null`, `indexStart?: string | null` with generic item inference `<I = unknown>`.
+  - Added bilingual JSDoc `@warning` regarding plain JSON-like object scope.
+  - Authoritative 16-test suite added and trilingual Storybook documentation updated.
+- **`replaceRecursive`**:
+  - Added `disableCopy: boolean = false` parameter (passed as `true` in self-recursion) to eliminate redundant nested deep clones and achieve linear $O(N)$ merge performance.
+  - Switched traversal to `forOwn`, automatically protecting against prototype pollution.
+  - Refined types to `<I = unknown>` and accepted `readonly I[] | null`.
+  - Added bilingual JSDoc `@warning` regarding plain JSON-like object scope.
+  - Expanded unit test suite to 19 tests and synchronized trilingual Storybook documentation.
+- **`uniqueArray`**:
+  - Optimized deduplication with $O(N)$ `Set` fast-path for primitive arrays while preserving deep structural deduplication for objects.
+  - Accepted `readonly I[] | null` collections and hardened boundary checks.
+  - Expanded unit test suite and synchronized trilingual Storybook documentation.
+- **`copyObject` / `copyObjectLite`**:
+  - Hardened prototype pollution safety by verifying property descriptors and skipping non-enumerable properties.
+  - Streamlined clone paths with `globalThis.structuredClone` and robust fallback handling.
+- **`getElement` / `getElementItem` / `getElementOrWindow` / `isElementVisible`**:
+  - Extended `ElementOrWindow` type union to include `SVGElement` and generic `Element`.
+  - Hardened SSR safety with `isDomRuntime()` guards and safe fallbacks across DOM queries.
+  - Expanded unit tests and updated Storybook documentation.
+- **`setElementItem`**:
+  - Decomposed into modular sub-utilities (`setElementItemStyle`, `setElementItemAttribute`, `setElementItemProperty`) while maintaining full backward-compatible API.
+- **`CookieStorage` / `DataStorage` / `ServerStorage`**:
+  - `CookieStorage`: added SameSite `'none'` with automatic `Secure` per RFC 6265bis, CHIPS `Partitioned` support, control character sanitization, and exact return type inference via `CookieStorageGet<T, D>`.
+  - `DataStorage`: exported `DataStorageGet<T, D>` conditional type, isolated keys by process prefix, and protected `JSON.parse` with `isObjectNotArray`.
+  - `ServerStorage`: refactored internal storage to use null-prototype dictionaries, integrated `executeFunction`, and hardened hydration traversal.
+- **`ErrorCenter` / `ErrorCenterHandler` / `ErrorCenterInstance`**:
+  - Added lifecycle unsubscription and cleanup methods (`remove`, `removeHandler`, `removeCallback`, `reset`).
+  - Added `getHandler(): ErrorCenterHandler` for direct handler access.
+  - Harmonized `group?: ErrorCenterGroup` typing across all methods.
+- **`GeoInstance`**:
+  - Refactored as a lightweight composite layer delegating to `GeoLocation`, `GeoList`, and `GeoTimezone`, maintaining 100% backward compatibility.
+- **Core Utilities**:
+  - `addTagHighlightMatch`: added `shouldRemoveTag` option and collision-resistant unique markers.
+  - `anyToString`: optimized options and string coercion.
+  - `isFilled`: hardened for empty tokens, `Date` instances, and prototype-less objects.
+  - `isNull`: refined TypeScript type predicate narrowing behavior.
+  - `getLast`: optimized array and object retrieval with strict return type inference.
+  - `encodeAttribute`: added fast-path check and non-string primitive support.
+  - `escapeExp`: supported numbers and nullish values safely.
+  - `capitalize`: enforced single unified signature without overloads (`T extends string ? Capitalize<T> : string`).
+  - `getElementSafeScript`: integrated `encodeAttribute` for robust XSS/injection protection and widened `id` to `string | number`.
+  - `getHydrationData`: supported numeric script IDs and nullish coalescing.
+  - `blobToBase64`: relaxed parameter typing to `Blob | null | undefined`.
+- **Documentation & Tests**:
+  - Synchronized Storybook documentation across English, Russian, and Vietnamese (`.en.mdx`, `.ru.mdx`, `.vi.mdx`).
+  - Comprehensive unit test expansion across all packages with 100% passing test suites.
+
+### Security
+- **Prototype Pollution Guards**:
+  - Comprehensive protection across `forOwn`, `splice`, `replaceRecursive`, `copyObject`, `setElementItemProperty`, `getObjectByKeys`, and `transformation` against prototype pollution vectors (`__proto__`, `constructor`, `prototype`).
+- **XSS & Injection Protection**:
+  - Hardened `getElementSafeScript` via `encodeAttribute` sanitization and precompiled regexes.
+  - Hardened cookie value sanitization in `CookieStorage` stripping control characters (`\r`, `\n`, `\0`, `;`).
+
 ## [1.14.0] - 2026-10-23
 
 ### Added

package/ai-description.md

@@ -1,8 +1,8 @@
-This package provides an isomorphic foundation of core utilities, HTTP client management, client-server state persistence, internationalization, and DOM interaction helpers for modern web applications. An AI assistant should study this package when implementing robust API fetching with caching and SSR hydration, managing cookies and localized storage, formatting dates, currencies, and units, or synchronizing URL state and SEO metadata.
+This package provides a comprehensive isomorphic foundation for web applications, supplying robust API request handling with SSR hydration, multi-layer client and server storage, internationalization engines, and browser lifecycle utilities. An AI assistant must study this package when implementing client-server data synchronization, localized formatting for dates, currencies, and measurement units, or managing URL query and cookie states across SSR and client runtimes. It is equally essential for executing multi-column search filtering with text highlighting, managing DOM events, processing images, and configuring SEO metadata.
 
-Key Capabilities: HTTP Client, API Request Caching, SSR Hydration, Cookie Management, Storage State, Broadcast Messaging, Date Localization, Number Formatting, Currency Formatting, Unit Conversion, Translation Management, Phone Masking, SEO Meta Tags, Open Graph Tags, URL Query Management, URL Hash Navigation, DOM Event Management, Search Filtering, Text Highlighting, Clipboard Integration, Image Resizing, Scroll Control, Global Loader State
+Key Capabilities: HTTP Client, API Interceptors, SSR Hydration, Server Storage, Cookie Management, Web Storage, Internationalization, Calendar Calculations, Localized Formatting, Unit Conversion, Phone Masking, Localization Translation, SEO Metadata, Open Graph Tags, URL State Management, Search Filtering, Match Highlighting, DOM Event Management, Image Resizing, Clipboard Access, Web Share Integration, Error Dispatching, Icon Management, Viewport Scrolling
 ## 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': Provides standards and examples for HTTP client requests, caching, storage, localization, and DOM utilities.
+- 'node_modules/@dxtmisha/functional-basic/ai-resources/api-reference.md': Comprehensive reference and examples for HTTP client, caching, storage, localization, and core utilities.
 - '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": "Provides standards and examples for HTTP client requests, caching, storage, localization, and DOM utilities."
+    "description": "Comprehensive reference and examples for HTTP client, caching, storage, localization, and core utilities."
   },
   {
     "uri": "@dxtmisha/functional-basic/ai-resources/design-config.md",

package/ai-resources/api-reference.md

@@ -104,6 +104,9 @@ const srv = ServerStorage.get('svc', () => new Svc()); // SSR isolated
 ```
 
 ## Geolocation, Formatting & Localization
+
+`TranslateInstance` groups queued translation codes by the language, location, and resolved API path captured when they were requested. API URL placeholders are resolved before the batching delay. File selection, cache writes, and asynchronous results retain that locale even if it changes during the delay or loading. `TranslateFile.getList(location?, language?)` and `isFile(location?, language?)` accept an explicit locale; omitted values use the current providers. File lookup still prefers location, then language, then `global`.
+
 ```typescript
 import { Geo, GeoIntl, GeoFlag, GeoPhone } from '@dxtmisha/functional-basic';
 const country = Geo.getCountry(); const lang = Geo.getLanguage(); Geo.set('en-US');