math-utils-simple 2.0.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # math-utils-simple
 
-A simple math utility library for JavaScript.
+A lightweight JavaScript math utility library built to scale for advanced use cases in the future.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "math-utils-simple",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "A simple math utility library for npm",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -54,4 +54,34 @@ export { default as roundToNearest } from "./rounding/roundToNearest.js";
 export { default as snap } from "./rounding/snap.js";
 export { default as isBetween } from "./rounding/isBetween.js";
 export { default as wrap } from "./rounding/wrap.js";
-export { default as normalize } from "./rounding/normalize.js";
+export { default as normalize } from "./rounding/normalize.js";
+
+// PERCENTAGES
+export { default as percentage } from "./percentages/percentage.js";
+export { default as increaseByPercentage } from "./percentages/increaseByPercentage.js";
+export { default as decreaseByPercentage } from "./percentages/decreaseByPercentage.js";
+export { default as percentageDifference } from "./percentages/percentageDifference.js";
+export { default as percentageChange } from "./percentages/percentageChange.js";
+export { default as findOriginalValue } from "./percentages/findOriginalValue.js";
+export { default as findFinalValue } from "./percentages/findFinalValue.js";
+export { default as discount } from "./percentages/discount.js";
+export { default as markup } from "./percentages/markup.js";
+export { default as profitPercentage } from "./percentages/profitPercentage.js";
+export { default as lossPercentage } from "./percentages/lossPercentage.js";
+export { default as margin } from "./percentages/margin.js";
+export { default as relativeChange } from "./percentages/relativeChange.js";
+
+// STATISTICS
+export { default as sum } from "./statistics/sum.js";
+export { default as average } from "./statistics/average.js";
+export { default as median } from "./statistics/median.js";
+export { default as mode } from "./statistics/mode.js";
+export { default as range } from "./statistics/range.js";
+export { default as variance } from "./statistics/variance.js";
+export { default as standardDeviation } from "./statistics/standardDeviation.js";
+export { default as max } from "./statistics/max.js";
+export { default as min } from "./statistics/min.js";
+export { default as count } from "./statistics/count.js";
+export { default as frequency } from "./statistics/frequency.js";
+export { default as quartiles } from "./statistics/quartiles.js";
+export { default as interQuartileRange } from "./statistics/interQuartileRange.js";

package/src/percentages/decreaseByPercentage.js

@@ -0,0 +1,3 @@
+export default function decreaseByPercentage(value, percent) {
+  return value * (1 - percent / 100);
+}

package/src/percentages/discount.js

@@ -0,0 +1,3 @@
+export default function discount(price, percent) {
+  return price * (1 - percent / 100);
+}

package/src/percentages/findFinalValue.js

@@ -0,0 +1,3 @@
+export default function findFinalValue(original, percent) {
+  return original * (1 + percent / 100);
+}

package/src/percentages/findOriginalValue.js

@@ -0,0 +1,7 @@
+export default function findOriginalValue(finalValue, percentIncrease) {
+  if (percentIncrease === -100) {
+    throw new Error("Percent increase cannot be -100.");
+  }
+
+  return finalValue / (1 + percentIncrease / 100);
+}

package/src/percentages/increaseByPercentage.js

@@ -0,0 +1,3 @@
+export default function increaseByPercentage(value, percent) {
+  return value * (1 + percent / 100);
+}

package/src/percentages/lossPercentage.js

@@ -0,0 +1,11 @@
+export default function lossPercentage(cost, sellingPrice) {
+  if (cost === 0) {
+    throw new Error("Cost cannot be zero.");
+  }
+
+  if (sellingPrice >= cost) {
+    return 0;
+  }
+
+  return ((cost - sellingPrice) / cost) * 100;
+}

package/src/percentages/margin.js

@@ -0,0 +1,7 @@
+export default function margin(cost, sellingPrice) {
+  if (sellingPrice === 0) {
+    throw new Error("Selling price cannot be zero.");
+  }
+
+  return ((sellingPrice - cost) / sellingPrice) * 100;
+}

package/src/percentages/markup.js

@@ -0,0 +1,3 @@
+export default function markup(cost, percent) {
+  return cost * (1 + percent / 100);
+}

package/src/percentages/percentage.js

@@ -0,0 +1,7 @@
+export default function percentage(value, total) {
+  if (total === 0) {
+    throw new Error("Total cannot be zero.");
+  }
+
+  return (value / total) * 100;
+}

package/src/percentages/percentageChange.js

@@ -0,0 +1,7 @@
+export default function percentageChange(oldValue, newValue) {
+  if (oldValue === 0) {
+    throw new Error("Old value cannot be zero.");
+  }
+
+  return ((newValue - oldValue) / oldValue) * 100;
+}

package/src/percentages/percentageDifference.js

@@ -0,0 +1,10 @@
+export default function percentageDifference(a, b) {
+  if (a === 0 && b === 0) {
+    return 0;
+  }
+
+  return (
+    (Math.abs(a - b) / ((Math.abs(a) + Math.abs(b)) / 2)) *
+    100
+  );
+}

package/src/percentages/profitPercentage.js

@@ -0,0 +1,7 @@
+export default function profitPercentage(cost, sellingPrice) {
+  if (cost === 0) {
+    throw new Error("Cost cannot be zero.");
+  }
+
+  return ((sellingPrice - cost) / cost) * 100;
+}

package/src/percentages/relativeChange.js

@@ -0,0 +1,7 @@
+export default function relativeChange(a, b) {
+  if (b === 0) {
+    throw new Error("Reference value cannot be zero.");
+  }
+
+  return ((a - b) / b) * 100;
+}

package/src/statistics/average.js

