// Default normalization (layers 1–8)
normalize('عِلمٌ')              // → 'علم'  (diacritics stripped)
normalize('علم\u200cہے')        // → 'علمہے' (ZWNJ removed)
normalize('\u0627\u0653')        // → 'آ'   (Alif+Madda → precomposed)
normalize('۱۲۳')                // → '123'  (Urdu numerals → ASCII)

// Full normalization for search indexing
normalize(userInput, {
  kashida: true,
  presentationForms: true,
  punctuationTrim: true,
  normalizeCharacters: true,  // ي→ی  ك→ک  ه→ہ
})

// Selective: strip diacritics only
normalize(text, {
  nfc: false, nbsp: false, alifMadda: false, numerals: false,
  zeroWidth: false, honorifics: false, hamza: false,
  diacritics: true,   // only this layer
})

fingerprint('عِلمٌ') === fingerprint('عَلم')    // → true (diacritics differ)
fingerprint('نبیؐ') === fingerprint('نبی')      // → true (honorific stripped)
fingerprint('علم\u200c') === fingerprint('علم') // → true (ZWNJ stripped)
fingerprint('يه') === fingerprint('یہ')         // → true (Arabic→Urdu chars)

stripDiacritics('عِلمٌ وَالعَمَلُ')  // → 'علم والعمل'
stripDiacritics('نَبِیؐ')             // → 'نبیؐ'  (honorifics NOT stripped — use normalize())

normalizeCharacters('يه ملك وكتاب')  // → 'یہ ملک وکتاب'
//                   ي→ی  ه→ہ  ك→ک

// Always enable when text comes from Arabic keyboards or Arabic websites:
normalize(arabicKeyboardInput, { normalizeCharacters: true })

normalizeAlif('آب اور أردو إسلام')   // → 'آب اور اردو اسلام' (variants → base ا)
normalizeHamza('أحمد ؤلوی')          // → 'احمد ولوی'
stripZeroWidth('علم\u200cہے')         // → 'علمہے' (ZWNJ/ZWJ removed)
normalizeNumerals('قیمت ۱۲۳')         // → 'قیمت 123'
removeKashida('ممـتاز')               // → 'ممتاز' (tatweel removed)
normalizePresentationForms('\uFB8A')   // → 'ژ'  (presentation form → base char)

match('عِلمٌ', 'علم')
// → { matched: true, layer: 'strip-diacritics', normalizedQuery: 'علم', ... }

match('نبیؐ', 'نبی')
// → { matched: true, layer: 'strip-honorifics', ... }

match('\u0623حمد', 'احمد')
// → { matched: true, layer: 'normalize-hamza', ... }

match('کتاب', 'علم')
// → { matched: false, layer: null, ... }

// Usage pattern:
const result = match(userQuery, dbValue)
if (result.matched) {
  console.log(`Matched at layer: ${result.layer}`)
}

getAllNormalizations('عِلمٌ')
// → ['عِلمٌ', 'عِلمٌ' (nfc), 'عِلمٌ' (no-zw), 'علم' (no-diacritics), ...]

// Database lookup pattern — never returns zero results for valid input:
async function search(userInput: string) {
  const forms = getAllNormalizations(userInput)
  for (const form of forms) {
    const result = await db.find({ text: form })
    if (result) return result
  }
  return null
}

fuzzyMatch('کتاب', ['علم', 'کتاب', 'قلم'])
// → { candidate: 'کتاب', score: 1.0 }

fuzzyMatch('کتاب', ['کتابیں', 'کتب', 'علم'])
// → { candidate: 'کتابیں', score: ~0.72 }

fuzzyMatch('پاکستان', ['hello', 'world'])
// → null  (nothing above threshold 0.5)

// Usage:
const result = fuzzyMatch(query, candidates)
if (result) {
  console.log(`Best match: ${result.candidate} (score: ${result.score.toFixed(2)})`)
}

numberToWords(0n)                                            // 'صفر'
numberToWords(100n)                                          // 'ایک سو'
numberToWords(1_000n)                                        // 'ایک ہزار'
numberToWords(100_000n)                                      // 'ایک لاکھ'
numberToWords(10_000_000n)                                   // 'ایک کروڑ'
numberToWords(1_000_000_000n)                                // 'ایک ارب'
numberToWords(505n)                                          // 'پانچ سو پانچ'
numberToWords(-7n)                                           // 'منفی سات'

// Ordinals with gender agreement:
numberToWords(1n,  { ordinal: true, gender: 'masculine' })   // 'پہلا'
numberToWords(1n,  { ordinal: true, gender: 'feminine'  })   // 'پہلی'
numberToWords(11n, { ordinal: true, gender: 'masculine' })   // 'گیارہواں'
numberToWords(2n,  { ordinal: true, gender: 'feminine'  })   // 'دوسری'

