### Install and Run Examples

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Navigate to the examples directory, install dependencies, and run a script. This can be used for currency, numbers, words, dates, text, bidi, or validation examples.

```sh
cd examples && npm install
node currency.mjs   # or numbers / words / dates / text / bidi / validate
```

--------------------------------

### Install and Run Examples

Source: https://github.com/cc1a2b/arabicfmt/blob/main/examples/README.md

Instructions for installing the arabicfmt package and running the provided examples using npm scripts or direct node execution.

```bash
cd examples
npm install        # installs arabicfmt ^0.1.2 from npm
node currency.mjs  # or any file below
```

```bash
npm run currency   # node currency.mjs
npm run all        # runs every example in sequence
```

--------------------------------

### Run Arabicfmt Demo Locally

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Navigate to the demo directory, install dependencies, and start the development server to run the Arabicfmt library locally.

```sh
cd demo && npm install && npm run dev
```

--------------------------------

### Development Setup for arabicfmt

Source: https://github.com/cc1a2b/arabicfmt/blob/main/CONTRIBUTING.md

Clone the repository, install dependencies, and run tests or build commands.

```sh
git clone https://github.com/cc1a2b/arabicfmt
cd arabicfmt
npm install
npm test          # run the suite (vitest)
npm run typecheck # tsc --noEmit
npm run build     # tsup → dist/
npm run verify    # re-verify currency data against CLDR
```

--------------------------------

### Local Development Commands

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/README.md

Commands to set up and run the arabicfmt demo locally. This includes installing dependencies, starting the development server, and building the static site.

```sh
cd demo
npm install
npm run dev      # http://localhost:5173
npm run build    # static site in demo/dist
```

--------------------------------

### Install arabicfmt via npm

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/index.html

Install the arabicfmt library using npm for use in your Node.js projects.

```bash
npm install arabicfmt
```

--------------------------------

### Currency Formatting Example

Source: https://github.com/cc1a2b/arabicfmt/blob/main/examples/README.md

Demonstrates currency formatting and related utilities using the 'arabicfmt/currency' subpath import.

```javascript
// currency.mjs
import {
  formatCurrency,
  getCurrencyInfo,
  resolveCurrencySymbol,
  currencyDigits,
  currencyForLocale,
  currencyForRegion,
  countryCurrency,
  spellCurrency,
  getSymbolData,
  CURRENCY_SYMBOLS,
  CURRENCY_WORDS,
  ARAB_LEAGUE_COUNTRIES,
} from 'arabicfmt/currency';

// Example usage (output is Arabic RTL, use UTF-8 terminal with Arabic font)
console.log('--- Currency Examples ---');

const amount = 1234.56;
const locale = 'ar-SA';
const currencyCode = 'SAR';

console.log(`Formatted Currency: ${formatCurrency(amount, currencyCode, locale)}`); // Expected: ١٬٢٣٤٫٥٦ ر.س.
console.log(`Currency Info:`, getCurrencyInfo(currencyCode)); // Expected: { code: 'SAR', name: 'Saudi Riyal', symbol: 'ر.س.', digits: 2, ... }
console.log(`Currency Symbol: ${resolveCurrencySymbol(currencyCode, locale)}`); // Expected: ر.س.
console.log(`Currency Digits: ${currencyDigits(currencyCode)}`); // Expected: 2
console.log(`Currency for Locale: ${currencyForLocale(locale)}`); // Expected: SAR
console.log(`Currency for Region: ${currencyForRegion('SA')}`); // Expected: SAR
console.log(`Country Currency: ${countryCurrency('SA')}`); // Expected: SAR
console.log(`Spelled Currency: ${spellCurrency(amount, currencyCode, locale)}`); // Expected: ألف ومائتان وأربعة وثلاثون ريالاً وخمسون هللة

console.log('--- Currency Constants ---');
console.log('CURRENCY_SYMBOLS:', CURRENCY_SYMBOLS);
console.log('CURRENCY_WORDS:', CURRENCY_WORDS);
console.log('ARAB_LEAGUE_COUNTRIES:', ARAB_LEAGUE_COUNTRIES);

```

--------------------------------

### Install Dependencies for Development

Source: https://github.com/cc1a2b/arabicfmt/blob/main/mcp/README.md

Install the necessary Node.js dependencies for developing the arabicfmt-mcp project. This is typically done within the 'mcp' directory.

```bash
cd mcp
npm install
```

--------------------------------

### Install arabicfmt using pnpm

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Install the arabicfmt package using pnpm. This is another package manager for Node.js projects.

```sh
pnpm add arabicfmt
```

--------------------------------

### Hijri Date Formatting Example

Source: https://github.com/cc1a2b/arabicfmt/blob/main/examples/README.md

Demonstrates formatting Hijri dates and converting between Hijri and Gregorian calendars using 'arabicfmt/date' and 'arabicfmt/umalqura'.

