# 📦 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. ---