nhb-toolbox 4.0.44 → 4.0.48

package/dist/cjs/dom/query.js

@@ -40,6 +40,9 @@ const generateQueryParams = (params = {}) => {
 exports.generateQueryParams = generateQueryParams;
 /**
  * * Get query params as standard `JavaScript` Object `Record<string, string>`.
+ *
+ * - **Note:** *Extracts query parameters from the current URL (window.location.search).*
+ *
  * @returns Query string as key-value paired object. `Record<string, string>`.
  */
 function getQueryParams() {
@@ -60,6 +63,8 @@ function updateQueryParam(key, value) {
  * Supports multiple values for the same key by returning arrays.
  * Optionally parses primitive string values into actual types (e.g., "1" → 1, "true" → true).
  *
+ * - **Note:** *This function does **not** access or depend on `current URL` a.k.a `window.location.search`.*
+ *
  * @param query - The query string to parse.
  * @param parsePrimitives - Whether to convert stringified primitives into real values (default: true).
  * @returns An object where keys are strings and values can be string, array, number, boolean, or null.

package/dist/cjs/form/convert.js

@@ -212,18 +212,6 @@ const createControlledFormData = (data, configs) => {
                     _addToFormData(key, JSON.stringify(value));
                 }
             }
-            // else if (Array.isArray(value) && value.every(isNotEmptyObject)) {
-            // 	if (shouldDotNotate(fullKey)) {
-            // 		value.forEach((item, index) =>
-            // 			_addToFormData(`${fullKey}[${index}]`, item),
-            // 		);
-            // 	} else if (shouldStringify(fullKey)) {
-            // 		_addToFormData(
-            // 			key,
-            // 			value.map((item) => _processObject(item, parentKey)),
-            // 		);
-            // 	}
-            // }
             else {
                 // * For other cases, just append as key-value
                 _addToFormData(key, value);

package/dist/cjs/object/sanitize.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sanitizeData = sanitizeData;
 exports.parseObjectValues = parseObjectValues;
+const guards_1 = require("../form/guards");
 const non_primitives_1 = require("../guards/non-primitives");
+const primitives_1 = require("../guards/primitives");
 const basics_1 = require("../string/basics");
 /**
  * * Sanitizes a string, array of strings, an object or array of objects by ignoring specified keys and trimming string values.
@@ -13,9 +15,46 @@ const basics_1 = require("../string/basics");
  * @returns A new string, object or array of strings or objects with the specified modifications.
  */
 function sanitizeData(input, options) {
-    const { keysToIgnore: ignoreKeys = [], trimStrings = true, ignoreNullish = false, } = options || {};
+    const { keysToIgnore = [], requiredKeys = [], trimStrings = true, ignoreNullish = false, ignoreFalsy = false, } = options || {};
     // Flatten the object keys and use the keys for comparison
-    const ignoreKeySet = new Set(ignoreKeys);
+    const ignoreKeySet = new Set(keysToIgnore);
+    const isRequiredKey = (key) => {
+        return Array.isArray(requiredKeys) ?
+            requiredKeys.some((path) => key === path || key.startsWith(`${path}.`))
+            : requiredKeys === '*';
+    };
+    /**
+     * * Recursively process an array and its nested content(s).
+     * @param arr Array to process.
+     * @param path Full path as dot notation if needed.
+     * @returns Processed array.
+     */
+    const _processArray = (arr, path) => {
+        return arr
+            .map((item) => {
+            if ((0, primitives_1.isString)(item) && trimStrings) {
+                return (0, basics_1.trimString)(item);
+            }
+            if (Array.isArray(item)) {
+                // Recursive sanitize
+                return _processArray(item, path);
+            }
+            if ((0, non_primitives_1.isObject)(item)) {
+                return _processObject(item, path);
+            }
+            return item;
+        })
+            .filter((v) => {
+            if (ignoreNullish && v == null)
+                return false;
+            if (ignoreFalsy && !v)
+                return false;
+            if (ignoreFalsy && (0, non_primitives_1.isObject)(v) && !(0, non_primitives_1.isNotEmptyObject)(v)) {
+                return false;
+            }
+            return true;
+        });
+    };
     /**
      * * Helper function to process a single object.
      *
@@ -30,23 +69,38 @@ function sanitizeData(input, options) {
             return acc;
         }
         // Exclude nullish values if specified
-        if (ignoreNullish && (value === null || value === undefined)) {
+        if (ignoreNullish && !isRequiredKey(fullKeyPath) && value == null) {
             return acc;
         }
-        // Trim string values if enabled
-        if (typeof value === 'string' && trimStrings) {
+        // Exclude falsy values `0`, `false`, `null` and `undefined`
+        if (ignoreFalsy && !value && !isRequiredKey(fullKeyPath)) {
+            return acc;
+        }
+        if ((0, primitives_1.isString)(value) && trimStrings) {
+            // Trim string values if enabled
             acc[key] = (0, basics_1.trimString)(value);
         }
-        else if (value &&
-            typeof value === 'object' &&
-            !Array.isArray(value)) {
+        else if (value && (0, non_primitives_1.isObject)(value)) {
             // Recursively process nested objects
             const processedValue = _processObject(value, fullKeyPath);
-            // Only add the property if it's not an empty object
-            if ((0, non_primitives_1.isNotEmptyObject)(processedValue)) {
+            // Add the property conditionally if it's not an empty object
+            if (!ignoreFalsy ||
+                isRequiredKey(fullKeyPath) ||
+                (0, non_primitives_1.isNotEmptyObject)(processedValue)) {
                 acc[key] = processedValue;
             }
         }
+        else if (value && Array.isArray(value)) {
+            // Keep file arrays untouched
+            if ((0, guards_1.isFileArray)(value) || (0, guards_1.isCustomFileArray)(value)) {
+                acc[key] = value;
+            }
+            // acc[key as keyof T] = value.map(sanitizeData) as T[keyof T];
+            const sanitizedArray = _processArray(value, fullKeyPath);
+            if (!ignoreFalsy || sanitizedArray.length > 0) {
+                acc[key] = sanitizedArray;
+            }
+        }
         else {
             // Add other values as-is
             acc[key] = value;
@@ -54,22 +108,31 @@ function sanitizeData(input, options) {
         return acc;
     }, {});
     // Process strings
-    if (typeof input === 'string') {
+    if ((0, primitives_1.isString)(input)) {
         return (0, basics_1.trimString)(input);
     }
     // Process array of strings and objects
     if (Array.isArray(input)) {
         // Process array of strings
-        if (typeof input[0] === 'string') {
+        if ((0, non_primitives_1.isArrayOfType)(input, primitives_1.isString)) {
             return (0, basics_1.trimString)(input);
         }
-        // Process array of objects
+        // * Handle arrays with nested strings/arrays/objects
         return input
-            .map((obj) => _processObject(obj))
-            .filter((obj) => (0, non_primitives_1.isNotEmptyObject)(obj));
+            .map((item) => sanitizeData(item, options))
+            .filter((val) => {
+            if (ignoreNullish && val == null)
+                return false;
+            if (ignoreFalsy && !val)
+                return false;
+            if (ignoreFalsy && (0, non_primitives_1.isObject)(val) && !(0, non_primitives_1.isNotEmptyObject)(val)) {
+                return false;
+            }
+            return true;
+        });
     }
     // Process object
-    if (typeof input === 'object' && input !== null) {
+    if ((0, non_primitives_1.isObject)(input)) {
         return _processObject(input);
     }
     return input;
@@ -87,7 +150,7 @@ function parseObjectValues(object) {
     const parsedBody = {};
     if ((0, non_primitives_1.isNotEmptyObject)(object)) {
         Object.entries(object).forEach(([key, value]) => {
-            if (typeof value !== 'string') {
+            if (!(0, primitives_1.isString)(value)) {
                 parsedBody[key] = value;
                 return;
             }

package/dist/dts/dom/query.d.ts

@@ -16,6 +16,9 @@ import type { QueryString } from '../string/types';
 export declare const generateQueryParams: <T extends QueryObject>(params?: T) => QueryString;
 /**
  * * Get query params as standard `JavaScript` Object `Record<string, string>`.
+ *
+ * - **Note:** *Extracts query parameters from the current URL (window.location.search).*
+ *
  * @returns Query string as key-value paired object. `Record<string, string>`.
  */
 export declare function getQueryParams(): Record<string, string>;
@@ -30,6 +33,8 @@ export declare function updateQueryParam(key: string, value: string): void;
  * Supports multiple values for the same key by returning arrays.
  * Optionally parses primitive string values into actual types (e.g., "1" → 1, "true" → true).
  *
+ * - **Note:** *This function does **not** access or depend on `current URL` a.k.a `window.location.search`.*
+ *
  * @param query - The query string to parse.
  * @param parsePrimitives - Whether to convert stringified primitives into real values (default: true).
  * @returns An object where keys are strings and values can be string, array, number, boolean, or null.

package/dist/dts/dom/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/dom/query.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,WAAW,WAChD,CAAC,KACP,WAkCF,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAI1D;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,UACrB,MAAM,gCAEX,YAqBF,CAAC"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/dom/query.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,WAAW,WAChD,CAAC,KACP,WAkCF,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAI1D;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,UACrB,MAAM,gCAEX,YAqBF,CAAC"}

package/dist/dts/form/convert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../src/form/convert.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAEX,aAAa,EAEb,MAAM,iBAAiB,CAAC;AAQzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,SAAS,aAAa,QACzD,CAAC,YACG,eAAe,CAAC,CAAC,CAAC,KAC1B,QAkQF,CAAC"}
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../src/form/convert.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAEX,aAAa,EAEb,MAAM,iBAAiB,CAAC;AAQzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,SAAS,aAAa,QACzD,CAAC,YACG,eAAe,CAAC,CAAC,CAAC,KAC1B,QAqPF,CAAC"}

package/dist/dts/object/sanitize.d.ts

@@ -10,14 +10,14 @@ import type { GenericObject, SanitizeOptions, StrictObject } from './types';
  */
 export declare function sanitizeData<T extends GenericObject>(object: T, options?: SanitizeOptions<T>): FlattenPartial<T>;
 /**
- * * Sanitizes an array of objects by ignoring specified keys and trimming string values based on options provided.
- * * Also excludes nullish values (null, undefined) if specified. Always ignores empty nested object(s).
+ * * Sanitizes a deeply nested array that may contain arrays, objects or other (mixed) data types.
+ * * Preserves structure while removing empty values and trimming strings and other operations.
  *
- * @param object - The object to sanitize.
- * @param options - Options that define which keys to ignore, whether to trim string values, and whether to exclude nullish values.
- * @returns A new array of objects with the specified modifications.
+ * @param array - A mixed array that may contain arrays, objects or other data types.
+ * @param options - Options to trim and filter values.
+ * @returns A new sanitized array with the specified modifications.
  */
-export declare function sanitizeData<T extends GenericObject>(array: T[], options?: SanitizeOptions<T>): FlattenPartial<T>[];
+export declare function sanitizeData<T>(array: T[], options?: SanitizeOptions<T>): FlattenPartial<T>[];
 /**
  * * Trims all the words in a string.
  *

package/dist/dts/object/sanitize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../../src/object/sanitize.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAEX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,MAAM,SAAS,CAAC;AAEjB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,EACnD,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,CAAC,CAAC,CAAC;AAErB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,EACnD,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;AAEvB;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;AA4FxD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CAgCrE"}
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../../src/object/sanitize.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAEX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,MAAM,SAAS,CAAC;AAEjB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,aAAa,EACnD,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,CAAC,CAAC,CAAC;AAErB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC1B,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;AAEvB;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;AAgKxD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CAgCrE"}

package/dist/dts/object/types.d.ts

@@ -41,14 +41,26 @@ export type NestedKeyString<T> = T extends AdvancedTypes ? never : T extends Gen
 export type NestedPrimitiveKey<T> = T extends AdvancedTypes ? never : T extends GenericObject ? {
     [K in keyof T & string]: NonNullable<T[K]> extends Primitive ? K : NonNullable<T[K]> extends GenericObject ? `${K}.${NestedPrimitiveKey<NonNullable<T[K]>>}` : never;
 }[keyof T & string] : never;
-/** - Options for `sanitizeData` */
-export interface SanitizeOptions<T extends GenericObject> {
-    /** Keys to ignore */
+/** - Options for `sanitizeData` utility. */
+export interface SanitizeOptions<T> {
+    /**
+     * An array of dot-notation keys to exclude from the sanitized output.
+     * This is only applicable when sanitizing plain objects or arrays of objects.
+     * When applied to nested or irregular array structures, behavior may be inconsistent or partially ignored.
+     */
     keysToIgnore?: DotNotationKey<T>[];
-    /** Whether to trim string values. Defaults to `true` */
+    /** Whether to trim string values. Defaults to `true`. */
     trimStrings?: boolean;
-    /** Whether to exclude nullish (null or undefined) values. Defaults to `false` */
+    /** Whether to exclude nullish (`null` or `undefined`) values. Defaults to `false`. */
     ignoreNullish?: boolean;
+    /** Whether to exclude all falsy values (`false`, `0`, `empty string: ''`, `null`, `undefined` and `empty object and arrays` (`{}`, `[]`)). Defaults to `false`. */
+    ignoreFalsy?: boolean;
+    /**
+     * An array of dot-notation key paths that must be preserved in the sanitized output.
+     * Use `"*"` to retain all keys. This applies primarily to plain or nested objects and arrays of objects.
+     * When applied to nested or irregular array structures, behavior may be inconsistent or partially ignored.
+     */
+    requiredKeys?: '*' | DotNotationKey<T>[];
 }
 /** - Data after sanitization.
  * ! Unused

package/dist/dts/object/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/object/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/object/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/dom/query.js

@@ -34,6 +34,9 @@ export const generateQueryParams = (params = {}) => {
 };
 /**
  * * Get query params as standard `JavaScript` Object `Record<string, string>`.
+ *
+ * - **Note:** *Extracts query parameters from the current URL (window.location.search).*
+ *
  * @returns Query string as key-value paired object. `Record<string, string>`.
  */
 export function getQueryParams() {
@@ -54,6 +57,8 @@ export function updateQueryParam(key, value) {
  * Supports multiple values for the same key by returning arrays.
  * Optionally parses primitive string values into actual types (e.g., "1" → 1, "true" → true).
  *
+ * - **Note:** *This function does **not** access or depend on `current URL` a.k.a `window.location.search`.*
+ *
  * @param query - The query string to parse.
  * @param parsePrimitives - Whether to convert stringified primitives into real values (default: true).
  * @returns An object where keys are strings and values can be string, array, number, boolean, or null.

package/dist/esm/form/convert.js

@@ -209,18 +209,6 @@ export const createControlledFormData = (data, configs) => {
                     _addToFormData(key, JSON.stringify(value));
                 }
             }
-            // else if (Array.isArray(value) && value.every(isNotEmptyObject)) {
-            // 	if (shouldDotNotate(fullKey)) {
-            // 		value.forEach((item, index) =>
-            // 			_addToFormData(`${fullKey}[${index}]`, item),
-            // 		);
-            // 	} else if (shouldStringify(fullKey)) {
-            // 		_addToFormData(
-            // 			key,
-            // 			value.map((item) => _processObject(item, parentKey)),
-            // 		);
-            // 	}
-            // }
             else {
                 // * For other cases, just append as key-value
                 _addToFormData(key, value);

package/dist/esm/object/sanitize.js

@@ -1,4 +1,6 @@
-import { isNotEmptyObject } from '../guards/non-primitives';
+import { isCustomFileArray, isFileArray } from '../form/guards';
+import { isArrayOfType, isNotEmptyObject, isObject, } from '../guards/non-primitives';
+import { isString } from '../guards/primitives';
 import { trimString } from '../string/basics';
 /**
  * * Sanitizes a string, array of strings, an object or array of objects by ignoring specified keys and trimming string values.
@@ -9,9 +11,46 @@ import { trimString } from '../string/basics';
  * @returns A new string, object or array of strings or objects with the specified modifications.
  */
 export function sanitizeData(input, options) {
-    const { keysToIgnore: ignoreKeys = [], trimStrings = true, ignoreNullish = false, } = options || {};
+    const { keysToIgnore = [], requiredKeys = [], trimStrings = true, ignoreNullish = false, ignoreFalsy = false, } = options || {};
     // Flatten the object keys and use the keys for comparison
-    const ignoreKeySet = new Set(ignoreKeys);
+    const ignoreKeySet = new Set(keysToIgnore);
+    const isRequiredKey = (key) => {
+        return Array.isArray(requiredKeys) ?
+            requiredKeys.some((path) => key === path || key.startsWith(`${path}.`))
+            : requiredKeys === '*';
+    };
+    /**
+     * * Recursively process an array and its nested content(s).
+     * @param arr Array to process.
+     * @param path Full path as dot notation if needed.
+     * @returns Processed array.
+     */
+    const _processArray = (arr, path) => {
+        return arr
+            .map((item) => {
+            if (isString(item) && trimStrings) {
+                return trimString(item);
+            }
+            if (Array.isArray(item)) {
+                // Recursive sanitize
+                return _processArray(item, path);
+            }
+            if (isObject(item)) {
+                return _processObject(item, path);
+            }
+            return item;
+        })
+            .filter((v) => {
+            if (ignoreNullish && v == null)
+                return false;
+            if (ignoreFalsy && !v)
+                return false;
+            if (ignoreFalsy && isObject(v) && !isNotEmptyObject(v)) {
+                return false;
+            }
+            return true;
+        });
+    };
     /**
      * * Helper function to process a single object.
      *
@@ -26,23 +65,38 @@ export function sanitizeData(input, options) {
             return acc;
         }
         // Exclude nullish values if specified
-        if (ignoreNullish && (value === null || value === undefined)) {
+        if (ignoreNullish && !isRequiredKey(fullKeyPath) && value == null) {
             return acc;
         }
-        // Trim string values if enabled
-        if (typeof value === 'string' && trimStrings) {
+        // Exclude falsy values `0`, `false`, `null` and `undefined`
+        if (ignoreFalsy && !value && !isRequiredKey(fullKeyPath)) {
+            return acc;
+        }
+        if (isString(value) && trimStrings) {
+            // Trim string values if enabled
             acc[key] = trimString(value);
         }
-        else if (value &&
-            typeof value === 'object' &&
-            !Array.isArray(value)) {
+        else if (value && isObject(value)) {
             // Recursively process nested objects
             const processedValue = _processObject(value, fullKeyPath);
-            // Only add the property if it's not an empty object
-            if (isNotEmptyObject(processedValue)) {
+            // Add the property conditionally if it's not an empty object
+            if (!ignoreFalsy ||
+                isRequiredKey(fullKeyPath) ||
+                isNotEmptyObject(processedValue)) {
                 acc[key] = processedValue;
             }
         }
+        else if (value && Array.isArray(value)) {
+            // Keep file arrays untouched
+            if (isFileArray(value) || isCustomFileArray(value)) {
+                acc[key] = value;
+            }
+            // acc[key as keyof T] = value.map(sanitizeData) as T[keyof T];
+            const sanitizedArray = _processArray(value, fullKeyPath);
+            if (!ignoreFalsy || sanitizedArray.length > 0) {
+                acc[key] = sanitizedArray;
+            }
+        }
         else {
             // Add other values as-is
             acc[key] = value;
@@ -50,22 +104,31 @@ export function sanitizeData(input, options) {
         return acc;
     }, {});
     // Process strings
-    if (typeof input === 'string') {
+    if (isString(input)) {
         return trimString(input);
     }
     // Process array of strings and objects
     if (Array.isArray(input)) {
         // Process array of strings
-        if (typeof input[0] === 'string') {
+        if (isArrayOfType(input, isString)) {
             return trimString(input);
         }
-        // Process array of objects
+        // * Handle arrays with nested strings/arrays/objects
         return input
-            .map((obj) => _processObject(obj))
-            .filter((obj) => isNotEmptyObject(obj));
+            .map((item) => sanitizeData(item, options))
+            .filter((val) => {
+            if (ignoreNullish && val == null)
+                return false;
+            if (ignoreFalsy && !val)
+                return false;
+            if (ignoreFalsy && isObject(val) && !isNotEmptyObject(val)) {
+                return false;
+            }
+            return true;
+        });
     }
     // Process object
-    if (typeof input === 'object' && input !== null) {
+    if (isObject(input)) {
         return _processObject(input);
     }
     return input;
@@ -83,7 +146,7 @@ export function parseObjectValues(object) {
     const parsedBody = {};
     if (isNotEmptyObject(object)) {
         Object.entries(object).forEach(([key, value]) => {
-            if (typeof value !== 'string') {
+            if (!isString(value)) {
                 parsedBody[key] = value;
                 return;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.0.44",
+  "version": "4.0.48",
   "description": "A versatile collection of smart, efficient, and reusable utility functions for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",