nambas/README.md

A simple JS library to format numbers using in-built Intl.NumberFormat

<p align="center"><a href="https://www.npmjs.com/package/nambas"> <img src="https://img.shields.io/npm/v/nambas?style=for-the-badge" alt="npm version"> </a> <a href="https://www.npmjs.com/package/nambas"> <img src="https://img.shields.io/npm/dm/nambas?style=for-the-badge" alt="npm downloads"> </a> <a href="https://github.com/your-repo/nambas/blob/main/LICENSE"> <img src="https://img.shields.io/npm/l/nambas?style=for-the-badge" alt="License"> </a> <a href="https://www.npmjs.com/package/nambas"> <img src="https://img.shields.io/npm/types/nambas?style=for-the-badge" alt="Types Included"> </a> <img src="https://img.shields.io/badge/Tree%20Shakeable-Yes-success?style=for-the-badge" alt="Tree Shakeable"></p>



# 📦 Nambas

A **modular**, **tree-shakeable**, flexible number formatter for JavaScript and TypeScript — powered by `Intl.NumberFormat`.  
Format **thousands**, **currency**, **percentages**, and more with easy strings or config objects!

---

## ✨ Features
- **Simple** and **recognizable** formatting strings (like `"0,0"`, `"0,0 %"`)
- Supports **decimal**, **currency**, **percent** styles
- **Locale-aware** output (e.g., French, German, Arabic formats)
- **Built for modularity and tree shaking**
- **Fully typed** (TypeScript-ready)
- **No dependencies**

---

## 📦 Installation

```bash
npm install nambas
# or
yarn add nambas
```

---

## 🚀 Usage

```javascript
import format from 'nambas';
```

### Example

```javascript
format(1234); 
// "1,234"

format(0.234, "0.0%");
// "23.4%"

format(1234, { currency: 'EUR', style: 'currency', locale: 'de-DE' });
// "1.234,00 €"
```

---

## 📚 API

```typescript
format(value: TNambaParameter, options?: IFormatOptions): string;
format(value: TNambaParameter, nambaFormat?: TNambaFormat | string): string;
```

- `value`: A number or numeric string to format
- `options`: (optional) Object or format string

---

## 🔥 Recognizable Formats

| Format Name         | Format String | Example Input | Example Output |
|:--------------------|:--------------|:--------------|:---------------|
| **Thousands**        | `'0,0'`        | `12345`       | `"12,345"`      |
| **French Percentage**| `'0,0 %'`      | `0.123`       | `"12,3 %"` (in fr-FR) |
| **German Percentage**| `'0 %'`        | `0.456`       | `"46 %"` (in de-DE) |

---

## 📈 Format String Examples

| Format String   | Meaning                         | Input      | Output           |
|:----------------|:---------------------------------|:-----------|:-----------------|
| `"0,0"`          | Thousands separator             | `1234567`  | `"1,234,567"`     |
| `"0.00"`         | 2 decimals, no separator         | `1234.56`  | `"1234.56"`       |
| `"0,0.00"`       | Thousands + 2 decimals           | `1234.56`  | `"1,234.56"`      |
| `"0.0%"`         | Percent with 1 decimal           | `0.452`    | `"45.2%"`         |
| `"0,0 %"`        | French-style percent             | `0.1234`   | `"12,3 %"` (fr-FR) |
| `"0 %"`          | German-style percent             | `0.4567`   | `"46 %"` (de-DE) |
| `"0.000"`        | 3 decimal places                 | `12.34567` | `"12.346"`        |
| `"0,0.0"`        | Thousands + 1 decimal            | `12345.67` | `"12,345.7"`      |

---

## 🛠️ Object Option Examples

| Options                                  | Input      | Output             |
|:-----------------------------------------|:-----------|:-------------------|
| `{ locale: 'en-US' }`                     | `1234.56`  | `"1,234.56"`        |
| `{ locale: 'de-DE' }`                     | `1234.56`  | `"1.234,56"`        |
| `{ locale: 'fr-FR', decimals: 2 }`         | `1234.56`  | `"1 234,56"`         |
| `{ style: 'percent' }`                    | `0.85`     | `"85%"`             |
| `{ style: 'currency', currency: 'USD' }`  | `1234.56`  | `"$1,234.56"`       |
| `{ style: 'currency', currency: 'EUR', locale: 'de-DE' }` | `1234.56` | `"1.234,56 €"` |
| `{ style: 'currency', currency: 'JPY' }`  | `1234.56`  | `"¥1,235"`          |
| `{ locale: 'ar-EG', style: 'percent' }`    | `0.5`      | `"٥٠٪"`             |

---

## ✍️ Quick Tip: Auto-detect Format Strings

You can pass simple string patterns like `"0,0"`, `"0.00%"`, `"0,0 %"` and `nambas` will **auto-detect**:
- Decimal separator (`,` or `.`)
- Style (`decimal` or `percent`)
- Number of decimals

No manual setup needed!

```javascript
format(0.75, "0.0%");
// "75.0%"
```

---

## 📜 License

MIT License.

---

# 🎯 Summary
**Nambas** makes it super easy to **format numbers smartly** across locales with modern tree-shaking and TypeScript love.  
Just `format(value, "pattern")` or `format(value, { options })`. Simple and clean.

---