@salespark/toolkit 2.1.1 → 2.1.3

package/README.md

@@ -311,48 +311,72 @@ sanitize("<script>alert('hack')</script>Hello World!", 20);
 
 ### 🔢 Number Utilities
 
-**`clamp(n: number, min: number, max: number): number`** — Restricts a number within min and max bounds.
+**`clamp(n: number, min: number, max: number): number`** — Restricts a number to be within the min and max bounds.
 
 ```javascript
-clamp(15, 0, 10);
-// Result: 10
+clamp(10, 0, 5); // 5
+clamp(-5, 0, 10); // 0
 ```
 
-**`round(n: number, decimals?: number): number`** — Rounds a number to fixed decimal places.
+**`round(n: number, decimals?: number): number`** — Rounds a number to a fixed number of decimals without floating point surprises.
 
 ```javascript
-round(3.14159, 2);
-// Result: 3.14
+round(1.2345, 2); // 1.23
+round(1.235, 2); // 1.24
 ```
 
-**`toInteger(value: unknown, defaultValue?: number): number`** — Safely converts a value to an integer.
+**`safeParseInt(value: unknown, defaultValue?: number): number`** — Safely converts a value to an integer with fallback.
 
 ```javascript
-toInteger("42.7");
-// Result: 42
+safeParseInt("42"); // 42
+safeParseInt("abc", 10); // 10
+safeParseInt(3.9); // 3
 ```
 
-**`safeParseInt(value: unknown, defaultValue?: number): number`** — Alias for safe integer conversion.
+**`safeParseFloat(value: unknown, decimals?: number): number`** — Safely parses a value into a number with decimal precision and comma/dot normalization.
 
 ```javascript
-safeParseInt("abc", 0);
-// Result: 0
+safeParseFloat("123.45"); // 123.45
+safeParseFloat("123,45"); // 123.45
+safeParseFloat("1,234.56"); // 1234.56
+safeParseFloat("abc"); // 0
 ```
 
-**`toNumber(value: unknown, decimals?: number): number`** — Safely parses a value into a number with optional decimal precision.
+**`randomDigits(length?: number, options?: { charset?: string; noLeadingZero?: boolean }): string`** — Generates a random string of digits with secure randomness when available.
 
 ```javascript
-toNumber("123,45", 2);
-// Result: 123.45
+randomDigits(6);
+// Result: "482751" (random)
 ```
 
 **`randomDigits(length?: number, options?: { charset?: string; noLeadingZero?: boolean }): string`** — Generates a random string of digits with secure randomness when available.
 
 ```javascript
-randomDigits(6);
-// Result: "482751" (random)
+randomDigits(6); // "847293"
+randomDigits(4, { noLeadingZero: true }); // "3847" (no leading zero)
+randomDigits(6, { charset: "ABCDEF0123456789" }); // "3F2A9D" (hex)
+```
+
+**`formatDecimalNumber(value: number | string | null | undefined, decimals?: number): string`** — Formats a number with specified decimal places, intelligently handling European (`1.234,56`) and US (`1,234.56`) number formats.
+
+**`formatDecimalNumber(value: number | string | null | undefined, decimals?: number): string`** — Formats a number with specified decimal places, intelligently handling European (`1.234,56`) and US (`1,234.56`) number formats.
+
+```javascript
+formatDecimalNumber(1234.5678); // "1234.57"
+formatDecimalNumber("1.234,56", 2); // "1234.56" (European format)
+formatDecimalNumber("1,234.56", 2); // "1234.56" (US format)
+formatDecimalNumber("1234,56", 3); // "1234.560"
+formatDecimalNumber(null, 2); // "0.00"
+formatDecimalNumber("invalid", 2); // "0.00"
 ```
 
+#### 🗑️ Deprecated (Number Utilities)
+
+- **`toInteger`** → Use `safeParseInt` instead
+- **`toNumber`** → Use `safeParseFloat` instead
+- **`parseToNumber`** → Use `safeParseFloat` instead
+- **`otp`** → Use `randomDigits` instead
+
 ### ✅ Boolean Utilities
 
 **`toBool(value: unknown, def?: boolean): boolean`** — Converts a value to boolean, supporting common string/number representations.
@@ -425,14 +449,20 @@ isNilText("undefined");
 // Result: true
 ```
 
-**`isNilOrEmpty(value: unknown): boolean`** — Checks if value is null/undefined or an empty string.
+**`isNilOrEmpty(value: unknown): boolean`** — Checks if value is null/undefined or an empty string (trimmed).
 
 ```javascript
 isNilOrEmpty("");
 // Result: true
 
