@salespark/toolkit 2.1.1 → 2.1.3

package/dist/index.d.cts

@@ -306,39 +306,39 @@ declare function round(n: number, decimals?: number): number;
  * Safely converts a value to an integer. Returns defaultValue if parsing fails or results in NaN.
  *
  * Notes:
- * Examples: toInteger("42") -> 42, toInteger("abc", 10) -> 10, toInteger(undefined) -> 0, toInteger(3.9) -> 3
+ * Examples: safeParseInt("42") -> 42, safeParseInt("abc", 10) -> 10, safeParseInt(undefined) -> 0, safeParseInt(3.9) -> 3
  * @param {unknown} value - Value to convert
  * @param {Number} defaultValue - Default value if parsing fails
  * History:
  * 21-08-2025: Created
+ * 29-10-2025: Renamed from toInteger to safeParseInt
  ****************************************************/
-declare function toInteger(value: unknown, defaultValue?: number): number;
-/******************************************************
- * ##: Safe Parse Int (Alias)
- * Alias for safe integer conversion (for discoverability/backward naming)
- * @param {unknown} value - Value to convert
- * @param {Number} defaultValue - Default value if parsing fails
- * History:
- * 21-08-2025: Created
- ****************************************************/
-declare const safeParseInt: typeof toInteger;
+declare function safeParseInt(value: unknown, defaultValue?: number): number;
+/**
+ * @deprecated Use `safeParseFloat` instead.
+ */
+declare const toInteger: typeof safeParseInt;
 /******************************************************
  * ##: Safe Number Conversion
  * Safely parses a value into a number with optional decimal precision
  *
  * Notes:
  * Handles commas as decimal/thousands separators. Returns 0 for null/undefined/empty string or invalid parsing.
- * Examples: toNumber("123.45") -> 123.45, toNumber("123,45") -> 123.45, toNumber("1,234.56") -> 1234.56, toNumber("abc", 2) -> 0, toNumber(42) -> 42
- * @param {unknown} value - Value to convert
+ * Examples: safeParseFloat("123.45") -> 123.45, safeParseFloat("123,45") -> 123.45, safeParseFloat("1,234.56") -> 1234.56, safeParseFloat("abc", 2) -> 0, safeParseFloat(42) -> 42 * @param {unknown} value - Value to convert
  * @param {Number} decimals - Number of decimal places
  * History:
  * 21-08-2025: Created
+ * * 29-10-2025: Renamed from toNumber to safeParseFloat
  ****************************************************/
-declare function toNumber(value: unknown, decimals?: number): number;
+declare function safeParseFloat(value: unknown, decimals?: number): number;
+/**
+ * @deprecated Use `safeParseFloat` instead.
+ */
+declare const toNumber: typeof safeParseFloat;
 /**
- * @deprecated Use `toNumber` instead.
+ * @deprecated Use `safeParseFloat` instead.
  */
-declare const parseToNumber: typeof toNumber;
+declare const parseToNumber: typeof safeParseFloat;
 /******************************************************
  * ##: Random Digits Generator
  * Generates a random string of digits with secure randomness when available
@@ -358,6 +358,19 @@ declare function randomDigits(length?: number, options?: {
  * @deprecated Use `randomDigits` instead.
  */
 declare const otp: typeof randomDigits;
+/******************************************************
+ * ##: Decimal Number Formatter
+ * Formats a number with specified decimal places, handling comma/dot normalization.
+ *
+ * Intelligently handles European number formats (1.234,56) and US formats (1,234.56).
+ * Converts strings to numbers and applies decimal formatting.
+ * @param {number|string|null|undefined} value Number value to format
+ * @param {number} decimals Number of decimal places (default: 2)
+ * @returns {string} Formatted number string with specified decimals
+ * History:
+ * 16-10-2025: Created
+ ****************************************************/
+declare const formatDecimalNumber: (value: number | string | null | undefined, decimals?: number) => string;
 
 /******************************************************
  * ##: Debounce Function
@@ -399,6 +412,7 @@ declare const isNilText: (value: unknown) => boolean;
  * @param {unknown} value - Value to check
  * History:
  * 21-08-2025: Created
+ * 18-10-2025: Trim before checking empty
  ****************************************************/
 declare const isNilOrEmpty: (value: unknown) => boolean;
 /******************************************************
@@ -681,4 +695,4 @@ declare const assessSecurityRisks: (risks: SecurityRisk[]) => {
 declare const isBrowser: boolean;
 declare const isNode: boolean;
 
-export { type SecurityCheckResult, type SecurityRisk, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseInt, sanitize, sanitizeMarkdown, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
+export { type SecurityCheckResult, type SecurityRisk, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseFloat, safeParseInt, sanitize, sanitizeMarkdown, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };

package/dist/index.d.ts

@@ -306,39 +306,39 @@ declare function round(n: number, decimals?: number): number;
  * Safely converts a value to an integer. Returns defaultValue if parsing fails or results in NaN.
  *
  * Notes:
- * Examples: toInteger("42") -> 42, toInteger("abc", 10) -> 10, toInteger(undefined) -> 0, toInteger(3.9) -> 3
+ * Examples: safeParseInt("42") -> 42, safeParseInt("abc", 10) -> 10, safeParseInt(undefined) -> 0, safeParseInt(3.9) -> 3
  * @param {unknown} value - Value to convert
  * @param {Number} defaultValue - Default value if parsing fails
  * History:
  * 21-08-2025: Created
+ * 29-10-2025: Renamed from toInteger to safeParseInt
  ****************************************************/