```javascript
// dates.mjs
import {
  formatHijri,
  toHijri,
  fromHijri,
  formatHijriDate,
} from 'arabicfmt/date';
import { UmmAlQura } from 'arabicfmt/umalqura'; // Assuming UmmAlQura is exported from umalqura module

// Example usage
console.log('\n--- Date Examples ---');

const gregorianDate = new Date(2023, 10, 21); // November 21, 2023
const hijriDate = { year: 1445, month: 5, day: 7 }; // 7th day of 5th month, 1445 AH

console.log(`Formatted Hijri Date (from Gregorian): ${formatHijri(gregorianDate)}`); // Expected: ٧ جمادى الأولى ١٤٤٥
console.log(`To Hijri (from Gregorian):`, toHijri(gregorianDate)); // Expected: { year: 1445, month: 5, day: 7, ... }
console.log(`From Hijri (to Gregorian):`, fromHijri(hijriDate)); // Expected: { year: 2023, month: 11, day: 21, ... }
console.log(`Formatted Hijri Date (specific): ${formatHijriDate(hijriDate)}`); // Expected: ٧ جمادى الأولى ١٤٤٥

// Example using UmmAlQura (assuming it's a class or object with methods)
const ummAlQura = new UmmAlQura();
console.log('Umm Al-Qura Month Names:', ummAlQura.monthNames);
console.log('Umm Al-Qura Era Names:', ummAlQura.eraNames);

```

--------------------------------

### Number Formatting Example

Source: https://github.com/cc1a2b/arabicfmt/blob/main/examples/README.md

Demonstrates various number formatting and parsing functions, including compact and percentage formats, and digit conversions.

```javascript
// numbers.mjs
import {
  formatNumber,
  formatCompact,
  formatPercent,
  parseNumber,
  parseCurrency,
  toArabicDigits,
  toLatinDigits,
  ARABIC_INDIC_DIGITS,
  EXTENDED_ARABIC_INDIC_DIGITS,
} from 'arabicfmt/number';

// Example usage
console.log('\n--- Number Examples ---');

const num = 12345.678;
const percent = 0.75;
const currencyString = '١٬٢٣٤٫٥٦ ر.س.';

console.log(`Formatted Number: ${formatNumber(num)}`); // Expected: ١٢٬٣٤٥٫٦٧٨
console.log(`Formatted Compact: ${formatCompact(num)}`); // Expected: ١٢ ألف
console.log(`Formatted Percent: ${formatPercent(percent)}`); // Expected: ٧٥٪
console.log(`Parsed Number: ${parseNumber('١٢٣٤٥')}`); // Expected: 12345
console.log(`Parsed Currency: ${parseCurrency(currencyString)}`); // Expected: { amount: 1234.56, currency: 'SAR' }
console.log(`To Arabic Digits: ${toArabicDigits('12345')}`); // Expected: ١٢٣٤٥
console.log(`To Latin Digits: ${toLatinDigits('١٢٣٤٥')}`); // Expected: 12345

console.log('--- Number Constants ---');
console.log('ARABIC_INDIC_DIGITS:', ARABIC_INDIC_DIGITS);
console.log('EXTENDED_ARABIC_INDIC_DIGITS:', EXTENDED_ARABIC_INDIC_DIGITS);

```

--------------------------------

### Install arabicfmt using yarn

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Install the arabicfmt package using yarn. This is an alternative package manager for Node.js projects.

```sh
yarn add arabicfmt
```

--------------------------------

### Arabic Text Manipulation Example

Source: https://github.com/cc1a2b/arabicfmt/blob/main/examples/README.md

Demonstrates text normalization, cleaning, searching, pluralization, sorting, and slugification using 'arabicfmt/text'.

```javascript
// text.mjs
import {
  normalizeArabic,
  stripTashkeel,
  removeTatweel,
  normalizeForSearch,
  arabicPluralForm,
  arabicPlural,
  sortArabic,
  compareArabic,
  formatList,
  slugify,
  transliterate,
} from 'arabicfmt/text';

// Example usage
console.log('\n--- Text Examples ---');

const textWithTashkeel = 'اَلْعَرَبِيَّةُ';
const textForSearch = 'مَرْحَبًا بِكُمْ';
const word = 'كتاب'; // book
const count = 3;
const list = ['تفاح', 'برتقال', 'موز'];
const unicodeText = '你好世界';

console.log(`Normalize Arabic: ${normalizeArabic(textWithTashkeel)}`); // Expected: العربية
console.log(`Strip Tashkeel: ${stripTashkeel(textWithTashkeel)}`); // Expected: العربية
console.log(`Remove Tatweel: ${removeTatweel('اَلْعَــرَبِيَّــة')}`); // Expected: العربية
console.log(`Normalize for Search: ${normalizeForSearch(textForSearch)}`); // Expected: مرحبا بكم
console.log(`Arabic Plural Form: ${arabicPluralForm(word, count)}`); // Expected: كتب
console.log(`Arabic Plural: ${arabicPlural(word, count)}`); // Expected: كتب
console.log(`Sort Arabic: ${sortArabic(list)}`); // Expected: ['برتقال', 'تفاح', 'موز'] (alphabetical order)
console.log(`Compare Arabic: ${compareArabic('أحمد', 'أحمد')}`); // Expected: 0 (equal)
console.log(`Format List: ${formatList(list)}`); // Expected: تفاح، برتقال و موز
console.log(`Slugify: ${slugify('مرحبا بالعالم')}`); // Expected: marhaba-bil-alam
console.log(`Transliterate: ${transliterate(unicodeText)}`); // Expected: nihaoshijie

```

