Number Module

import Sugar from 'sugar';

// Access Number methods via Sugar.Number
Sugar.Number.random(1, 100);
Sugar.Number.format(12345.67, 2);

// Or extend native numbers for instance methods
Sugar.extend();
(42).times(i => console.log(i));
(1000).bytes();

const Sugar = require('sugar');
Sugar.extend();

/**
 * Generate a random number between two values (inclusive)
 * @param n1 - First number (default: 0)
 * @param n2 - Second number (default: 1)
 * @returns Random number in the specified range
 */
function random(n1?: number, n2?: number): number;

/**
 * Create an array representing a range of numbers
 * @param start - Starting number (default: 0)
 * @param end - Ending number (default: 0)  
 * @returns Array of numbers in the range
 */
function range(start?: number, end?: number): number[];

// Random numbers
Sugar.Number.random();        // 0.0 to 1.0
Sugar.Number.random(1, 6);    // 1 to 6 (dice roll)
Sugar.Number.random(100);     // 0 to 100

// Number ranges
Sugar.Number.range(1, 5);     // [1, 2, 3, 4, 5]
Sugar.Number.range(-2, 2);    // [-2, -1, 0, 1, 2]

// With native extension
Math.random.call(null, 1, 10); // Using Sugar's enhanced random

/**
 * Format number with abbreviated suffixes (K, M, B, etc.)
 * @param instance - Number to format
 * @param precision - Decimal places (default: 0)
 * @returns Abbreviated string representation
 */
function abbr(instance: number, precision?: number): string;

/**
 * Format number as byte size with appropriate units
 * @param instance - Number to format as bytes
 * @param precision - Decimal places (default: 0)
 * @param binary - Use binary (1024) vs decimal (1000) base (default: false)
 * @param units - Unit system to use (default: "bytes")
 * @returns Formatted byte string
 */
function bytes(instance: number, precision?: number, binary?: boolean, units?: string): string;

/**
 * Format number as duration string
 * @param instance - Number of milliseconds
 * @param locale - Locale for formatting (default: current locale)
 * @returns Human-readable duration string
 */
function duration(instance: number, locale?: string): string;

/**
 * Format number with thousands separators
 * @param instance - Number to format
 * @param place - Decimal places (default: 0)
 * @returns Formatted number string
 */
function format(instance: number, place?: number): string;

/**
 * Format number as hexadecimal string
 * @param instance - Number to convert
 * @param pad - Minimum width with zero padding (default: 1)
 * @returns Hexadecimal string representation
 */
function hex(instance: number, pad?: number): string;

/**
 * Format number with metric unit suffixes
 * @param instance - Number to format
 * @param precision - Decimal places (default: 0)
 * @param units - Unit system to use (default: "")
 * @returns Formatted metric string
 */
function metric(instance: number, precision?: number, units?: string): string;

/**
 * Format number as ordinal (1st, 2nd, 3rd, etc.)
 * @param instance - Number to ordinalize
 * @returns Ordinal string representation
 */
function ordinalize(instance: number): string;

/**
 * Pad number with leading zeros or other characters
 * @param instance - Number to pad
 * @param place - Minimum width (default: 1)
 * @param sign - Include sign for positive numbers (default: false)
 * @param base - Number base for conversion (default: 10)
 * @returns Padded string representation
 */
function pad(instance: number, place?: number, sign?: boolean, base?: number): string;

// Abbreviation formatting
(1000).abbr();           // "1K"
(1500000).abbr(1);       // "1.5M"
(2300000000).abbr();     // "2B"

// Byte formatting
(1024).bytes();          // "1KB"
(1536).bytes(1, true);   // "1.5KB" (binary)
(1000).bytes(0, false);  // "1KB" (decimal)

// Duration formatting
(5000).duration();       // "5 seconds"
(3661000).duration();    // "1 hour"
(90000).duration();      // "1 minute"

// Number formatting
(1234567.89).format(2);  // "1,234,567.89"
(1000).format();         // "1,000"

// Hexadecimal formatting
(255).hex();             // "ff"
(10).hex(4);             // "000a"

// Metric formatting
(1000).metric();         // "1k"
(1500000).metric(1, "g"); // "1.5Mg"

// Ordinal formatting
(1).ordinalize();        // "1st"
(22).ordinalize();       // "22nd"
(103).ordinalize();      // "103rd"

// Padding
(5).pad(3);              // "005"
(-5).pad(4, true);       // "-005"
(10).pad(4, false, 2);   // "1010" (binary)

/**
 * Mathematical functions - trigonometric, logarithmic, and basic math
 */
function abs(instance: number): number;
function acos(instance: number): number;
function asin(instance: number): number;
function atan(instance: number): number;
function cos(instance: number): number;
function exp(instance: number): number;
function log(instance: number): number;
function pow(instance: number, power: number): number;
function sin(instance: number): number;
function sqrt(instance: number): number;
function tan(instance: number): number;

