Number Operations

/**
 * Precise addition avoiding floating-point errors
 * @param num1 - First number
 * @param num2 - Second number
 * @returns Sum with correct precision
 */
function add(num1: number, num2: number): number;

/**
 * Precise subtraction avoiding floating-point errors
 * @param num1 - First number (minuend)
 * @param num2 - Second number (subtrahend)
 * @returns Difference with correct precision
 */
function subtract(num1: number, num2: number): number;

/**
 * Precise multiplication avoiding floating-point errors
 * @param num1 - First number
 * @param num2 - Second number
 * @returns Product with correct precision
 */
function multiply(num1: number, num2: number): number;

/**
 * Precise division avoiding floating-point errors
 * @param num1 - Dividend
 * @param num2 - Divisor
 * @returns Quotient with correct precision
 */
function divide(num1: number, num2: number): number;

/**
 * Round number to specified decimal places
 * @param num - Number to round
 * @param digits - Number of decimal places (default: 0)
 * @returns Rounded number
 */
function round(num: number, digits?: number): number;

/**
 * Ceiling (round up) to specified decimal places
 * @param num - Number to round up
 * @param digits - Number of decimal places (default: 0)
 * @returns Rounded up number
 */
function ceil(num: number, digits?: number): number;

/**
 * Floor (round down) to specified decimal places
 * @param num - Number to round down
 * @param digits - Number of decimal places (default: 0)
 * @returns Rounded down number
 */
function floor(num: number, digits?: number): number;

/**
 * Format number to fixed decimal places
 * @param num - Number, string, or null to format
 * @param digits - Number of decimal places (optional)
 * @returns Formatted number string
 */
function toFixed(num: number | string | null, digits?: number): string;

/**
 * Convert value to integer
 * @param num - Value to convert
 * @returns Integer value or NaN if conversion fails
 */
function toInteger(num: any): number;

/**
 * Convert value to number
 * @param num - Value to convert
 * @returns Number value or NaN if conversion fails
 */
function toNumber(num: any): number;

/**
 * Convert number to string representation
 * @param num - Number to convert
 * @returns String representation of number
 */
function toNumberString(num: number): string;

/**
 * Add thousand separators to number with comprehensive formatting options
 * @param num - Number or string to format
 * @param options - Formatting options
 * @returns Formatted number string with separators
 */
function commafy(num: number | string, options?: CommafyOptions): string;

interface CommafyOptions {
  /** Number of digits in each group (default: 3) */
  spaceNumber?: number;
  /** Separator character (default: ',') */
  separator?: string;
  /** Number of decimal places to display (default: null) */
  digits?: number;
  /** Whether to round the number (default: true) */
  round?: boolean;
  /** Whether to round up (ceil) */
  ceil?: boolean;
  /** Whether to round down (floor) */
  floor?: boolean;
}

/**
 * Calculate sum of array values
 * @param array - Array of numbers or objects
 * @param iterate - Optional function to extract numeric values
 * @param context - Optional context for iterator
 * @returns Sum of all values
 */
function sum<T, C = any>(
  array: T[], 
  iterate?: (this: C, item: T, index: number, array: T[]) => number, 
  context?: C
): number;

/**
 * Calculate mean (average) of array values
 * @param array - Array of numbers or objects
 * @param iterate - Optional function to extract numeric values
 * @param context - Optional context for iterator
 * @returns Mean of all values
 */
function mean<T, C = any>(
  array: T[], 
  iterate?: (this: C, item: T, index: number, array: T[]) => number, 
  context?: C
): number;

/**
 * Find minimum value in array
 * @param array - Array of numbers or objects
 * @param iterate - Optional function to extract comparable values
 * @returns Minimum value or undefined for empty array
 */
function min<T>(array: T[], iterate?: (item: T) => any): T | undefined;

/**
 * Find maximum value in array
 * @param array - Array of numbers or objects
 * @param iterate - Optional function to extract comparable values
 * @returns Maximum value or undefined for empty array
 */
function max<T>(array: T[], iterate?: (item: T) => any): T | undefined;

/**
 * Generate random number within range
 * @param min - Minimum value (inclusive)
 * @param max - Maximum value (inclusive)
 * @returns Random number between min and max
 */
function random(min: number, max: number): number;

/**
 * Generate random number from 0 to max
 * @param max - Maximum value (inclusive)
 * @returns Random number between 0 and max
 */
function random(max: number): number;

/**
 * Generate random number from 0 to 1
 * @returns Random number between 0 and 1
 */
function random(): number;

import { 
  add, subtract, multiply, divide, round, commafy, 
  sum, mean, min, max, random, toFixed 
} from 'xe-utils';

// Precise arithmetic (solves 0.1 + 0.2 = 0.30000000000000004)
console.log(add(0.1, 0.2)); // 0.3 (exact)
console.log(subtract(1.5, 1.2)); // 0.3 (exact)
console.log(multiply(0.3, 3)); // 0.9 (exact)
console.log(divide(0.9, 3)); // 0.3 (exact)

// Rounding with precision
console.log(round(3.14159, 2)); // 3.14
console.log(round(3.14159, -1)); // 0 (round to nearest 10)

// Number formatting
console.log(commafy(1234567.89)); // '1,234,567.89'
console.log(commafy(1234567.89, { separator: ' ', fixed: 2 })); // '1 234 567.89'

// Aggregate calculations
const scores = [85, 92, 78, 96, 89];
console.log(sum(scores)); // 440
console.log(mean(scores)); // 88

const products = [
  { name: 'A', price: 10.99 },
  { name: 'B', price: 25.50 },
  { name: 'C', price: 8.75 }
];

const totalPrice = sum(products, item => item.price); // 45.24
const avgPrice = mean(products, item => item.price); // 15.08

// Min/Max operations
console.log(min(scores)); // 78
console.log(max(scores)); // 96

const cheapest = min(products, item => item.price); // { name: 'C', price: 8.75 }
const mostExpensive = max(products, item => item.price); // { name: 'B', price: 25.50 }

// Random numbers
console.log(random()); // Random between 0-1
console.log(random(10)); // Random between 0-10
console.log(random(5, 15)); // Random between 5-15

// Financial calculations example
function calculateTax(amount, rate) {
  const tax = multiply(amount, divide(rate, 100));
  const total = add(amount, tax);
  
  return {
    subtotal: commafy(amount, { fixed: 2 }),
    tax: commafy(tax, { fixed: 2 }),
    total: commafy(total, { fixed: 2 })
  };
}

console.log(calculateTax(99.99, 8.25));
// { subtotal: '99.99', tax: '8.25', total: '108.24' }