--------------------------------

### Bi-Directional Text Handling Example

Source: https://github.com/cc1a2b/arabicfmt/blob/main/examples/README.md

Provides utilities for character direction, detection, isolation, and stripping of BiDi control characters using 'arabicfmt/bidi'.

```javascript
// bidi.mjs
import {
  charDirection,
  detectDirection,
  isRTL,
  isolate,
  wrapLTR,
  wrapRTL,
  stripBidi,
  isolateForeign,
  LRI, RLI, FSI, PDI, LRM, RLM, ALM // Control constants
} from 'arabicfmt/bidi';

// Example usage
console.log('\n--- BiDi Examples ---');

const rtlChar = 'ب';
const ltrChar = 'A';
const mixedText = 'Hello مرحبا';

console.log(`Character Direction ('${rtlChar}'): ${charDirection(rtlChar)}`); // Expected: R (RTL)
console.log(`Character Direction ('${ltrChar}'): ${charDirection(ltrChar)}`); // Expected: L (LTR)
console.log(`Detect Direction ('${mixedText}'): ${detectDirection(mixedText)}`); // Expected: R (RTL)
console.log(`Is RTL ('${rtlChar}'): ${isRTL(rtlChar)}`); // Expected: true
console.log(`Is RTL ('${ltrChar}'): ${isRTL(ltrChar)}`); // Expected: false

const isolatedText = isolate(mixedText);
console.log(`Isolated Text: ${isolatedText}`); // Expected: \u200fHello \u200fمرحبا\u200e\u200e (with control chars)
console.log(`Wrap LTR: ${wrapLTR(mixedText)}`); // Expected: \u202aHello مرحبا\u202c
console.log(`Wrap RTL: ${wrapRTL(mixedText)}`); // Expected: \u202bHello مرحبا\u202c
console.log(`Strip BiDi: ${stripBidi(isolatedText)}`); // Expected: Hello مرحبا
console.log(`Isolate Foreign: ${isolateForeign(mixedText)}`); // Expected: \u2068Hello \u200fمرحبا\u200e\u200e

console.log('--- BiDi Control Constants ---');
console.log('LRI:', LRI); // Expected: \u2066
console.log('RLI:', RLI); // Expected: \u2067
console.log('FSI:', FSI); // Expected: \u2068
console.log('PDI:', PDI); // Expected: \u2069
console.log('LRM:', LRM); // Expected: \u200e
console.log('RLM:', RLM); // Expected: \u200f
console.log('ALM:', ALM); // Expected: \u200c

```

--------------------------------

### React/Next.js Currency and Date Formatting

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Demonstrates how to use `formatCurrency` and `formatHijri` within React or Next.js components. Ensure `arabicfmt` is installed.

```tsx
import { formatCurrency, detectLocale } from "arabicfmt";
import { formatHijri } from "arabicfmt/umalqura";

export function PriceTag({ amount, currency }: { amount: number; currency: string }) {
  const locale = detectLocale();
  return (
    <span dir="rtl">
      {formatCurrency(amount, { currency, locale })}
    </span>
  );
}

export function HijriDate({ date }: { date: Date }) {
  return <time>{formatHijri(date, { numerals: "arab" })}</time>;
}
```

--------------------------------

### IBAN and Saudi ID Validation Example

Source: https://github.com/cc1a2b/arabicfmt/blob/main/examples/README.md

Demonstrates validation and formatting for IBAN numbers and Saudi national IDs using 'arabicfmt/validate'.

```javascript
// validate.mjs
import {
  isValidIBAN,
  formatIBAN,
  normalizeIBAN,
  IBAN_LENGTHS,
  isValidSaudiId,
  saudiIdType,
} from 'arabicfmt/validate';

// Example usage
console.log('\n--- Validation Examples ---');

const iban = 'SA0380000000608010975477'; // Example Saudi IBAN
const saudiId = '1234567890'; // Example Saudi ID

console.log(`Is Valid IBAN: ${isValidIBAN(iban)}`); // Expected: true
console.log(`Formatted IBAN: ${formatIBAN(iban)}`); // Expected: SA03 8000 0000 6080 1097 5477
console.log(`Normalized IBAN: ${normalizeIBAN(iban)}`); // Expected: SA0380000000608010975477
console.log('IBAN Lengths:', IBAN_LENGTHS);

console.log(`Is Valid Saudi ID: ${isValidSaudiId(saudiId)}`); // Expected: true (for a valid format, checksum might fail)
console.log(`Saudi ID Type: ${saudiIdType(saudiId)}`); // Expected: 'National ID' or 'Iqama' or null

```

--------------------------------

### Browser Usage with CDN

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Import and use arabicfmt functions directly from a CDN in the browser without a build step. This example shows how to format currency and Hijri dates.