/**
 * Rounding functions with optional precision
 * @param instance - Number to round
 * @param precision - Decimal places for precision (default: 0)
 * @returns Rounded number
 */
function ceil(instance: number, precision?: number): number;
function floor(instance: number, precision?: number): number;
function round(instance: number, precision?: number): number;

/**
 * Limit number to maximum value
 * @param instance - Number to cap
 * @param max - Maximum value (default: instance)
 * @returns Number capped at maximum
 */
function cap(instance: number, max?: number): number;

/**
 * Constrain number to range between two values
 * @param instance - Number to clamp
 * @param start - Minimum value (default: instance)
 * @param end - Maximum value (default: instance)
 * @returns Number constrained to range
 */
function clamp(instance: number, start?: number, end?: number): number;

/**
 * Convert number to character using String.fromCharCode
 * @param instance - Character code number
 * @returns Character string
 */
function chr(instance: number): string;

/**
 * Ensure value is a number type
 * @param instance - Value to convert
 * @returns Number representation
 */
function toNumber(instance: number): number;

// Basic math functions
(-5).abs();              // 5
(0.5).acos();           // 1.0471975511965979
(1).asin();             // 1.5707963267948966
(Math.PI/4).cos();      // 0.7071067811865476
(2).log();              // 0.6931471805599453
(2).pow(3);             // 8
(9).sqrt();             // 3

// Precision rounding
(4.6789).ceil(2);       // 4.68
(4.6789).floor(2);      // 4.67
(4.6789).round(2);      // 4.68
(4.6234).round(1);      // 4.6

// Range limiting
(150).cap(100);         // 100
(50).cap(100);          // 50
(150).clamp(25, 100);   // 100
(-10).clamp(0, 50);     // 0
(25).clamp(10, 30);     // 25

// Character conversion
(65).chr();             // "A"
(97).chr();             // "a"
(8364).chr();           // "€"

// Type conversion
(42.7).toNumber();      // 42.7

/**
 * Test if number is even
 * @param instance - Number to test
 * @returns True if even, false if odd
 */
function isEven(instance: number): boolean;

/**
 * Test if number is odd
 * @param instance - Number to test
 * @returns True if odd, false if even
 */
function isOdd(instance: number): boolean;

/**
 * Test if number is an integer
 * @param instance - Number to test
 * @returns True if integer, false if decimal
 */
function isInteger(instance: number): boolean;

/**
 * Test if number is a multiple of another number
 * @param instance - Number to test
 * @param num - Number to check as multiple
 * @returns True if instance is multiple of num
 */
function isMultipleOf(instance: number, num: number): boolean;

// Parity tests
(4).isEven();           // true
(4).isOdd();            // false
(7).isEven();           // false
(7).isOdd();            // true

// Integer test
(42).isInteger();       // true
(42.5).isInteger();     // false
(0).isInteger();        // true

// Multiple test
(15).isMultipleOf(3);   // true
(15).isMultipleOf(4);   // false
(0).isMultipleOf(5);    // true
(8).isMultipleOf(2);    // true

/**
 * Execute function n times, collecting results
 * @param instance - Number of times to execute
 * @param indexMapFn - Function to execute on each iteration
 * @returns Array of results from function calls
 */
function times<T>(instance: number, indexMapFn?: (i: number) => T): T[];

/**
 * Count from instance up to target number
 * @param instance - Starting number
 * @param num - Target number
 * @param step - Step size (default: 1)
 * @param everyFn - Function to execute for each step
 * @returns Array of results
 */
function upto<T>(instance: number, num: number, step?: number, everyFn?: (i: number) => T): T[];

/**
 * Count from instance down to target number
 * @param instance - Starting number
 * @param num - Target number
 * @param step - Step size (default: 1)
 * @param everyFn - Function to execute for each step
 * @returns Array of results
 */
function downto<T>(instance: number, num: number, step?: number, everyFn?: (i: number) => T): T[];

// Execute function multiple times
(3).times(i => console.log(i));        // Logs: 0, 1, 2
(5).times(i => i * 2);                 // Returns: [0, 2, 4, 6, 8]
(4).times();                           // Returns: [0, 1, 2, 3]

// Count up with function
(1).upto(5, 1, i => i * i);           // [1, 4, 9, 16, 25]
(0).upto(10, 2, i => i);              // [0, 2, 4, 6, 8, 10]

// Count down with function  
(5).downto(1, 1, i => `Item ${i}`);   // ["Item 5", "Item 4", "Item 3", "Item 2", "Item 1"]
(10).downto(0, 3, i => i);            // [10, 7, 4, 1]

/**
 * Duration conversion methods - convert number to milliseconds
 */
