@salespark/toolkit 2.1.5 → 2.1.7

package/README.md

@@ -27,7 +27,7 @@ npm i @salespark/toolkit
 - **Array utilities**: chunk, uniqBy, deep equality, flatten, groupBy, etc.
 - **Object utilities**: pick, omit, clean objects, deep merge, etc.
 - **String utilities**: slugify, template fill, deburr, sanitize, etc.
-- **Number utilities**: clamp, round, safe parse, random digits, etc.
+- **Number utilities**: clamp, round, safe arithmetic/comparisons, safe parse (locale-aware), random digits, etc.
 - **Function utilities**: debounce, throttle, formatCurrency, parseName, currency conversions, etc.
 - **Boolean utilities**: safe boolean conversion with common representations
 - **Validation utilities**: IBAN validator (ISO 13616), Portuguese tax ID validator
@@ -325,6 +325,42 @@ round(1.2345, 2); // 1.23
 round(1.235, 2); // 1.24
 ```
 
+**`safeAdd(a: number, b: number, decimals?: number): number`** — Adds two numbers with rounding and guards against invalid operands and precision errors.
+
+```javascript
+safeAdd(0.1, 0.2, 2); // 0.3
+safeAdd(Number.NaN, 5); // 0 (invalid operand)
+```
+
+**`safeMultiply(a: number, b: number, decimals?: number): number`** — Multiplies two numbers safely with rounding and operand validation.
+
+```javascript
+safeMultiply(0.1, 0.2, 4); // 0.02
+safeMultiply(Infinity, 2); // 0 (invalid operand)
+```
+
+**`safeSubtract(a: number, b: number, decimals?: number): number`** — Subtracts numbers safely, clamping decimal precision when needed.
+
+```javascript
+safeSubtract(10, 3.3333, 2); // 6.67
+safeSubtract(5, Number.NaN); // 0 (invalid operand)
+```
+
+**`safeDivide(a: number, b: number, decimals?: number): number`** — Divides numbers with division-by-zero protection and precision normalization.
+
+```javascript
+safeDivide(1, 3, 3); // 0.333
+safeDivide(10, 0); // 0 (division by zero)
+```
+
+**`numbersEqual(a: number, b: number, decimals?: number): boolean`** — Safely compares two numbers using fixed decimal precision and invalid operand guards.
+
+```javascript
+numbersEqual(0.1 + 0.2, 0.3); // true
+numbersEqual(1.2345, 1.2344, 4); // false
+numbersEqual(NaN, 1); // false
+```
+
 **`safeParseInt(value: unknown, defaultValue?: number): number`** — Safely converts a value to an integer with fallback.
 
 ```javascript
@@ -333,13 +369,16 @@ safeParseInt("abc", 10); // 10
 safeParseInt(3.9); // 3
 ```
 
-**`safeParseFloat(value: unknown, decimals?: number): number`** — Safely parses a value into a number with decimal precision and comma/dot normalization.
+**`safeParseFloat(value: unknown, decimals?: number): number`** — Safely parses a value into a number with decimal precision, handling locale separators (commas, dots, spaces) and invalid inputs.
 
 ```javascript
 safeParseFloat("123.45"); // 123.45
 safeParseFloat("123,45"); // 123.45
 safeParseFloat("1,234.56"); // 1234.56
+safeParseFloat("1 234,56"); // 1234.56 (spaces as thousands)
+safeParseFloat("1.234,56"); // 1234.56 (dot thousands, comma decimals)
 safeParseFloat("abc"); // 0