```html
<script type="module">
  import { formatCurrency, formatHijri } from "https://cdn.jsdelivr.net/npm/arabicfmt/+esm";

  console.log(formatCurrency(1234.5, { currency: "SAR", numerals: "arab" })); // ١٬٢٣٤٫٥٠ ر.س
  console.log(formatHijri(new Date(), { numerals: "arab" }));                 // ٢٧ ذو الحجة ١٤٤٧ هـ
</script>
```

--------------------------------

### Arabic Words and Ordinals Example

Source: https://github.com/cc1a2b/arabicfmt/blob/main/examples/README.md

Provides functions for converting numbers to Arabic words, handling ordinals, fractions, and noun counts.

```javascript
// words.mjs
import {
  arabicToWords,
  arabicOrdinal,
  arabicFraction,
  countedNoun,
} from 'arabicfmt/number';

// Example usage
console.log('\n--- Words Examples ---');

const number = 25;
const ordinalNumber = 3;
const fraction = { numerator: 1, denominator: 4 };
const count = 5;
const noun = 'كتاب'; // book

console.log(`Arabic to Words: ${arabicToWords(number)}`); // Expected: خمسة وعشرون
console.log(`Arabic Ordinal: ${arabicOrdinal(ordinalNumber)}`); // Expected: الثالث
console.log(`Arabic Fraction: ${arabicFraction(fraction)}`); // Expected: ربع
console.log(`Counted Noun: ${countedNoun(count, noun)}`); // Expected: خمسة كتب

```

--------------------------------

### Arabic Currency Unit Agreement Examples

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Demonstrates automatic unit agreement (singular, dual, plural, accusative) for Arabic currency based on the numeric value.

```typescript
// Unit agreement is automatic (العدد والمعدود)
spellCurrency(1,   { currency: "SAR" })   // "ريال واحد"      (singular)
spellCurrency(2,   { currency: "SAR" })   // "ريالان"         (dual)
spellCurrency(3,   { currency: "SAR" })   // "ثلاثة ريالات"   (plural, 3–10)
spellCurrency(11,  { currency: "SAR" })   // "أحد عشر ريالاً" (accusative, 11–99)
spellCurrency(100, { currency: "SAR" })   // "مئة ريال"       (genitive singular)
```

--------------------------------

### Regenerate Lockfile

Source: https://github.com/cc1a2b/arabicfmt/blob/main/CONTRIBUTING.md

Remove existing node_modules and lockfile, then perform a clean npm install to ensure all optional binaries are recorded for all platforms.

```sh
rm -rf node_modules package-lock.json
npm install
```

--------------------------------

### Format Currency with Default Numerals

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/public/llms.txt

Formats a given value as currency using the specified currency code. This example uses default (Latin) numerals.

```javascript
import { formatCurrency } from "arabicfmt/currency";

formatCurrency(1.2, { currency: "KWD" }); // "1.200 د.ك" (3 decimals, CLDR-correct)
```

--------------------------------

### Get Deterministic Hijri Dates

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/index.html

Use formatHijri from the umalqura module for consistent Hijri dates across different environments. It utilizes frozen official Umm al-Qura tables.

```javascript
formatHijri(new Date())
```

--------------------------------

### Arabic Currency Minor Unit Precision

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Shows how minor unit precision is derived from CLDR, with examples for KWD (1000 fils) and SAR (100 halalas).

```typescript
// Minor-unit precision comes from CLDR — KWD = 1000 fils, SAR = 100 halalas
spellCurrency(1.5, { currency: "KWD" })   // "دينار واحد وخمسمئة فلس"
spellCurrency(0.75, { currency: "SAR" })  // "خمس وسبعون هللةً"
```

--------------------------------

### Run arabicfmt-mcp Server

Source: https://github.com/cc1a2b/arabicfmt/blob/main/mcp/README.md

Launch the arabicfmt-mcp server using npx. This command runs the server over stdio and is intended to be launched by an MCP client.

```bash
npx arabicfmt-mcp
```

--------------------------------

### All Currency Formatting Options

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Illustrates various currency formatting options including locale-based resolution, numeral systems, accounting notation, and hiding symbols or fractions.

```typescript
// Resolve from locale region — no need to know the currency code
formatCurrency(99.9,  { locale: "ar-BH" });                  // "99.900 د.ب"
formatCurrency(1234,  { locale: "ar-AE", numerals: "arab", symbolMode: "text" }); // "١٬٢٣٤٫٠٠ د.إ"  (auto → U+20C3 sign)

// Accounting notation (negatives in parentheses)
formatCurrency(-1234.5, { currency: "SAR", accounting: true }); // "(1,234.50 ر.س)"

// Hide/override
formatCurrency(100, { currency: "SAR", showSymbol: false, fractionDigits: 0 }); // "100"

// Currency metadata
getCurrencyInfo("SAR");
// {
//   code: "SAR", digits: 2,
//   symbols: { auto: "ر.س", text: "ر.س", code: "SAR", new: "⃁" },
//   unicode: { codepoint: "U+20C1", unicodeVersion: "17.0", live: true, autoDefault: false },
//   displayName: "ريال سعودي"
// }
```

