nhb-toolbox 4.30.15 → 4.30.16

package/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 All notable changes to the package will be documented here.
 
+## [4.30.16] - 2026-05-24
+
+- **Fixed** multiple issues with `createFormData`: Now handles configuration options properly and it is more reliable now.
+- **Updated** `isDateLike` utility to correctly identify `Temporal` instances while making the return type `value is DateLike` to improve type-safety, previously it was returning `boolean`.
+
 ## [4.30.14] - 2026-05-19
 
 - **Updated** *signature* of `Chronos` plugin method `isPalindromeDate()`: now accepts `shortYear` parameter as optional (default `false`).

package/README.md

@@ -351,17 +351,19 @@ getColorForInitial('Banana', 50); // '#00376E80' (50% opacity)
 ```typescript
 import { createFormData } from 'nhb-toolbox';
 
-const formData = createFormData({
+const data = {
   user: {
     name: ' John Doe ',
     age: 30,
     preferences: { theme: 'dark' }
   },
   files: [file1, file2]
-}, {
+};
+
+const formData = createFormData(data, {
   trimStrings: true,
   lowerCaseValues: ['user.name'],
-  dotNotateNested: ['user.preferences'],
+  dotNotateNested: ['user'],
   breakArray: ['files']
 });
 

package/dist/cjs/date/guards.js

@@ -53,9 +53,19 @@ function isDateLike(value) {
             (0, non_primitives_1.isFunction)(value.getClass)) {
             return true;
         }
+        const temporals = [
+            'Instant',
+            'Duration',
+            'PlainDate',
+            'PlainTime',
+            'PlainDateTime',
+            'PlainMonthDay',
+            'PlainYearMonth',
+            'ZonedDateTime',
+        ];
         if ((0, non_primitives_1.isFunction)(value.toJSON) &&
             (0, non_primitives_1.isFunction)(value.toString) &&
-            ['PlainDate', 'ZonedDateTime', 'Instant'].includes(value.constructor?.name ?? '')) {
+            temporals.includes(value.constructor?.name ?? '')) {
             return true;
         }
     }

package/dist/cjs/form/convert.js

@@ -4,52 +4,62 @@ exports.createControlledFormData = void 0;
 const guards_1 = require("../date/guards");
 const non_primitives_1 = require("../guards/non-primitives");
 const primitives_1 = require("../guards/primitives");
+const basics_1 = require("../string/basics");
 const guards_2 = require("./guards");
 const createControlledFormData = (data, configs) => {
+    if (typeof FormData === 'undefined') {
+        throw new Error('FormData is not available! Please make sure your environment supports FormData.');
+    }
     const formData = new FormData();
-    const { stringifyNested = '*' } = configs || {};
+    const { stringifyNested = '*', ignoreKeys = [], breakArray, lowerCaseKeys, dotNotateNested, lowerCaseValues, requiredKeys, } = configs || {};
+    const _compareKeyPaths = (key, paths) => {
+        return paths.some((path) => key === path || key.startsWith(`${path}.`));
+    };
     const _shouldLowercaseKeys = (key) => {
-        return Array.isArray(configs?.lowerCaseKeys)
-            ? configs?.lowerCaseKeys?.some((path) => key === path || key.startsWith(`${path}.`))
-            : configs?.lowerCaseKeys === '*';
+        return Array.isArray(lowerCaseKeys)
+            ? _compareKeyPaths(key, lowerCaseKeys)
+            : lowerCaseKeys === '*';
     };
     const _shouldLowercaseValue = (key) => {
-        return Array.isArray(configs?.lowerCaseValues)
-            ? configs.lowerCaseValues?.some((path) => key === path || key?.startsWith(`${path}.`))
-            : configs?.lowerCaseValues === '*';
+        return Array.isArray(lowerCaseValues)
+            ? _compareKeyPaths(key, lowerCaseValues)
+            : lowerCaseValues === '*';
     };
     const _transformKey = (key) => {
-        return _shouldLowercaseKeys(key) ? key.toLowerCase() : key;
+        return (_shouldLowercaseKeys(key) ? key.toLowerCase() : key);
+    };
+    const _parseDateLike = (value) => {
+        return String(JSON.parse(JSON.stringify(value)));
     };
     const _isRequiredKey = (key) => {
         const transformedKey = _transformKey(key);
-        return Array.isArray(configs?.requiredKeys)
-            ? configs?.requiredKeys?.some((path) => transformedKey === path || transformedKey?.startsWith(`${path}.`))
-            : configs?.requiredKeys === '*';
+        return Array.isArray(requiredKeys)
+            ? _compareKeyPaths(transformedKey, requiredKeys)
+            : requiredKeys === '*';
     };
     const _shouldDotNotate = (key) => {
         const transformedKey = _transformKey(key);
-        return Array.isArray(configs?.dotNotateNested)
-            ? configs.dotNotateNested.includes(transformedKey)
-            : configs?.dotNotateNested === '*';
+        return Array.isArray(dotNotateNested)
+            ? _compareKeyPaths(transformedKey, dotNotateNested)
+            : dotNotateNested === '*';
     };
     const _shouldStringify = (key) => {
         const transformedKey = _transformKey(key);
         return Array.isArray(stringifyNested)
-            ? stringifyNested.includes(transformedKey)
+            ? _compareKeyPaths(transformedKey, stringifyNested)
             : stringifyNested === '*';
     };
     const _shouldBreakArray = (key) => {
         const transformedKey = _transformKey(key);
-        return Array.isArray(configs?.breakArray)
-            ? configs.breakArray.includes(transformedKey)
-            : configs?.breakArray === '*';
+        return Array.isArray(breakArray)
+            ? _compareKeyPaths(transformedKey, breakArray)
+            : breakArray === '*';
     };
     const _cleanObject = (obj, parentKey = '') => {
         return Object.entries(obj).reduce((acc, [key, value]) => {
             const transformedKey = _transformKey(key);
             const fullKey = parentKey ? `${parentKey}.${transformedKey}` : transformedKey;
-            if (configs?.ignoreKeys?.includes(fullKey)) {
+            if (_compareKeyPaths(fullKey, ignoreKeys)) {
                 return acc;
             }
             const shouldKeep = (value != null && value !== '') ||
@@ -58,7 +68,10 @@ const createControlledFormData = (data, configs) => {
                 (0, non_primitives_1.isValidArray)(value) ||
                 (0, non_primitives_1.isNotEmptyObject)(value);
             if (shouldKeep) {
-                if ((0, non_primitives_1.isNotEmptyObject)(value)) {
+                if ((0, guards_1.isDateLike)(value)) {
+                    acc[transformedKey] = value;
+                }
+                else if ((0, non_primitives_1.isNotEmptyObject)(value)) {
                     if ((0, guards_1.isDateLike)(value)) {
                         acc[transformedKey] = value;
                     }
@@ -74,7 +87,7 @@ const createControlledFormData = (data, configs) => {
                         if ((0, primitives_1.isNonEmptyString)(value)) {
                             let cleanString = value;
                             if (configs?.trimStrings) {
-                                cleanString = cleanString?.trim();
+                                cleanString = (0, basics_1.trimString)(cleanString);
                             }
                             if (_shouldLowercaseValue(fullKey)) {
                                 cleanString = cleanString?.toLowerCase();
@@ -105,6 +118,9 @@ const createControlledFormData = (data, configs) => {
     };
     const _addToFormData = (key, value) => {
         const transformedKey = _transformKey(key);
+        if (_compareKeyPaths(transformedKey, ignoreKeys)) {
+            return;
+        }
         if ((0, guards_2.isCustomFileArray)(value)) {
             value?.forEach((file) => formData.append(transformedKey, file?.originFileObj));
         }
@@ -157,7 +173,7 @@ const createControlledFormData = (data, configs) => {
             }
         }
         else if ((0, guards_1.isDateLike)(value)) {
-            formData.append(transformedKey, JSON.parse(JSON.stringify(value)));
+            formData.append(transformedKey, _parseDateLike(value));
         }
         else if ((0, non_primitives_1.isNotEmptyObject)(value)) {
             if (_shouldStringify(key) && !_shouldDotNotate(key)) {
@@ -175,8 +191,15 @@ const createControlledFormData = (data, configs) => {
         else {
             const isNotNullish = value != null && value !== '';
             if (isNotNullish || _isRequiredKey(key)) {
-                if ((0, primitives_1.isString)(value) && _shouldLowercaseValue(key)) {
-                    formData.append(transformedKey, value?.toLowerCase());
+                if ((0, primitives_1.isString)(value)) {
+                    let processedValue = value;
+                    if (configs?.trimStrings) {
+                        processedValue = (0, basics_1.trimString)(processedValue);
+                    }
+                    if (_shouldLowercaseValue(key)) {
+                        processedValue = processedValue.toLowerCase();
+                    }
+                    formData.append(transformedKey, processedValue);
                 }
                 else {
                     formData.append(transformedKey, value);
@@ -188,18 +211,18 @@ const createControlledFormData = (data, configs) => {
         Object.entries(obj).forEach(([key, value]) => {
             const transformedKey = _transformKey(key);
             const fullKey = parentKey ? `${parentKey}.${transformedKey}` : transformedKey;
-            if (configs?.ignoreKeys?.includes(fullKey)) {
+            if (_compareKeyPaths(fullKey, ignoreKeys)) {
                 return;
             }
             if (configs?.trimStrings && (0, primitives_1.isNonEmptyString)(value)) {
-                value = value?.trim();
+                value = (0, basics_1.trimString)(value);
             }
             if (_shouldDotNotate(fullKey)) {
                 _addToFormData(fullKey, value);
             }
             else if ((0, non_primitives_1.isNotEmptyObject)(value) && !_shouldStringify(fullKey)) {
                 if ((0, guards_1.isDateLike)(value)) {
-                    _addToFormData(key, JSON.parse(JSON.stringify(value)));
+                    _addToFormData(key, _parseDateLike(value));
                 }
                 else {
                     _processObject(value, key);
@@ -209,7 +232,7 @@ const createControlledFormData = (data, configs) => {
                 _addToFormData(key, value);
             }
             else if ((0, guards_1.isDateLike)(value)) {
-                _addToFormData(key, JSON.parse(JSON.stringify(value)));
+                _addToFormData(key, _parseDateLike(value));
             }
             else if ((0, non_primitives_1.isEmptyObject)(value)) {
                 if (_isRequiredKey(fullKey)) {

package/dist/dts/date/guards.d.ts

@@ -1,5 +1,5 @@
 import type { Numeric } from '../types/index';
-import type { $TimeZoneIdentifier, ClockTime, TimeWithUnit, TimeZoneIdNative, UTCOffset } from './types';
+import type { $TimeZoneIdentifier, ClockTime, DateLike, TimeWithUnit, TimeZoneIdNative, UTCOffset } from './types';
 /**
  * * Checks if the provided value is a valid time string in "HH:MM" format.
  *
@@ -51,6 +51,6 @@ export declare function isLeapYear(year: Numeric): boolean;
  * @param value Value to check if it is date-like object.
  * @returns `true` if the value is date-like object, otherwise `false`.
  */
-export declare function isDateLike(value: unknown): boolean;
+export declare function isDateLike(value: unknown): value is DateLike;
 /** Checks if a value represents time value (number) with different forms of {@link TimeWithUnit units} */
 export declare function isTimeWithUnit(value: unknown): value is TimeWithUnit;

package/dist/esm/date/guards.js

@@ -44,9 +44,19 @@ export function isDateLike(value) {
             isFunction(value.getClass)) {
             return true;
         }
+        const temporals = [
+            'Instant',
+            'Duration',
+            'PlainDate',
+            'PlainTime',
+            'PlainDateTime',
+            'PlainMonthDay',
+            'PlainYearMonth',
+            'ZonedDateTime',
+        ];
         if (isFunction(value.toJSON) &&
             isFunction(value.toString) &&
-            ['PlainDate', 'ZonedDateTime', 'Instant'].includes(value.constructor?.name ?? '')) {
+            temporals.includes(value.constructor?.name ?? '')) {
             return true;
         }
     }

package/dist/esm/form/convert.js

@@ -1,52 +1,62 @@
 import { isDateLike } from '../date/guards.js';
 import { isEmptyObject, isNotEmptyObject, isValidArray } from '../guards/non-primitives.js';
 import { isNonEmptyString, isString } from '../guards/primitives.js';
+import { trimString } from '../string/basics.js';
 import { isCustomFile, isCustomFileArray, isFileArray, isFileList, isFileOrBlob, isFileUpload, } from './guards.js';
 export const createControlledFormData = (data, configs) => {
+    if (typeof FormData === 'undefined') {
+        throw new Error('FormData is not available! Please make sure your environment supports FormData.');
+    }
     const formData = new FormData();
-    const { stringifyNested = '*' } = configs || {};
+    const { stringifyNested = '*', ignoreKeys = [], breakArray, lowerCaseKeys, dotNotateNested, lowerCaseValues, requiredKeys, } = configs || {};
+    const _compareKeyPaths = (key, paths) => {
+        return paths.some((path) => key === path || key.startsWith(`${path}.`));
+    };
     const _shouldLowercaseKeys = (key) => {
-        return Array.isArray(configs?.lowerCaseKeys)
-            ? configs?.lowerCaseKeys?.some((path) => key === path || key.startsWith(`${path}.`))
-            : configs?.lowerCaseKeys === '*';
+        return Array.isArray(lowerCaseKeys)
+            ? _compareKeyPaths(key, lowerCaseKeys)
+            : lowerCaseKeys === '*';
     };
     const _shouldLowercaseValue = (key) => {
-        return Array.isArray(configs?.lowerCaseValues)
-            ? configs.lowerCaseValues?.some((path) => key === path || key?.startsWith(`${path}.`))
-            : configs?.lowerCaseValues === '*';
+        return Array.isArray(lowerCaseValues)
+            ? _compareKeyPaths(key, lowerCaseValues)
+            : lowerCaseValues === '*';
     };
     const _transformKey = (key) => {
-        return _shouldLowercaseKeys(key) ? key.toLowerCase() : key;
+        return (_shouldLowercaseKeys(key) ? key.toLowerCase() : key);
+    };
+    const _parseDateLike = (value) => {
+        return String(JSON.parse(JSON.stringify(value)));
     };
     const _isRequiredKey = (key) => {
         const transformedKey = _transformKey(key);
-        return Array.isArray(configs?.requiredKeys)
-            ? configs?.requiredKeys?.some((path) => transformedKey === path || transformedKey?.startsWith(`${path}.`))
-            : configs?.requiredKeys === '*';
+        return Array.isArray(requiredKeys)
+            ? _compareKeyPaths(transformedKey, requiredKeys)
+            : requiredKeys === '*';
     };
     const _shouldDotNotate = (key) => {
         const transformedKey = _transformKey(key);
-        return Array.isArray(configs?.dotNotateNested)
-            ? configs.dotNotateNested.includes(transformedKey)
-            : configs?.dotNotateNested === '*';
+        return Array.isArray(dotNotateNested)
+            ? _compareKeyPaths(transformedKey, dotNotateNested)
+            : dotNotateNested === '*';
     };
     const _shouldStringify = (key) => {
         const transformedKey = _transformKey(key);
         return Array.isArray(stringifyNested)
-            ? stringifyNested.includes(transformedKey)
+            ? _compareKeyPaths(transformedKey, stringifyNested)
             : stringifyNested === '*';
     };
     const _shouldBreakArray = (key) => {
         const transformedKey = _transformKey(key);
-        return Array.isArray(configs?.breakArray)
-            ? configs.breakArray.includes(transformedKey)
-            : configs?.breakArray === '*';
+        return Array.isArray(breakArray)
+            ? _compareKeyPaths(transformedKey, breakArray)
+            : breakArray === '*';
     };
     const _cleanObject = (obj, parentKey = '') => {
         return Object.entries(obj).reduce((acc, [key, value]) => {
             const transformedKey = _transformKey(key);
             const fullKey = parentKey ? `${parentKey}.${transformedKey}` : transformedKey;
-            if (configs?.ignoreKeys?.includes(fullKey)) {
+            if (_compareKeyPaths(fullKey, ignoreKeys)) {
                 return acc;
             }
             const shouldKeep = (value != null && value !== '') ||
@@ -55,7 +65,10 @@ export const createControlledFormData = (data, configs) => {
                 isValidArray(value) ||
                 isNotEmptyObject(value);
             if (shouldKeep) {
-                if (isNotEmptyObject(value)) {
+                if (isDateLike(value)) {
+                    acc[transformedKey] = value;
+                }
+                else if (isNotEmptyObject(value)) {
                     if (isDateLike(value)) {
                         acc[transformedKey] = value;
                     }
@@ -71,7 +84,7 @@ export const createControlledFormData = (data, configs) => {
                         if (isNonEmptyString(value)) {
                             let cleanString = value;
                             if (configs?.trimStrings) {
-                                cleanString = cleanString?.trim();
+                                cleanString = trimString(cleanString);
                             }
                             if (_shouldLowercaseValue(fullKey)) {
                                 cleanString = cleanString?.toLowerCase();
@@ -102,6 +115,9 @@ export const createControlledFormData = (data, configs) => {
     };
     const _addToFormData = (key, value) => {
         const transformedKey = _transformKey(key);
+        if (_compareKeyPaths(transformedKey, ignoreKeys)) {
+            return;
+        }
         if (isCustomFileArray(value)) {
             value?.forEach((file) => formData.append(transformedKey, file?.originFileObj));
         }
@@ -154,7 +170,7 @@ export const createControlledFormData = (data, configs) => {
             }
         }
         else if (isDateLike(value)) {
-            formData.append(transformedKey, JSON.parse(JSON.stringify(value)));
+            formData.append(transformedKey, _parseDateLike(value));
         }
         else if (isNotEmptyObject(value)) {
             if (_shouldStringify(key) && !_shouldDotNotate(key)) {
@@ -172,8 +188,15 @@ export const createControlledFormData = (data, configs) => {
         else {
             const isNotNullish = value != null && value !== '';
             if (isNotNullish || _isRequiredKey(key)) {
-                if (isString(value) && _shouldLowercaseValue(key)) {
-                    formData.append(transformedKey, value?.toLowerCase());
+                if (isString(value)) {
+                    let processedValue = value;
+                    if (configs?.trimStrings) {
+                        processedValue = trimString(processedValue);
+                    }
+                    if (_shouldLowercaseValue(key)) {
+                        processedValue = processedValue.toLowerCase();
+                    }
+                    formData.append(transformedKey, processedValue);
                 }
                 else {
                     formData.append(transformedKey, value);
@@ -185,18 +208,18 @@ export const createControlledFormData = (data, configs) => {
         Object.entries(obj).forEach(([key, value]) => {
             const transformedKey = _transformKey(key);
             const fullKey = parentKey ? `${parentKey}.${transformedKey}` : transformedKey;
-            if (configs?.ignoreKeys?.includes(fullKey)) {
+            if (_compareKeyPaths(fullKey, ignoreKeys)) {
                 return;
             }
             if (configs?.trimStrings && isNonEmptyString(value)) {
-                value = value?.trim();
+                value = trimString(value);
             }
             if (_shouldDotNotate(fullKey)) {
                 _addToFormData(fullKey, value);
             }
             else if (isNotEmptyObject(value) && !_shouldStringify(fullKey)) {
                 if (isDateLike(value)) {
-                    _addToFormData(key, JSON.parse(JSON.stringify(value)));
+                    _addToFormData(key, _parseDateLike(value));
                 }
                 else {
                     _processObject(value, key);
@@ -206,7 +229,7 @@ export const createControlledFormData = (data, configs) => {
                 _addToFormData(key, value);
             }
             else if (isDateLike(value)) {
-                _addToFormData(key, JSON.parse(JSON.stringify(value)));
+                _addToFormData(key, _parseDateLike(value));
             }
             else if (isEmptyObject(value)) {
                 if (_isRequiredKey(fullKey)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.30.15",
+  "version": "4.30.16",
   "description": "A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -46,12 +46,12 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.9.0",
+    "@types/node": "^25.9.1",
     "husky": "^9.1.7",
     "jest": "^30.4.2",
     "lint-staged": "^17.0.5",
     "nhb-scripts": "^1.9.2",
-    "ts-jest": "^29.4.9",
+    "ts-jest": "^29.4.11",
     "typescript": "^6.0.3"
   },
   "keywords": [