legal-markdown-js 0.1.0

package/dist/helpers/number-helpers.d.ts

@@ -0,0 +1,269 @@
+/**
+ * @fileoverview Number Formatting and Conversion Helpers
+ *
+ * This module provides comprehensive number formatting utilities specifically
+ * designed for legal and financial documents. It includes functions for currency
+ * formatting, percentage display, number-to-words conversion, and various
+ * numerical representations commonly used in legal contexts.
+ *
+ * Features:
+ * - Currency formatting with multiple currency support (EUR, USD, GBP)
+ * - Percentage formatting with customizable precision
+ * - Number-to-words conversion for legal document amounts
+ * - Integer formatting with thousand separators
+ * - Flexible number formatting with custom separators
+ * - Rounding utilities for precise calculations
+ *
+ * @example
+ * ```typescript
+ * import { formatCurrency, formatPercent, numberToWords } from './number-helpers';
+ *
+ * // Currency formatting
+ * const amount = formatCurrency(1234.56, 'USD');  // "$1,234.56"
+ *
+ * // Percentage formatting
+ * const rate = formatPercent(0.155, 2);           // "15.50%"
+ *
+ * // Number to words for legal documents
+ * const words = numberToWords(1500);              // "one thousand five hundred"
+ * ```
+ */
+/**
+ * Formats a number as an integer with thousand separators
+ *
+ * Converts a number to an integer representation with customizable thousand
+ * separators. Useful for displaying whole numbers in legal documents with
+ * proper formatting for readability.
+ *
+ * @param {number | string} value - The number to format
+ * @param {string} separator - The thousand separator character (default: ',')
+ * @returns {string} The formatted integer string
+ *
+ * @example
+ * ```typescript
+ * // Standard formatting
+ * formatInteger(1234567);        // "1,234,567"
+ * formatInteger(1234567.89);     // "1,234,567" (decimal part removed)
+ *
+ * // Custom separator
+ * formatInteger(1234567, '.');   // "1.234.567"
+ * formatInteger(1234567, ' ');   // "1 234 567"
+ *
+ * // String input
+ * formatInteger('1234567');      // "1,234,567"
+ *
+ * // Invalid input handling
+ * formatInteger('not a number'); // "not a number"
+ * ```
+ */
+export declare function formatInteger(value: number | string, separator?: string): string;
+/**
+ * Formats a number as a percentage with customizable precision
+ *
+ * Converts a number to percentage format with configurable decimal places
+ * and optional percentage symbol. Useful for displaying rates, discounts,
+ * and other percentage values in legal documents.
+ *
+ * @param {number | string} value - The number to format as percentage
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @param {boolean} symbol - Whether to include the % symbol (default: true)
+ * @returns {string} The formatted percentage string
+ *
+ * @example
+ * ```typescript
+ * // Standard percentage formatting
+ * formatPercent(0.1556);           // "15.56%"
+ * formatPercent(0.1556, 1);        // "15.6%"
+ * formatPercent(0.1556, 0);        // "16%"
+ *
+ * // Without percentage symbol
+ * formatPercent(0.1556, 2, false); // "15.56"
+ *
+ * // String input
+ * formatPercent('0.25');           // "25.00%"
+ *
+ * // Whole number input (treated as percentage)
+ * formatPercent(25);               // "25.00%"
+ * ```
+ */
+export declare function formatPercent(value: number | string, decimals?: number, symbol?: boolean): string;
+/**
+ * Formats a number as currency with support for multiple currencies
+ *
+ * Converts a number to currency format with proper symbol placement,
+ * thousand separators, and decimal precision. Supports EUR, USD, and GBP
+ * with correct formatting conventions for each currency.
+ *
+ * @param {number | string} value - The number to format as currency
+ * @param {'EUR' | 'USD' | 'GBP'} currency - The currency type (default: 'EUR')
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @returns {string} The formatted currency string
+ *
+ * @example
+ * ```typescript
+ * // Euro formatting (symbol after amount)
+ * formatCurrency(1234.56, 'EUR');    // "1,234.56 €"
+ * formatCurrency(1234.56, 'EUR', 0); // "1,235 €"
+ *
+ * // US Dollar formatting (symbol before amount)
+ * formatCurrency(1234.56, 'USD');    // "$1,234.56"
+ *
+ * // British Pound formatting (symbol before amount)
+ * formatCurrency(1234.56, 'GBP');    // "£1,234.56"
+ *
+ * // String input
+ * formatCurrency('1234.56', 'USD');  // "$1,234.56"
+ * ```
+ */
+export declare function formatCurrency(value: number | string, currency?: 'EUR' | 'USD' | 'GBP', decimals?: number): string;
+/**
+ * Formats a number as Euro currency
+ *
+ * Convenience function for formatting numbers as Euro currency with
+ * proper Euro symbol placement and formatting conventions.
+ *
+ * @param {number | string} value - The number to format as Euro
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @returns {string} The formatted Euro currency string
+ *
+ * @example
+ * ```typescript
+ * formatEuro(1234.56);     // "1,234.56 €"
+ * formatEuro(1234.56, 0);  // "1,235 €"
+ * formatEuro('500');       // "500.00 €"
+ * ```
+ */
+export declare function formatEuro(value: number | string, decimals?: number): string;
+/**
+ * Formats a number as US Dollar currency
+ *
+ * Convenience function for formatting numbers as US Dollar currency with
+ * proper dollar symbol placement and formatting conventions.
+ *
+ * @param {number | string} value - The number to format as US Dollar
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @returns {string} The formatted US Dollar currency string
+ *
+ * @example
+ * ```typescript
+ * formatDollar(1234.56);     // "$1,234.56"
+ * formatDollar(1234.56, 0);  // "$1,235"
+ * formatDollar('500');       // "$500.00"
+ * ```
+ */
+export declare function formatDollar(value: number | string, decimals?: number): string;
+/**
+ * Formats a number as British Pound currency
+ *
+ * Convenience function for formatting numbers as British Pound currency with
+ * proper pound symbol placement and formatting conventions.
+ *
+ * @param {number | string} value - The number to format as British Pound
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @returns {string} The formatted British Pound currency string
+ *
+ * @example
+ * ```typescript
+ * formatPound(1234.56);     // "£1,234.56"
+ * formatPound(1234.56, 0);  // "£1,235"
+ * formatPound('500');       // "£500.00"
+ * ```
+ */
+export declare function formatPound(value: number | string, decimals?: number): string;
+/**
+ * Converts a number to its written word representation
+ *
+ * Transforms numeric values into their English word equivalents, which is
+ * particularly useful for legal documents where amounts are often written
+ * in both numeric and word form for clarity and legal precision.
+ *
+ * @param {number | string} num - The number to convert to words
+ * @returns {string} The number expressed in words
+ *
+ * Supported range: Supports numbers from 0 to 999,999,999 with decimal support
+ * Decimal handling: Decimal parts are expressed as "and X cents"
+ *
+ * @example
+ * ```typescript
+ * // Whole numbers
+ * numberToWords(0);        // "zero"
+ * numberToWords(42);       // "forty two"
+ * numberToWords(1500);     // "one thousand five hundred"
+ * numberToWords(1000000);  // "one million"
+ *
+ * // Decimal numbers
+ * numberToWords(123.45);   // "one hundred twenty three and forty five cents"
+ * numberToWords(1000.50);  // "one thousand and fifty cents"
+ *
+ * // String input
+ * numberToWords('456');    // "four hundred fifty six"
+ *
+ * // Negative numbers
+ * numberToWords(-100);     // "negative one hundred"
+ *
+ * // Invalid input
+ * numberToWords('invalid'); // "invalid"
+ * ```
+ */
+export declare function numberToWords(num: number | string): string;
+/**
+ * Formats a number with custom decimal and thousand separators
+ *
+ * Provides flexible number formatting with customizable separators for
+ * different locales and formatting requirements. Useful for international
+ * legal documents that require specific number formatting conventions.
+ *
+ * @param {number | string} value - The number to format
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @param {string} decimalSeparator - Character for decimal separation (default: '.')
+ * @param {string} thousandSeparator - Character for thousand separation (default: ',')
+ * @returns {string} The formatted number string
+ *
+ * @example
+ * ```typescript
+ * // Standard US formatting
+ * formatNumber(1234.56);              // "1,234.56"
+ * formatNumber(1234.56, 3);           // "1,234.560"
+ *
+ * // European formatting (comma as decimal separator)
+ * formatNumber(1234.56, 2, ',', ' '); // "1 234,56"
+ * formatNumber(1234.56, 2, ',', '.'); // "1.234,56"
+ *
+ * // Custom formatting
+ * formatNumber(1234.56, 1, ':', '|'); // "1|234:6"
+ *
+ * // String input
+ * formatNumber('1234.56');            // "1,234.56"
+ * ```
+ */
+export declare function formatNumber(value: number | string, decimals?: number, decimalSeparator?: string, thousandSeparator?: string): string;
+/**
+ * Rounds a number to a specified number of decimal places
+ *
+ * Provides precise rounding functionality for numerical calculations in
+ * legal documents. Uses standard mathematical rounding rules (0.5 rounds up).
+ *
+ * @param {number | string} value - The number to round
+ * @param {number} decimals - Number of decimal places to round to (default: 0)
+ * @returns {number} The rounded number
+ *
+ * @example
+ * ```typescript
+ * // Round to whole numbers
+ * round(1234.56);        // 1235
+ * round(1234.44);        // 1234
+ *
+ * // Round to decimal places
+ * round(1234.5678, 2);   // 1234.57
+ * round(1234.5678, 1);   // 1234.6
+ * round(1234.5678, 3);   // 1234.568
+ *
+ * // String input
+ * round('1234.56', 1);   // 1234.6
+ *
+ * // Invalid input handling
+ * round('invalid');      // 0
+ * ```
+ */
+export declare function round(value: number | string, decimals?: number): number;
+//# sourceMappingURL=number-helpers.d.ts.map