--------------------------------

### Configure Claude Desktop MCP Server

Source: https://github.com/cc1a2b/arabicfmt/blob/main/mcp/README.md

Add the arabicfmt-mcp server to Claude Desktop's configuration. This allows Claude Desktop to use the arabicfmt tools.

```json
{
  "mcpServers": {
    "arabicfmt": {
      "command": "npx",
      "args": ["-y", "arabicfmt-mcp"]
    }
  }
}
```

--------------------------------

### Arabic Pluralization Forms

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Get the CLDR plural form name for a given number and select the appropriate string based on these forms.

```typescript
import { arabicPluralForm, arabicPlural } from "arabicfmt";

// Get the CLDR form name
arabicPluralForm(0)    // "zero"
arabicPluralForm(1)    // "one"
arabicPluralForm(2)    // "two"
arabicPluralForm(5)    // "few"   (3–10)
arabicPluralForm(15)   // "many"  (11–99)
arabicPluralForm(100)  // "other"

// Select the right string
const forms = {
  zero:  "لا كتب",
  one:   "كتاب واحد",
  two:   "كتابان",
  few:   "كتب",       // 3–10
  many:  "كتاباً",    // 11–99
  other: "كتاب",
};

arabicPlural(0,   forms)  // "لا كتب"
arabicPlural(1,   forms)  // "كتاب واحد"
arabicPlural(2,   forms)  // "كتابان"
arabicPlural(5,   forms)  // "كتب"
arabicPlural(25,  forms)  // "كتاباً"
arabicPlural(100, forms)  // "كتاب"

```

--------------------------------

### Formatting Currency with arabicfmt

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Demonstrates different ways to format currency values, including symbol, precision, locale, and accounting formats.

```typescript
// Currency
formatCurrency(1.2, { currency: "KWD" });                      // "1.200 د.ك"
formatCurrency(1234, { locale: "ar-SA", numerals: "arab" });    // "١٬٢٣٤٫٠٠ ر.س"
formatCurrency(-500, { currency: "SAR", accounting: true });    // "(500.00 ر.س)"
formatCompact(1_500_000, { locale: "ar", numerals: "arab" });    // "١٫٥ مليون"
```

--------------------------------

### Subpath Imports for Tree-Shaking

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Illustrates importing specific modules from `arabicfmt` to minimize bundle size. This allows including only necessary functionalities.

```ts
import { formatCurrency, spellCurrency } from "arabicfmt/currency";
import { formatNumber, arabicToWords, formatDuration, formatFileSize } from "arabicfmt/number";
import { formatHijri, toHijri }  from "arabicfmt/date";       // tabular core (tiny)
import { formatHijri, toHijri }  from "arabicfmt/umalqura";   // accurate, opt-in
import { isolateForeign }        from "arabicfmt/bidi";
import { normalizeForSearch, arabicPlural, slugify } from "arabicfmt/text";
import { isValidIBAN, isValidSaudiId }      from "arabicfmt/validate";
```

--------------------------------

### Configure MCP Server for Arabicfmt

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Add the arabicfmt-mcp server to your client's mcpServers configuration. This enables AI agents to call arabicfmt tools directly.

```json
{
  "mcpServers": {
    "arabicfmt": { "command": "npx", "args": [ "-y", "arabicfmt-mcp" ] }
  }
}
```

--------------------------------

### Get Arabic Plural Form

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/public/llms.txt

Determines the correct Arabic plural form for a given number based on CLDR rules (zero, one, two, few, many, other).

```javascript
import { arabicPluralForm } from "arabicfmt/text";

arabicPluralForm(5); // "many"
```

--------------------------------

### MCP Server Tools

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Tools available through the arabicfmt-mcp Model Context Protocol server for AI agents.

```APIDOC
## MCP Server Tools

AI agents can call arabicfmt directly through the `arabicfmt-mcp` Model Context Protocol server.

### Available Tools (Examples)
- `format_currency`
- `spell_currency`
- `format_hijri`
- `arabic_to_words`
- `isolate_foreign`
- `validate_iban`

Configuration example:
```json
{
  "mcpServers": {
    "arabicfmt": { "command": "npx", "args": ["-y", "arabicfmt-mcp"] }
  }
}
```

Source and full tool list: [`mcp/`](./mcp).
```

--------------------------------

### Importing arabicfmt Utilities

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Import all necessary functions from the main arabicfmt package for various formatting tasks.

```typescript
import {
  formatCurrency,
  formatCompact,
  arabicToWords,
  spellCurrency,
  arabicOrdinal,
  formatDuration,
  formatFileSize,
  formatRelativeTime,
  formatList,
  parseCurrency,
  arabicPlural,
  sortArabic,
  slugify,
  isValidIBAN,
  isValidSaudiId,
  isolateForeign,
  normalizeForSearch,
  detectLocale,
} from "arabicfmt";

import { formatHijri, toHijri } from "arabicfmt/umalqura"; // deterministic Hijri calendar
```

