# 🧮 @ubuligan/number-formatter

A lightweight and elegant TypeScript utility for formatting numbers with thousand separators and decimal precision — simple, fast, and locale-friendly.

---

## 🚀 Features

✅ Formats both **numbers** and **numeric strings**
✅ Adds **thousand separators** automatically
✅ Keeps **two decimal digits** (for financial or price displays)
✅ Locale-aware (defaults to **French locale → `fr-FR`**)
✅ Written in **TypeScript** with full type definitions
✅ Safe — automatically handles invalid or null values

---

## 📦 Installation

```bash
npm install @ubuligan/number-formatter

or

yarn add @ubuligan/number-formatter

🧠 Usage

import { formatNumber, formatThousand } from "@ubuligan/number-formatter";

// Format with two decimal digits
console.log(formatNumber(12345.6));     // "12 345,60"

// Format as integer with thousand separators
console.log(formatThousand(987654321)); // "987 654 321"

// Handle string input safely
console.log(formatNumber("4567.8"));    // "4 567,80"

// Handle invalid input (defaults to 0)
console.log(formatNumber(undefined));   // "0,00"

⚙️ API Reference

formatNumber(value: number | string): string

Formats a number or numeric string with two decimal places and space-separated thousands, e.g. 12 345,67.

Example:

formatNumber(12345.678); // "12 345,68"

formatThousand(value: number | string): string

Formats a number or numeric string with thousand separators only, no decimals are shown.

Example:

formatThousand(1234567); // "1 234 567"

🌍 Localization (optional tip)

This package uses the fr-FR locale internally to produce:

• , as the decimal separator
• (space) as the thousand separator

If you want to adapt it to another locale (e.g., en-US), you can easily extend it in your own project:

const formatNumberCustom = (value: number | string, locale = "en-US") => {
  const num = Number(value) || 0;
  return num.toLocaleString(locale, {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  });
};

console.log(formatNumberCustom(12345.6, "en-US")); // "12,345.60"

🧪 Example Output

| Input | formatNumber Output | formatThousand Output | | ----------- | --------------------- | ----------------------- | | 12345.678 | "12 345,68" | "12 346" | | "4567.8" | "4 567,80" | "4 568" | | 987654321 | "987 654 321,00" | "987 654 321" | | null | "0,00" | "0" |

🛠️ Development

Build the package

npm run build

Test locally

node dist/index.js

📘 Project Structure

number-formatter/
├── src/
│   └── index.ts
├── dist/
├── package.json
├── tsconfig.json
└── README.md

👨‍💻 Author

Javid Salimov 📦 npm: @ubuligan 💻 GitHub: ubuligan

📄 License

MIT License © 2025 Javid Salimov

⭐ Support

If you like this package, please consider giving it a star on GitHub — it helps a lot!