+isNilOrEmpty(" ");
+// Result: true
+
 isNilOrEmpty(null);
 // Result: true
+
+isNilOrEmpty(undefined);
+// Result: true
 ```
 
 **`hasNilOrEmpty(array: unknown): boolean`** — Checks if any element in array is nil or empty.
@@ -596,15 +626,17 @@ checkMarkdownSecurity("# Hello World\n\nThis is **bold** text.");
 
 // Dangerous content with script
 checkMarkdownSecurity('<script>alert("xss")</script>');
-// Result: { 
-//   isValid: false, 
-//   text: "", 
-//   risks: [{ type: "scriptTags", severity: "critical", description: "..." }], 
-//   sanitized: true 
+// Result: {
+//   isValid: false,
+//   text: "",
+//   risks: [{ type: "scriptTags", severity: "critical", description: "..." }],
+//   sanitized: true
 // }
 
 // Content with multiple threats
-checkMarkdownSecurity('<iframe src="evil.com"></iframe><div onclick="bad()">test</div>');
+checkMarkdownSecurity(
+  '<iframe src="evil.com"></iframe><div onclick="bad()">test</div>'
+);
 // Result: Multiple risks detected, sorted by severity
 ```
 
@@ -613,13 +645,13 @@ checkMarkdownSecurity('<iframe src="evil.com"></iframe><div onclick="bad()">test
 ```typescript
 import { sanitizeMarkdown } from "@salespark/toolkit";
 
-sanitizeMarkdown('<p>Hello <strong>World</strong></p>');
+sanitizeMarkdown("<p>Hello <strong>World</strong></p>");
 // Result: "Hello World"
 
 sanitizeMarkdown('javascript:alert("xss")');
 // Result: "alert(\"xss\")"
 
-sanitizeMarkdown('<script>alert(1)</script>Safe text');
+sanitizeMarkdown("<script>alert(1)</script>Safe text");
 // Result: "Safe text"
 ```
 
@@ -629,7 +661,11 @@ sanitizeMarkdown('<script>alert(1)</script>Safe text');
 import { assessSecurityRisks } from "@salespark/toolkit";
 
 const risks = [
-  { type: "scriptTags", severity: "critical", description: "Script injection detected" }
+  {
+    type: "scriptTags",
+    severity: "critical",
+    description: "Script injection detected",
+  },
 ];
 
 assessSecurityRisks(risks);
@@ -655,10 +691,10 @@ assessSecurityRisks([]);
 ```typescript
 import { isPTTaxId } from "@salespark/toolkit";
 
-isPTTaxId("123456789");        // false (invalid check digit)
-isPTTaxId("123 456 789");      // false (spaces stripped automatically)
-isPTTaxId("513183504");        // true (valid NIF)
-isPTTaxId("423456789");        // false (invalid prefix - 4 not allowed)
+isPTTaxId("123456789"); // false (invalid check digit)
+isPTTaxId("123 456 789"); // false (spaces stripped automatically)
+isPTTaxId("513183504"); // true (valid NIF)
+isPTTaxId("423456789"); // false (invalid prefix - 4 not allowed)
 
 // Deprecated alias (use isPTTaxId instead)
 // isValidPTTaxId("513183504");   // true
@@ -669,12 +705,12 @@ isPTTaxId("423456789");        // false (invalid prefix - 4 not allowed)
 ```typescript
 import { isValidIBAN } from "@salespark/toolkit";
 
-isValidIBAN("NL91ABNA0417164300");     // true (valid Dutch IBAN)
+isValidIBAN("NL91ABNA0417164300"); // true (valid Dutch IBAN)
 isValidIBAN("NL91 ABNA 0417 1643 00"); // true (spaces stripped automatically)
 isValidIBAN("GB29NWBK60161331926819"); // true (valid UK IBAN)
-isValidIBAN("DE89370400440532013000");  // true (valid German IBAN)
-isValidIBAN("NL91ABNA0417164301");     // false (invalid checksum)
-isValidIBAN("XX1234567890");           // false (invalid country code)
+isValidIBAN("DE89370400440532013000"); // true (valid German IBAN)
+isValidIBAN("NL91ABNA0417164301"); // false (invalid checksum)
+isValidIBAN("XX1234567890"); // false (invalid country code)
 ```
 
 ### 🌐 Environment Detection
@@ -710,7 +746,7 @@ The following functions are deprecated but maintained for backward compatibility
 ### ⚡ Function Utilities (Deprecated)
 
 - `isNullOrUndefined` — Use `isNil` instead.
-- `isNullOrUndefinedTextInc` — Use `isNilText` instead.  
+- `isNullOrUndefinedTextInc` — Use `isNilText` instead.
 - `isNullUndefinedOrEmpty` — Use `isNilOrEmpty` instead.
 - `isNullOrUndefinedInArray` — Use `hasNilOrEmpty` instead.
 - `isNullOrUndefinedEmptyOrZero` — Use `isNilEmptyOrZeroLen` instead.
@@ -779,5 +815,5 @@ MIT © [SalesPark](https://salespark.io)
 
 ---
 
-_Document version: 5_  
-_Last update: 25-09-2025_
+_Document version: 6_  
+_Last update: 29-10-2025_

package/dist/index.cjs

@@ -253,7 +253,7 @@ function round(n, decimals = 0) {
   const f = Math.pow(10, decimals);
   return Math.round((n + Number.EPSILON) * f) / f;
 }
-function toInteger(value, defaultValue = 0) {
+function safeParseInt(value, defaultValue = 0) {
   try {
     const safeValue = parseInt(String(value), 10);
     return isNaN(safeValue) ? defaultValue : safeValue;
@@ -261,8 +261,8 @@ function toInteger(value, defaultValue = 0) {
     return defaultValue;
   }
 }
-var safeParseInt = toInteger;
-function toNumber(value, decimals = 6) {
+var toInteger = safeParseInt;
+function safeParseFloat(value, decimals = 6) {
   try {
     if (value === void 0 || value === null || value === "") return 0;
     let str = String(value);
@@ -278,7 +278,8 @@ function toNumber(value, decimals = 6) {
     return 0;
   }
 }
-var parseToNumber = toNumber;
+var toNumber = safeParseFloat;
+var parseToNumber = safeParseFloat;
 function secureRandomIndex(max) {
   if (max <= 0) return 0;
   const g = globalThis;
@@ -310,6 +311,30 @@ function randomDigits(length = 6, options) {
   return out;
 }
 var otp = randomDigits;
+var formatDecimalNumber = (value, decimals = 2) => {
+  try {
+    let processedValue = value ?? 0;
+    if (typeof processedValue === "string") {
+      const trimmed = processedValue.trim();
+      if (trimmed.includes(",") && trimmed.includes(".")) {
+        const lastComma = trimmed.lastIndexOf(",");
+        const lastDot = trimmed.lastIndexOf(".");
+        processedValue = lastComma > lastDot ? trimmed.replace(/\./g, "").replace(",", ".") : trimmed.replace(/,/g, "");
+      } else if (trimmed.includes(",")) {
+        processedValue = trimmed.replace(/,/g, ".");
+      } else {
+        processedValue = trimmed;
+      }
+    }
+    const numValue = parseFloat(String(processedValue));
+    if (isNaN(numValue)) {
+      return 0 .toFixed(Math.max(0, Math.floor(decimals)));
+    }
+    return numValue.toFixed(Math.max(0, Math.floor(decimals)));
+  } catch (error) {
+    return 0 .toFixed(Math.max(0, Math.floor(decimals)));
+  }
+};
 
 // src/utils/func.ts
 function debounce(fn, wait = 250) {
@@ -348,7 +373,7 @@ var isNilText = (value) => {
 };
 var isNilOrEmpty = (value) => {
   try {
-    return isNil(value) || value === "";
+    return isNil(value) || typeof value === "string" && value?.trim() === "";
   } catch {
     return true;
   }
@@ -1615,6 +1640,7 @@ exports.flattenDepthBase = flattenDepthBase;
 exports.flattenOnce = flattenOnce;
 exports.formatBytes = formatBytes;
 exports.formatCurrency = formatCurrency;
+exports.formatDecimalNumber = formatDecimalNumber;
 exports.getStringSimilarity = getStringSimilarity;
 exports.groupBy = groupBy;
 exports.hasNilOrEmpty = hasNilOrEmpty;
@@ -1653,6 +1679,7 @@ exports.pushAll = pushAll;
 exports.randomDigits = randomDigits;
 exports.removeDiacritics = removeDiacritics;
 exports.round = round;
+exports.safeParseFloat = safeParseFloat;
 exports.safeParseInt = safeParseInt;
 exports.sanitize = sanitize;
 exports.sanitizeMarkdown = sanitizeMarkdown;