--------------------------------

### Webfont Guide for Saudi Riyal Unicode Symbol

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Provides CSS to scope a custom font for the Saudi Riyal's Unicode symbol (U+20C1), ensuring it only affects that specific character and doesn't impact other text.

```css
/* Scope the Saudi Riyal font to just that codepoint — zero impact on body text */
@font-face {
  font-family: "Riyal";
  src: url("/fonts/saudi-riyal.woff2") format("woff2");
  unicode-range: U+20C1;
}
:root { font-family: "Riyal", "Noto Naskh Arabic", sans-serif; }
```

--------------------------------

### Currency Formatting with Symbol Modes

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Demonstrates different symbol display modes for currency formatting. Use 'auto' for broad compatibility, 'new' for the dedicated Unicode symbol (requires webfont), 'text' for safe text symbols, and 'code' for ISO codes.

```typescript
import { formatCurrency, resolveCurrencySymbol, getCurrencyInfo } from "arabicfmt/currency";

formatCurrency(1234.5, { currency: "SAR" });
// → "1,234.50 ر.س"   (auto: safe text symbol, renders everywhere today)

formatCurrency(1234.5, { currency: "SAR", symbolMode: "new" });
// → "1,234.50 ⃁"     (U+20C1 — use with a webfont; see webfont guide below)

formatCurrency(1234.5, { currency: "SAR", symbolMode: "code" });
// → "1,234.50 SAR"   (ISO code — for accounting tables)
```

--------------------------------

### Bidi / RTL Support

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/public/llms.txt

Utilities for handling bidirectional text, including isolating foreign language runs and detecting text direction.

```APIDOC
## Bidi / RTL Functions

### `isolateForeign(text)`

Wraps Left-to-Right (LTR) text runs (like phone numbers or Latin text) in appropriate Unicode control characters (FSI…PDI) to prevent them from being scrambled by surrounding Right-to-Left (RTL) text.

- **text** (string) - The input string containing mixed directionality text.

### `detectDirection(s)`, `isRTL(s)`, `wrapLTR`, `wrapRTL`, `stripBidi`

Functions to detect text direction, check if text is RTL, and wrap text with directionality control characters or strip them.
```

--------------------------------

### Formatting Durations and File Sizes

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Formats time durations in a human-readable format and file sizes with appropriate units.

```typescript
// Duration & file size
formatDuration(7_500_000);               // "ساعتان وخمس دقائق"
formatFileSize(1536);                    // "1.5 كيلوبايت"
```

--------------------------------

### Format File Size in Arabic Data Units

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Use formatFileSize to display file sizes in Arabic units like بايت, كيلوبايت, etc. Supports binary (default) or decimal bases, and different numeral and unit styles.

```typescript
import { formatFileSize } from "arabicfmt";

formatFileSize(0)                          // "0 بايت"
formatFileSize(1536)                       // "1.5 كيلوبايت"
formatFileSize(5 * 1024 * 1024)            // "5 ميجابايت"
formatFileSize(1_500_000, { base: 1000 })  // "1.5 ميجابايت"  (decimal/SI)
formatFileSize(2048, { numerals: "arab" }) // "٢ كيلوبايت"
formatFileSize(2048, { unitStyle: "latin" })// "2 KB"
```

--------------------------------

### arabicfmt/bidi Functions

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Functions for bidirectional text handling and direction detection.

```APIDOC
## Module: arabicfmt/bidi

### Functions
- `isolateForeign`
- `isolate`
- `wrapLTR`
- `wrapRTL`
- `stripBidi`
- `detectDirection`
- `isRTL`
- `charDirection`
```

--------------------------------

### arabicfmt/currency Functions

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Functions for currency formatting and information retrieval.

```APIDOC
## Module: arabicfmt/currency

### Functions
- `formatCurrency`
- `spellCurrency`
- `getCurrencyInfo`
- `resolveCurrencySymbol`
```

--------------------------------

### arabicfmt/umalqura Functions

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Functions for Hijri (Umm al-Qura) date formatting and conversion.

```APIDOC
## Module: arabicfmt/umalqura

### Functions
- `formatHijri`
- `toHijri`
- `fromHijri`
- `gregorianToUmalqura`
- `umalquraToGregorian`
```

--------------------------------

### Arabic Currency with Suffix and Locale

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Illustrates using the `suffix` option for cheque-ready endings and `locale` for deriving currency from the locale.

```typescript
// Cheque-ready ending and locale-derived currency
spellCurrency(100, { currency: "EGP", suffix: true }) // "مئة جنيه فقط لا غير"
spellCurrency(-5,  { locale: "ar-AE" })               // "سالب خمسة دراهم"
```

--------------------------------

### Number Formatting

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/public/llms.txt

Functions for converting numbers to Arabic words, handling ordinals, fractions, and various formatting options like compact, percentage, duration, and file size.