formatCurrency(505.50, 'PKR')   // 'پانچ سو پانچ روپے پچاس پیسے'
formatCurrency(1000,   'PKR')   // 'ایک ہزار روپے'
formatCurrency(1.01,   'INR')   // 'ایک روپیہ ایک پیسہ'

toUrduNumerals('2024-12-25')         // '۲۰۲۴-۱۲-۲۵'  (ASCII → Extended Arabic-Indic)
toUrduNumerals('Order #123')         // 'Order #۱۲۳'

wordsToNumber('ایک کروڑ')           // 10_000_000n
wordsToNumber('پانچ سو پانچ')       // 505n
wordsToNumber('منفی بیس')           // -20n

tokenize('پاکستان AI 2024 میں')
// → [
//   { text: 'پاکستان', type: 'urdu-word' },
//   { text: ' ',       type: 'whitespace' },
//   { text: 'AI',      type: 'latin-word' },
//   { text: ' ',       type: 'whitespace' },
//   { text: '2024',    type: 'numeral'    },
//   { text: ' ',       type: 'whitespace' },
//   { text: 'میں',    type: 'urdu-word'  },
// ]

// Filter to Urdu words only:
const urduWords = tokenize(text)
  .filter(t => t.type === 'urdu-word')
  .map(t => t.text)

sentences('پہلا جملہ۔ دوسرا جملہ؟ تیسرا!')
// → ['پہلا جملہ', 'دوسرا جملہ', 'تیسرا']

// ، is NOT a sentence boundary:
sentences('آم، کیلا، اور سیب بہت اچھے ہیں۔')
// → ['آم، کیلا، اور سیب بہت اچھے ہیں']  (one sentence)

// N-grams for NLP:
const words = tokenize('ایک دو تین چار')
  .filter(t => t.type === 'urdu-word').map(t => t.text)
ngrams(words, 2)
// → [['ایک','دو'], ['دو','تین'], ['تین','چار']]

reverse('پاکستان ہندوستان ایران')   // 'ایران ہندوستان پاکستان'

truncate('یہ ایک بہت لمبا جملہ ہے', 10)  // 'یہ ایک...'
truncate('علم', 10)                        // 'علم'  (under limit, unchanged)

wordCount('پاکستان زندہ باد')   // 3
charCount('عِلم')               // 3  (ع+ِ = 1 grapheme, ل, م)
'عِلم'.length                   // 4  (code units — wrong for display)

extractUrdu('The word علم means knowledge and عمل means action')
// → ['علم', 'عمل']

// TinyMCE / Quill output — decode first:
decodeHtmlEntities('کتاب’خانہ علم ہے & مزید')
// → 'کتاب\u2019خانہ علم\u00A0ہے & مزید'

// Then normalize:
normalize(decodeHtmlEntities(editorOutput))

pad('علم', 8)           // '     علم'  (5 spaces + 3 chars = 8, from start)
pad('علم', 8, '*', 'end')  // 'علم*****'

const buffer = await fs.readFile('document.inp')
const enc = detectEncoding(new Uint8Array(buffer))

switch (enc) {
  case 'inpage-v1v2': return decodeInpage(buf, 'v1')
  case 'inpage-v3':   return decodeInpage(buf, 'v3')
  case 'windows-1256': return convertWindows1256ToUnicode(buf)
  case 'utf-8': return new TextDecoder('utf-8').decode(buf)
}

const buffer = new Uint8Array(await fs.readFile('article.inp'))
const result = decodeInpage(buffer, 'auto')

result.paragraphs        // string[] — each paragraph as Unicode
result.pageBreakIndices  // number[] — indices of page breaks in paragraphs
result.filteredCount     // number  — characters dropped during decoding

// Join paragraphs:
const text = result.paragraphs.join('\n')

// Parse \xFF escape sequences, then convert:
const raw = '\\x81\\xc1\\xff'
const parsed = raw.replace(/\\x([0-9a-fA-F]{2})/g,
  (_, h) => String.fromCharCode(parseInt(h, 16)))
const unicode = convertWindows1256ToUnicode(parsed)

import { detectCompounds } from 'urdu-tools/compound'

// Affix-based compound (خانہ suffix):
detectCompounds('کتاب خانہ بہت اچھا ہے')
// → [{ text: 'کتاب خانہ', type: 'affix',
//      components: ['کتاب', 'خانہ'], start: 0, end: 1 }]

// Izafat via vav-e-atf:
detectCompounds('علم و عمل ضروری ہے')
// → [{ text: 'علم و عمل', type: 'izafat',
//      components: ['علم', 'و', 'عمل'], start: 0, end: 2 }]

// Greedy N-gram: 3-word compound wins over two 2-word spans:
detectCompounds('امورِ خانہ داری')
// → [{ text: 'امورِ خانہ داری', type: 'affix',
//      components: ['امورِ', 'خانہ', 'داری'], start: 0, end: 2 }]

// Lexicon compound (echo/fixed expression):
detectCompounds('ہاتھ پاؤں پھیلانا')
// → [{ text: 'ہاتھ پاؤں', type: 'lexicon',
//      components: ['ہاتھ', 'پاؤں'], start: 0, end: 1 }]