function day(instance: number): number;
function days(instance: number): number;
function hour(instance: number): number;
function hours(instance: number): number;
function minute(instance: number): number;
function minutes(instance: number): number;
function second(instance: number): number;
function seconds(instance: number): number;
function week(instance: number): number;
function weeks(instance: number): number;
function month(instance: number): number;
function months(instance: number): number;
function year(instance: number): number;
function years(instance: number): number;

/**
 * Create dates relative to now (past)
 */
function dayAgo(instance: number): Date;
function daysAgo(instance: number): Date;
function hourAgo(instance: number): Date;
function hoursAgo(instance: number): Date;
function minuteAgo(instance: number): Date;
function minutesAgo(instance: number): Date;
function secondAgo(instance: number): Date;
function secondsAgo(instance: number): Date;
function weekAgo(instance: number): Date;
function weeksAgo(instance: number): Date;
function monthAgo(instance: number): Date;
function monthsAgo(instance: number): Date;
function yearAgo(instance: number): Date;
function yearsAgo(instance: number): Date;

/**
 * Create dates relative to now (future)
 */
function dayFromNow(instance: number): Date;
function daysFromNow(instance: number): Date;
function hourFromNow(instance: number): Date;
function hoursFromNow(instance: number): Date;
function minuteFromNow(instance: number): Date;
function minutesFromNow(instance: number): Date;
function secondFromNow(instance: number): Date;
function secondsFromNow(instance: number): Date;
function weekFromNow(instance: number): Date;
function weeksFromNow(instance: number): Date;
function monthFromNow(instance: number): Date;
function monthsFromNow(instance: number): Date;
function yearFromNow(instance: number): Date;
function yearsFromNow(instance: number): Date;

/**
 * Create dates relative to specific date (after)
 * @param instance - Number of units
 * @param date - Reference date
 * @param options - Date creation options
 * @returns Date after the reference date
 */
function dayAfter(instance: number, date: Date, options?: any): Date;
function daysAfter(instance: number, date: Date, options?: any): Date;
function hourAfter(instance: number, date: Date, options?: any): Date;
function hoursAfter(instance: number, date: Date, options?: any): Date;
function minuteAfter(instance: number, date: Date, options?: any): Date;
function minutesAfter(instance: number, date: Date, options?: any): Date;
function secondAfter(instance: number, date: Date, options?: any): Date;
function secondsAfter(instance: number, date: Date, options?: any): Date;
function weekAfter(instance: number, date: Date, options?: any): Date;
function weeksAfter(instance: number, date: Date, options?: any): Date;
function monthAfter(instance: number, date: Date, options?: any): Date;
function monthsAfter(instance: number, date: Date, options?: any): Date;
function yearAfter(instance: number, date: Date, options?: any): Date;
function yearsAfter(instance: number, date: Date, options?: any): Date;

/**
 * Create dates relative to specific date (before)
 * @param instance - Number of units
 * @param date - Reference date
 * @param options - Date creation options
 * @returns Date before the reference date
 */
function dayBefore(instance: number, date: Date, options?: any): Date;
function daysBefore(instance: number, date: Date, options?: any): Date;
function hourBefore(instance: number, date: Date, options?: any): Date;
function hoursBefore(instance: number, date: Date, options?: any): Date;
function minuteBefore(instance: number, date: Date, options?: any): Date;
function minutesBefore(instance: number, date: Date, options?: any): Date;
function secondBefore(instance: number, date: Date, options?: any): Date;
function secondsBefore(instance: number, date: Date, options?: any): Date;
function weekBefore(instance: number, date: Date, options?: any): Date;
function weeksBefore(instance: number, date: Date, options?: any): Date;
function monthBefore(instance: number, date: Date, options?: any): Date;
function monthsBefore(instance: number, date: Date, options?: any): Date;
function yearBefore(instance: number, date: Date, options?: any): Date;
function yearsBefore(instance: number, date: Date, options?: any): Date;

// Duration conversion (returns milliseconds)
(1).day();              // 86400000 (24 * 60 * 60 * 1000)
(2).hours();            // 7200000 (2 * 60 * 60 * 1000)
(30).minutes();         // 1800000 (30 * 60 * 1000)
(5).seconds();          // 5000

// Dates relative to now (past)
(2).daysAgo();          // Date 2 days ago
(3).hoursAgo();         // Date 3 hours ago
(1).weekAgo();          // Date 1 week ago

// Dates relative to now (future)
(5).daysFromNow();      // Date 5 days from now
(2).hoursFromNow();     // Date 2 hours from now
(1).monthFromNow();     // Date 1 month from now

// Dates relative to specific date
const baseDate = new Date('2023-01-15');
(3).daysAfter(baseDate);    // 2023-01-18
(1).weekBefore(baseDate);   // 2023-01-08
(6).monthsAfter(baseDate);  // 2023-07-15

// Chaining with date operations
const futureDate = (2).weeksFromNow();
const pastDate = (5).daysBefore(futureDate);

/**
 * Map function type for transformation operations
 */
type mapFn<T, U> = (item: T, index?: number) => U;