```APIDOC
## Number Formatting Functions

### `arabicToWords(n, { gender? })`

Converts a number into its Arabic word representation.

- **n** (number) - The number to convert.
- **gender** (string) - Optional. 'male' or 'female' for gendered nouns.

**Example:**
```javascript
arabicToWords(1234)
// Output: "ألف ومئتان وأربعة وثلاثون"
```

### `arabicOrdinal(n, { gender? })`

Converts a number into its Arabic ordinal form.

- **n** (number) - The number to convert.
- **gender** (string) - Optional. 'male' or 'female'.

**Example:**
```javascript
arabicOrdinal(25, { gender: "female" })
// Output: "الخامسة والعشرون"
```

### `arabicFraction(num, den)`

Represents a fraction in Arabic words.

- **num** (number) - The numerator.
- **den** (number) - The denominator.

**Example:**
```javascript
arabicFraction(3, 4)
// Output: "ثلاثة أرباع"
```

### `countedNoun(n, forms)`

Applies Arabic number-noun agreement rules.

- **n** (number) - The count.
- **forms** (object) - An object containing different forms of the noun based on count.

### `formatNumber(n, opts)`, `formatPercent(ratio, opts)`, `formatCompact(n, opts)`

General-purpose number formatting with options for different formats (standard, percentage, compact).

**Example:**
```javascript
formatCompact(1200000)
// Output: "١٫٢ مليون"
```

### `formatDuration(ms)`

Formats a duration in milliseconds into a human-readable string.

- **ms** (number) - Duration in milliseconds.

**Example:**
```javascript
formatDuration(7500000)
// Output: "ساعتان وخمس دقائق"
```

### `formatFileSize(bytes)`

Formats a file size in bytes into a human-readable string.

- **bytes** (number) - Size in bytes.

**Example:**
```javascript
formatFileSize(1536)
// Output: "1.5 كيلوبايت"
```

### `formatRelativeTime(date)`

Formats a date relative to the current time (e.g., "3 days ago").

- **date** (Date) - The date to format.

**Example:**
```javascript
formatRelativeTime(new Date(Date.now() - 3 * 24 * 60 * 60 * 1000))
// Output: "قبل ٣ أيام"
```

### `parseNumber(str)` / `parseCurrency(str)`

Parses a string representation of a number or currency into a numeric value.

- **str** (string) - The string to parse.

**Example:**
```javascript
parseNumber("١٬٢٣٤٫٥٦")
// Output: 1234.56
```

### `toArabicDigits(str)` / `toLatinDigits(str)`

Converts between Eastern-Arabic and Western (Latin) digits in a string.
```

--------------------------------

### Currency Formatting

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/public/llms.txt

Functions for formatting currency values, spelling them out, and retrieving currency information. Supports the Unicode currency symbol transition.

```APIDOC
## Currency Formatting Functions

### `formatCurrency(value, { currency, numerals?, symbolMode?, accounting?, locale? })`

Formats a numeric value as currency according to ISO 4217 codes. Supports custom numeral systems and symbol display modes.

- **value** (number) - The numeric value to format.
- **currency** (string) - Required. The ISO 4217 currency code (e.g., "SAR", "AED", "KWD").
- **numerals** (string) - Optional. Use 'arab' for Eastern-Arabic digits.
- **symbolMode** (string) - Optional. Controls how the currency symbol is displayed: 'auto', 'new' (U+20C1 etc.), 'text' (ر.س), or 'code' (SAR).
- **accounting** (boolean) - Optional. For accounting format.
- **locale** (string) - Optional. Locale for formatting.

**Example:**
```javascript
formatCurrency(1234.5, { currency: "SAR", numerals: "arab" })
// Output: "١٬٢٣٤٫٥٠ ر.س"
```

### `spellCurrency(value, { currency, suffix? })`

Spells out a currency value in Arabic words, suitable for cheques (تفقيط).

- **value** (number) - The numeric value to spell out.
- **currency** (string) - Required. The ISO 4217 currency code.
- **suffix** (string) - Optional. Suffix for the currency name.

**Example:**
```javascript
spellCurrency(1234.5, { currency: "SAR" })
// Output: "ألف ومئتان وأربعة وثلاثون ريالاً وخمسون هللةً"
```

### `getCurrencyInfo(code)`

Retrieves metadata about a currency, including its symbols, precision, and Unicode transition information.

- **code** (string) - Required. The ISO 4217 currency code.

**Example:**
```javascript
getCurrencyInfo("SAR")
// Returns object with symbol, precision, etc.
```
```

--------------------------------

### Format List in Arabic

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/public/llms.txt

Formats an array of items into a grammatically correct Arabic list string, using appropriate conjunctions.

```javascript
import { formatList } from "arabicfmt/text";

formatList(["أحمد", "محمد", "علي"]); // "أحمد ومحمد وعلي"
```

--------------------------------

### Create URL Slugs from Arabic Text

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Use `slugify` to create URL-safe slugs from Arabic text. Customize the separator and casing with options.

```typescript
slugify("مدينة نصر")                      // "mdynh-nsr"
slugify("القاهرة 2026")                   // "alqahrh-2026"
slugify("Hello العالم", { separator: "_" }) // "hello_alalm"
slugify("Hello World", { lowercase: false }) // "Hello-World"
```