-declare function toInteger(value: unknown, defaultValue?: number): number;
-/******************************************************
- * ##: Safe Parse Int (Alias)
- * Alias for safe integer conversion (for discoverability/backward naming)
- * @param {unknown} value - Value to convert
- * @param {Number} defaultValue - Default value if parsing fails
- * History:
- * 21-08-2025: Created
- ****************************************************/
-declare const safeParseInt: typeof toInteger;
+declare function safeParseInt(value: unknown, defaultValue?: number): number;
+/**
+ * @deprecated Use `safeParseFloat` instead.
+ */
+declare const toInteger: typeof safeParseInt;
 /******************************************************
  * ##: Safe Number Conversion
  * Safely parses a value into a number with optional decimal precision
  *
  * Notes:
  * Handles commas as decimal/thousands separators. Returns 0 for null/undefined/empty string or invalid parsing.
- * Examples: toNumber("123.45") -> 123.45, toNumber("123,45") -> 123.45, toNumber("1,234.56") -> 1234.56, toNumber("abc", 2) -> 0, toNumber(42) -> 42
- * @param {unknown} value - Value to convert
+ * Examples: safeParseFloat("123.45") -> 123.45, safeParseFloat("123,45") -> 123.45, safeParseFloat("1,234.56") -> 1234.56, safeParseFloat("abc", 2) -> 0, safeParseFloat(42) -> 42 * @param {unknown} value - Value to convert
  * @param {Number} decimals - Number of decimal places
  * History:
  * 21-08-2025: Created
+ * * 29-10-2025: Renamed from toNumber to safeParseFloat
  ****************************************************/
-declare function toNumber(value: unknown, decimals?: number): number;
+declare function safeParseFloat(value: unknown, decimals?: number): number;
+/**
+ * @deprecated Use `safeParseFloat` instead.
+ */
+declare const toNumber: typeof safeParseFloat;
 /**
- * @deprecated Use `toNumber` instead.
+ * @deprecated Use `safeParseFloat` instead.
  */
-declare const parseToNumber: typeof toNumber;
+declare const parseToNumber: typeof safeParseFloat;
 /******************************************************
  * ##: Random Digits Generator
  * Generates a random string of digits with secure randomness when available
@@ -358,6 +358,19 @@ declare function randomDigits(length?: number, options?: {
  * @deprecated Use `randomDigits` instead.
  */
 declare const otp: typeof randomDigits;
+/******************************************************
+ * ##: Decimal Number Formatter
+ * Formats a number with specified decimal places, handling comma/dot normalization.
+ *
+ * Intelligently handles European number formats (1.234,56) and US formats (1,234.56).
+ * Converts strings to numbers and applies decimal formatting.
+ * @param {number|string|null|undefined} value Number value to format
+ * @param {number} decimals Number of decimal places (default: 2)
+ * @returns {string} Formatted number string with specified decimals
+ * History:
+ * 16-10-2025: Created
+ ****************************************************/
+declare const formatDecimalNumber: (value: number | string | null | undefined, decimals?: number) => string;
 
 /******************************************************
  * ##: Debounce Function
@@ -399,6 +412,7 @@ declare const isNilText: (value: unknown) => boolean;
  * @param {unknown} value - Value to check
  * History:
  * 21-08-2025: Created
+ * 18-10-2025: Trim before checking empty
  ****************************************************/
 declare const isNilOrEmpty: (value: unknown) => boolean;
 /******************************************************
@@ -681,4 +695,4 @@ declare const assessSecurityRisks: (risks: SecurityRisk[]) => {
 declare const isBrowser: boolean;
 declare const isNode: boolean;
 
-export { type SecurityCheckResult, type SecurityRisk, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseInt, sanitize, sanitizeMarkdown, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
+export { type SecurityCheckResult, type SecurityRisk, addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseFloat, safeParseInt, sanitize, sanitizeMarkdown, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };

package/dist/index.js

@@ -251,7 +251,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;
@@ -259,8 +259,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);
@@ -276,7 +276,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;
@@ -308,6 +309,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) {
@@ -346,7 +371,7 @@ var isNilText = (value) => {
 };
 var isNilOrEmpty = (value) => {
   try {
-    return isNil(value) || value === "";
+    return isNil(value) || typeof value === "string" && value?.trim() === "";
   } catch {
     return true;
   }
@@ -1590,6 +1615,6 @@ var assessSecurityRisks = (risks) => {
 var isBrowser = typeof globalThis !== "undefined" && typeof globalThis.document !== "undefined";
 var isNode = typeof process !== "undefined" && !!process.versions?.node;
 
-export { addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseInt, sanitize, sanitizeMarkdown, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
+export { addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, assessSecurityRisks, basicSanitize, checkMarkdownSecurity, chunk, clamp, cleanObject, compact, currencyToSymbol, debounce, deburr, delay, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, formatCurrency, formatDecimalNumber, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNilTextOrEmpty, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrEmptyEnforced, isNullUndefinedOrZero, isPTTaxId, isValidIBAN, isValidPTTaxId, objectToString, omit, otp, parseName, parseToBool, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseFloat, safeParseInt, sanitize, sanitizeMarkdown, shuffle, slugify, sortBy, stringSimilarity, symbolToCurrency, throttle, toBool, toInteger, toNumber, uniq, uniqBy };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map