@dxtmisha/functional-basic 1.11.1 → 1.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +252 -0
- package/ai-description.md +3 -3
- package/ai-doc.md +1 -1
- package/ai-mcp-resources.json +1 -1
- package/ai-resources/api-reference.md +13 -0
- package/ai-types.md +740 -664
- package/dist/library.d.ts +1952 -1586
- package/dist/library.js +1706 -1294
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,258 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## [1.14.0] - 2026-10-23
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
- **`isPrototypeKey`**:
|
|
9
|
+
- Added `isPrototypeKey(key: string): boolean` utility function to detect prototype pollution keys (`'__proto__'`, `'constructor'`, `'prototype'`).
|
|
10
|
+
- Exported `isPrototypeKey` in public library exports (`src/library.ts`).
|
|
11
|
+
- Added comprehensive unit test suite in `src/functions/__tests__/isPrototypeKey.test.ts`.
|
|
12
|
+
- Added multilingual Storybook documentation in English, Russian, and Vietnamese.
|
|
13
|
+
- Generated AI type definitions in `ai-types-list/functions/isPrototypeKey.d.ts`.
|
|
14
|
+
- **`toPascalCase`**:
|
|
15
|
+
- Added `toPascalCase(value?: string): string` utility function to convert kebab-case, snake_case, or camelCase strings to PascalCase.
|
|
16
|
+
- Exported `toPascalCase` in public library exports (`src/library.ts`).
|
|
17
|
+
- Added comprehensive unit test suite in `src/functions/__tests__/toPascalCase.test.ts`.
|
|
18
|
+
- Added multilingual Storybook documentation in English, Russian, and Vietnamese.
|
|
19
|
+
- Generated AI type definitions in `ai-types-list/functions/toPascalCase.d.ts`.
|
|
20
|
+
- **`UrlInstanceAbstract` Test Suite**:
|
|
21
|
+
- Added comprehensive unit test suite covering URL abstraction methods, query parsing, and pathname manipulation in `src/classes/__tests__/UrlInstanceAbstract.test.ts`.
|
|
22
|
+
- **Documentation**:
|
|
23
|
+
- Added multilingual Storybook documentation for `encodeLiteAttribute`, `getHydrationData`, `isPrototypeKey`, and `toPascalCase` across English, Russian, and Vietnamese (`src/storybook/functions/`).
|
|
24
|
+
- Synchronized default component and function parameters across all Storybook stories (`.en.mdx`, `.ru.mdx`, `.vi.mdx`).
|
|
25
|
+
|
|
26
|
+
### Changed
|
|
27
|
+
- **`uint8ArrayToBase64`**:
|
|
28
|
+
- Optimized conversion with Node.js `Buffer.from()` fast-path.
|
|
29
|
+
- Added `globalThis.btoa` fallback for Web Workers and isolated runtime environments.
|
|
30
|
+
- Implemented 32KB chunking (`CHUNK_SIZE = 0x8000`) for large arrays to avoid call stack limits in `String.fromCharCode.apply`.
|
|
31
|
+
- Added modern runtime support for native `Uint8Array.prototype.toBase64` when available.
|
|
32
|
+
- Extracted local `BufferType` interface and eliminated all `any` usages.
|
|
33
|
+
- **`transformation`**:
|
|
34
|
+
- Added generic type parameter inference: `transformation<T = unknown>(value: unknown, isFunctionCheck?: boolean): T`.
|
|
35
|
+
- Added balanced JSON bracket validation (`{...}`, `[...]`) before parsing to prevent unnecessary exceptions on non-JSON strings.
|
|
36
|
+
- Integrated prototype pollution guard via `isPrototypeKey`, skipping dangerous keys (`__proto__`, `constructor`, `prototype`).
|
|
37
|
+
- Renamed parameter `isFunction` to `isFunctionCheck` and modernized window lookup using `hasKey`, `isString`, and `isFunction`.
|
|
38
|
+
- **`copyObject`**:
|
|
39
|
+
- Added modern fast-path using native `globalThis.structuredClone` with safe fallback to `JSON.parse(JSON.stringify(value))` for non-cloneable objects.
|
|
40
|
+
- **`writeClipboardData`**:
|
|
41
|
+
- Added robust fallback `copyByExecCommand` using a hidden temporary `textarea` element created via `createElement` when `navigator.clipboard` is unavailable or fails.
|
|
42
|
+
- Integrated centralized error logging via `ErrorCenter.on` (`group: 'clipboard'`, `code: 'error'`).
|
|
43
|
+
- **`toDate`**:
|
|
44
|
+
- Normalized ISO-8601 UTC date formatting (`YYYY-MM-DDTHH:mm:ss.sssZ`).
|
|
45
|
+
- Precompiled static regular expressions for date parts to eliminate regex compilation overhead.
|
|
46
|
+
- Hardened string date parsing with bounds validation and fallback handling.
|
|
47
|
+
- **`toCamelCase` / `toCamelCaseFirst` / `toKebabCase`**:
|
|
48
|
+
- Precompiled regular expressions into static constants (`REGEXP_INVALID_CHARS`, `REGEXP_SEPARATORS`, `REGEXP_ACRONYMS`, `REGEXP_CAMEL_BOUNDARY`, `REGEXP_FIRST_CHAR`, `REGEXP_TRAILING_DASHES`).
|
|
49
|
+
- Added support for `snake_case` word boundaries, dots, and acronym normalization.
|
|
50
|
+
- Hardened nullish boundary checks for `null` and `undefined`.
|
|
51
|
+
- **`encodeAttribute` / `encodeLiteAttribute`**:
|
|
52
|
+
- Precompiled static regular expressions (`REGEXP_SPECIAL_CHARACTERS`, `REGEXP_SPECIAL_CHARACTERS_LITE`).
|
|
53
|
+
- Replaced `String(text)` with `toString(text)` helper for safe nullish coercion.
|
|
54
|
+
- Standardized constants naming to `SPECIAL_CHARACTERS` and `SPECIAL_CHARACTERS_LITE`.
|
|
55
|
+
- **`escapeExp`**:
|
|
56
|
+
- Precompiled static regular expression `REGEXP_SPECIAL_CHARS`.
|
|
57
|
+
- Guaranteed escaping of hyphen (`-`) characters in character class expressions.
|
|
58
|
+
- **`executeFunction`**:
|
|
59
|
+
- Modernized signature with generic argument inference: `executeFunction<T, Args extends unknown[] = unknown[]>(callback: T | FunctionArgs<never, T> | ((...args: Args) => T), ...args: Args): T`, eliminating all `any` types.
|
|
60
|
+
- **`getObjectByKeys`**:
|
|
61
|
+
- Protected against prototype pollution using `!isPrototypeKey(key) && hasKey(data, key)` before copying properties.
|
|
62
|
+
- Replaced `Record<string, any>` with `Record<string, unknown>`.
|
|
63
|
+
- **`getItemByPath`**:
|
|
64
|
+
- Hardened nested path resolution when intermediate properties are missing or undefined.
|
|
65
|
+
- Replaced `Record<string, any>` with `Record<string, unknown>`.
|
|
66
|
+
- **`toArray`**:
|
|
67
|
+
- Replaced `Array.isArray` with `isArray` helper and refined generic signature to `T extends unknown[] ? T : [T]`.
|
|
68
|
+
- **`isFunction` / `isObject` / `isObjectNotArray`**:
|
|
69
|
+
- Replaced `any` with strongly typed constructs: `FunctionAnyType` and `ObjectItem`.
|
|
70
|
+
- Replaced `Array.isArray` with `isArray` helper in `isObjectNotArray`.
|
|
71
|
+
- **`isString`**:
|
|
72
|
+
- Streamlined type predicate parameter: `isString(value: unknown): value is string`.
|
|
73
|
+
- **`isSelected` / `isSelectedByList`**:
|
|
74
|
+
- Supported intelligent numeric string comparison in arrays (matching numeric strings like `'42'` with number `42`).
|
|
75
|
+
- Cleaned up redundant type assertions and replaced `Array.isArray` with `isArray`.
|
|
76
|
+
- **`isNumber`**:
|
|
77
|
+
- Refined return type predicate to `value is number | string`.
|
|
78
|
+
- Enhanced regular expression with sign support (`[+-]?`) and trimmed input whitespace.
|
|
79
|
+
- **`isInput`**:
|
|
80
|
+
- Added isomorphic SSR guard via `isDomRuntime()`.
|
|
81
|
+
- Added `includeDisabled?: boolean` option to optionally include disabled and readonly form elements.
|
|
82
|
+
- Refined type predicate to `target is HTMLElement`.
|
|
83
|
+
- **`isFloat`**:
|
|
84
|
+
- Implemented finite float regular expression validation and accepted `value: unknown`.
|
|
85
|
+
- **`isFilled`**:
|
|
86
|
+
- Replaced `Object.keys()` with `for...in` loop and `hasKey` check, optimizing performance and memory footprint.
|
|
87
|
+
- Replaced `Array.isArray` with `isArray`.
|
|
88
|
+
- **`isEnter`**:
|
|
89
|
+
- Modernized keyboard event key check and added SSR safety with `isDomRuntime()`.
|
|
90
|
+
- **`isElementVisible`**:
|
|
91
|
+
- Improved DOM visibility detection with `isDomRuntime()` check and computed styles verification.
|
|
92
|
+
- **`isDifferent`**:
|
|
93
|
+
- Enhanced deep equality comparisons across complex nested structures and primitives.
|
|
94
|
+
- Replaced `forEach` with a fast breakable `for...in` loop.
|
|
95
|
+
- **`goScroll` / `goScrollSmooth` / `goScrollTo`**:
|
|
96
|
+
- Added isomorphic SSR guards (`isDomRuntime()`).
|
|
97
|
+
- Replaced manual `typeof === 'object'` and `typeof === 'function'` checks with `isObject` and `isFunction` helpers.
|
|
98
|
+
- Improved smooth scrolling fallback logic and bounding rect calculations.
|
|
99
|
+
- **`replaceComponentName`**:
|
|
100
|
+
- Converted to standard function declaration with explicit `string | undefined` return type.
|
|
101
|
+
- **`ApiInstance`**:
|
|
102
|
+
- Ensured SSR safety when handling `FormData` with `typeof FormData !== 'undefined'` in `getBody` and `getBodyForGet`.
|
|
103
|
+
- Enhanced `getBodyForGet` to distinguish between `FormData` and object query parameters.
|
|
104
|
+
- **`apiTypes`**:
|
|
105
|
+
- Documented global caching behavior in `ApiFetch` (`cache`, `enableClientCache`, `cacheId`) clarifying user-independent request scope.
|
|
106
|
+
- Expanded `ApiErrorStorageItem.code` type from `string | undefined` to `string | number | undefined`.
|
|
107
|
+
- **`getElementSafeScript`**:
|
|
108
|
+
- Precompiled static regular expressions `REGEXP_DOUBLE_QUOTE` and `REGEXP_CLOSING_SCRIPT`.
|
|
109
|
+
- **Local Type Extraction**:
|
|
110
|
+
- Extracted inline types to scoped local types across all utility functions (`blobToBase64`, `copyObject`, `encodeAttribute`, `escapeExp`, `executeFunction`, `forEach`, `getElementSafeScript`, `getObjectByKeys`, `getRandomText`, `goScrollSmooth`, `goScrollTo`, `isDomRuntime`, `isFilled`, `isObjectNotArray`, `isSelectedByList`, `replaceComponentName`, `sortList`, `splice`, `strSplit`, `toArray`, `toCamelCase`, `transformation`, `uint8ArrayToBase64`, `writeClipboardData`) maintaining clean encapsulation without leaking unexported types.
|
|
111
|
+
- **Tests & AI Documentation**:
|
|
112
|
+
- Comprehensive unit test expansion across all 185 test suites (3271 tests passing with 100% coverage).
|
|
113
|
+
- Synchronized bilingual Storybook documentation across English, Russian, and Vietnamese.
|
|
114
|
+
- Refreshed AI type definitions and search keywords in `ai-types-list/`.
|
|
115
|
+
|
|
116
|
+
### Fixed
|
|
117
|
+
- **`toNumberByMax`**:
|
|
118
|
+
- Fixed falsy max value bug: correctly handles `max = 0` instead of falling back to default max value.
|
|
119
|
+
- **`toNumberPositive`**:
|
|
120
|
+
- Delegated number parsing to `toNumber` and enforced `> 0` check with fallback.
|
|
121
|
+
- **`toNumber`**:
|
|
122
|
+
- Eliminated variable shadowing and improved numeric parsing for edge cases.
|
|
123
|
+
- **`setElementItem`**:
|
|
124
|
+
- Prevented prototype pollution by validating property keys against `isPrototypeKey`.
|
|
125
|
+
- Fixed boolean and ARIA attribute handling: formatted `aria-*` attributes as `'true'`/`'false'`, set empty string for true boolean attributes, and removed attributes when value is `false` or `null`.
|
|
126
|
+
- **`sortTypes`**:
|
|
127
|
+
- Eliminated `any` in `SortFunction` by replacing with `Record<string, unknown>`.
|
|
128
|
+
- **`ApiStatus`**:
|
|
129
|
+
- Replaced `in` operator checks with `hasKey` helper in `setLastResponse` to prevent `TS2638` type narrowing errors.
|
|
130
|
+
- **`BroadcastMessage`**:
|
|
131
|
+
- Added fallback in `getBroadcastName` to guarantee `string` return type (`TS2322`).
|
|
132
|
+
|
|
133
|
+
## [1.13.0] - 2026-10-18
|
|
134
|
+
|
|
135
|
+
### Added
|
|
136
|
+
- **`hasKey`**:
|
|
137
|
+
- Added `hasKey<K extends PropertyKey, T extends object = Record<K, unknown>>(object: unknown, key: K): object is T & Record<K, unknown>` utility function to safely check for own object properties (`Object.prototype.hasOwnProperty`) with TypeScript type narrowing.
|
|
138
|
+
- Exported `hasKey` in public library exports (`src/library.ts`).
|
|
139
|
+
- Added comprehensive unit test suite in `src/functions/__tests__/hasKey.test.ts`.
|
|
140
|
+
- Added multilingual Storybook documentation in English, Russian, and Vietnamese.
|
|
141
|
+
- Generated AI type definitions in `ai-types-list/functions/hasKey.d.ts`.
|
|
142
|
+
- **`resetGetElementId`**:
|
|
143
|
+
- Added `resetGetElementId(): void` function to reset the registered SSR context listener back to `undefined`.
|
|
144
|
+
- **Type Definitions**:
|
|
145
|
+
- Exported `GetElementImageCallback` type for image `onload` and `onerror` event callback signatures.
|
|
146
|
+
- Exported `ResizeImageByMaxType` ('auto' | 'width' | 'height') type definition.
|
|
147
|
+
|
|
148
|
+
### Changed
|
|
149
|
+
- **`executePromise`**:
|
|
150
|
+
- Enhanced type signature to accept `PromiseLike<T> | T` and generic arguments `Args extends unknown[]`, returning `Promise<Awaited<T>>` with zero `any`.
|
|
151
|
+
- Simplified asynchronous resolution with native `await`.
|
|
152
|
+
- **`ensureMaxSize`**:
|
|
153
|
+
- Refactored `file` parameter typing to `Uint8Array` / `BlobPart` with safe fallback to `blobToBase64` when image dimensions are within size limits or resizing is not required.
|
|
154
|
+
- Ensured reliable object URL revocation (`URL.revokeObjectURL`) in all execution branches (`onload`, `onerror`, and fallback).
|
|
155
|
+
- **`getElementImage`**:
|
|
156
|
+
- Added optional `onload` and `onerror` callbacks (`GetElementImageCallback`) for `HTMLImageElement` creation from string sources.
|
|
157
|
+
- Directly returns existing `HTMLImageElement` instances without re-wrapping.
|
|
158
|
+
- **`resizeImageByMax`**:
|
|
159
|
+
- Added explicit `maxSize > 0` validation guard and rounded dimensions (`Math.round`) for canvas scaling.
|
|
160
|
+
- Documented design rationale for returning `undefined` when resizing is unneeded or impossible to prevent unnecessary canvas re-encoding.
|
|
161
|
+
- **`applyTemplate`**:
|
|
162
|
+
- Refactored template macro matching with static precompiled regexes (`EXP_LIST_MACROS`, `EXP_TAG_MACROS`, `EXP_KEY_MACROS`, `EXP_CONTENT_MACROS`).
|
|
163
|
+
- Integrated `hasKey` for checking replacement object own properties, avoiding prototype pollution.
|
|
164
|
+
- Added string fast-path checks (`includes('[') || includes('{')`) before executing regex replacements.
|
|
165
|
+
- **`addTagHighlightMatch`**:
|
|
166
|
+
- Replaced inline tags with uppercase constants (`TAG_START`, `TAG_END`, `EXP_TAG`) and extracted tag helper functions (`getTagStart`, `getTagEnd`).
|
|
167
|
+
- Added `isSearchValid` helper to safely validate search strings and regular expressions.
|
|
168
|
+
- Added direct fast-path return when `shouldEscape` is `false`.
|
|
169
|
+
- **`getAttributes`**:
|
|
170
|
+
- Modernized attribute extraction to use standard `item.getAttributeNames()` and `item.getAttribute(name)` with `getAttributeNames in item` guard, eliminating deprecated `NamedNodeMap` iteration.
|
|
171
|
+
- **`forEach`**:
|
|
172
|
+
- Added overloaded TypeScript signatures for `readonly T[]`, `Set<T>`, `Map<K, V>`, and `Record<string, T>` collections with strongly typed keys (`ForEachKey<D>`).
|
|
173
|
+
- Optimized array and object iteration using standard `for` loops and `Object.keys()` instead of native `forEach` and `for...in`.
|
|
174
|
+
- **`frame`**:
|
|
175
|
+
- Added `timestamp: DOMHighResTimeStamp` parameter to `callback` and `next` functions.
|
|
176
|
+
- Passed `0` timestamp fallback in SSR/non-DOM environments.
|
|
177
|
+
- **`getObjectNoUndefined`**:
|
|
178
|
+
- Added overloads for `readonly V[]` and `Record<PropertyKey, unknown>` with strict types.
|
|
179
|
+
- Replaced `forEach` with `Object.entries()` and `Object.is()` comparison for exception value filtering.
|
|
180
|
+
- **`getElementId`**:
|
|
181
|
+
- Added `Window` support: assigning and retrieving ID directly on `document.body` when a `Window` object is passed.
|
|
182
|
+
- Extracted `SERVER_STORAGE_KEY` constant (`__ui:getElementId__`).
|
|
183
|
+
- Hardened context ID check with `!isNull(contextId) && contextId !== ''`.
|
|
184
|
+
- Added explicit `void` return type for `initGetElementId`.
|
|
185
|
+
- **`getElementItem`**:
|
|
186
|
+
- Renamed parameter `index` to `property` for clarity and consistency across element accessor functions.
|
|
187
|
+
- **`getElementSafeScript`**:
|
|
188
|
+
- Added generic type parameter `T = unknown` for data input.
|
|
189
|
+
- Added fallback `?? 'null'` when `JSON.stringify` returns `undefined`.
|
|
190
|
+
- **`getItemByPath`**:
|
|
191
|
+
- Hardened nested path resolution when intermediate properties are missing or undefined.
|
|
192
|
+
- **`getLast`**:
|
|
193
|
+
- Supported `readonly T[]` in value parameter type.
|
|
194
|
+
- Optimized object property access via `Object.keys()` without full value array allocations.
|
|
195
|
+
- **`getLength`**:
|
|
196
|
+
- Replaced `value: any` with `value: unknown` and `Array.isArray` with `isArray` helper.
|
|
197
|
+
- **`setElementItem`**:
|
|
198
|
+
- Extracted helper functions `setElementItemProperty` and `setElementItemBoolean`.
|
|
199
|
+
- Added support for CSS custom properties (`--*`) on style targets via `setProperty()`.
|
|
200
|
+
- Added direct `cssText` assignment when setting `'style'` with a string value.
|
|
201
|
+
- Used `Reflect.set` for safe element property assignment.
|
|
202
|
+
- **`createElement`**:
|
|
203
|
+
- Supported `Element | DocumentFragment` for `parentElement` parameter and `Node | null` for `referenceElement`.
|
|
204
|
+
- Replaced `typeof options === 'function'` with `isFunction(options)`.
|
|
205
|
+
- Documented `document.createElementNS` usage recommendation for SVG/MathML elements in `@remarks`.
|
|
206
|
+
- **`domContentLoaded`**:
|
|
207
|
+
- Added optional `isServer` parameter (default `true`) allowing callers to disable SSR fallback execution.
|
|
208
|
+
- Allowed calling without arguments to return a promise that resolves upon DOM readiness.
|
|
209
|
+
- **`anyToString`**:
|
|
210
|
+
- Added double `try...catch` fallback resolving `Object.prototype.toString.call(value)` when standard serialization fails.
|
|
211
|
+
- **`encodeAttribute` / `encodeLiteAttribute`**:
|
|
212
|
+
- Replaced `String(text)` with `toString(text)` helper for safe nullish coercion.
|
|
213
|
+
- Standardized constants naming to `SPECIAL_CHARACTERS` and `SPECIAL_CHARACTERS_LITE`.
|
|
214
|
+
- **`isDifferent`**:
|
|
215
|
+
- Replaced `forEach` with a fast breakable `for...in` loop.
|
|
216
|
+
- **Tests & AI Documentation**:
|
|
217
|
+
- Overhauled and expanded unit test suites across all core utility functions (`addTagHighlightMatch`, `anyToString`, `applyTemplate`, `arrFill`, `blobToBase64`, `capitalize`, `createElement`, `domContentLoaded`, `encodeAttribute`, `encodeLiteAttribute`, `ensureMaxSize`, `escapeExp`, `executePromise`, `forEach`, `frame`, `getArrayHighlightMatch`, `getAttributes`, `getColumn`, `getElementId`, `getElementImage`, `getElementItem`, `getElementSafeScript`, `getHydrationData`, `getItemByPath`, `getLast`, `getLength`, `getObjectNoUndefined`, `getSeparatingSearchExp`, `hasKey`, `resizeImageByMax`, `setElementItem`, `toString`) following zero-`any` and edge-case boundary testing standards.
|
|
218
|
+
- Updated Storybook documentation for `executePromise`, `frame`, `getElementImage`, and `hasKey` across English, Russian, and Vietnamese.
|
|
219
|
+
- Refreshed AI type definitions and search keywords in `ai-types-list/`.
|
|
220
|
+
|
|
221
|
+
### Fixed
|
|
222
|
+
- **`getSeparatingSearchExp`**:
|
|
223
|
+
- Fixed word matching ordering by sorting terms by descending length (`b.length - a.length`), ensuring longer terms match before shorter substrings.
|
|
224
|
+
- Fixed empty or whitespace-only search returning `/^/` (which falsely matched empty lines) by returning a never-matching regex `/(?!)/`.
|
|
225
|
+
- **`getArrayHighlightMatch`**:
|
|
226
|
+
- Guaranteed global flag (`g`) on regular expressions via `toGlobalExp`.
|
|
227
|
+
- Fixed potential infinite loop on zero-width matches by manually advancing `lastIndex`.
|
|
228
|
+
- **`getHydrationData`**:
|
|
229
|
+
- Replaced `typeof document !== 'undefined'` with isomorphic helper `isDomRuntime()`.
|
|
230
|
+
- Added `script.tagName === 'SCRIPT'` tag validation guard.
|
|
231
|
+
- Wrapped `script.remove()` in a `finally` block to guarantee DOM cleanup even on JSON parse errors.
|
|
232
|
+
- **`setElementItem`**:
|
|
233
|
+
- Fixed boolean and ARIA attribute handling: formatted `aria-*` attributes as `'true'`/`'false'`, set empty string for true boolean attributes, and removed attributes when value is `false` or `null`.
|
|
234
|
+
- **`capitalize`**:
|
|
235
|
+
- Fixed capitalization of astral plane Unicode characters / surrogate pairs (code points > 0xFFFF) by extracting code-point-aware character slices.
|
|
236
|
+
- **`escapeExp`**:
|
|
237
|
+
- Fixed regex escaping to escape hyphen (`-`) characters in character class expressions.
|
|
238
|
+
- **`blobToBase64`**:
|
|
239
|
+
- Wrapped conversion logic in a safe `try...catch` block to return `undefined` on unhandled FileReader or corrupt blob errors.
|
|
240
|
+
|
|
241
|
+
## [1.12.0] - 2026-10-14
|
|
242
|
+
|
|
243
|
+
### Added
|
|
244
|
+
- **`skipFrame`**:
|
|
245
|
+
- Added `skipFrame(callback?: () => T | Promise<T>, count: number = 1): Promise<T | void>` utility function to wait for or skip a specified number of animation frames (`requestAnimationFrame`) before executing a callback or resolving.
|
|
246
|
+
- Added SSR-safe resolution: immediately resolves in non-DOM environments (`!isDomRuntime()`) without invoking `requestAnimationFrame`.
|
|
247
|
+
- Added comprehensive unit test suite in `src/functions/__tests__/skipFrame.test.ts`.
|
|
248
|
+
- Added multilingual Storybook documentation across English, Russian, and Vietnamese.
|
|
249
|
+
|
|
250
|
+
### Changed
|
|
251
|
+
- **Dependencies**:
|
|
252
|
+
- Updated `@dxtmisha/media` dependency to `>=0.8.1`.
|
|
253
|
+
- **Tests & AI Documentation**:
|
|
254
|
+
- Improved hydration test mocks in `getHydrationData.test.ts`.
|
|
255
|
+
- Updated AI type declarations and package descriptions.
|
|
256
|
+
|
|
5
257
|
## [1.11.1] - 2026-10-04
|
|
6
258
|
|
|
7
259
|
### Changed
|
package/ai-description.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
This package provides
|
|
1
|
+
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.
|
|
2
2
|
|
|
3
|
-
Key Capabilities: HTTP Client, API
|
|
3
|
+
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
|
|
4
4
|
## Mandatory Rules
|
|
5
5
|
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:
|
|
6
|
-
- 'node_modules/@dxtmisha/functional-basic/ai-resources/api-reference.md': Provides
|
|
6
|
+
- 'node_modules/@dxtmisha/functional-basic/ai-resources/api-reference.md': Provides standards and examples for HTTP client requests, caching, storage, localization, and DOM utilities.
|
|
7
7
|
- '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.
|
|
8
8
|
- '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
CHANGED
|
@@ -2,7 +2,7 @@ Framework-agnostic utility library. **Vue developers MUST search `@dxtmisha/func
|
|
|
2
2
|
|
|
3
3
|
## Coding Standards & Conventions
|
|
4
4
|
|
|
5
|
-
- **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.
|
|
5
|
+
- **Class Structure**: Properties/Variables (`public`->`protected`->`private`) -> Constructor -> Computed/Reactive Properties (`computed` and similar reactive fields are ALWAYS placed after the 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 (they always go in pairs, e.g., `min` / `max`, `width` / `height`, `x` / `y` / `z`), and remaining methods are sorted alphabetically.
|
|
6
6
|
- **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.
|
|
7
7
|
- **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.
|
|
8
8
|
- **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
CHANGED
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
"uri": "@dxtmisha/functional-basic/ai-resources/api-reference.md",
|
|
16
16
|
"name": "Functional Basic API Reference (@dxtmisha/functional-basic)",
|
|
17
17
|
"mimeType": "text/markdown",
|
|
18
|
-
"description": "Provides
|
|
18
|
+
"description": "Provides standards and examples for HTTP client requests, caching, storage, localization, and DOM utilities."
|
|
19
19
|
},
|
|
20
20
|
{
|
|
21
21
|
"uri": "@dxtmisha/functional-basic/ai-resources/design-config.md",
|
|
@@ -12,6 +12,19 @@ const updated = await Api.post<User>({ path: 'profile', request: { name: 'New' }
|
|
|
12
12
|
await ApiCache.set('k', { a: 1 }, 60000); const cache = await ApiCache.get<{a: number}>('k');
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
+
### Global Response Caching (`ApiCache` & `ApiFetch.cache`)
|
|
16
|
+
- **Intentional Global Scope (User-Independent)**: `ApiCache` (and the `cache?: number` option in `ApiFetch`) is **intentionally a global, shared cache** across the application process (and across all SSR requests when backed by memory or Nitro storage via `initPluginApiCache`).
|
|
17
|
+
- **Use Case**: Enable `cache` (TTL in seconds) **only for public, user-independent requests** (e.g., reference dictionaries, static configurations, public catalogs) whose responses do not depend on the current user or session.
|
|
18
|
+
- **Warning**: Do **NOT** use `cache` on personalized or user-specific endpoints. If a public endpoint varies by external context (e.g., locale or tenant) not present in `request`, pass an explicit `cacheId` in `ApiFetch` to segment the cache key:
|
|
19
|
+
```typescript
|
|
20
|
+
const countries = await Api.get({
|
|
21
|
+
path: 'public/countries',
|
|
22
|
+
cache: 3600, // Cached globally for 1 hour (in seconds)
|
|
23
|
+
cacheId: Geo.getLocation(), // Optional custom discriminator for global cache key
|
|
24
|
+
enableClientCache: true // Optional: also enable in browser runtime (SSR is enabled by default when `cache` is set)
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
15
28
|
### Error Responses & Return Types (`ApiData<T>`)
|
|
16
29
|
|
|
17
30
|
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:
|