@rabex-kit/rabex-ui 0.2.45 → 0.2.46

package/dist/utils/numberUtils.d.ts

@@ -1,30 +1,202 @@
 import bigDecimal from 'js-big-decimal';
-declare function suffix(num: number | string, options: {
+/**
+ * Type definition for suffix function options
+ */
+interface SuffixOptions {
     precision?: number;
     round?: 'roundDown' | 'roundUp';
     suffix?: Array<'K' | 'M' | 'B' | 'T'>;
-}): string;
+}
+/**
+ * NUMBER SUFFIX FORMATTER (K, M, B, T)
+ *
+ * Purpose: Converts large numbers to human-readable format with suffixes
+ *
+ * @param num - Input number to format
+ * @param options - Formatting options (precision, rounding method, allowed suffixes)
+ * @returns Formatted string with appropriate suffix
+ *
+ * Key Features:
+ * - Uses bigDecimal for all calculations to avoid scientific notation
+ * - Supports custom precision and rounding methods
+ * - Configurable suffix types (K=thousands, M=millions, B=billions, T=trillions)
+ * - Falls back to original number if no suffix applies
+ *
+ * Examples:
+ * suffix(1000, {precision: 1}) → "1K"
+ * suffix(1500000, {precision: 2, round: 'roundUp'}) → "1.5M"
+ * suffix(2.5e9) → "2.5B"
+ *
+ * Scientific Notation Prevention:
+ * - Uses string-based thresholds instead of numeric literals
+ * - BigDecimal comparison instead of JavaScript's Math.abs()
+ * - BigDecimal division instead of standard division operator
+ */
+declare function suffix(num: number | string, options?: SuffixOptions): string;
 declare const _default: {
+    /**
+     * Add thousand separators to numbers
+     * Usage: delimiter(1234567) → "1,234,567"
+     */
     delimiter: (num: number | string, separator?: string | undefined, separateBy?: number | undefined) => string | number;
-    removeDelimiter: (num: string, separator?: string) => number;
+    /**
+     * Remove thousand separators from formatted strings
+     * Usage: removeDelimiter("1,234,567") → "1234567"
+     */
+    removeDelimiter: (num: string, separator?: string) => string;
+    /**
+     * Format large numbers with K/M/B/T suffixes
+     * Usage: suffix(1000000) → "1M"
+     */
+    suffix: typeof suffix;
+    /**
+     * Round number down to specified decimal places
+     * Usage: roundDown(3.14159, 2) → "3.14"
+     */
     roundDown: (val: number, dec: number) => string;
+    /**
+     * Round number up to specified decimal places
+     * Usage: roundUp(3.14159, 2) → "3.15"
+     */
     roundUp: (val: number, dec: number) => string;
+    /**
+     * Validate if decimal places are within specified limit
+     * Usage: isDecimalValid("12.34", 2) → true
+     */
     isDecimalValid: (val: string, dec: number) => boolean;
+    /**
+     * Validate if input contains only valid numeric characters
+     * Usage: isValid("123.45") → true
+     */
     isValid: (val: number | string) => boolean;
-    toEn: (val: string) => any;
-    suffix: typeof suffix;
+    /**
+     * Convert Persian numerals to English numerals
+     * Usage: toEn("۱۲۳") → "123"
+     */
+    toEn: (val: string) => string;
+    /**
+     * Convert scientific notation to decimal string
+     * Usage: convertScientific(1e-8) → "0.00000001"
+     */
+    convertScientific: (num: string | number) => string | undefined;
+    /**
+     * Safe number conversion with fallback to "0"
+     * Usage: safeNumber(1e-8) → "0.00000001"
+     */
+    safeNumber: (num: string | number) => string;
+    /**
+     * Complete suite of safe mathematical operations
+     * All operations prevent scientific notation and maintain precision
+     */
+    safeMath: {
+        /**
+         * SAFE ADDITION
+         * @param num1 - First addend
+         * @param num2 - Second addend
+         * @returns Sum as decimal string
+         */
+        add: (num1: string | number, num2: string | number) => string;
+        /**
+         * SAFE SUBTRACTION
+         * @param num1 - Minuend (number to subtract from)
+         * @param num2 - Subtrahend (number to subtract)
+         * @returns Difference as decimal string
+         */
+        subtract: (num1: string | number, num2: string | number) => string;
+        /**
+         * SAFE MULTIPLICATION
+         * @param num1 - First factor
+         * @param num2 - Second factor
+         * @returns Product as decimal string
+         */
+        multiply: (num1: string | number, num2: string | number) => string;
+        /**
+         * SAFE DIVISION
+         * @param num1 - Dividend
+         * @param num2 - Divisor
+         * @param precision - Decimal places in result (default: 10)
+         * @returns Quotient as decimal string
+         */
+        divide: (num1: string | number, num2: string | number, precision?: number) => string;
+    };
+    /**
+     * Direct access to bigDecimal library for advanced operations
+     */
     bigDecimal: typeof bigDecimal;
-    modulus: typeof bigDecimal.modulus;
-    divide: (num1: string | number, num2: string | number, precision: any) => string;
-    multiply: typeof bigDecimal.multiply;
-    subtract: typeof bigDecimal.subtract;
-    add: typeof bigDecimal.add;
-    negate: typeof bigDecimal.negate;
-    compareTo: typeof bigDecimal.compareTo;
-    ceil: typeof bigDecimal.ceil;
-    floor: typeof bigDecimal.floor;
-    abs: typeof bigDecimal.abs;
-    round: typeof bigDecimal.round;
-    getPrettyValue: typeof bigDecimal.getPrettyValue;
+    /**
+     * Modulus operation with precision
+     * Usage: modulus(10, 3) → remainder as string
+     */
+    modulus: (num1: number | string, num2: number | string) => string;
+    /**
+     * Division with configurable precision
+     * Usage: divide(10, 3, 4) → "3.3333"
+     */
+    divide: (num1: string | number, num2: string | number, precision?: number) => string;
+    /**
+     * Multiplication with precision
+     * Usage: multiply(1.5, 2.3) → "3.45"
+     */
+    multiply: (num1: number | string, num2: number | string) => string;
+    /**
+     * Subtraction with precision
+     * Usage: subtract(10, 3.5) → "6.5"
+     */
+    subtract: (num1: number | string, num2: number | string) => string;
+    /**
+     * Addition with precision
+     * Usage: add(1.1, 2.2) → "3.3"
+     */
+    add: (num1: number | string, num2: number | string) => string;
+    /**
+     * Number negation
+     * Usage: negate(5) → "-5"
+     */
+    negate: (num: number | string) => string;
+    /**
+     * Number comparison (-1: less, 0: equal, 1: greater)
+     * Usage: compareTo(5, 3) → 1
+     */
+    compareTo: (num1: number | string, num2: number | string) => 0 | 1 | -1;
+    /**
+     * Ceiling function (round up to nearest integer)
+     * Usage: ceil(3.14) → "4"
+     */
+    ceil: (num: number | string) => any;
+    /**
+     * Floor function (round down to nearest integer)
+     * Usage: floor(3.14) → "3"
+     */
+    floor: (num: number | string) => any;
+    /**
+     * Absolute value
+     * Usage: abs(-5) → "5"
+     */
+    abs: (num: number | string) => string;
+    /**
+     * Round to specified precision
+     * Usage: round(3.14159, 2) → "3.14"
+     */
+    round: (num: number | string, precision: number) => string;
+    /**
+     * Format number with pretty printing (thousands separators)
+     * Usage: getPrettyValue(1234567, 2, ",") → "1,234,567.00"
+     */
+    getPrettyValue: (num: number | string, precision?: number | undefined, separator?: string | undefined) => string;
 };
+/**
+ * COMPREHENSIVE NUMBER UTILITIES EXPORT
+ *
+ * This object provides the complete API for all number operations, formatting,
+ * validation, and mathematical calculations. All functions are designed to
+ * prevent scientific notation and maintain high precision.
+ *
+ * Categories:
+ * 1. Formatting: delimiter, removeDelimiter, suffix
+ * 2. Rounding: roundUp, roundDown
+ * 3. Validation: isValid, isDecimalValid
+ * 4. Conversion: toEn, convertScientific, safeNumber
+ * 5. Mathematics: All bigDecimal operations + safeMath suite
+ * 6. Utilities: Direct access to bigDecimal library
+ */
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rabex-kit/rabex-ui",
-  "version": "0.2.45",
+  "version": "0.2.46",
   "license": "MIT",
   "author": "Seyyed Mahdi Hosseini",
   "main": "dist/index.js",