@salespark/toolkit 2.1.6 → 2.1.8

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
@@ -267,16 +267,31 @@ objectToString({ name: "John", age: 30 });
 // Result: "name=John_age=30"
 ```
 
-**`cleanObject<T>(obj: T): any`** — Deep-cleans an object by removing null/undefined values.
+**`cleanObject<T>(obj: T, removeEmptyString?: boolean): any`** — Deep-cleans an object by removing null/undefined-like values, with optional empty-string removal.
 
 ```javascript
+// Default behaviour: keep empty strings
 cleanObject({
   name: "John",
   age: null,
   city: undefined,
+  note: "",
   data: { valid: true, invalid: null },
 });
-// Result: {name: 'John', data: {valid: true}}
+// Result: {name: 'John', note: '', data: {valid: true}}
+
+// With removeEmptyString enabled
+cleanObject(
+  {
+    name: "John",
+    age: null,
+    city: undefined,
+    note: "",
+    tags: ["", "ok"],
+  },
+  true
+);
+// Result: {name: 'John', tags: ['ok']}
 ```
 
 ### 🔤 String Utilities
@@ -325,6 +340,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 +871,5 @@ MIT © [SalesPark](https://salespark.io)
 
 ---
 
-_Document version: 8_  
-_Last update: 10-12-2025_
+_Document version: 10_  
+_Last update: 11-12-2025_

package/dist/index.cjs

@@ -187,18 +187,18 @@ function objectToString(obj) {
     }
   }
 }
-var isRemovable = (v) => v === null || v === void 0 || v === "null" || v === "undefined";
-function cleanObject(obj) {
+var isRemovable = (v, removeEmptyString) => v === null || v === void 0 || v === "null" || v === "undefined" || removeEmptyString && v === "";
+function cleanObject(obj, removeEmptyString = false) {
   if (Array.isArray(obj)) {
-    const cleanedArray = obj.map((item) => cleanObject(item)).filter((item) => !isRemovable(item));
+    const cleanedArray = obj.map((item) => cleanObject(item, removeEmptyString)).filter((item) => !isRemovable(item, removeEmptyString));
     return cleanedArray;
   }
   if (obj !== null && typeof obj === "object") {
     const cleaned = {};
     for (const [key, value] of Object.entries(obj)) {
-      if (isRemovable(value)) continue;
-      const nested = cleanObject(value);
-      if (isRemovable(nested)) continue;
+      if (isRemovable(value, removeEmptyString)) continue;
+      const nested = cleanObject(value, removeEmptyString);
+      if (isRemovable(nested, removeEmptyString)) continue;
       const isObj = typeof nested === "object" && nested !== null;
       const isEmptyObj = isObj && !Array.isArray(nested) && Object.keys(nested).length === 0;
       const isEmptyArr = Array.isArray(nested) && nested.length === 0;
@@ -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;