package/dist/helpers/number-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"number-helpers.d.ts","sourceRoot":"","sources":["../../src/helpers/number-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,MAAM,CAOrF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,QAAQ,GAAE,MAAU,EACpB,MAAM,GAAE,OAAc,GACrB,MAAM,CAMR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,QAAQ,GAAE,KAAK,GAAG,KAAK,GAAG,KAAa,EACvC,QAAQ,GAAE,MAAU,GACnB,MAAM,CAmBR;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAE/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAEjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAEhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAuF1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,QAAQ,GAAE,MAAU,EACpB,gBAAgB,GAAE,MAAY,EAC9B,iBAAiB,GAAE,MAAY,GAC9B,MAAM,CAQR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAM1E"}

package/dist/helpers/number-helpers.js

@@ -0,0 +1,406 @@
+"use strict";
+/**
+ * @fileoverview Number Formatting and Conversion Helpers
+ *
+ * This module provides comprehensive number formatting utilities specifically
+ * designed for legal and financial documents. It includes functions for currency
+ * formatting, percentage display, number-to-words conversion, and various
+ * numerical representations commonly used in legal contexts.
+ *
+ * Features:
+ * - Currency formatting with multiple currency support (EUR, USD, GBP)
+ * - Percentage formatting with customizable precision
+ * - Number-to-words conversion for legal document amounts
+ * - Integer formatting with thousand separators
+ * - Flexible number formatting with custom separators
+ * - Rounding utilities for precise calculations
+ *
+ * @example
+ * ```typescript
+ * import { formatCurrency, formatPercent, numberToWords } from './number-helpers';
+ *
+ * // Currency formatting
+ * const amount = formatCurrency(1234.56, 'USD');  // "$1,234.56"
+ *
+ * // Percentage formatting
+ * const rate = formatPercent(0.155, 2);           // "15.50%"
+ *
+ * // Number to words for legal documents
+ * const words = numberToWords(1500);              // "one thousand five hundred"
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatInteger = formatInteger;
+exports.formatPercent = formatPercent;
+exports.formatCurrency = formatCurrency;
+exports.formatEuro = formatEuro;
+exports.formatDollar = formatDollar;
+exports.formatPound = formatPound;
+exports.numberToWords = numberToWords;
+exports.formatNumber = formatNumber;
+exports.round = round;
+/**
+ * Formats a number as an integer with thousand separators
+ *
+ * Converts a number to an integer representation with customizable thousand
+ * separators. Useful for displaying whole numbers in legal documents with
+ * proper formatting for readability.
+ *
+ * @param {number | string} value - The number to format
+ * @param {string} separator - The thousand separator character (default: ',')
+ * @returns {string} The formatted integer string
+ *
+ * @example
+ * ```typescript
+ * // Standard formatting
+ * formatInteger(1234567);        // "1,234,567"
+ * formatInteger(1234567.89);     // "1,234,567" (decimal part removed)
+ *
+ * // Custom separator
+ * formatInteger(1234567, '.');   // "1.234.567"
+ * formatInteger(1234567, ' ');   // "1 234 567"
+ *
+ * // String input
+ * formatInteger('1234567');      // "1,234,567"
+ *
+ * // Invalid input handling
+ * formatInteger('not a number'); // "not a number"
+ * ```
+ */
+function formatInteger(value, separator = ',') {
+    const num = typeof value === 'string' ? parseFloat(value) : value;
+    if (isNaN(num))
+        return String(value);
+    return Math.floor(num)
+        .toString()
+        .replace(/\B(?=(\d{3})+(?!\d))/g, separator);
+}
+/**
+ * Formats a number as a percentage with customizable precision
+ *
+ * Converts a number to percentage format with configurable decimal places
+ * and optional percentage symbol. Useful for displaying rates, discounts,
+ * and other percentage values in legal documents.
+ *
+ * @param {number | string} value - The number to format as percentage
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @param {boolean} symbol - Whether to include the % symbol (default: true)
+ * @returns {string} The formatted percentage string
+ *
+ * @example
+ * ```typescript
+ * // Standard percentage formatting
+ * formatPercent(0.1556);           // "15.56%"
+ * formatPercent(0.1556, 1);        // "15.6%"
+ * formatPercent(0.1556, 0);        // "16%"
+ *
+ * // Without percentage symbol
+ * formatPercent(0.1556, 2, false); // "15.56"
+ *
+ * // String input
+ * formatPercent('0.25');           // "25.00%"
+ *
+ * // Whole number input (treated as percentage)
+ * formatPercent(25);               // "25.00%"
+ * ```
+ */
+function formatPercent(value, decimals = 2, symbol = true) {
+    const num = typeof value === 'string' ? parseFloat(value) : value;
+    if (isNaN(num))
+        return String(value);
+    const formatted = num.toFixed(decimals);
+    return symbol ? `${formatted}%` : formatted;
+}
+/**
+ * Formats a number as currency with support for multiple currencies
+ *
+ * Converts a number to currency format with proper symbol placement,
+ * thousand separators, and decimal precision. Supports EUR, USD, and GBP
+ * with correct formatting conventions for each currency.
+ *
+ * @param {number | string} value - The number to format as currency
+ * @param {'EUR' | 'USD' | 'GBP'} currency - The currency type (default: 'EUR')
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @returns {string} The formatted currency string
+ *
+ * @example
+ * ```typescript
+ * // Euro formatting (symbol after amount)
+ * formatCurrency(1234.56, 'EUR');    // "1,234.56 €"
+ * formatCurrency(1234.56, 'EUR', 0); // "1,235 €"
+ *
+ * // US Dollar formatting (symbol before amount)
+ * formatCurrency(1234.56, 'USD');    // "$1,234.56"
+ *
+ * // British Pound formatting (symbol before amount)
+ * formatCurrency(1234.56, 'GBP');    // "£1,234.56"
+ *
+ * // String input
+ * formatCurrency('1234.56', 'USD');  // "$1,234.56"
+ * ```
+ */
+function formatCurrency(value, currency = 'EUR', decimals = 2) {
+    const num = typeof value === 'string' ? parseFloat(value) : value;
+    if (isNaN(num))
+        return String(value);
+    const symbols = {
+        EUR: '€',
+        USD: '$',
+        GBP: '£',
+    };
+    const formatted = num.toFixed(decimals).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+    const symbol = symbols[currency] || currency;
+    // Different positioning for different currencies
+    if (currency === 'EUR') {
+        return `${formatted} ${symbol}`;
+    }
+    else {
+        return `${symbol}${formatted}`;
+    }
+}
+/**
+ * Formats a number as Euro currency
+ *
+ * Convenience function for formatting numbers as Euro currency with
+ * proper Euro symbol placement and formatting conventions.
+ *
+ * @param {number | string} value - The number to format as Euro
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @returns {string} The formatted Euro currency string
+ *
+ * @example
+ * ```typescript
+ * formatEuro(1234.56);     // "1,234.56 €"
+ * formatEuro(1234.56, 0);  // "1,235 €"
+ * formatEuro('500');       // "500.00 €"
+ * ```
+ */
+function formatEuro(value, decimals = 2) {
+    return formatCurrency(value, 'EUR', decimals);
+}
+/**
+ * Formats a number as US Dollar currency
+ *
+ * Convenience function for formatting numbers as US Dollar currency with
+ * proper dollar symbol placement and formatting conventions.
+ *
+ * @param {number | string} value - The number to format as US Dollar
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @returns {string} The formatted US Dollar currency string
+ *
+ * @example
+ * ```typescript
+ * formatDollar(1234.56);     // "$1,234.56"
+ * formatDollar(1234.56, 0);  // "$1,235"
+ * formatDollar('500');       // "$500.00"
+ * ```
+ */
+function formatDollar(value, decimals = 2) {
+    return formatCurrency(value, 'USD', decimals);
+}
+/**
+ * Formats a number as British Pound currency
+ *
+ * Convenience function for formatting numbers as British Pound currency with
+ * proper pound symbol placement and formatting conventions.
+ *
+ * @param {number | string} value - The number to format as British Pound
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @returns {string} The formatted British Pound currency string
+ *
+ * @example
+ * ```typescript
+ * formatPound(1234.56);     // "£1,234.56"
+ * formatPound(1234.56, 0);  // "£1,235"
+ * formatPound('500');       // "£500.00"
+ * ```
+ */
+function formatPound(value, decimals = 2) {
+    return formatCurrency(value, 'GBP', decimals);
+}
+/**
+ * Converts a number to its written word representation
+ *
+ * Transforms numeric values into their English word equivalents, which is
+ * particularly useful for legal documents where amounts are often written
+ * in both numeric and word form for clarity and legal precision.
+ *
+ * @param {number | string} num - The number to convert to words
+ * @returns {string} The number expressed in words
+ *
+ * Supported range: Supports numbers from 0 to 999,999,999 with decimal support
+ * Decimal handling: Decimal parts are expressed as "and X cents"
+ *
+ * @example
+ * ```typescript
+ * // Whole numbers
+ * numberToWords(0);        // "zero"
+ * numberToWords(42);       // "forty two"
+ * numberToWords(1500);     // "one thousand five hundred"
+ * numberToWords(1000000);  // "one million"
+ *
+ * // Decimal numbers
+ * numberToWords(123.45);   // "one hundred twenty three and forty five cents"
+ * numberToWords(1000.50);  // "one thousand and fifty cents"
+ *
+ * // String input
+ * numberToWords('456');    // "four hundred fifty six"
+ *
+ * // Negative numbers
+ * numberToWords(-100);     // "negative one hundred"
+ *
+ * // Invalid input
+ * numberToWords('invalid'); // "invalid"
+ * ```
+ */
+function numberToWords(num) {
+    const n = typeof num === 'string' ? parseFloat(num) : num;
+    if (isNaN(n))
+        return String(num);
+    if (n === 0)
+        return 'zero';
+    const ones = ['', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine'];
+    const tens = [
+        '',
+        '',
+        'twenty',
+        'thirty',
+        'forty',
+        'fifty',
+        'sixty',
+        'seventy',
+        'eighty',
+        'ninety',
+    ];
+    const teens = [
+        'ten',
+        'eleven',
+        'twelve',
+        'thirteen',
+        'fourteen',
+        'fifteen',
+        'sixteen',
+        'seventeen',
+        'eighteen',
+        'nineteen',
+    ];
+    const convertMillions = (num) => {
+        if (num >= 1000000) {
+            return (convertMillions(Math.floor(num / 1000000)) + ' million ' + convertThousands(num % 1000000));
+        }
+        else {
+            return convertThousands(num);
+        }
+    };
+    const convertThousands = (num) => {
+        if (num >= 1000) {
+            return convertHundreds(Math.floor(num / 1000)) + ' thousand ' + convertHundreds(num % 1000);
+        }
+        else {
+            return convertHundreds(num);
+        }
+    };
+    const convertHundreds = (num) => {
+        let str = '';
+        if (num > 99) {
+            str += ones[Math.floor(num / 100)] + ' hundred ';
+            num %= 100;
+        }
+        if (num > 19) {
+            str += tens[Math.floor(num / 10)] + ' ';
+            num %= 10;
+        }
+        else if (num > 9) {
+            str += teens[num - 10] + ' ';
+            return str.trim();
+        }
+        if (num > 0) {
+            str += ones[num] + ' ';
+        }
+        return str.trim();
+    };
+    if (n < 0) {
+        return 'negative ' + numberToWords(Math.abs(n));
+    }
+    const integerPart = Math.floor(n);
+    const decimalPart = Math.round((n - integerPart) * 100);
+    let result = convertMillions(integerPart);
+    if (decimalPart > 0) {
+        result += ' and ' + convertHundreds(decimalPart) + ' cents';
+    }
+    return result.trim();
+}
+/**
+ * Formats a number with custom decimal and thousand separators
+ *
+ * Provides flexible number formatting with customizable separators for
+ * different locales and formatting requirements. Useful for international
+ * legal documents that require specific number formatting conventions.
+ *
+ * @param {number | string} value - The number to format
+ * @param {number} decimals - Number of decimal places (default: 2)
+ * @param {string} decimalSeparator - Character for decimal separation (default: '.')
+ * @param {string} thousandSeparator - Character for thousand separation (default: ',')
+ * @returns {string} The formatted number string
+ *
+ * @example
+ * ```typescript
+ * // Standard US formatting
+ * formatNumber(1234.56);              // "1,234.56"
+ * formatNumber(1234.56, 3);           // "1,234.560"
+ *
+ * // European formatting (comma as decimal separator)
+ * formatNumber(1234.56, 2, ',', ' '); // "1 234,56"
+ * formatNumber(1234.56, 2, ',', '.'); // "1.234,56"
+ *
+ * // Custom formatting
+ * formatNumber(1234.56, 1, ':', '|'); // "1|234:6"
+ *
+ * // String input
+ * formatNumber('1234.56');            // "1,234.56"
+ * ```
+ */
+function formatNumber(value, decimals = 2, decimalSeparator = '.', thousandSeparator = ',') {
+    const num = typeof value === 'string' ? parseFloat(value) : value;
+    if (isNaN(num))
+        return String(value);
+    const parts = num.toFixed(decimals).split('.');
+    parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, thousandSeparator);
+    return parts.join(decimalSeparator);
+}
+/**
+ * Rounds a number to a specified number of decimal places
+ *
+ * Provides precise rounding functionality for numerical calculations in
+ * legal documents. Uses standard mathematical rounding rules (0.5 rounds up).
+ *
+ * @param {number | string} value - The number to round
+ * @param {number} decimals - Number of decimal places to round to (default: 0)
+ * @returns {number} The rounded number
+ *
+ * @example
+ * ```typescript
+ * // Round to whole numbers
+ * round(1234.56);        // 1235
+ * round(1234.44);        // 1234
+ *
+ * // Round to decimal places
+ * round(1234.5678, 2);   // 1234.57
+ * round(1234.5678, 1);   // 1234.6
+ * round(1234.5678, 3);   // 1234.568
+ *
+ * // String input
+ * round('1234.56', 1);   // 1234.6
+ *
+ * // Invalid input handling
+ * round('invalid');      // 0
+ * ```
+ */
+function round(value, decimals = 0) {
+    const num = typeof value === 'string' ? parseFloat(value) : value;
+    if (isNaN(num))
+        return 0;
+    const factor = Math.pow(10, decimals);
+    return Math.round(num * factor) / factor;
+}
+//# sourceMappingURL=number-helpers.js.map

package/dist/helpers/number-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"number-helpers.js","sourceRoot":"","sources":["../../src/helpers/number-helpers.ts"],"names":[],"mappings":"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"}