nhb-toolbox 4.0.30 → 4.0.32

package/dist/cjs/index.js

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFibonacci = exports.generateFibonacci = exports.fibonacciGenerator = exports.sumOfNumbers = exports.sumNumbers = exports.sumDigits = exports.reverseNumber = exports.percentageOfWhat = exports.getValueFromPercentage = exports.getSumOfNumbers = exports.getRandomNumber = exports.getPercentageResult = exports.getPercentageOfWhat = exports.getPercentage = exports.getOriginalNumberFromPercentage = exports.getAverageOfNumbers = exports.getAverage = exports.convertToDecimal = exports.calculatePercentage = exports.calculateOriginalFromPercentage = exports.calculateLCM = exports.calculateLCD = exports.calculateHCF = exports.calculateGCD = exports.calculateAverage = exports.levenshteinDistance = exports.getLevenshteinDistance = exports.extractNumbersFromString = exports.slugifyString = exports.reverseString = exports.replaceAllInString = exports.normalizeString = exports.maskString = exports.formatWithPlural = exports.formatUnitWithPlural = exports.formatNumberWithPluralUnit = exports.extractURLs = exports.extractEmails = exports.convertStringCase = exports.isSnakeCase = exports.isPascalCase = exports.isPalindrome = exports.isKebabCase = exports.isEmojiOnly = exports.isCamelCase = exports.generateAnagrams = exports.truncateString = exports.trimString = exports.generateRandomID = exports.capitalizeString = void 0;
-exports.convertHslToRgb = exports.convertHslToHex = exports.convertHslaToRgba = exports.convertHslaToHex8 = exports.convertHexToRgb = exports.convertHexToHsl = exports.convertHex8ToRgba = exports.convertHex8ToHsla = exports.convertColorCode = exports.generateRandomHSLColor = exports.generateRandomColorInHexRGB = exports.getColorForInitial = exports.getNumbersInRange = exports.roundToNearestInterval = exports.roundToNearest = exports.roundNumberToNearestInterval = exports.roundNumber = exports.numberToOrdinal = exports.getRandomFloat = exports.getRandomDecimal = exports.getOrdinalNumber = exports.getOrdinal = exports.formatCurrency = exports.convertToOrdinal = exports.convertNumberToOrdinal = exports.convertNumberToCurrency = exports.clampNumber = exports.cardinalToOrdinal = exports.isPrimeNumber = exports.isPrime = exports.getPrimeNumbers = exports.findPrimeNumbers = exports.numberToWords = exports.convertToRomanNumerals = exports.convertNumberToWords = exports.isPerfectSquare = exports.isParOfFibonacciSeries = exports.isParOfFibonacci = exports.isOddNumber = exports.isOdd = exports.isMultiple = exports.isFibonacci = exports.isEvenNumber = exports.isEven = exports.getNthFibonacci = exports.getMemoizedFibonacciSeries = exports.getMemoizedFibonacci = exports.getFibonacciSeriesMemo = exports.getFibonacciSeries = exports.getFibonacciNumbers = void 0;
-exports.splitArray = exports.rotateArray = exports.removeDuplicatesFromArray = exports.moveArrayElement = exports.createOptionsArray = exports.sortAnArray = exports.shuffleArray = exports.isValidEmptyArray = exports.isInvalidOrEmptyArray = exports.getLastArrayElement = exports.flattenArray = exports.filterArrayOfObjects = exports.minutesToUTCOffset = exports.getTotalMinutesFromUTC = exports.getTotalMinutesFromTime = exports.getTotalMinutes = exports.getTimeStringFromUTC = exports.getMinutesFromUTC = exports.getCurrentTime = exports.getCurrentDateTime = exports.formatUTCOffset = exports.extractTotalMinutesFromTime = exports.extractTimeStringFromUTC = exports.extractTimeFromUTC = exports.extractMinutesFromUTC = exports.extractHourMinute = exports.convertMinutesToUTCOffset = exports.chronusts = exports.chronusjs = exports.chronus = exports.chronosts = exports.chronosjs = exports.chronos = exports.Chronus = exports.Chronos = exports.isValidUTCOffSet = exports.isValidUTC = exports.isValidTimeString = exports.isValidTime = exports.isLeapYear = exports.greet = exports.getGreeting = exports.generateGreeting = exports.Colour = exports.Color = exports.convertRgbToRgba = exports.convertRgbToHsl = exports.convertRgbToHex = exports.convertRgbaToHsla = exports.convertRgbaToHex8 = void 0;
-exports.removeFromLocalStorage = exports.getFromSessionStorage = exports.getFromLocalStorage = exports.toggleFullScreen = exports.smoothScrollTo = exports.copyToClipboard = exports.updateQueryParam = exports.getQueryParams = exports.generateQueryParams = exports.formatQueryParams = exports.createQueryParams = exports.remapObjectFields = exports.remapFields = exports.pickObjectFieldsByCondition = exports.pickObjectFields = exports.pickFieldsByCondition = exports.pickFields = exports.convertObjectValues = exports.sanitizeData = exports.parseStringifiedValues = exports.parseStringifiedPrimitives = exports.parseStringifiedObjectValues = exports.parsePrimitives = exports.parsePrimitiveData = exports.parseObjectValues = exports.mergeObjects = exports.mergeAndFlattenObjects = exports.flattenObjectKeyValue = exports.flattenObjectDotNotation = exports.extractUpdatedFields = exports.extractUpdatedAndNewFields = exports.extractNewFields = exports.countObjectFields = exports.cloneObject = exports.isValidFormData = exports.isOriginFileObj = exports.isFileUpload = exports.isFileList = exports.isFileArray = exports.isCustomFileArray = exports.isCustomFile = exports.serializeForm = exports.parseFormData = exports.createFormData = exports.createControlledFormData = exports.convertIntoFormData = exports.naturalSortForString = exports.naturalSort = exports.compareSorter = exports.compareNaturally = void 0;
-exports.isSet = exports.isReturningPromise = exports.isRegularExpression = exports.isRegExp = exports.isPromise = exports.isObjectWithKeys = exports.isObjectEmpty = exports.isObject = exports.isNotEmptyObject = exports.isMethodDescriptor = exports.isMethod = exports.isMap = exports.isJSONObject = exports.isJSON = exports.isFunction = exports.isError = exports.isEmptyObjectGuard = exports.isEmptyObject = exports.isDate = exports.isBigInt = exports.isArrayWithLength = exports.isArrayOfType = exports.isArray = exports.doesReturnPromise = exports.isUndefined = exports.isTruthy = exports.isSymbol = exports.isString = exports.isPrimitive = exports.isPositiveInteger = exports.isNumber = exports.isNull = exports.isNonEmptyString = exports.isInteger = exports.isFalsy = exports.isBoolean = exports.throttleAction = exports.isDeepEqual = exports.getStaticMethodsCount = exports.getStaticMethodNames = exports.getInstanceMethodsCount = exports.getInstanceMethodNames = exports.getClassDetails = exports.debounceAction = exports.countStaticMethods = exports.countInstanceMethods = exports.convertArrayToString = exports.saveToSessionStorage = exports.saveToLocalStorage = exports.removeFromSessionStorage = void 0;
-exports.isValidURL = exports.isValidEmail = exports.isUUID = exports.isURL = exports.isPhoneNumber = exports.isNumericString = exports.isNodeEnvironment = exports.isNodeENV = exports.isNode = exports.isIPAddress = exports.isExpectedNodeENV = exports.isEnvironment = exports.isEmailArray = exports.isEmail = exports.isDateString = exports.isBrowser = exports.isBase64 = exports.isValidSet = exports.isValidObject = exports.isValidMap = exports.isValidJSON = exports.isValidArray = void 0;
+exports.areInvalidNumbers = exports.getNthFibonacci = exports.getMemoizedFibonacciSeries = exports.getMemoizedFibonacci = exports.getFibonacciSeriesMemo = exports.getFibonacciSeries = exports.getFibonacciNumbers = exports.getFibonacci = exports.generateFibonacci = exports.fibonacciGenerator = exports.calculatePercentage = exports.sumOfNumbers = exports.sumNumbers = exports.sumDigits = exports.reverseNumber = exports.getSumOfNumbers = exports.getRandomNumber = exports.getAverageOfNumbers = exports.getAverage = exports.convertToDecimal = exports.calculateLCM = exports.calculateLCD = exports.calculateHCF = exports.calculateGCD = exports.calculateAverage = exports.levenshteinDistance = exports.getLevenshteinDistance = exports.extractNumbersFromString = exports.slugifyString = exports.reverseString = exports.replaceAllInString = exports.normalizeString = exports.maskString = exports.formatWithPlural = exports.formatUnitWithPlural = exports.formatNumberWithPluralUnit = exports.extractURLs = exports.extractEmails = exports.convertStringCase = exports.isSnakeCase = exports.isPascalCase = exports.isPalindrome = exports.isKebabCase = exports.isEmojiOnly = exports.isCamelCase = exports.generateAnagrams = exports.truncateString = exports.trimString = exports.generateRandomID = exports.capitalizeString = void 0;
+exports.convertRgbToRgba = exports.convertRgbToHsl = exports.convertRgbToHex = exports.convertRgbaToHsla = exports.convertRgbaToHex8 = exports.convertHslToRgb = exports.convertHslToHex = exports.convertHslaToRgba = exports.convertHslaToHex8 = exports.convertHexToRgb = exports.convertHexToHsl = exports.convertHex8ToRgba = exports.convertHex8ToHsla = exports.convertColorCode = exports.generateRandomHSLColor = exports.generateRandomColorInHexRGB = exports.getColorForInitial = exports.getNumbersInRange = exports.roundToNearestInterval = exports.roundToNearest = exports.roundNumberToNearestInterval = exports.roundNumber = exports.numberToOrdinal = exports.getRandomFloat = exports.getRandomDecimal = exports.getOrdinalNumber = exports.getOrdinal = exports.formatCurrency = exports.convertToOrdinal = exports.convertNumberToOrdinal = exports.convertNumberToCurrency = exports.clampNumber = exports.cardinalToOrdinal = exports.isPrimeNumber = exports.isPrime = exports.getPrimeNumbers = exports.findPrimeNumbers = exports.numberToWords = exports.convertToRomanNumerals = exports.convertNumberToWords = exports.isPerfectSquare = exports.isParOfFibonacciSeries = exports.isParOfFibonacci = exports.isOddNumber = exports.isOdd = exports.isMultiple = exports.isInvalidNumbers = exports.isFibonacci = exports.isEvenNumber = exports.isEven = void 0;
+exports.convertIntoFormData = exports.naturalSortForString = exports.naturalSort = exports.compareSorter = exports.compareNaturally = exports.splitArray = exports.rotateArray = exports.removeDuplicatesFromArray = exports.moveArrayElement = exports.createOptionsArray = exports.sortAnArray = exports.shuffleArray = exports.isValidEmptyArray = exports.isInvalidOrEmptyArray = exports.getLastArrayElement = exports.flattenArray = exports.filterArrayOfObjects = exports.minutesToUTCOffset = exports.getTotalMinutesFromUTC = exports.getTotalMinutesFromTime = exports.getTotalMinutes = exports.getTimeStringFromUTC = exports.getMinutesFromUTC = exports.getCurrentTime = exports.getCurrentDateTime = exports.formatUTCOffset = exports.extractTotalMinutesFromTime = exports.extractTimeStringFromUTC = exports.extractTimeFromUTC = exports.extractMinutesFromUTC = exports.extractHourMinute = exports.convertMinutesToUTCOffset = exports.chronusts = exports.chronusjs = exports.chronus = exports.chronosts = exports.chronosjs = exports.chronos = exports.Chronus = exports.Chronos = exports.isValidUTCOffSet = exports.isValidUTC = exports.isValidTimeString = exports.isValidTime = exports.isLeapYear = exports.greet = exports.getGreeting = exports.generateGreeting = exports.Colour = exports.Color = void 0;
+exports.countInstanceMethods = exports.convertArrayToString = exports.saveToSessionStorage = exports.saveToLocalStorage = exports.removeFromSessionStorage = exports.removeFromLocalStorage = exports.getFromSessionStorage = exports.getFromLocalStorage = exports.toggleFullScreen = exports.smoothScrollTo = exports.copyToClipboard = exports.updateQueryParam = exports.getQueryParams = exports.generateQueryParams = exports.formatQueryParams = exports.createQueryParams = exports.remapObjectFields = exports.remapFields = exports.pickObjectFieldsByCondition = exports.pickObjectFields = exports.pickFieldsByCondition = exports.pickFields = exports.convertObjectValues = exports.sanitizeData = exports.parseStringifiedValues = exports.parseStringifiedPrimitives = exports.parseStringifiedObjectValues = exports.parsePrimitives = exports.parsePrimitiveData = exports.parseObjectValues = exports.mergeObjects = exports.mergeAndFlattenObjects = exports.flattenObjectKeyValue = exports.flattenObjectDotNotation = exports.extractUpdatedFields = exports.extractUpdatedAndNewFields = exports.extractNewFields = exports.countObjectFields = exports.cloneObject = exports.isValidFormData = exports.isOriginFileObj = exports.isFileUpload = exports.isFileList = exports.isFileArray = exports.isCustomFileArray = exports.isCustomFile = exports.serializeForm = exports.parseFormData = exports.createFormData = exports.createControlledFormData = void 0;
+exports.isValidSet = exports.isValidObject = exports.isValidMap = exports.isValidJSON = exports.isValidArray = exports.isSet = exports.isReturningPromise = exports.isRegularExpression = exports.isRegExp = exports.isPromise = exports.isObjectWithKeys = exports.isObjectEmpty = exports.isObject = exports.isNotEmptyObject = exports.isMethodDescriptor = exports.isMethod = exports.isMap = exports.isJSONObject = exports.isJSON = exports.isFunction = exports.isError = exports.isEmptyObjectGuard = exports.isEmptyObject = exports.isDate = exports.isBigInt = exports.isArrayWithLength = exports.isArrayOfType = exports.isArray = exports.doesReturnPromise = exports.isUndefined = exports.isTruthy = exports.isSymbol = exports.isString = exports.isPrimitive = exports.isPositiveInteger = exports.isNumber = exports.isNull = exports.isNonEmptyString = exports.isInteger = exports.isFalsy = exports.isBoolean = exports.throttleAction = exports.isDeepEqual = exports.getStaticMethodsCount = exports.getStaticMethodNames = exports.getInstanceMethodsCount = exports.getInstanceMethodNames = exports.getClassDetails = exports.debounceAction = exports.countStaticMethods = void 0;
+exports.isValidURL = exports.isValidEmail = exports.isUUID = exports.isURL = exports.isPhoneNumber = exports.isNumericString = exports.isNodeEnvironment = exports.isNodeENV = exports.isNode = exports.isIPAddress = exports.isExpectedNodeENV = exports.isEnvironment = exports.isEmailArray = exports.isEmail = exports.isDateString = exports.isBrowser = exports.isBase64 = void 0;
 // ! String Utilities
 var basics_1 = require("./string/basics");
 Object.defineProperty(exports, "capitalizeString", { enumerable: true, get: function () { return basics_1.capitalizeString; } });
