nig-utils/dist/money/index.d.ts

A fully-typed, production-grade utility library for Nigerian developers

/**
 * Nigerian Money Utilities - Naira Formatting & Currency Helpers
 *
 * @fileoverview Comprehensive utilities for Nigerian currency operations
 * @author Ademuyiwa Johnson
 * @license MIT
 */
type CurrencyFormat = 'standard' | 'compact' | 'words' | 'kobo';
type CurrencySymbol = '₦' | 'NGN' | 'N';
interface MoneyFormatOptions {
    symbol?: CurrencySymbol;
    compact?: boolean;
    decimals?: number;
    showKobo?: boolean;
    locale?: string;
}
interface MoneyParseOptions {
    allowNegative?: boolean;
    defaultCurrency?: CurrencySymbol;
    strict?: boolean;
}
/**
 * Formats a number as Nigerian Naira
 *
 * @public
 * @param amount - The amount to format
 * @param options - Formatting options
 * @returns Formatted Naira string
 *
 * @example
 * ```typescript
 * formatNaira(1500); // "₦1,500.00"
 * formatNaira(1500, { compact: true }); // "₦1.5K"
 * formatNaira(1500, { symbol: 'NGN' }); // "NGN 1,500.00"
 * formatNaira(1500, { showKobo: true }); // "₦1,500.00"
 * ```
 */
declare function formatNaira(amount: number, options?: MoneyFormatOptions): string;
/**
 * Parses a formatted Naira string back to number
 *
 * @public
 * @param text - The formatted money string to parse
 * @param options - Parsing options
 * @returns Parsed amount as number
 *
 * @example
 * ```typescript
 * parseNaira('₦1,500.00'); // 1500
 * parseNaira('NGN 2.5K'); // 2500
 * parseNaira('₦1.5M'); // 1500000
 * parseNaira('₦1,500.50'); // 1500.5
 * ```
 */
declare function parseNaira(text: string, options?: MoneyParseOptions): number;
/**
 * Converts Naira to Kobo
 *
 * @public
 * @param naira - Amount in Naira
 * @returns Amount in Kobo
 *
 * @example
 * ```typescript
 * nairaToKobo(1.50); // 150
 * nairaToKobo(1000); // 100000
 * ```
 */
declare function nairaToKobo(naira: number): number;
/**
 * Converts Kobo to Naira
 *
 * @public
 * @param kobo - Amount in Kobo
 * @returns Amount in Naira
 *
 * @example
 * ```typescript
 * koboToNaira(150); // 1.50
 * koboToNaira(100000); // 1000
 * ```
 */
declare function koboToNaira(kobo: number): number;
/**
 * Formats amount in words (spells out the amount)
 *
 * @public
 * @param amount - Amount to spell out
 * @returns Amount spelled out in words
 *
 * @example
 * ```typescript
 * spellOutNaira(1500); // "One thousand, five hundred Naira only"
 * spellOutNaira(1500.50); // "One thousand, five hundred Naira and fifty Kobo only"
 * ```
 */
declare function spellOutNaira(amount: number): string;
/**
 * Validates if a string is a valid Naira amount
 *
 * @public
 * @param text - Text to validate
 * @returns True if valid Naira format
 *
 * @example
 * ```typescript
 * isValidNairaAmount('₦1,500.00'); // true
 * isValidNairaAmount('NGN 2.5K'); // true
 * isValidNairaAmount('invalid'); // false
 * ```
 */
declare function isValidNairaAmount(text: string): boolean;
/**
 * Calculates percentage of an amount
 *
 * @public
 * @param amount - Base amount
 * @param percentage - Percentage to calculate
 * @returns Calculated amount
 *
 * @example
 * ```typescript
 * calculatePercentage(1000, 15); // 150
 * calculatePercentage(5000, 7.5); // 375
 * ```
 */
declare function calculatePercentage(amount: number, percentage: number): number;
/**
 * Adds VAT (Value Added Tax) to an amount
 *
 * @public
 * @param amount - Base amount
 * @param vatRate - VAT rate (default: 7.5% for Nigeria)
 * @returns Amount with VAT
 *
 * @example
 * ```typescript
 * addVAT(1000); // 1075 (7.5% VAT)
 * addVAT(1000, 5); // 1050 (5% VAT)
 * ```
 */
declare function addVAT(amount: number, vatRate?: number): number;
/**
 * Removes VAT from an amount
 *
 * @public
 * @param amount - Amount including VAT
 * @param vatRate - VAT rate (default: 7.5% for Nigeria)
 * @returns Amount without VAT
 *
 * @example
 * ```typescript
 * removeVAT(1075); // 1000
 * removeVAT(1050, 5); // 1000
 * ```
 */
declare function removeVAT(amount: number, vatRate?: number): number;
/**
 * Formats a range of amounts
 *
 * @public
 * @param min - Minimum amount
 * @param max - Maximum amount
 * @param options - Formatting options
 * @returns Formatted range string
 *
 * @example
 * ```typescript
 * formatRange(1000, 5000); // "₦1,000.00 - ₦5,000.00"
 * formatRange(1000, 5000, { compact: true }); // "₦1K - ₦5K"
 * ```
 */
declare function formatRange(min: number, max: number, options?: MoneyFormatOptions): string;
/**
 * Rounds amount to nearest Naira
 *
 * @public
 * @param amount - Amount to round
 * @returns Rounded amount
 *
 * @example
 * ```typescript
 * roundToNaira(1500.75); // 1501
 * roundToNaira(1500.25); // 1500
 * ```
 */
declare function roundToNaira(amount: number): number;
/**
 * Rounds amount to nearest Kobo
 *
 * @public
 * @param amount - Amount to round
 * @returns Rounded amount
 *
 * @example
 * ```typescript
 * roundToKobo(1500.75); // 1500.75
 * roundToKobo(1500.123); // 1500.12
 * ```
 */
declare function roundToKobo(amount: number): number;

export { type CurrencyFormat, type CurrencySymbol, type MoneyFormatOptions, type MoneyParseOptions, addVAT, calculatePercentage, formatNaira, formatRange, isValidNairaAmount, koboToNaira, nairaToKobo, parseNaira, removeVAT, roundToKobo, roundToNaira, spellOutNaira };