--------------------------------

### Convert Money Amount to Arabic Words (Tafqit)

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/index.html

Use spellCurrency to generate the legal Arabic wording for monetary amounts, ensuring correct agreement for singular, dual, and plural forms.

```javascript
spellCurrency(1234.5, { currency: 'SAR' })
```

--------------------------------

### Format File Size in Arabic

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/public/llms.txt

Converts a file size in bytes into a human-readable Arabic string with appropriate units (e.g., كيلوبايت).

```javascript
import { formatFileSize } from "arabicfmt/number";

formatFileSize(1536); // "1.5 كيلوبايت"
```

--------------------------------

### Format Currency with Arabic Numerals

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/public/llms.txt

Formats a given value as currency using the specified currency code and Arabic numerals. Ensure to pass the ISO 4217 currency code.

```javascript
import { formatCurrency } from "arabicfmt/currency";

formatCurrency(1234.5, { currency: "SAR", numerals: "arab" }); // "١٬٢٣٤٫٥٠ ر.س"
```

--------------------------------

### Create URL Slug from Arabic Text

Source: https://github.com/cc1a2b/arabicfmt/blob/main/demo/public/llms.txt

Generates a URL-friendly slug from Arabic text by transliterating and replacing spaces with hyphens.

```javascript
import { slugify } from "arabicfmt/text";

slugify("مدينة نصر"); // "mdynh-nsr"
```

--------------------------------

### Hijri and Gregorian Month/Weekday Names

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Access predefined arrays of month and weekday names for both Hijri and Gregorian calendars in Arabic and English.

```typescript
import {
  HIJRI_MONTHS_AR,
  HIJRI_MONTHS_EN,
  GREGORIAN_MONTHS_AR, // Arabic Gregorian month names (يناير، فبراير…)
  GREGORIAN_MONTHS_EN,
  ARABIC_WEEKDAYS_AR,  // Arabic weekday names (الأحد، الاثنين…)
  ARABIC_WEEKDAYS_EN,
} from "arabicfmt/date";

HIJRI_MONTHS_AR[8]        // "رمضان"  (index 0 = Muharram)
GREGORIAN_MONTHS_AR[0]    // "يناير"  (index 0 = January)
ARABIC_WEEKDAYS_AR[5]     // "الجمعة" (index 0 = Sunday)

```

--------------------------------

### Hijri Date Conversion and Formatting

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Convert between Gregorian and Hijri dates, and format Hijri dates in various locales and numeral systems.

```typescript
import { toHijri, fromHijri, formatHijri, umalquraToGregorian } from "arabicfmt/umalqura";

// Convert
toHijri(new Date("2025-09-23"))        // { year: 1447, month: 4, day: 1 }
umalquraToGregorian(1447, 9, 1)        // JavaScript Date — first day of Ramadan 1447

// Format — Arabic
formatHijri(new Date("2025-09-23"))
// "1 ربيع الآخر 1447 هـ"

formatHijri(new Date("2025-09-23"), { numerals: "arab" })
// "١ ربيع الآخر ١٤٤٧ هـ"

// Format — English
formatHijri(new Date("2025-09-23"), { locale: "en" })
// "1 Rabi al-Thani 1447 AH"

// Format — ISO-style numeric
formatHijri(new Date("2025-09-23"), {
  locale: "en", month: "2-digit", day: "2-digit", order: "ymd", era: false,
})
// "1447/04/01"

```

--------------------------------

### Format Percentages

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Use formatPercent to display numbers as percentages, with locale support.

```typescript
// Percent
formatPercent(0.853, { locale: "en" });                    // "85.3%"
```

--------------------------------

### Formatting Lists in Arabic

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Formats arrays of strings into a grammatically correct Arabic list, with options for conjunction type.

```typescript
// Lists
formatList(["أحمد", "محمد", "علي"]);                    // "أحمد ومحمد وعلي"
formatList(["تفاح", "موز"], { type: "disjunction" });   // "تفاح أو موز"
```

--------------------------------

### Compact Number Formatting

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Utilize formatCompact for short notation suitable for dashboards, with options for locale and numerals.

```typescript
// Compact / short notation — dashboards and data cards
formatCompact(1_500_000);                                   // "1.5M"
formatCompact(1_500_000, { locale: "ar" });                 // "1.5 مليون"
formatCompact(1_500_000, { locale: "ar", numerals: "arab" }); // "١٫٥ مليون"
```

--------------------------------

### Format Arabic Lists

Source: https://github.com/cc1a2b/arabicfmt/blob/main/README.md

Join values into a grammatical Arabic list using `formatList`. This function wraps `Intl.ListFormat` and degrades gracefully on runtimes without it. Supports different list types and numeral formats.

```typescript
import { formatList } from "arabicfmt";

formatList(["أحمد", "محمد", "علي"])                      // "أحمد ومحمد وعلي"
formatList(["تفاح", "موز", "برتقال"], { type: "disjunction" }) // "تفاح أو موز أو برتقال"
formatList([1, 2, 3], { numerals: "arab" })              // "١ و٢ و٣"
```