Core Functionality

/**
 * Create a numeral instance from various input types
 * @param input - Number, string, or existing numeral instance to convert
 * @returns New Numeral instance
 */
function numeral(input: number | string | Numeral | null | undefined): Numeral;

const numeral = require('numeral');

// From numbers
const num1 = numeral(1234.56);
console.log(num1.value()); // 1234.56

// From strings
const num2 = numeral('1,234.56');
console.log(num2.value()); // 1234.56

// From formatted strings
const num3 = numeral('$1,234.56');
console.log(num3.value()); // 1234.56

// From existing numerals
const num4 = numeral(num1);
console.log(num4.value()); // 1234.56

// Edge cases
console.log(numeral(null).value()); // null
console.log(numeral(0).value()); // 0
console.log(numeral('not a number').value()); // null

/**
 * Get the numeric value of the numeral instance
 * @returns The numeric value or null
 */
value(): number | null;

/**
 * Get the original input value used to create this instance
 * @returns The original input value
 */
input(): any;

/**
 * Set a new numeric value for this instance
 * @param value - New numeric value to set
 * @returns This instance for chaining
 */
set(value: number): Numeral;

/**
 * Create a copy of this numeral instance
 * @returns New Numeral instance with the same value
 */
clone(): Numeral;

const num = numeral(1234.56);

// Get value and input
console.log(num.value()); // 1234.56
console.log(num.input()); // 1234.56

// Set new value
num.set(9876.54);
console.log(num.value()); // 9876.54

// Clone instance
const copy = num.clone();
console.log(copy.value()); // 9876.54

/**
 * Add a value to the current number with precision handling
 * @param value - Number to add
 * @returns This instance for chaining
 */
add(value: number): Numeral;

/**
 * Subtract a value from the current number with precision handling
 * @param value - Number to subtract  
 * @returns This instance for chaining
 */
subtract(value: number): Numeral;

/**
 * Multiply the current number by a value with precision handling
 * @param value - Number to multiply by
 * @returns This instance for chaining
 */
multiply(value: number): Numeral;

/**
 * Divide the current number by a value with precision handling
 * @param value - Number to divide by
 * @returns This instance for chaining
 */
divide(value: number): Numeral;

/**
 * Calculate the absolute difference between current number and a value
 * @param value - Number to calculate difference with
 * @returns Absolute difference as a regular number (not chainable)
 */
difference(value: number): number;

const numeral = require('numeral');

// Chained operations
const result = numeral(100)
    .add(50)          // 150
    .multiply(2)      // 300
    .subtract(25)     // 275
    .divide(5);       // 55
console.log(result.value()); // 55

// Individual operations
const num = numeral(10.5);
num.add(5.7);
console.log(num.value()); // 16.2 (precision handled correctly)

// Difference calculation
const diff = numeral(100).difference(75);
console.log(diff); // 25

/**
 * Format the number using a format string and optional rounding function
 * @param inputString - Format string (optional, uses default if not provided)
 * @param roundingFunction - Custom rounding function (optional, uses Math.round)
 * @returns Formatted string representation
 */
format(inputString?: string, roundingFunction?: Function): string;

const num = numeral(1234.567);

// Basic formatting
console.log(num.format('0')); // "1235" (rounded)
console.log(num.format('0.0')); // "1234.6"
console.log(num.format('0,0')); // "1,235"
console.log(num.format('0,0.00')); // "1,234.57"

// Custom rounding
console.log(num.format('0.0', Math.floor)); // "1234.5"
console.log(num.format('0.0', Math.ceil)); // "1234.6"

// Default format (if set)
numeral.defaultFormat('0,0.00');
console.log(num.format()); // "1,234.57"

/**
 * Check if an object is a numeral instance
 * @param obj - Object to check
 * @returns True if object is a Numeral instance
 */
numeral.isNumeral(obj: any): boolean;

/**
 * Library version string
 */
numeral.version: string; // "2.0.6"

/**
 * Validate if a string can be parsed as a number in the given culture
 * @param val - String value to validate
 * @param culture - Optional culture/locale code for validation context
 * @returns True if the string is a valid number format
 */
numeral.validate(val: string, culture?: string): boolean;

// Instance check
const num = numeral(123);
console.log(numeral.isNumeral(num)); // true
console.log(numeral.isNumeral(123)); // false

// Version
console.log(numeral.version); // "2.0.6"

// Validation
console.log(numeral.validate('1,234.56')); // true
console.log(numeral.validate('$1,234.56')); // true  
console.log(numeral.validate('not a number')); // false
console.log(numeral.validate('1.234,56', 'de')); // true (German format)

/**
 * Reset all configuration options to their default values
 */
numeral.reset(): void;

/**
 * Set or get the default format string used when no format is specified
 * @param format - Format string to set as default
 */
numeral.defaultFormat(format: string): void;

/**
 * Set custom format string for zero values
 * @param format - Format string for zero values, or null to use default
 */
numeral.zeroFormat(format?: string | null): void;

/**
 * Set custom format string for null values  
 * @param format - Format string for null values, or null to use default
 */
numeral.nullFormat(format?: string | null): void;

// Set custom zero format
numeral.zeroFormat('N/A');
console.log(numeral(0).format()); // "N/A"

// Set custom null format
numeral.nullFormat('--');
console.log(numeral(null).format()); // "--"

// Set default format
numeral.defaultFormat('0,0.00');
console.log(numeral(1234.5).format()); // "1,234.50"

// Reset all settings
numeral.reset();
console.log(numeral(0).format()); // "0" (back to default)

/**
 * Access to current configuration options
 */
numeral.options: ConfigOptions;

/**
 * Access to registered format plugins
 */
numeral.formats: Record<string, FormatPlugin>;

/**
 * Access to registered locales
 */
numeral.locales: Record<string, LocaleData>;

/**
 * Access to internal utility functions (intended for internal use)
 */
numeral._: InternalUtilities;

interface ConfigOptions {
  currentLocale: string;
  zeroFormat: string | null;
  nullFormat: string | null;
  defaultFormat: string;
  scalePercentBy100: boolean;
}

interface InternalUtilities {
  numberToFormat: (value: number, format: string, roundingFunction: Function) => string;
  stringToNumber: (string: string) => number | null;
  isNaN: (value: any) => boolean;
  includes: (string: string, search: string) => boolean;
  insert: (string: string, subString: string, start: number) => string;
  reduce: (array: any[], callback: Function, initialValue?: any) => any;
  multiplier: (x: number) => number;
  correctionFactor: (...args: number[]) => number;
  toFixed: (value: number, maxDecimals: number, roundingFunction: Function, optionals?: number) => string;
}

// Check current options
console.log(numeral.options.currentLocale); // "en"
console.log(numeral.options.defaultFormat); // "0,0"

// See available formats
console.log(Object.keys(numeral.formats)); 
// ["bps", "bytes", "currency", "exponential", "ordinal", "percentage", "time"]

// See available locales  
console.log(Object.keys(numeral.locales)); 
// ["en", ...] (plus any loaded locales)

// Internal utilities (not recommended for external use)
console.log(typeof numeral._); // "object"
console.log(typeof numeral._.numberToFormat); // "function"
console.log(typeof numeral._.stringToNumber); // "function"