// Affix layer only:
detectCompounds('کتاب خانہ اور علم و عمل', { layers: ['affix'] })
// → [{ text: 'کتاب خانہ', type: 'affix', ... }]  // izafat skipped

import { joinCompounds } from 'urdu-tools/compound'

// Default binder: ZWNJ (U+200C) — invisible but meaningful
joinCompounds('کتاب خانہ اچھا ہے')
// → 'کتاب‌خانہ اچھا ہے'   (ZWNJ between کتاب and خانہ)

// NBSP binder: non-breaking space (U+00A0)
joinCompounds('کتاب خانہ اچھا ہے', { binder: 'nbsp' })
// → 'کتاب\u00A0خانہ اچھا ہے'

// Word Joiner binder (U+2060)
joinCompounds('کتاب خانہ اچھا ہے', { binder: 'wj' })
// → 'کتاب\u2060خانہ اچھا ہے'

// Multiple compounds in one string:
joinCompounds('کتاب خانہ میں آب و ہوا اچھی ہے')
// → 'کتاب‌خانہ میں آب‌و‌ہوا اچھی ہے'

import { splitCompounds } from 'urdu-tools/compound'

splitCompounds('کتاب‌خانہ')
// → 'کتاب خانہ'   (ZWNJ → space)

splitCompounds('آب\u00A0و\u00A0ہوا')
// → 'آب و ہوا'    (NBSP → space)

// Round-trip:
const joined = joinCompounds('کتاب خانہ بہت اچھا ہے')
splitCompounds(joined)
// → 'کتاب خانہ بہت اچھا ہے'  (original restored)

import { isCompound } from 'urdu-tools/compound'

isCompound('کتاب', 'خانہ')
// → { matched: true, type: 'affix' }

isCompound('علم', 'و')
// → { matched: true, type: 'izafat' }

isCompound('اچھا', 'آدمی')
// → { matched: false, type: null }

// Check only the lexicon layer:
isCompound('ہاتھ', 'پاؤں', { layers: ['lexicon'] })
// → { matched: true, type: 'lexicon' }

isCompound('کتاب', 'خانہ', { layers: ['lexicon'] })
// → { matched: false, type: null }  // affix match excluded

sort(['ے', 'ا', 'ک', 'ب'])
// → ['ا', 'ب', 'ک', 'ے']

sort(['زبان', 'اردو', 'بہترین', 'پاکستان'])
// → ['اردو', 'بہترین', 'زبان', 'پاکستان']

sort(words, true)   // reverse=true for ے→ء order

compare('ا', 'ب')   // < 0  (ا comes before ب)
compare('ے', 'ا')   // > 0  (ے comes after ا)
compare('عِلم', 'عَلم')  // 0  (diacritics stripped, equal)

sortKey('پاکستان')  // '030003091102280814'  (deterministic, cacheable)

toRoman('پاکستان')        // 'pakistan'
toRoman('بھارت')          // 'bharat'   (not 'b'+'harat')
toRoman('چھوٹا بھائی')    // 'chhota bhai'
toRoman('زندہ باد')       // 'zinda bad'

fromRoman('pakistan')     // 'پاکستان'
fromRoman('bharat')       // 'بھارت'
fromRoman('lahore')       // 'لاہور'

// Use case: search index aliases
const aliases = [toRoman(urduWord), urduWord]
// → store both 'pakistan' and 'پاکستان' in search index

getScript('پاکستان')               // 'urdu'
getScript('مرحبا')                  // 'arabic'
getScript('Hello پاکستان')         // 'mixed'
getScript('Hello World')            // 'latin'

isRTL('پاکستان')                   // true
isRTL('Hello')                      // false
isRTL('123')                        // false

getUrduDensity('پاکستان زندہ باد')  // ~0.42  (high → render RTL)
getUrduDensity('مرحبا')             // ~0.0   (Arabic, not Urdu-specific)

// Dynamic direction for user content:
const dir = getUrduDensity(userContent) > 0.3 ? 'rtl' : 'ltr'
element.setAttribute('dir', dir)

isUrduChar('پ')     // true  (U+067E — Urdu-specific)
isUrduChar('ب')     // false (U+0628 — shared Arabic/Urdu)
isUrduChar('۱')     // true  (U+06F1 — Extended Arabic-Indic numeral)

isUrduText('پاکستان')           // true  (above 0.1 threshold)
isUrduText('مرحبا')             // false (Arabic letters, not Urdu-specific)
isUrduText('Hello', 0.0)        // false

classifyChar('پ')   // 'urdu-letter'
classifyChar('ب')   // 'arabic-letter'
classifyChar('َ')   // 'diacritic'    (zabar)
classifyChar('۱')   // 'numeral'
classifyChar(' ')   // 'whitespace'
classifyChar('A')   // 'latin'
classifyChar('!')   // 'punctuation'