@@ -44,23 +44,17 @@ Object.defineProperty(exports, "calculateGCD", { enumerable: true, get: function
 Object.defineProperty(exports, "calculateHCF", { enumerable: true, get: function () { return basics_2.calculateHCF; } });
 Object.defineProperty(exports, "calculateLCD", { enumerable: true, get: function () { return basics_2.calculateLCM; } });
 Object.defineProperty(exports, "calculateLCM", { enumerable: true, get: function () { return basics_2.calculateLCM; } });
-Object.defineProperty(exports, "calculateOriginalFromPercentage", { enumerable: true, get: function () { return basics_2.getOriginalFromPercentage; } });
-Object.defineProperty(exports, "calculatePercentage", { enumerable: true, get: function () { return basics_2.getPercentage; } });
 Object.defineProperty(exports, "convertToDecimal", { enumerable: true, get: function () { return basics_2.convertToDecimal; } });
 Object.defineProperty(exports, "getAverage", { enumerable: true, get: function () { return basics_2.getAverage; } });
 Object.defineProperty(exports, "getAverageOfNumbers", { enumerable: true, get: function () { return basics_2.getAverage; } });
-Object.defineProperty(exports, "getOriginalNumberFromPercentage", { enumerable: true, get: function () { return basics_2.getOriginalFromPercentage; } });
-Object.defineProperty(exports, "getPercentage", { enumerable: true, get: function () { return basics_2.getPercentage; } });
-Object.defineProperty(exports, "getPercentageOfWhat", { enumerable: true, get: function () { return basics_2.getOriginalFromPercentage; } });
-Object.defineProperty(exports, "getPercentageResult", { enumerable: true, get: function () { return basics_2.getValueFromPercentage; } });
 Object.defineProperty(exports, "getRandomNumber", { enumerable: true, get: function () { return basics_2.getRandomNumber; } });
 Object.defineProperty(exports, "getSumOfNumbers", { enumerable: true, get: function () { return basics_2.sumNumbers; } });
-Object.defineProperty(exports, "getValueFromPercentage", { enumerable: true, get: function () { return basics_2.getValueFromPercentage; } });
-Object.defineProperty(exports, "percentageOfWhat", { enumerable: true, get: function () { return basics_2.getOriginalFromPercentage; } });
 Object.defineProperty(exports, "reverseNumber", { enumerable: true, get: function () { return basics_2.reverseNumber; } });
 Object.defineProperty(exports, "sumDigits", { enumerable: true, get: function () { return basics_2.sumDigits; } });
 Object.defineProperty(exports, "sumNumbers", { enumerable: true, get: function () { return basics_2.sumNumbers; } });
 Object.defineProperty(exports, "sumOfNumbers", { enumerable: true, get: function () { return basics_2.sumNumbers; } });
+var percent_1 = require("./number/percent");
+Object.defineProperty(exports, "calculatePercentage", { enumerable: true, get: function () { return percent_1.calculatePercentage; } });
 var fibonacci_1 = require("./number/fibonacci");
 Object.defineProperty(exports, "fibonacciGenerator", { enumerable: true, get: function () { return fibonacci_1.fibonacciGenerator; } });
 Object.defineProperty(exports, "generateFibonacci", { enumerable: true, get: function () { return fibonacci_1.fibonacciGenerator; } });
@@ -72,9 +66,11 @@ Object.defineProperty(exports, "getMemoizedFibonacci", { enumerable: true, get:
 Object.defineProperty(exports, "getMemoizedFibonacciSeries", { enumerable: true, get: function () { return fibonacci_1.getFibonacciSeriesMemo; } });
 Object.defineProperty(exports, "getNthFibonacci", { enumerable: true, get: function () { return fibonacci_1.getNthFibonacci; } });
 var guards_2 = require("./number/guards");
+Object.defineProperty(exports, "areInvalidNumbers", { enumerable: true, get: function () { return guards_2.areInvalidNumbers; } });
 Object.defineProperty(exports, "isEven", { enumerable: true, get: function () { return guards_2.isEven; } });
 Object.defineProperty(exports, "isEvenNumber", { enumerable: true, get: function () { return guards_2.isEven; } });
 Object.defineProperty(exports, "isFibonacci", { enumerable: true, get: function () { return guards_2.isFibonacci; } });
+Object.defineProperty(exports, "isInvalidNumbers", { enumerable: true, get: function () { return guards_2.areInvalidNumbers; } });
 Object.defineProperty(exports, "isMultiple", { enumerable: true, get: function () { return guards_2.isMultiple; } });
 Object.defineProperty(exports, "isOdd", { enumerable: true, get: function () { return guards_2.isOdd; } });
 Object.defineProperty(exports, "isOddNumber", { enumerable: true, get: function () { return guards_2.isOdd; } });

package/dist/cjs/number/basics.js

@@ -5,9 +5,6 @@ exports.sumDigits = sumDigits;
 exports.sumNumbers = sumNumbers;
 exports.reverseNumber = reverseNumber;
 exports.getAverage = getAverage;
-exports.getPercentage = getPercentage;
-exports.getValueFromPercentage = getValueFromPercentage;
-exports.getOriginalFromPercentage = getOriginalFromPercentage;
 const helpers_1 = require("./helpers");
 /**
  * * Utility to generate a random number between a given range.
@@ -137,69 +134,17 @@ function reverseNumber(num) {
  * * Calculates the average of a set of numbers.
  *
  * @param numbers - A list of numbers for which to calculate the average.
- * @returns The average of the provided numbers. Returns `NaN` if no numbers are provided or if any invalid values are encountered.
+ * @returns The average of the provided numbers. Returns `NaN` if no numbers are valid.
  */
 function getAverage(...numbers) {
-    const cNumbers = numbers.map(Number);
-    // Edge case: check if the input is an empty array or contains invalid values
-    if (cNumbers.length === 0) {
-        return NaN; // Return NaN if no numbers are provided
+    let sum = 0;
+    let count = 0;
+    for (const n of numbers) {
+        const num = Number(n);
+        if (typeof num === 'number' && !isNaN(num)) {
+            sum += num;
+            count++;
+        }
     }
-    // Validate each number in the array
-    const validNumbers = cNumbers.filter((num) => typeof num === 'number' && !isNaN(num));
-    // Edge case: check if the valid numbers array is empty after filtering
-    if (validNumbers.length === 0) {
-        return NaN; // Return NaN if no valid numbers are found
-    }
-    // Calculate the sum of the valid numbers
-    const sum = validNumbers.reduce((acc, curr) => acc + curr, 0);
-    // Return the average
-    return sum / validNumbers.length;
-}
-/**
- * * Calculates the percentage of a number based on a given part and total.
- *
- * @param part - The part of the total value.
- * @param total - The total value.
- * @returns The percentage of the part in relation to the total, rounded to two decimal places.
- *          Returns `NaN` if the total is zero or invalid.
- */
-function getPercentage(part, total) {
-    if (total === 0 || !Number.isFinite(total) || !Number.isFinite(part)) {
-        return NaN; // Prevent division by zero or invalid values
-    }
-    return (part / total) * 100;
-}
-/**
- * * Calculates the number that a given percentage corresponds to based on a total value.
- *
- * @param percentage - The percentage of the total value.
- * @param total - The total value.
- * @returns The number corresponding to the given percentage of the total, rounded to two decimal places.
- *          Returns `NaN` if the total is zero or invalid.
- */
-function getValueFromPercentage(percentage, total) {
-    if (total === 0 ||
-        !Number.isFinite(total) ||
-        !Number.isFinite(percentage)) {
-        return NaN; // Prevent division by zero or invalid values
-    }
-    return (percentage / 100) * total;
-}
-/**
- * * Calculates the original number based on the given percentage and the corresponding value.
- *
- * @param percentage - The percentage value (e.g., 10 for 10%).
- * @param percentageValue - The value corresponding to the given percentage.
- * @returns The original number from which the percentage value is derived, or `NaN` if invalid inputs are provided.
- */
-function getOriginalFromPercentage(percentage, percentageValue) {
-    if (percentage === 0 ||
-        percentageValue === 0 ||
-        !Number.isFinite(percentage) ||
-        !Number.isFinite(percentageValue)) {
-        return NaN; // Prevent division by zero or invalid values
-    }
-    const original = (percentageValue / percentage) * 100;
-    return Math.round(original * 100) / 100;
+    return count === 0 ? NaN : Math.round((sum / count) * 1000) / 1000;
 }

package/dist/cjs/number/guards.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isMultiple = exports.isOdd = exports.isEven = void 0;
 exports.isPerfectSquare = isPerfectSquare;
 exports.isFibonacci = isFibonacci;
+exports.areInvalidNumbers = areInvalidNumbers;
 /**
  * * Check if a number is even or not.
  *
@@ -52,3 +53,12 @@ function isPerfectSquare(num) {
 function isFibonacci(num) {
     return (isPerfectSquare(5 * num * num + 4) || isPerfectSquare(5 * num * num - 4));
 }
+/**
+ * * Checks whether any input is not a finite number.
+ *
+ * @param numbers - The list of numbers to validate.
+ * @returns `true` if any input is not finite.
+ */
+function areInvalidNumbers(...numbers) {
+    return numbers.some((n) => !Number.isFinite(n));
+}

package/dist/cjs/number/percent.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculatePercentage = calculatePercentage;
+const basics_1 = require("./basics");
+const guards_1 = require("./guards");
+/**
+ * * Performs a percentage-related calculation based on the given mode and inputs.
+ *
+ * - `get-percent`: Calculates what percentage the `part` is of the `total`.
+ * - `get-value`: Calculates the value from a given `percentage` of a `total`.
+ * - `get-original`: Calculates the original value from a known `value` and `percentage`.
+ * - `get-change-percent`: Percent increase/decrease from `oldValue` to `newValue`.
+ * - `apply-percent-change`: Applies increase/decrease by `percentage` to `baseValue`.
+ * - `get-percent-difference`: Absolute percent difference between two values.
+ * - `inverse-percent`: What percent `total` is of `part`.
+ *
+ * @param options - The calculation mode and inputs required for the operation.
+ * @returns The calculated number rounded to three decimal places, or `NaN` if input is invalid.
+ */
+function calculatePercentage(options) {
+    switch (options?.mode) {
+        case 'get-percent': {
+            const { part, total } = options;
+            if ((0, guards_1.areInvalidNumbers)(part, total) || total === 0) {
+                return NaN;
+            }
+            return Math.round((part / total) * 100 * 1000) / 1000;
+        }
+        case 'get-value': {
+            const { percentage, total } = options;
+            if ((0, guards_1.areInvalidNumbers)(percentage, total) || total === 0) {
+                return NaN;
+            }
+            return Math.round((percentage / 100) * total * 1000) / 1000;
+        }
+        case 'get-original': {
+            const { percentage, value } = options;
+            if ((0, guards_1.areInvalidNumbers)(percentage, value) || percentage === 0) {
+                return NaN;
+            }
+            return Math.round((value / percentage) * 100 * 1000) / 1000;
+        }
+        case 'get-change-percent': {
+            const { oldValue, newValue } = options;
+            if ((0, guards_1.areInvalidNumbers)(oldValue, newValue) || oldValue === 0) {
+                return NaN;
+            }
+            const change = ((newValue - oldValue) / oldValue) * 100;
+            return Math.round(change * 1000) / 1000;
+        }
+        case 'apply-percent-change': {
+            const { baseValue, percentage } = options;
+            if ((0, guards_1.areInvalidNumbers)(baseValue, percentage)) {
+                return NaN;
+            }
+            const value = baseValue * (1 + percentage / 100);
+            return Math.round(value * 1000) / 1000;
+        }
+        case 'get-percent-difference': {
+            const { value1, value2 } = options;
+            if ((0, guards_1.areInvalidNumbers)(value1, value2)) {
+                return NaN;
+            }
+            const avg = (0, basics_1.getAverage)(value1, value2);
+            if (avg === 0) {
+                return NaN;
+            }
+            const diff = (Math.abs(value1 - value2) / avg) * 100;
+            return Math.round(diff * 1000) / 1000;
+        }
+        case 'inverse-percent': {
+            const { part, total } = options;
+            if ((0, guards_1.areInvalidNumbers)(part, total) || part === 0) {
+                return NaN;
+            }
+            return Math.round((total / part) * 100 * 1000) / 1000;
+        }
+        default:
+            return NaN;
+    }
+}

package/dist/dts/index.d.ts

@@ -3,9 +3,10 @@ export { generateAnagrams } from './string/anagram';
 export { isCamelCase, isEmojiOnly, isKebabCase, isPalindrome, isPascalCase, isSnakeCase, } from './string/guards';
 export { convertStringCase, extractEmails, extractURLs, formatUnitWithPlural as formatNumberWithPluralUnit, formatUnitWithPlural, formatUnitWithPlural as formatWithPlural, maskString, normalizeString, replaceAllInString, reverseString, slugifyString, } from './string/convert';
 export { extractNumbersFromString, getLevenshteinDistance, getLevenshteinDistance as levenshteinDistance, } from './string/utilities';
-export { getAverage as calculateAverage, calculateHCF as calculateGCD, calculateHCF, calculateLCM as calculateLCD, calculateLCM, getOriginalFromPercentage as calculateOriginalFromPercentage, getPercentage as calculatePercentage, convertToDecimal, getAverage, getAverage as getAverageOfNumbers, getOriginalFromPercentage as getOriginalNumberFromPercentage, getPercentage, getOriginalFromPercentage as getPercentageOfWhat, getValueFromPercentage as getPercentageResult, getRandomNumber, sumNumbers as getSumOfNumbers, getValueFromPercentage, getOriginalFromPercentage as percentageOfWhat, reverseNumber, sumDigits, sumNumbers, sumNumbers as sumOfNumbers, } from './number/basics';
+export { getAverage as calculateAverage, calculateHCF as calculateGCD, calculateHCF, calculateLCM as calculateLCD, calculateLCM, convertToDecimal, getAverage, getAverage as getAverageOfNumbers, getRandomNumber, sumNumbers as getSumOfNumbers, reverseNumber, sumDigits, sumNumbers, sumNumbers as sumOfNumbers, } from './number/basics';
+export { calculatePercentage } from './number/percent';
 export { fibonacciGenerator, fibonacciGenerator as generateFibonacci, getFibonacciSeries as getFibonacci, getFibonacciSeries as getFibonacciNumbers, getFibonacciSeries, getFibonacciSeriesMemo, getFibonacciSeriesMemo as getMemoizedFibonacci, getFibonacciSeriesMemo as getMemoizedFibonacciSeries, getNthFibonacci, } from './number/fibonacci';
-export { isEven, isEven as isEvenNumber, isFibonacci, isMultiple, isOdd, isOdd as isOddNumber, isFibonacci as isParOfFibonacci, isFibonacci as isParOfFibonacciSeries, isPerfectSquare, } from './number/guards';
+export { areInvalidNumbers, isEven, isEven as isEvenNumber, isFibonacci, areInvalidNumbers as isInvalidNumbers, isMultiple, isOdd, isOdd as isOddNumber, isFibonacci as isParOfFibonacci, isFibonacci as isParOfFibonacciSeries, isPerfectSquare, } from './number/guards';
 export { numberToWords as convertNumberToWords, convertToRomanNumerals, numberToWords, } from './number/convert';
 export { findPrimeNumbers, findPrimeNumbers as getPrimeNumbers, isPrime, isPrime as isPrimeNumber, } from './number/prime';
 export { getOrdinal as cardinalToOrdinal, clampNumber, formatCurrency as convertNumberToCurrency, getOrdinal as convertNumberToOrdinal, getOrdinal as convertToOrdinal, formatCurrency, getOrdinal, getOrdinal as getOrdinalNumber, getRandomFloat as getRandomDecimal, getRandomFloat, getOrdinal as numberToOrdinal, roundToNearest as roundNumber, roundToNearest as roundNumberToNearestInterval, roundToNearest, roundToNearest as roundToNearestInterval, } from './number/utilities';

package/dist/dts/index.d.ts.map

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

package/dist/dts/number/basics.d.ts

@@ -56,33 +56,7 @@ export declare function reverseNumber(num: Numeric): number;
  * * Calculates the average of a set of numbers.
  *
  * @param numbers - A list of numbers for which to calculate the average.
- * @returns The average of the provided numbers. Returns `NaN` if no numbers are provided or if any invalid values are encountered.
+ * @returns The average of the provided numbers. Returns `NaN` if no numbers are valid.
  */
 export declare function getAverage(...numbers: Numeric[]): number;
-/**
- * * Calculates the percentage of a number based on a given part and total.
- *
- * @param part - The part of the total value.
- * @param total - The total value.
- * @returns The percentage of the part in relation to the total, rounded to two decimal places.
- *          Returns `NaN` if the total is zero or invalid.
- */
-export declare function getPercentage(part: number, total: number): number;
-/**
- * * Calculates the number that a given percentage corresponds to based on a total value.
- *
- * @param percentage - The percentage of the total value.
- * @param total - The total value.
- * @returns The number corresponding to the given percentage of the total, rounded to two decimal places.
- *          Returns `NaN` if the total is zero or invalid.
- */
-export declare function getValueFromPercentage(percentage: number, total: number): number;
-/**
- * * Calculates the original number based on the given percentage and the corresponding value.
- *
- * @param percentage - The percentage value (e.g., 10 for 10%).
- * @param percentageValue - The value corresponding to the given percentage.
- * @returns The original number from which the percentage value is derived, or `NaN` if invalid inputs are provided.
- */
-export declare function getOriginalFromPercentage(percentage: number, percentageValue: number): number;
 //# sourceMappingURL=basics.d.ts.map

package/dist/dts/number/basics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"basics.d.ts","sourceRoot":"","sources":["../../../src/number/basics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,KAAK,EACX,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,MAAM,SAAS,CAAC;AAEjB;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,aAAc,mBAAmB,KAAG,MA+C/D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,OAAO,GAAG,SAAS,iBACtD,OAAO,YACJ,cAAc,CAAC,CAAC,CAAC,KACzB,gBAAgB,CAAC,CAAC,CAQpB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,eAAgB,OAAO,EAAE,KAAG,MAYpD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,eAAgB,OAAO,EAAE,KAAG,MAYpD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAK9C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAIxD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAOlD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAsBxD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACrC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACX,MAAM,CASR;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACxC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,GACrB,MAAM,CAYR"}
+{"version":3,"file":"basics.d.ts","sourceRoot":"","sources":["../../../src/number/basics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,KAAK,EACX,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,MAAM,SAAS,CAAC;AAEjB;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,aAAc,mBAAmB,KAAG,MA+C/D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,OAAO,GAAG,SAAS,iBACtD,OAAO,YACJ,cAAc,CAAC,CAAC,CAAC,KACzB,gBAAgB,CAAC,CAAC,CAQpB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,eAAgB,OAAO,EAAE,KAAG,MAYpD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,eAAgB,OAAO,EAAE,KAAG,MAYpD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAK9C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAIxD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAOlD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,CAaxD"}

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

@@ -34,4 +34,11 @@ export declare function isPerfectSquare(num: number): boolean;
  * @returns `true` if the number is a Fibonacci number, otherwise `false`.
  */
 export declare function isFibonacci(num: number): boolean;
+/**
+ * * Checks whether any input is not a finite number.
+ *
+ * @param numbers - The list of numbers to validate.
+ * @returns `true` if any input is not finite.
+ */
+export declare function areInvalidNumbers(...numbers: number[]): boolean;
 //# sourceMappingURL=guards.d.ts.map

package/dist/dts/number/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../src/number/guards.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,MAAM,UAAW,MAAM,KAAG,OAEtC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,UAAW,MAAM,KAAG,OAErC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,UAAW,MAAM,cAAc,MAAM,KAAG,OAE9D,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAIhD"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../src/number/guards.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,MAAM,UAAW,MAAM,KAAG,OAEtC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,UAAW,MAAM,KAAG,OAErC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,UAAW,MAAM,cAAc,MAAM,KAAG,OAE9D,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAIhD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAE/D"}

package/dist/dts/number/percent.d.ts

@@ -0,0 +1,17 @@
+import type { PercentageOptions } from './types';
+/**
+ * * Performs a percentage-related calculation based on the given mode and inputs.
+ *
+ * - `get-percent`: Calculates what percentage the `part` is of the `total`.
+ * - `get-value`: Calculates the value from a given `percentage` of a `total`.
+ * - `get-original`: Calculates the original value from a known `value` and `percentage`.
+ * - `get-change-percent`: Percent increase/decrease from `oldValue` to `newValue`.
+ * - `apply-percent-change`: Applies increase/decrease by `percentage` to `baseValue`.
+ * - `get-percent-difference`: Absolute percent difference between two values.
+ * - `inverse-percent`: What percent `total` is of `part`.
+ *
+ * @param options - The calculation mode and inputs required for the operation.
+ * @returns The calculated number rounded to three decimal places, or `NaN` if input is invalid.
+ */
+export declare function calculatePercentage(options: PercentageOptions): number;
+//# sourceMappingURL=percent.d.ts.map

package/dist/dts/number/percent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"percent.d.ts","sourceRoot":"","sources":["../../../src/number/percent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAuFtE"}

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

@@ -38,4 +38,69 @@ export type RangedNumbers<T extends GetAs> = T extends 'array' ? number[] : stri
 export type CurrencyCode = keyof typeof CURRENCY_LOCALES | (typeof CURRENCY_CODES)[number];
 /** - List of all supported BCP 47 locales */
 export type LocaleCode = (typeof CURRENCY_LOCALES)[keyof typeof CURRENCY_LOCALES] | (typeof LOCALE_CODES)[number];
+/** * Options to calculate what percentage a `part` is of a `total`. */
+export interface GetPercentOptions {
+    /** Mode to calculate percentage from `part` and `total` */
+    mode: 'get-percent';
+    /** The part value (e.g., 25 out of 100) */
+    part: number;
+    /** The total value representing 100% */
+    total: number;
+}
+/** * Options to calculate a value from a `percentage` of a `total`. */
+export interface GetValueOptions {
+    /** Mode to calculate value from `percentage` and `total` */
+    mode: 'get-value';
+    /** The percentage (e.g., 25%) */
+    percentage: number;
+    /** The total value representing 100% */
+    total: number;
+}
+/** * Options to calculate the original total from a known `value` and `percentage`. */
+export interface GetOriginalOptions {
+    /** Mode to calculate original total from `value` and `percentage` */
+    mode: 'get-original';
+    /** The percentage the `value` represents */
+    percentage: number;
+    /** The known value that is a percentage of the original total */
+    value: number;
+}
+/** * Calculates the percentage change from `oldValue` to `newValue`. */
+export interface GetChangeOptions {
+    /** Mode to calculate percentage change from `oldValue` to `newValue` */
+    mode: 'get-change-percent';
+    /** The original value before the change */
+    oldValue: number;
+    /** The new value after the change */
+    newValue: number;
+}
+/** * Applies a percentage increase or decrease to a `baseValue`. */
+export interface ApplyChangeOptions {
+    /** Mode to apply percentage change to `baseValue` */
+    mode: 'apply-percent-change';
+    /** The base value to apply the percentage change to */
+    baseValue: number;
+    /** The percentage change to apply (positive or negative) */
+    percentage: number;
+}
+/** * Calculates the absolute percentage difference between two values. */
+export interface GetDifferenceOptions {
+    /** Mode to calculate percentage difference between `value1` and `value2` */
+    mode: 'get-percent-difference';
+    /** The first value to compare */
+    value1: number;
+    /** The second value to compare */
+    value2: number;
+}
+/** * Calculates the inverse percentage: what percent `total` is of `part`. */
+export interface InversePercentageOptions {
+    /** Mode to calculate inverse percentage from `part` and `total` */
+    mode: 'inverse-percent';
+    /** The part value to calculate inverse percentage from */
+    part: number;
+    /** The total value to calculate inverse percentage of */
+    total: number;
+}
+/** * Options for calculating percentages and related values. */
+export type PercentageOptions = GetPercentOptions | GetValueOptions | GetOriginalOptions | GetChangeOptions | ApplyChangeOptions | GetDifferenceOptions | InversePercentageOptions;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/number/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,MAAM,aAAa,CAAC;AAErB,4CAA4C;AAC5C,MAAM,WAAW,mBAAmB;IACnC,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,OAAO,GAAG,SAAS,GAAG,KAAK;IACpE,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,CAAC;CACb;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,IAAI,GAAG,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC;AAExE,oCAAoC;AACpC,MAAM,MAAM,UAAU,GACnB,KAAK,GACL,SAAS,GACT,KAAK,GACL,MAAM,GACN,OAAO,GACP,QAAQ,CAAC;AAEZ,gDAAgD;AAChD,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEvC,kDAAkD;AAClD,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,KAAK,CAAE,SAAQ,mBAAmB;IACzE,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,KAAK,CAAC,EAAE,CAAC,CAAC;CACV;AAED,4DAA4D;AAC5D,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,KAAK,IACxC,CAAC,SAAS,OAAO,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC;AAEvC,uCAAuC;AACvC,MAAM,MAAM,YAAY,GACrB,MAAM,OAAO,gBAAgB,GAC7B,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnC,6CAA6C;AAC7C,MAAM,MAAM,UAAU,GACnB,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,GACxD,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/number/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -5,9 +5,10 @@ export { isCamelCase, isEmojiOnly, isKebabCase, isPalindrome, isPascalCase, isSn
 export { convertStringCase, extractEmails, extractURLs, formatUnitWithPlural as formatNumberWithPluralUnit, formatUnitWithPlural, formatUnitWithPlural as formatWithPlural, maskString, normalizeString, replaceAllInString, reverseString, slugifyString, } from './string/convert';
 export { extractNumbersFromString, getLevenshteinDistance, getLevenshteinDistance as levenshteinDistance, } from './string/utilities';
 // ! Number Utilities
-export { getAverage as calculateAverage, calculateHCF as calculateGCD, calculateHCF, calculateLCM as calculateLCD, calculateLCM, getOriginalFromPercentage as calculateOriginalFromPercentage, getPercentage as calculatePercentage, convertToDecimal, getAverage, getAverage as getAverageOfNumbers, getOriginalFromPercentage as getOriginalNumberFromPercentage, getPercentage, getOriginalFromPercentage as getPercentageOfWhat, getValueFromPercentage as getPercentageResult, getRandomNumber, sumNumbers as getSumOfNumbers, getValueFromPercentage, getOriginalFromPercentage as percentageOfWhat, reverseNumber, sumDigits, sumNumbers, sumNumbers as sumOfNumbers, } from './number/basics';
+export { getAverage as calculateAverage, calculateHCF as calculateGCD, calculateHCF, calculateLCM as calculateLCD, calculateLCM, convertToDecimal, getAverage, getAverage as getAverageOfNumbers, getRandomNumber, sumNumbers as getSumOfNumbers, reverseNumber, sumDigits, sumNumbers, sumNumbers as sumOfNumbers, } from './number/basics';
+export { calculatePercentage } from './number/percent';
 export { fibonacciGenerator, fibonacciGenerator as generateFibonacci, getFibonacciSeries as getFibonacci, getFibonacciSeries as getFibonacciNumbers, getFibonacciSeries, getFibonacciSeriesMemo, getFibonacciSeriesMemo as getMemoizedFibonacci, getFibonacciSeriesMemo as getMemoizedFibonacciSeries, getNthFibonacci, } from './number/fibonacci';
-export { isEven, isEven as isEvenNumber, isFibonacci, isMultiple, isOdd, isOdd as isOddNumber, isFibonacci as isParOfFibonacci, isFibonacci as isParOfFibonacciSeries, isPerfectSquare, } from './number/guards';
+export { areInvalidNumbers, isEven, isEven as isEvenNumber, isFibonacci, areInvalidNumbers as isInvalidNumbers, isMultiple, isOdd, isOdd as isOddNumber, isFibonacci as isParOfFibonacci, isFibonacci as isParOfFibonacciSeries, isPerfectSquare, } from './number/guards';
 export { numberToWords as convertNumberToWords, convertToRomanNumerals, numberToWords, } from './number/convert';
 export { findPrimeNumbers, findPrimeNumbers as getPrimeNumbers, isPrime, isPrime as isPrimeNumber, } from './number/prime';
 export { getOrdinal as cardinalToOrdinal, clampNumber, formatCurrency as convertNumberToCurrency, getOrdinal as convertNumberToOrdinal, getOrdinal as convertToOrdinal, formatCurrency, getOrdinal, getOrdinal as getOrdinalNumber, getRandomFloat as getRandomDecimal, getRandomFloat, getOrdinal as numberToOrdinal, roundToNearest as roundNumber, roundToNearest as roundNumberToNearestInterval, roundToNearest, roundToNearest as roundToNearestInterval, } from './number/utilities';

package/dist/esm/number/basics.js

@@ -123,69 +123,17 @@ export function reverseNumber(num) {
  * * Calculates the average of a set of numbers.
  *
  * @param numbers - A list of numbers for which to calculate the average.
- * @returns The average of the provided numbers. Returns `NaN` if no numbers are provided or if any invalid values are encountered.
+ * @returns The average of the provided numbers. Returns `NaN` if no numbers are valid.
  */
 export function getAverage(...numbers) {
-    const cNumbers = numbers.map(Number);
-    // Edge case: check if the input is an empty array or contains invalid values
-    if (cNumbers.length === 0) {
-        return NaN; // Return NaN if no numbers are provided
+    let sum = 0;
+    let count = 0;
+    for (const n of numbers) {
+        const num = Number(n);
+        if (typeof num === 'number' && !isNaN(num)) {
+            sum += num;
+            count++;
+        }
     }
-    // Validate each number in the array
-    const validNumbers = cNumbers.filter((num) => typeof num === 'number' && !isNaN(num));
-    // Edge case: check if the valid numbers array is empty after filtering
-    if (validNumbers.length === 0) {
-        return NaN; // Return NaN if no valid numbers are found
-    }
-    // Calculate the sum of the valid numbers
-    const sum = validNumbers.reduce((acc, curr) => acc + curr, 0);
-    // Return the average
-    return sum / validNumbers.length;
-}
-/**
- * * Calculates the percentage of a number based on a given part and total.
- *
- * @param part - The part of the total value.
- * @param total - The total value.
- * @returns The percentage of the part in relation to the total, rounded to two decimal places.
- *          Returns `NaN` if the total is zero or invalid.
- */
-export function getPercentage(part, total) {
-    if (total === 0 || !Number.isFinite(total) || !Number.isFinite(part)) {
-        return NaN; // Prevent division by zero or invalid values
-    }
-    return (part / total) * 100;
-}
-/**
- * * Calculates the number that a given percentage corresponds to based on a total value.
- *
- * @param percentage - The percentage of the total value.
- * @param total - The total value.
- * @returns The number corresponding to the given percentage of the total, rounded to two decimal places.
- *          Returns `NaN` if the total is zero or invalid.
- */
-export function getValueFromPercentage(percentage, total) {
-    if (total === 0 ||
-        !Number.isFinite(total) ||
-        !Number.isFinite(percentage)) {
-        return NaN; // Prevent division by zero or invalid values
-    }
-    return (percentage / 100) * total;
-}
-/**
- * * Calculates the original number based on the given percentage and the corresponding value.
- *
- * @param percentage - The percentage value (e.g., 10 for 10%).
- * @param percentageValue - The value corresponding to the given percentage.
- * @returns The original number from which the percentage value is derived, or `NaN` if invalid inputs are provided.
- */
-export function getOriginalFromPercentage(percentage, percentageValue) {
-    if (percentage === 0 ||
-        percentageValue === 0 ||
-        !Number.isFinite(percentage) ||
-        !Number.isFinite(percentageValue)) {
-        return NaN; // Prevent division by zero or invalid values
-    }
-    const original = (percentageValue / percentage) * 100;
-    return Math.round(original * 100) / 100;
+    return count === 0 ? NaN : Math.round((sum / count) * 1000) / 1000;
 }

package/dist/esm/number/guards.js

@@ -44,3 +44,12 @@ export function isPerfectSquare(num) {
 export function isFibonacci(num) {
     return (isPerfectSquare(5 * num * num + 4) || isPerfectSquare(5 * num * num - 4));
 }
+/**
+ * * Checks whether any input is not a finite number.
+ *
+ * @param numbers - The list of numbers to validate.
+ * @returns `true` if any input is not finite.
+ */
+export function areInvalidNumbers(...numbers) {
+    return numbers.some((n) => !Number.isFinite(n));
+}

package/dist/esm/number/percent.js

@@ -0,0 +1,78 @@
+import { getAverage } from './basics';
+import { areInvalidNumbers } from './guards';
+/**
+ * * Performs a percentage-related calculation based on the given mode and inputs.
+ *
+ * - `get-percent`: Calculates what percentage the `part` is of the `total`.
+ * - `get-value`: Calculates the value from a given `percentage` of a `total`.
+ * - `get-original`: Calculates the original value from a known `value` and `percentage`.
+ * - `get-change-percent`: Percent increase/decrease from `oldValue` to `newValue`.
+ * - `apply-percent-change`: Applies increase/decrease by `percentage` to `baseValue`.
+ * - `get-percent-difference`: Absolute percent difference between two values.
+ * - `inverse-percent`: What percent `total` is of `part`.
+ *
+ * @param options - The calculation mode and inputs required for the operation.
+ * @returns The calculated number rounded to three decimal places, or `NaN` if input is invalid.
+ */
+export function calculatePercentage(options) {
+    switch (options?.mode) {
+        case 'get-percent': {
+            const { part, total } = options;
+            if (areInvalidNumbers(part, total) || total === 0) {
+                return NaN;
+            }
+            return Math.round((part / total) * 100 * 1000) / 1000;
+        }
+        case 'get-value': {
+            const { percentage, total } = options;
+            if (areInvalidNumbers(percentage, total) || total === 0) {
+                return NaN;
+            }
+            return Math.round((percentage / 100) * total * 1000) / 1000;
+        }
+        case 'get-original': {
+            const { percentage, value } = options;
+            if (areInvalidNumbers(percentage, value) || percentage === 0) {
+                return NaN;
+            }
+            return Math.round((value / percentage) * 100 * 1000) / 1000;
+        }
+        case 'get-change-percent': {
+            const { oldValue, newValue } = options;
+            if (areInvalidNumbers(oldValue, newValue) || oldValue === 0) {
+                return NaN;
+            }
+            const change = ((newValue - oldValue) / oldValue) * 100;
+            return Math.round(change * 1000) / 1000;
+        }
+        case 'apply-percent-change': {
+            const { baseValue, percentage } = options;
+            if (areInvalidNumbers(baseValue, percentage)) {
+                return NaN;
+            }
+            const value = baseValue * (1 + percentage / 100);
+            return Math.round(value * 1000) / 1000;
+        }
+        case 'get-percent-difference': {
+            const { value1, value2 } = options;
+            if (areInvalidNumbers(value1, value2)) {
+                return NaN;
+            }
+            const avg = getAverage(value1, value2);
+            if (avg === 0) {
+                return NaN;
+            }
+            const diff = (Math.abs(value1 - value2) / avg) * 100;
+            return Math.round(diff * 1000) / 1000;
+        }
+        case 'inverse-percent': {
+            const { part, total } = options;
+            if (areInvalidNumbers(part, total) || part === 0) {
+                return NaN;
+            }
+            return Math.round((total / part) * 100 * 1000) / 1000;
+        }
+        default:
+            return NaN;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.0.30",
+  "version": "4.0.32",
   "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",