@@ -0,0 +1,13 @@
+import sum from "./sum.js";
+
+export default function average(array) {
+  if (!Array.isArray(array)) {
+    throw new TypeError("Expected an array.");
+  }
+
+  if (array.length === 0) {
+    throw new Error("Cannot calculate average of an empty array.");
+  }
+
+  return sum(array) / array.length;
+}

package/src/statistics/count.js

@@ -0,0 +1,7 @@
+export default function count(array) {
+  if (!Array.isArray(array)) {
+    throw new TypeError("Expected an array.");
+  }
+
+  return array.length;
+}

package/src/statistics/frequency.js

@@ -0,0 +1,13 @@
+export default function frequency(array) {
+  if (!Array.isArray(array)) {
+    throw new TypeError("Expected an array.");
+  }
+
+  const result = {};
+
+  for (const value of array) {
+    result[value] = (result[value] || 0) + 1;
+  }
+
+  return result;
+}

package/src/statistics/interQuartileRange.js

@@ -0,0 +1,7 @@
+import quartiles from "./quartiles.js";
+
+export default function interQuartileRange(array) {
+  const { q1, q3 } = quartiles(array);
+
+  return q3 - q1;
+}

package/src/statistics/max.js

@@ -0,0 +1,19 @@
+export default function max(array) {
+  if (!Array.isArray(array)) {
+    throw new TypeError("Expected an array.");
+  }
+
+  if (array.length === 0) {
+    throw new Error("Cannot find maximum of an empty array.");
+  }
+
+  let largest = array[0];
+
+  for (const value of array) {
+    if (value > largest) {
+      largest = value;
+    }
+  }
+
+  return largest;
+}

package/src/statistics/median.js

@@ -0,0 +1,18 @@
+export default function median(array) {
+  if (!Array.isArray(array)) {
+    throw new TypeError("Expected an array.");
+  }
+
+  if (array.length === 0) {
+    throw new Error("Cannot calculate median of an empty array.");
+  }
+
+  const sorted = [...array].sort((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+
+  if (sorted.length % 2 === 0) {
+    return (sorted[middle - 1] + sorted[middle]) / 2;
+  }
+
+  return sorted[middle];
+}

package/src/statistics/min.js

@@ -0,0 +1,19 @@
+export default function min(array) {
+  if (!Array.isArray(array)) {
+    throw new TypeError("Expected an array.");
+  }
+
+  if (array.length === 0) {
+    throw new Error("Cannot find minimum of an empty array.");
+  }
+
+  let smallest = array[0];
+
+  for (const value of array) {
+    if (value < smallest) {
+      smallest = value;
+    }
+  }
+
+  return smallest;
+}

package/src/statistics/mode.js

@@ -0,0 +1,38 @@
+export default function mode(array) {
+  if (!Array.isArray(array)) {
+    throw new TypeError("Expected an array.");
+  }
+
+  if (array.length === 0) {
+    throw new Error("Cannot calculate mode of an empty array.");
+  }
+
+  const counts = new Map();
+
+  for (const value of array) {
+    counts.set(value, (counts.get(value) || 0) + 1);
+  }
+
+  let maxFrequency = 0;
+
+  for (const frequency of counts.values()) {
+    if (frequency > maxFrequency) {
+      maxFrequency = frequency;
+    }
+  }
+
+  // No mode if every value occurs equally often.
+  if (maxFrequency === 1) {
+    return [];
+  }
+
+  const modes = [];
+
+  for (const [value, frequency] of counts) {
+    if (frequency === maxFrequency) {
+      modes.push(value);
+    }
+  }
+
+  return modes.sort((a, b) => a - b);
+}

package/src/statistics/quartiles.js

@@ -0,0 +1,37 @@
+import median from "./median.js";
+
+export default function quartiles(array) {
+  if (!Array.isArray(array)) {
+    throw new TypeError("Expected an array.");
+  }
+
+  if (array.length === 0) {
+    throw new Error("Cannot calculate quartiles of an empty array.");
+  }
+
+  const sorted = [...array].sort((a, b) => a - b);
+
+  const q2 = median(sorted);
+
+  const middle = Math.floor(sorted.length / 2);
+
+  let lowerHalf;
+  let upperHalf;
+
+  if (sorted.length % 2 === 0) {
+    lowerHalf = sorted.slice(0, middle);
+    upperHalf = sorted.slice(middle);
+  } else {
+    lowerHalf = sorted.slice(0, middle);
+    upperHalf = sorted.slice(middle + 1);
+  }
+
+  const q1 = median(lowerHalf);
+  const q3 = median(upperHalf);
+
+  return {
+    q1,
+    q2,
+    q3,
+  };
+}

package/src/statistics/range.js

@@ -0,0 +1,6 @@
+import min from "./min.js";
+import max from "./max.js";
+
+export default function range(array) {
+  return max(array) - min(array);
+}

package/src/statistics/standardDeviation.js

@@ -0,0 +1,5 @@
+import variance from "./variance.js";
+
+export default function standardDeviation(array) {
+  return Math.sqrt(variance(array));
+}

package/src/statistics/sum.js

@@ -0,0 +1,7 @@
+export default function sum(array) {
+  if (!Array.isArray(array)) {
+    throw new TypeError("Expected an array.");
+  }
+
+  return array.reduce((total, value) => total + value, 0);
+}

package/src/statistics/variance.js

@@ -0,0 +1,21 @@
+import average from "./average.js";
+
+export default function variance(array) {
+  if (!Array.isArray(array)) {
+    throw new TypeError("Expected an array.");
+  }
+
+  if (array.length === 0) {
+    throw new Error("Cannot calculate variance of an empty array.");
+  }
+
+  const mean = average(array);
+
+  let sum = 0;
+
+  for (const value of array) {
+    sum += (value - mean) ** 2;
+  }
+
+  return sum / array.length;
+}