@salespark/toolkit 2.1.6 → 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 (locale-aware), 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
@@ -820,5 +856,5 @@ MIT © [SalesPark](https://salespark.io)
 
 ---
 
-_Document version: 8_  
-_Last update: 10-12-2025_
+_Document version: 9_  
+_Last update: 01-12-2025_

package/dist/index.cjs

@@ -261,6 +261,61 @@ 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 {
@@ -292,7 +347,8 @@ function safeParseFloat(value, decimals = 6) {
     }
     const num = parseFloat(normalized);
     if (!isFinite(num)) return 0;
-    return Number(num.toFixed(decimals));
+    const precision = normalizeDecimals(decimals);
+    return Number(num.toFixed(precision));
   } catch {
     return 0;
   }
@@ -1692,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;
@@ -1704,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;