@puraty/smart-number-formatter

A TypeScript-first number formatting utility designed for simplicity and security. It leverages the native JavaScript Intl.NumberFormat API to easily handle currency, percentage, and automatic K/M/B (compact/abbreviated) notation.

Installation

npm install @puraty/smart-number-formatter

or

yarn add @puraty/smart-number-formatter

Usage

The library exports a single, type-safe function: smartNumberFormat.

1. Abbreviated Notation (K/M/B) Use style: 'abbreviate' to automatically apply locale-specific compact notation (e.g., K for thousands, M for millions, B for billions).

import { smartNumberFormat } from '@puraty/smart-number-formatter';

// English locale abbreviation (1.2M)
console.log(smartNumberFormat(1234567, { style: 'abbreviate', locale: 'en-US' })); 
// => "1.2M"

// French locale abbreviation (1,2 M)
console.log(smartNumberFormat(1234567, { style: 'abbreviate', locale: 'fr-FR' })); 
// => "1,2 M" 

// Abbreviation with no fraction digits (1M)
console.log(smartNumberFormat(1000000, { 
    style: 'abbreviate', 
    maximumFractionDigits: 0 
})); 
// => "1M"

2. Currency, Percent, and Decimal Formatting Standard formatting options are supported with type safety.

import { smartNumberFormat } from '@puraty/smart-number-formatter';

// Currency formatting (Euro in France)
console.log(smartNumberFormat(9876.543, { 
    style: 'currency', 
    currency: 'EUR', 
    locale: 'fr-FR',
    maximumFractionDigits: 2
})); 
// => "9 876,54 €" 

// Currency formatting (US Dollar)
console.log(smartNumberFormat(12345.67, { 
    style: 'currency', 
    currency: 'USD', 
    locale: 'en-US'
})); 
// => "$12,345.67" 

// Percentage formatting
console.log(smartNumberFormat(0.75, { style: 'percent' })); 
// => "75%"

// Always show sign
console.log(smartNumberFormat(-1000, { signDisplay: 'always' })); 
// => "-1,000"

API Reference

smartNumberFormat(value: number, options?: SmartFormatOptions): string

Formats a number according to the specified locale and style options.

| Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | value | number | N/A | The numeric value to format. | | options | SmartFormatOptions | {} | The optional object for formatting. |

SmartFormatOptions Interface

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | style | 'decimal' \| 'currency' \| 'percent' \| 'abbreviate' | 'decimal' | The formatting style. 'abbreviate' enables K/M/B compact notation. | | locale | string | 'en-US' | The locale string (e.g., 'en-US', 'fr-FR', 'es-ES'). | | currency | string | N/A | The currency code (e.g., 'USD', 'EUR', 'GBP'). Required if style is 'currency'. | | maximumFractionDigits | number | 1 (if style is 'abbreviate') | The maximum number of digits after the decimal point. | | signDisplay | 'auto' \| 'always' \| 'exceptZero' \| 'never' | 'auto' | Controls the display of the sign (+/-). |

Returns: A secure, alphanumeric, URL-safe string.

License

This project is licensed under the ISC License. See the LICENSE file for details.

Contributing

Contributions, bug reports, and feature suggestions are always welcome! Please feel free to open an Issue or submit a Pull Request.