toolbox-x 2.2.5 → 2.4.0

package/dist/index.cjs

@@ -17,13 +17,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primitives = require('./primitives-CBGICrDR.cjs');
 const require_case = require('./case-Bd7QLHYw.cjs');
-const require_specials = require('./specials-DU8u108m.cjs');
 const require_constants = require('./constants-B3nc8psr.cjs');
-const require_utilities = require('./utilities-BVpk3LKy.cjs');
 const require_countries = require('./countries-C0x58zVg.cjs');
-const require_basics = require('./basics-byj0VH1c.cjs');
-const require_guards = require('./guards-BSwFQX1M.cjs');
-const require_query = require('./query-sWSi-d7u.cjs');
+const require_utils = require('./utils-DR9g0Sef.cjs');
+const require_specials = require('./specials-DU8u108m.cjs');
+const require_basics = require('./basics-Cif013VV.cjs');
+const require_utilities = require('./utilities-_COSGq1U.cjs');
+const require_query = require('./query-Blm7AiEZ.cjs');
 
 //#region src/string/anagram.ts
 /** `WeakMap` to cache user provided dictionary array */
@@ -577,8 +577,8 @@ function getAverage(...numbers) {
 	let sum = 0;
 	let count = 0;
 	for (const n of numbers) {
-		const num = Number(n);
-		if (require_primitives.isNumber(num)) {
+		const num = require_utilities.normalizeNumber(n);
+		if (!require_primitives.isUndefined(num)) {
 			sum += num;
 			count++;
 		}
@@ -586,6 +586,72 @@ function getAverage(...numbers) {
 	return count === 0 ? NaN : Math.round(sum / count * 1e3) / 1e3;
 }
 /**
+* * Returns the number of decimal places represented by a number.
+*
+* @param value - The number or numeric string for which to calculate the number of decimal places.
+* @returns The number of decimal places.
+*
+* @throws - {@link TypeError} - If the input value cannot be converted to a number, e.g. `undefined`, `null`, `NaN`, `'11x'` etc..
+*
+* @remarks
+* - If a numeric string in scientific notation (e.g., '1e-6') is provided, it will calculate the decimal places accordingly.
+* - If a numeric string has trailing zeros (e.g., ''1.00'' or `'9.900'`),
+*   it will convert them as: `'1.00'` -> `1`, `'9.900'` -> `9.9` and return `0` and `1` respectively.
+* - If a number is an integer, it will return `0`.
+* - Internally uses {@link normalizeNumber} to normalize the input value.
+*
+* @example
+* getDecimalPlaces(123.456); // 3
+* getDecimalPlaces('123.45600'); // 3
+* getDecimalPlaces(123); // 0
+* getDecimalPlaces('1e-6'); // 6
+* getDecimalPlaces('1.00'); // 0
+* getDecimalPlaces('9.900'); // 1
+*/
+function getDecimalPlaces(value) {
+	const number = require_utilities.normalizeNumber(value);
+	if (require_primitives.isUndefined(number)) throw new TypeError(`Invalid numeric representation: ${value}`);
+	const str = String(number);
+	if (str.includes("e-")) {
+		const [, exponent] = str.split("e-");
+		return Number(exponent);
+	}
+	const [, decimal = ""] = str.split(".");
+	return decimal.length;
+}
+/**
+* * Adds numbers safely, avoiding floating-point arithmetic issues.
+*
+* @param values - A list of numbers or numeric strings to add.
+* @returns The sum of the provided numbers, with floating-point inaccuracies mitigated.
+*
+* @remarks
+* - This function addresses common floating-point addition errors (e.g., `0.1 + 0.2 !== 0.3`)
+*   by temporarily scaling numbers to integers, performing the addition, and then scaling back.
+* - Non-numeric values are safely ignored in the runtime.
+* - Rounding is used to mitigate floating-point inaccuracies.
+* - Intended for use cases where floating-point inaccuracies are a concern.
+* - Internally uses {@link normalizeNumber}, {@link getDecimalPlaces}, {@link roundNumber}.
+* - It does not handle numbers beyond {@link Number.MAX_SAFE_INTEGER} or {@link Number.MIN_SAFE_INTEGER}.
+*   May output incorrect results if the numbers are too large.
+* @example
+* safeAdd(0.1, 0.2); // → 0.3 (correctly handles floating-point error)
+* safeAdd(1, '2', 3.456); // → 6.456
+* safeAdd(0.1, 0.2, 0.3, 0.4); // → 1.0 (accurate sum)
+*/
+function safeAdd(...values) {
+	let scale = 1;
+	const nums = [];
+	for (const value of values) {
+		const num = require_utilities.normalizeNumber(value);
+		if (!require_primitives.isUndefined(num)) {
+			nums.push(num);
+			scale = Math.max(scale, 10 ** getDecimalPlaces(num));
+		}
+	}
+	return nums.reduce((total, value) => total + roundNumber(value * scale, 0), 0) / scale;
+}
+/**
 * * Rounds a number to a specified number of decimal places.
 *
 * @param number - The number to round.
@@ -1126,39 +1192,39 @@ function calculatePercentage(options) {
 	switch (options?.mode) {
 		case "get-percent": {
 			const { part, total } = options;
-			if (require_guards.areInvalidNumbers(part, total) || total === 0) return NaN;
+			if (require_basics.areInvalidNumbers(part, total) || total === 0) return NaN;
 			return _roundNumber(part / total * 100);
 		}
 		case "get-value": {
 			const { percentage, total } = options;
-			if (require_guards.areInvalidNumbers(percentage, total) || total === 0) return NaN;
+			if (require_basics.areInvalidNumbers(percentage, total) || total === 0) return NaN;
 			return _roundNumber(percentage / 100 * total);
 		}
 		case "get-original": {
 			const { percentage, value } = options;
-			if (require_guards.areInvalidNumbers(percentage, value) || percentage === 0) return NaN;
+			if (require_basics.areInvalidNumbers(percentage, value) || percentage === 0) return NaN;
 			return _roundNumber(value / percentage * 100);
 		}
 		case "get-change-percent": {
 			const { oldValue, newValue } = options;
-			if (require_guards.areInvalidNumbers(oldValue, newValue) || oldValue === 0) return NaN;
+			if (require_basics.areInvalidNumbers(oldValue, newValue) || oldValue === 0) return NaN;
 			return _roundNumber((newValue - oldValue) / oldValue * 100);
 		}
 		case "apply-percent-change": {
 			const { baseValue, percentage } = options;
-			if (require_guards.areInvalidNumbers(baseValue, percentage)) return NaN;
+			if (require_basics.areInvalidNumbers(baseValue, percentage)) return NaN;
 			return _roundNumber(baseValue * (1 + percentage / 100));
 		}
 		case "get-percent-difference": {
 			const { value1, value2 } = options;
-			if (require_guards.areInvalidNumbers(value1, value2)) return NaN;
+			if (require_basics.areInvalidNumbers(value1, value2)) return NaN;
 			const avg = getAverage(value1, value2);
 			if (avg === 0) return NaN;
 			return _roundNumber(Math.abs(value1 - value2) / avg * 100);
 		}
 		case "inverse-percent": {
 			const { part, total } = options;
-			if (require_guards.areInvalidNumbers(part, total) || part === 0) return NaN;
+			if (require_basics.areInvalidNumbers(part, total) || part === 0) return NaN;
 			return _roundNumber(total / part * 100);
 		}
 		default: return NaN;
@@ -1539,7 +1605,7 @@ function getNumbersInRange(type = "any", options) {
 	if (type === "prime" && !require_primitives.isUndefined(multiplesOf)) console.warn("Warning: The \"multiplesOf\" option is ignored when the type is \"prime\"!");
 	switch (type) {
 		case "random":
-			output = require_guards.shuffleArray(_applyRangeOptions(min, max).map((n) => getRandomNumber({
+			output = require_basics.shuffleArray(_applyRangeOptions(min, max).map((n) => getRandomNumber({
 				min: n,
 				max: n,
 				includeMin,
@@ -1547,13 +1613,13 @@ function getNumbersInRange(type = "any", options) {
 			})));
 			break;
 		case "prime":
-			output = _applyRangeOptions(min, max).filter(require_guards.isPrime);
+			output = _applyRangeOptions(min, max).filter(require_basics.isPrime);
 			break;
 		case "odd":
-			output = _applyRangeOptions(min, max).filter(require_guards.isOdd);
+			output = _applyRangeOptions(min, max).filter(require_basics.isOdd);
 			break;
 		case "even":
-			output = _applyRangeOptions(min, max).filter(require_guards.isEven);
+			output = _applyRangeOptions(min, max).filter(require_basics.isEven);
 			break;
 		case "natural":
 			output = _applyRangeOptions(Math.max(min, 1), max);
@@ -1563,7 +1629,7 @@ function getNumbersInRange(type = "any", options) {
 			break;
 	}
 	if (type !== "prime") output = _applyMultiples(output, multiplesOf);
-	return getAsString ? require_basics.convertArrayToString(output, { separator }) : output;
+	return getAsString ? require_utils.convertArrayToString(output, { separator }) : output;
 }
 
 //#endregion
@@ -1593,7 +1659,7 @@ function createOptionsArray(data, config) {
 * @returns A new array with duplicates removed.
 */
 function removeDuplicatesFromArray(array) {
-	return array?.filter((item, index, self) => index === self?.findIndex((el) => require_basics.isDeepEqual(el, item)));
+	return array?.filter((item, index, self) => index === self?.findIndex((el) => require_utils.isDeepEqual(el, item)));
 }
 /**
 * * Finds duplicate values in an array, runs deep comparison for objects and arrays.
@@ -1605,8 +1671,8 @@ function getDuplicates(array) {
 	const seen = [];
 	const duplicates = [];
 	for (const item of array) {
-		const hasSeen = seen?.find((el) => require_basics.isDeepEqual(el, item));
-		const hasDuplicate = duplicates?.find((el) => require_basics.isDeepEqual(el, item));
+		const hasSeen = seen?.find((el) => require_utils.isDeepEqual(el, item));
+		const hasDuplicate = duplicates?.find((el) => require_utils.isDeepEqual(el, item));
 		if (hasSeen && !hasDuplicate) duplicates?.push(item);
 		else if (!hasSeen) seen?.push(item);
 	}
@@ -1631,7 +1697,7 @@ function getDuplicates(array) {
 function findMissingElements(array1, array2, missingFrom) {
 	const source = (missingFrom === "from-first" ? array1 : array2) ?? [];
 	const target = (missingFrom === "from-first" ? array2 : array1) ?? [];
-	return source.filter((s) => !target?.some((t) => require_basics.isDeepEqual(t, s)));
+	return source.filter((s) => !target?.some((t) => require_utils.isDeepEqual(t, s)));
 }
 /**
 * * Splits an array into chunks of a given size.
@@ -1665,7 +1731,7 @@ function splitArrayByProperty(source, property) {
 	if (!require_specials.isValidArray(source)) return [];
 	const grouped = {};
 	source.forEach((item) => {
-		const rawKey = require_basics._resolveNestedKey(item, property);
+		const rawKey = require_utils._resolveNestedKey(item, property);
 		const key = rawKey != null ? String(rawKey) : "__undefined__";
 		if (!grouped[key]) grouped[key] = [];
 		grouped[key].push(item);
@@ -1718,7 +1784,7 @@ function moveArrayElement(arr, fromIndex, toIndex) {
 function sumFieldDifference(data, first, second, roundTo = 2) {
 	if (!require_specials.isValidArray(data)) return 0;
 	const total = data?.reduce((acc, item) => {
-		return acc + (require_basics._getNumericProp(item, first) - require_basics._getNumericProp(item, second));
+		return acc + (require_utils._getNumericProp(item, first) - require_utils._getNumericProp(item, second));
 	}, 0);
 	return roundNumber(total, roundTo);
 }
@@ -1736,7 +1802,7 @@ function sumFieldDifference(data, first, second, roundTo = 2) {
 */
 function sumByField(data, field, roundTo = 2) {
 	if (!require_specials.isValidArray(data)) return 0;
-	const total = data?.reduce((acc, item) => acc + require_basics._getNumericProp(item, field), 0);
+	const total = data?.reduce((acc, item) => acc + require_utils._getNumericProp(item, field), 0);
 	return roundNumber(total, roundTo);
 }
 /**
@@ -1753,7 +1819,7 @@ function sumByField(data, field, roundTo = 2) {
 */
 function averageByField(data, field, roundTo = 2) {
 	if (!require_specials.isValidArray(data)) return 0;
-	const total = data?.reduce((acc, item) => acc + require_basics._getNumericProp(item, field), 0);
+	const total = data?.reduce((acc, item) => acc + require_utils._getNumericProp(item, field), 0);
 	return roundNumber(total / data.length, roundTo);
 }
 /**
@@ -1771,7 +1837,7 @@ function averageByField(data, field, roundTo = 2) {
 */
 function groupAndSumByField(data, groupBy, sumBy, roundTo = 2) {
 	if (!require_specials.isValidArray(data)) return [];
-	return splitArrayByProperty(data, groupBy).map((group) => ({ [`${require_basics._resolveNestedKey(group[0], groupBy)}`]: sumByField(group, sumBy, roundTo) }));
+	return splitArrayByProperty(data, groupBy).map((group) => ({ [`${require_utils._resolveNestedKey(group[0], groupBy)}`]: sumByField(group, sumBy, roundTo) }));
 }
 /**
 * * Groups an array of objects by a primitive field and averages another numeric field per group.
@@ -1788,7 +1854,7 @@ function groupAndSumByField(data, groupBy, sumBy, roundTo = 2) {
 */
 function groupAndAverageByField(data, groupBy, averageBy, roundTo = 2) {
 	if (!require_specials.isValidArray(data)) return [];
-	return splitArrayByProperty(data, groupBy).map((group) => ({ [`${require_basics._resolveNestedKey(group[0], groupBy)}`]: averageByField(group, averageBy, roundTo) }));
+	return splitArrayByProperty(data, groupBy).map((group) => ({ [`${require_utils._resolveNestedKey(group[0], groupBy)}`]: averageByField(group, averageBy, roundTo) }));
 }
 
 //#endregion
@@ -2176,7 +2242,9 @@ exports.Currency = Currency;
 exports.Finder = Finder;
 exports.Unit = Unit;
 exports.UnitConverter = Unit;
+exports.add = safeAdd;
 exports.arabicToRoman = convertToRomanNumerals;
+exports.average = getAverage;
 exports.averageByField = averageByField;
 exports.avgByField = averageByField;
 exports.banglaToDigit = banglaToDigit;
@@ -2191,11 +2259,11 @@ exports.capitalizeString = require_case.capitalizeString;
 exports.cardinalToOrdinal = require_utilities.getOrdinal;
 exports.cardinalWordsToOrdinal = numberToWordsOrdinal;
 exports.clampNumber = require_utilities.clampNumber;
-exports.cloneObject = require_guards.cloneObject;
-exports.compareNaturally = require_basics.naturalSort;
-exports.compareSorter = require_basics.naturalSort;
+exports.cloneObject = require_basics.cloneObject;
+exports.compareNaturally = require_utils.naturalSort;
+exports.compareSorter = require_utils.naturalSort;
 exports.computeTextDiff = computeTextDiff;
-exports.convertArrayToString = require_basics.convertArrayToString;
+exports.convertArrayToString = require_utils.convertArrayToString;
 exports.convertNumberToCurrency = require_utilities.formatCurrency;
 exports.convertNumberToOrdinal = require_utilities.getOrdinal;
 exports.convertNumberToWords = numberToWords;
@@ -2211,58 +2279,59 @@ exports.convertToOrdinal = require_utilities.getOrdinal;
 exports.convertToRomanNumerals = convertToRomanNumerals;
 exports.convertWordToNumber = wordsToNumber;
 exports.convertWordsToNumber = wordsToNumber;
-exports.countInstanceMethods = require_basics.countInstanceMethods;
-exports.countObjectFields = require_guards.countObjectFields;
-exports.countStaticMethods = require_basics.countStaticMethods;
+exports.countInstanceMethods = require_utils.countInstanceMethods;
+exports.countObjectFields = require_basics.countObjectFields;
+exports.countStaticMethods = require_utils.countStaticMethods;
 exports.countWords = countWords;
 exports.countWordsInString = countWords;
 exports.createOptionsArray = createOptionsArray;
 exports.createQueryParams = require_query.generateQueryParams;
-exports.debounceAction = require_basics.debounceAction;
-exports.deepParsePrimitives = require_basics.deepParsePrimitives;
-exports.definePrototypeMethod = require_basics.definePrototypeMethod;
+exports.debounceAction = require_utils.debounceAction;
+exports.decimalPlaces = getDecimalPlaces;
+exports.deepParsePrimitives = require_utils.deepParsePrimitives;
+exports.definePrototypeMethod = require_utils.definePrototypeMethod;
 exports.deleteFields = deleteFields;
 exports.deleteObjectFields = deleteFields;
 exports.digitToBangla = digitToBangla;
 exports.extractDuplicates = getDuplicates;
 exports.extractDuplicatesFromArray = getDuplicates;
-exports.extractEmails = require_guards.extractEmails;
-exports.extractEntries = require_guards.extractObjectEntries;
-exports.extractKeys = require_guards.extractObjectKeys;
-exports.extractKeysDeep = require_guards.extractObjectKeysDeep;
+exports.extractEmails = require_basics.extractEmails;
+exports.extractEntries = require_basics.extractObjectEntries;
+exports.extractKeys = require_basics.extractObjectKeys;
+exports.extractKeysDeep = require_basics.extractObjectKeysDeep;
 exports.extractMissingElements = findMissingElements;
 exports.extractNewFields = require_query.extractNewFields;
 exports.extractNumbers = extractNumbersFromString;
 exports.extractNumbersFromString = extractNumbersFromString;
-exports.extractObjectEntries = require_guards.extractObjectEntries;
-exports.extractObjectKeys = require_guards.extractObjectKeys;
-exports.extractObjectKeysDeep = require_guards.extractObjectKeysDeep;
-exports.extractURLs = require_guards.extractURLs;
+exports.extractObjectEntries = require_basics.extractObjectEntries;
+exports.extractObjectKeys = require_basics.extractObjectKeys;
+exports.extractObjectKeysDeep = require_basics.extractObjectKeysDeep;
+exports.extractURLs = require_basics.extractURLs;
 exports.extractUpdatedAndNewFields = require_query.extractUpdatedAndNewFields;
 exports.extractUpdatedFields = require_query.extractUpdatedFields;
 exports.factorial = factorial;
 exports.factorsOf = getFactors;
 exports.fibonacciGenerator = fibonacciGenerator;
-exports.filterArrayOfObjects = require_guards.filterArrayOfObjects;
+exports.filterArrayOfObjects = require_basics.filterArrayOfObjects;
 exports.findMissingElements = findMissingElements;
-exports.findPrimeNumbers = require_guards.findPrimeNumbers;
-exports.flattenArray = require_guards.flattenArray;
+exports.findPrimeNumbers = require_basics.findPrimeNumbers;
+exports.flattenArray = require_basics.flattenArray;
 exports.flattenObjectDotNotation = require_query.flattenObjectDotNotation;
 exports.flattenObjectKeyValue = require_query.flattenObjectKeyValue;
 exports.formatCurrency = require_utilities.formatCurrency;
-exports.formatNumberWithPluralUnit = require_guards.formatUnitWithPlural;
+exports.formatNumberWithPluralUnit = require_basics.formatUnitWithPlural;
 exports.formatQueryParams = require_query.generateQueryParams;
-exports.formatUnitWithPlural = require_guards.formatUnitWithPlural;
-exports.formatWithPlural = require_guards.formatUnitWithPlural;
+exports.formatUnitWithPlural = require_basics.formatUnitWithPlural;
+exports.formatWithPlural = require_basics.formatUnitWithPlural;
 exports.generateAnagrams = generateAnagrams;
 exports.generateFibonacci = fibonacciGenerator;
 exports.generateQueryParams = require_query.generateQueryParams;
-exports.generateRandomID = require_basics.generateRandomID;
+exports.generateRandomID = require_utils.generateRandomID;
 exports.getAverage = getAverage;
-exports.getAverageOfNumbers = getAverage;
 exports.getCharacterDifferences = getCharacterDifferences;
-exports.getClassDetails = require_basics.getClassDetails;
+exports.getClassDetails = require_utils.getClassDetails;
 exports.getCountryByPhone = getCountryByPhone;
+exports.getDecimalPlaces = getDecimalPlaces;
 exports.getDivisors = getFactors;
 exports.getDuplicates = getDuplicates;
 exports.getDuplicatesFromArray = getDuplicates;
@@ -2272,10 +2341,10 @@ exports.getFibonacci = getFibonacciSeries;
 exports.getFibonacciNumbers = getFibonacciSeries;
 exports.getFibonacciSeries = getFibonacciSeries;
 exports.getFibonacciSeriesMemo = getFibonacciSeriesMemo;
-exports.getInstanceGetterNames = require_basics.getInstanceGetterNames;
-exports.getInstanceMethodNames = require_basics.getInstanceMethodNames;
-exports.getInstanceMethodsCount = require_basics.countInstanceMethods;
-exports.getLastArrayElement = require_guards.getLastArrayElement;
+exports.getInstanceGetterNames = require_utils.getInstanceGetterNames;
+exports.getInstanceMethodNames = require_utils.getInstanceMethodNames;
+exports.getInstanceMethodsCount = require_utils.countInstanceMethods;
+exports.getLastArrayElement = require_basics.getLastArrayElement;
 exports.getLevenshteinDistance = getLevenshteinDistance;
 exports.getMemoizedFibonacci = getFibonacciSeriesMemo;
 exports.getMemoizedFibonacciSeries = getFibonacciSeriesMemo;
@@ -2284,50 +2353,50 @@ exports.getNthFibonacci = getNthFibonacci;
 exports.getNumbersInRange = getNumbersInRange;
 exports.getOrdinal = require_utilities.getOrdinal;
 exports.getOrdinalNumber = require_utilities.getOrdinal;
-exports.getPrimeNumbers = require_guards.findPrimeNumbers;
+exports.getPrimeNumbers = require_basics.findPrimeNumbers;
 exports.getQueryStringAsObject = require_query.parseQueryString;
 exports.getRandomDecimal = require_utilities.getRandomFloat;
 exports.getRandomFloat = require_utilities.getRandomFloat;
 exports.getRandomInt = getRandomNumber;
 exports.getRandomNumber = getRandomNumber;
-exports.getStaticGetterNames = require_basics.getStaticGetterNames;
-exports.getStaticMethodNames = require_basics.getStaticMethodNames;
-exports.getStaticMethodsCount = require_basics.countStaticMethods;
+exports.getStaticGetterNames = require_utils.getStaticGetterNames;
+exports.getStaticMethodNames = require_utils.getStaticMethodNames;
+exports.getStaticMethodsCount = require_utils.countStaticMethods;
 exports.getSumOfNumbers = sumNumbers;
 exports.groupAndAverageByField = groupAndAverageByField;
 exports.groupAndAvgByField = groupAndAverageByField;
 exports.groupAndSumByField = groupAndSumByField;
 exports.groupArrayByProperty = splitArrayByProperty;
 exports.integerToRoman = convertToRomanNumerals;
-exports.isDeepEqual = require_basics.isDeepEqual;
-exports.isInvalidOrEmptyArray = require_guards.isInvalidOrEmptyArray;
-exports.isPrime = require_guards.isPrime;
-exports.isPrimeNumber = require_guards.isPrime;
-exports.joinArrayElements = require_basics.convertArrayToString;
+exports.isDeepEqual = require_utils.isDeepEqual;
+exports.isInvalidOrEmptyArray = require_basics.isInvalidOrEmptyArray;
+exports.isPrime = require_basics.isPrime;
+exports.isPrimeNumber = require_basics.isPrime;
+exports.joinArrayElements = require_utils.convertArrayToString;
 exports.levenshteinDistance = getLevenshteinDistance;
 exports.literalQueryStringToObject = require_query.parseQueryStringLiteral;
-exports.maskString = require_guards.maskString;
+exports.maskString = require_basics.maskString;
 exports.mergeAndFlattenObjects = require_query.mergeAndFlattenObjects;
 exports.mergeObjects = require_query.mergeObjects;
 exports.moveArrayElement = moveArrayElement;
-exports.naturalSort = require_basics.naturalSort;
-exports.naturalSortForString = require_basics.naturalSort;
+exports.naturalSort = require_utils.naturalSort;
+exports.naturalSortForString = require_utils.naturalSort;
 exports.normalizeNumber = require_utilities.normalizeNumber;
-exports.normalizeString = require_guards.normalizeString;
+exports.normalizeString = require_basics.normalizeString;
 exports.numberToOrdinal = require_utilities.getOrdinal;
 exports.numberToRoman = convertToRomanNumerals;
 exports.numberToWords = numberToWords;
 exports.numberToWordsOrdinal = numberToWordsOrdinal;
 exports.numericToRoman = convertToRomanNumerals;
-exports.objectEntries = require_guards.extractObjectEntries;
+exports.objectEntries = require_basics.extractObjectEntries;
 exports.omitFields = deleteFields;
 exports.omitObjectFields = deleteFields;
-exports.parseJSON = require_basics.parseJSON;
-exports.parseJsonDeep = require_basics.parseJSON;
+exports.parseJSON = require_utils.parseJSON;
+exports.parseJsonDeep = require_utils.parseJSON;
 exports.parseJsonToObject = require_query.parseJsonToObject;
 exports.parseNumbersFromText = extractNumbersFromString;
 exports.parseObjectValues = require_query.parseObjectValues;
-exports.parsePrimitivesDeep = require_basics.deepParsePrimitives;
+exports.parsePrimitivesDeep = require_utils.deepParsePrimitives;
 exports.parseQueryString = require_query.parseQueryString;
 exports.parseQueryStringLiteral = require_query.parseQueryStringLiteral;
 exports.parseStringifiedObjectValues = require_query.parseObjectValues;
@@ -2342,9 +2411,9 @@ exports.removeDuplicates = removeDuplicatesFromArray;
 exports.removeDuplicatesFromArray = removeDuplicatesFromArray;
 exports.removeFields = deleteFields;
 exports.removeObjectFields = deleteFields;
-exports.replaceAllInString = require_guards.replaceAllInString;
+exports.replaceAllInString = require_basics.replaceAllInString;
 exports.reverseNumber = reverseNumber;
-exports.reverseString = require_guards.reverseString;
+exports.reverseString = require_basics.reverseString;
 exports.romanToArabic = romanToInteger;
 exports.romanToInteger = romanToInteger;
 exports.romanToNumeric = romanToInteger;
@@ -2354,25 +2423,26 @@ exports.roundNumberToNearestInterval = require_utilities.roundToNearest;
 exports.roundToDecimal = roundNumber;
 exports.roundToNearest = require_utilities.roundToNearest;
 exports.roundToNearestInterval = require_utilities.roundToNearest;
+exports.safeAdd = safeAdd;
 exports.sanitizeData = require_query.sanitizeData;
-exports.shuffleArray = require_guards.shuffleArray;
-exports.slugifyString = require_guards.slugifyString;
-exports.sortAnArray = require_basics.sortAnArray;
+exports.shuffleArray = require_basics.shuffleArray;
+exports.slugifyString = require_basics.slugifyString;
+exports.sortAnArray = require_utils.sortAnArray;
 exports.splitArray = splitArray;
 exports.splitArrayByProperty = splitArrayByProperty;
-exports.stableStringify = require_basics.stableStringify;
-exports.stripJsonEdgeGarbage = require_basics.stripJsonEdgeGarbage;
+exports.stableStringify = require_utils.stableStringify;
+exports.stripJsonEdgeGarbage = require_utils.stripJsonEdgeGarbage;
 exports.sumByField = sumByField;
 exports.sumDigits = sumDigits;
 exports.sumFieldDifference = sumFieldDifference;
 exports.sumNumbers = sumNumbers;
 exports.sumOfNumbers = sumNumbers;
-exports.throttleAction = require_basics.throttleAction;
+exports.throttleAction = require_utils.throttleAction;
 exports.toRoman = convertToRomanNumerals;
 exports.toRomanNumeral = convertToRomanNumerals;
 exports.totalDeltaByField = sumFieldDifference;
-exports.trimString = require_basics.trimString;
-exports.truncateString = require_basics.truncateString;
+exports.trimString = require_utils.trimString;
+exports.truncateString = require_utils.truncateString;
 exports.wordCount = countWords;
 exports.wordToNumber = wordsToNumber;
 exports.wordsToNumber = wordsToNumber;

package/dist/index.d.cts

@@ -292,6 +292,51 @@ declare function reverseNumber(num: Numeric): number;
  * @returns The average of the provided numbers. Returns `NaN` if no numbers are valid.
  */
 declare function getAverage(...numbers: Numeric[]): number;
+/**
+ * * Returns the number of decimal places represented by a number.
+ *
+ * @param value - The number or numeric string for which to calculate the number of decimal places.
+ * @returns The number of decimal places.
+ *
+ * @throws - {@link TypeError} - If the input value cannot be converted to a number, e.g. `undefined`, `null`, `NaN`, `'11x'` etc..
+ *
+ * @remarks
+ * - If a numeric string in scientific notation (e.g., '1e-6') is provided, it will calculate the decimal places accordingly.
+ * - If a numeric string has trailing zeros (e.g., ''1.00'' or `'9.900'`),
+ *   it will convert them as: `'1.00'` -> `1`, `'9.900'` -> `9.9` and return `0` and `1` respectively.
+ * - If a number is an integer, it will return `0`.
+ * - Internally uses {@link normalizeNumber} to normalize the input value.
+ *
+ * @example
+ * getDecimalPlaces(123.456); // 3
+ * getDecimalPlaces('123.45600'); // 3
+ * getDecimalPlaces(123); // 0
+ * getDecimalPlaces('1e-6'); // 6
+ * getDecimalPlaces('1.00'); // 0
+ * getDecimalPlaces('9.900'); // 1
+ */
+declare function getDecimalPlaces(value: Numeric): number;
+/**
+ * * Adds numbers safely, avoiding floating-point arithmetic issues.
+ *
+ * @param values - A list of numbers or numeric strings to add.
+ * @returns The sum of the provided numbers, with floating-point inaccuracies mitigated.
+ *
+ * @remarks
+ * - This function addresses common floating-point addition errors (e.g., `0.1 + 0.2 !== 0.3`)
+ *   by temporarily scaling numbers to integers, performing the addition, and then scaling back.
+ * - Non-numeric values are safely ignored in the runtime.
+ * - Rounding is used to mitigate floating-point inaccuracies.
+ * - Intended for use cases where floating-point inaccuracies are a concern.
+ * - Internally uses {@link normalizeNumber}, {@link getDecimalPlaces}, {@link roundNumber}.
+ * - It does not handle numbers beyond {@link Number.MAX_SAFE_INTEGER} or {@link Number.MIN_SAFE_INTEGER}.
+ *   May output incorrect results if the numbers are too large.
+ * @example
+ * safeAdd(0.1, 0.2); // → 0.3 (correctly handles floating-point error)
+ * safeAdd(1, '2', 3.456); // → 6.456
+ * safeAdd(0.1, 0.2, 0.3, 0.4); // → 1.0 (accurate sum)
+ */
+declare function safeAdd(...values: Numeric[]): number;
 /**
  * * Rounds a number to a specified number of decimal places.
  *
@@ -1235,4 +1280,4 @@ declare function remapFields<Source extends GenericObject, Target extends Record
  */
 declare function getCountryByPhone(phone: number | string): CountryDetails[];
 //#endregion
-export { Currency, Finder, Unit, Unit as UnitConverter, convertToRomanNumerals as arabicToRoman, convertToRomanNumerals, convertToRomanNumerals as integerToRoman, convertToRomanNumerals as numberToRoman, convertToRomanNumerals as numericToRoman, convertToRomanNumerals as toRoman, convertToRomanNumerals as toRomanNumeral, averageByField, averageByField as avgByField, banglaToDigit, getAverage as calculateAverage, getAverage, getAverage as getAverageOfNumbers, factorial as calculateFactorial, factorial, factorial as getFactorial, calculateHCF as calculateGCD, calculateHCF, calculateLCM as calculateLCD, calculateLCM, calculatePercentage, capitalizeString, getOrdinal as cardinalToOrdinal, getOrdinal as convertNumberToOrdinal, getOrdinal as convertToOrdinal, getOrdinal, getOrdinal as getOrdinalNumber, getOrdinal as numberToOrdinal, numberToWordsOrdinal as cardinalWordsToOrdinal, numberToWordsOrdinal as convertNumberToWordsOrdinal, numberToWordsOrdinal, clampNumber, cloneObject, naturalSort as compareNaturally, naturalSort as compareSorter, naturalSort, naturalSort as naturalSortForString, computeTextDiff, convertArrayToString, convertArrayToString as joinArrayElements, formatCurrency as convertNumberToCurrency, formatCurrency, numberToWords as convertNumberToWords, numberToWords, convertObjectValues, romanToInteger as convertRomanToArabic, romanToInteger as convertRomanToInteger, romanToInteger as convertRomanToNumeric, romanToInteger as romanToArabic, romanToInteger, romanToInteger as romanToNumeric, convertStringCase, convertToDecimal, convertToDecimal as convertToFixed, wordsToNumber as convertWordToNumber, wordsToNumber as convertWordsToNumber, wordsToNumber as wordToNumber, wordsToNumber, countInstanceMethods, countInstanceMethods as getInstanceMethodsCount, countObjectFields, countStaticMethods, countStaticMethods as getStaticMethodsCount, countWords, countWords as countWordsInString, countWords as wordCount, createOptionsArray, generateQueryParams as createQueryParams, generateQueryParams as formatQueryParams, generateQueryParams, debounceAction, deepParsePrimitives, deepParsePrimitives as parsePrimitivesDeep, definePrototypeMethod, deleteFields, deleteFields as deleteObjectFields, deleteFields as omitFields, deleteFields as omitObjectFields, deleteFields as removeFields, deleteFields as removeObjectFields, digitToBangla, getDuplicates as extractDuplicates, getDuplicates as extractDuplicatesFromArray, getDuplicates, getDuplicates as getDuplicatesFromArray, extractEmails, extractObjectEntries as extractEntries, extractObjectEntries, extractObjectEntries as objectEntries, extractObjectKeys as extractKeys, extractObjectKeys, extractObjectKeysDeep as extractKeysDeep, extractObjectKeysDeep, findMissingElements as extractMissingElements, findMissingElements, findMissingElements as getMissingElements, extractNewFields, extractNumbersFromString as extractNumbers, extractNumbersFromString, extractNumbersFromString as parseNumbersFromText, extractURLs, extractUpdatedAndNewFields, extractUpdatedFields, getFactors as factorsOf, getFactors as getDivisors, getFactors, fibonacciGenerator, fibonacciGenerator as generateFibonacci, filterArrayOfObjects, findPrimeNumbers, findPrimeNumbers as getPrimeNumbers, flattenArray, flattenObjectDotNotation, flattenObjectKeyValue, formatUnitWithPlural as formatNumberWithPluralUnit, formatUnitWithPlural, formatUnitWithPlural as formatWithPlural, generateAnagrams, generateRandomID, getCharacterDifferences, getClassDetails, getCountryByPhone, getFibonacciSeries as getFibonacci, getFibonacciSeries as getFibonacciNumbers, getFibonacciSeries, getFibonacciSeriesMemo, getFibonacciSeriesMemo as getMemoizedFibonacci, getFibonacciSeriesMemo as getMemoizedFibonacciSeries, getInstanceGetterNames, getInstanceMethodNames, getLastArrayElement, getLevenshteinDistance, getLevenshteinDistance as levenshteinDistance, getNthFibonacci, getNumbersInRange, parseQueryString as getQueryStringAsObject, parseQueryString, parseQueryString as queryStringToObject, getRandomFloat as getRandomDecimal, getRandomFloat, getRandomNumber as getRandomInt, getRandomNumber, getStaticGetterNames, getStaticMethodNames, sumNumbers as getSumOfNumbers, sumNumbers, sumNumbers as sumOfNumbers, groupAndAverageByField, groupAndAverageByField as groupAndAvgByField, groupAndSumByField, splitArrayByProperty as groupArrayByProperty, splitArrayByProperty, isDeepEqual, isInvalidOrEmptyArray, isPrime, isPrime as isPrimeNumber, parseQueryStringLiteral as literalQueryStringToObject, parseQueryStringLiteral, maskString, mergeAndFlattenObjects, mergeObjects, moveArrayElement, normalizeNumber, normalizeString, parseJSON, parseJSON as parseJsonDeep, parseJsonToObject, parseObjectValues, parseObjectValues as parseStringifiedObjectValues, pickFields, pickFields as pickObjectFields, pickObjectFieldsByCondition as pickFieldsByCondition, pickObjectFieldsByCondition, remapFields, remapFields as remapObjectFields, removeDuplicatesFromArray as removeDuplicates, removeDuplicatesFromArray, replaceAllInString, reverseNumber, reverseString, rotateArray, roundNumber, roundNumber as roundToDecimal, roundToNearest as roundNumberToNearestInterval, roundToNearest, roundToNearest as roundToNearestInterval, sanitizeData, shuffleArray, slugifyString, sortAnArray, splitArray, stableStringify, stripJsonEdgeGarbage, sumByField, sumDigits, sumFieldDifference, sumFieldDifference as totalDeltaByField, throttleAction, trimString, truncateString };
+export { Currency, Finder, Unit, Unit as UnitConverter, safeAdd as add, safeAdd, convertToRomanNumerals as arabicToRoman, convertToRomanNumerals, convertToRomanNumerals as integerToRoman, convertToRomanNumerals as numberToRoman, convertToRomanNumerals as numericToRoman, convertToRomanNumerals as toRoman, convertToRomanNumerals as toRomanNumeral, getAverage as average, getAverage as calculateAverage, getAverage, averageByField, averageByField as avgByField, banglaToDigit, factorial as calculateFactorial, factorial, factorial as getFactorial, calculateHCF as calculateGCD, calculateHCF, calculateLCM as calculateLCD, calculateLCM, calculatePercentage, capitalizeString, getOrdinal as cardinalToOrdinal, getOrdinal as convertNumberToOrdinal, getOrdinal as convertToOrdinal, getOrdinal, getOrdinal as getOrdinalNumber, getOrdinal as numberToOrdinal, numberToWordsOrdinal as cardinalWordsToOrdinal, numberToWordsOrdinal as convertNumberToWordsOrdinal, numberToWordsOrdinal, clampNumber, cloneObject, naturalSort as compareNaturally, naturalSort as compareSorter, naturalSort, naturalSort as naturalSortForString, computeTextDiff, convertArrayToString, convertArrayToString as joinArrayElements, formatCurrency as convertNumberToCurrency, formatCurrency, numberToWords as convertNumberToWords, numberToWords, convertObjectValues, romanToInteger as convertRomanToArabic, romanToInteger as convertRomanToInteger, romanToInteger as convertRomanToNumeric, romanToInteger as romanToArabic, romanToInteger, romanToInteger as romanToNumeric, convertStringCase, convertToDecimal, convertToDecimal as convertToFixed, wordsToNumber as convertWordToNumber, wordsToNumber as convertWordsToNumber, wordsToNumber as wordToNumber, wordsToNumber, countInstanceMethods, countInstanceMethods as getInstanceMethodsCount, countObjectFields, countStaticMethods, countStaticMethods as getStaticMethodsCount, countWords, countWords as countWordsInString, countWords as wordCount, createOptionsArray, generateQueryParams as createQueryParams, generateQueryParams as formatQueryParams, generateQueryParams, debounceAction, getDecimalPlaces as decimalPlaces, getDecimalPlaces, deepParsePrimitives, deepParsePrimitives as parsePrimitivesDeep, definePrototypeMethod, deleteFields, deleteFields as deleteObjectFields, deleteFields as omitFields, deleteFields as omitObjectFields, deleteFields as removeFields, deleteFields as removeObjectFields, digitToBangla, getDuplicates as extractDuplicates, getDuplicates as extractDuplicatesFromArray, getDuplicates, getDuplicates as getDuplicatesFromArray, extractEmails, extractObjectEntries as extractEntries, extractObjectEntries, extractObjectEntries as objectEntries, extractObjectKeys as extractKeys, extractObjectKeys, extractObjectKeysDeep as extractKeysDeep, extractObjectKeysDeep, findMissingElements as extractMissingElements, findMissingElements, findMissingElements as getMissingElements, extractNewFields, extractNumbersFromString as extractNumbers, extractNumbersFromString, extractNumbersFromString as parseNumbersFromText, extractURLs, extractUpdatedAndNewFields, extractUpdatedFields, getFactors as factorsOf, getFactors as getDivisors, getFactors, fibonacciGenerator, fibonacciGenerator as generateFibonacci, filterArrayOfObjects, findPrimeNumbers, findPrimeNumbers as getPrimeNumbers, flattenArray, flattenObjectDotNotation, flattenObjectKeyValue, formatUnitWithPlural as formatNumberWithPluralUnit, formatUnitWithPlural, formatUnitWithPlural as formatWithPlural, generateAnagrams, generateRandomID, getCharacterDifferences, getClassDetails, getCountryByPhone, getFibonacciSeries as getFibonacci, getFibonacciSeries as getFibonacciNumbers, getFibonacciSeries, getFibonacciSeriesMemo, getFibonacciSeriesMemo as getMemoizedFibonacci, getFibonacciSeriesMemo as getMemoizedFibonacciSeries, getInstanceGetterNames, getInstanceMethodNames, getLastArrayElement, getLevenshteinDistance, getLevenshteinDistance as levenshteinDistance, getNthFibonacci, getNumbersInRange, parseQueryString as getQueryStringAsObject, parseQueryString, parseQueryString as queryStringToObject, getRandomFloat as getRandomDecimal, getRandomFloat, getRandomNumber as getRandomInt, getRandomNumber, getStaticGetterNames, getStaticMethodNames, sumNumbers as getSumOfNumbers, sumNumbers, sumNumbers as sumOfNumbers, groupAndAverageByField, groupAndAverageByField as groupAndAvgByField, groupAndSumByField, splitArrayByProperty as groupArrayByProperty, splitArrayByProperty, isDeepEqual, isInvalidOrEmptyArray, isPrime, isPrime as isPrimeNumber, parseQueryStringLiteral as literalQueryStringToObject, parseQueryStringLiteral, maskString, mergeAndFlattenObjects, mergeObjects, moveArrayElement, normalizeNumber, normalizeString, parseJSON, parseJSON as parseJsonDeep, parseJsonToObject, parseObjectValues, parseObjectValues as parseStringifiedObjectValues, pickFields, pickFields as pickObjectFields, pickObjectFieldsByCondition as pickFieldsByCondition, pickObjectFieldsByCondition, remapFields, remapFields as remapObjectFields, removeDuplicatesFromArray as removeDuplicates, removeDuplicatesFromArray, replaceAllInString, reverseNumber, reverseString, rotateArray, roundNumber, roundNumber as roundToDecimal, roundToNearest as roundNumberToNearestInterval, roundToNearest, roundToNearest as roundToNearestInterval, sanitizeData, shuffleArray, slugifyString, sortAnArray, splitArray, stableStringify, stripJsonEdgeGarbage, sumByField, sumDigits, sumFieldDifference, sumFieldDifference as totalDeltaByField, throttleAction, trimString, truncateString };