+safeParseFloat(NaN); // 0
 ```
 
 **`randomDigits(length?: number, options?: { charset?: string; noLeadingZero?: boolean }): string`** — Generates a random string of digits with secure randomness when available.
@@ -817,5 +856,5 @@ MIT © [SalesPark](https://salespark.io)
 
 ---
 
-_Document version: 7_  
-_Last update: 08-11-2025_
+_Document version: 9_  
+_Last update: 01-12-2025_

package/dist/index.cjs

@@ -261,19 +261,94 @@ function safeParseInt(value, defaultValue = 0) {
     return defaultValue;
   }
 }
+function normalizeDecimals(decimals) {
+  if (!Number.isFinite(decimals)) return 0;
+  const int = Math.floor(decimals);
+  if (int < 0) return 0;
+  if (int > 100) return 100;
+  return int;
+}
+function sanitizeOperands(...values) {
+  return values.every((value) => Number.isFinite(value));
+}
+function safeAdd(a, b, decimals = 2) {
+  try {
+    if (!sanitizeOperands(a, b)) return 0;
+    const precision = normalizeDecimals(decimals);
+    return Number((a + b).toFixed(precision));
+  } catch {
+    return 0;
+  }
+}
+function safeMultiply(a, b, decimals = 2) {
+  try {
+    if (!sanitizeOperands(a, b)) return 0;
+    const precision = normalizeDecimals(decimals);
+    return Number((a * b).toFixed(precision));
+  } catch {
+    return 0;
+  }
+}
+function safeSubtract(a, b, decimals = 2) {
+  try {
+    if (!sanitizeOperands(a, b)) return 0;
+    const precision = normalizeDecimals(decimals);
+    return Number((a - b).toFixed(precision));
+  } catch {
+    return 0;
+  }
+}
+function safeDivide(a, b, decimals = 2) {
+  try {
+    if (!sanitizeOperands(a, b) || b === 0) return 0;
+    const precision = normalizeDecimals(decimals);
+    return Number((a / b).toFixed(precision));
+  } catch {
+    return 0;
+  }
+}
+function numbersEqual(a, b, decimals = 2) {
+  try {
+    if (!sanitizeOperands(a, b)) return false;
+    const precision = normalizeDecimals(decimals);
+    return a.toFixed(precision) === b.toFixed(precision);
+  } catch {
+    return false;
+  }
+}
 var toInteger = safeParseInt;
 function safeParseFloat(value, decimals = 6) {
   try {
+    if (typeof value === "number") {
+      return isNaN(value) ? 0 : Number(value.toFixed(decimals));
+    }
     if (value === void 0 || value === null || value === "") return 0;
-    let str = String(value);
+    let str = String(value).trim();
+    if (!str) return 0;
+    str = str.replace(/\s+/g, "");
+    let normalized;
     if (str.includes(",") && str.includes(".")) {
-      str = str.replace(/,/g, "");
+      const lastComma = str.lastIndexOf(",");
+      const lastDot = str.lastIndexOf(".");
+      if (lastDot > lastComma) {
+        normalized = str.replace(/,/g, "");
+      } else {
+        normalized = str.replace(/\./g, "").replace(",", ".");
+      }
     } else if (str.includes(",")) {
-      str = str.replace(",", ".");
+      const parts = str.split(",");
+      if (parts.length === 2 && parts[1].length <= 2) {
+        normalized = str.replace(",", ".");
+      } else {
+        normalized = str.replace(/,/g, "");
+      }
+    } else {
+      normalized = str;
     }
-    const num = parseFloat(str);
-    if (isNaN(num)) return 0;
-    return parseFloat(num.toFixed(decimals));
+    const num = parseFloat(normalized);
+    if (!isFinite(num)) return 0;
+    const precision = normalizeDecimals(decimals);
+    return Number(num.toFixed(precision));
   } catch {
     return 0;
   }
@@ -1673,6 +1748,7 @@ exports.isNullUndefinedOrZero = isNullUndefinedOrZero;
 exports.isPTTaxId = isPTTaxId;
 exports.isValidIBAN = isValidIBAN;
 exports.isValidPTTaxId = isValidPTTaxId;
+exports.numbersEqual = numbersEqual;
 exports.objectToString = objectToString;
 exports.omit = omit;
 exports.otp = otp;
@@ -1685,8 +1761,12 @@ exports.pushAll = pushAll;
 exports.randomDigits = randomDigits;
 exports.removeDiacritics = removeDiacritics;
 exports.round = round;
+exports.safeAdd = safeAdd;
+exports.safeDivide = safeDivide;
+exports.safeMultiply = safeMultiply;
 exports.safeParseFloat = safeParseFloat;
 exports.safeParseInt = safeParseInt;
+exports.safeSubtract = safeSubtract;
 exports.sanitize = sanitize;
 exports.sanitizeMarkdown = sanitizeMarkdown;
 exports.shuffle = shuffle;