تفقيط المبلغ بالحروف في TypeScript: دالة صحيحة نحوياً

tafqit(1520, { currency: 'SAR' });
// ألف وخمسمائة وعشرون ريال سعودي فقط لا غير
 
tafqit('1.15', { currency: 'SAR' });
// واحد ريال سعودي وخمس عشرة هللة فقط لا غير
 
tafqit('1.5', { currency: 'KWD' });
// واحد دينار كويتي وخمسمائة فلس فقط لا غير
 
tafqit(234000, { currency: 'SAR' });
// مائتان وأربعة وثلاثون ألفًا ريال سعودي فقط لا غير

mkdir tafqit && cd tafqit
npm init -y
npm install --save-dev typescript @types/node
npx tsc --init --target es2020 --module nodenext --strict
mkdir src

// src/normalize.ts
 
/** Normalise Arabic-Indic and Eastern digits so pasted amounts just work. */
export function normalizeDigits(s: string): string {
  return s.replace(/[٠-٩۰-۹]/g, (d) => {
    const code = d.charCodeAt(0);
    const base = code >= 0x06f0 ? 0x06f0 : 0x0660;
    return String(code - base);
  });
}

// src/numbers.ts
 
/** Gender of the noun being counted — not of the number word. */
export type Gender = 'm' | 'f';
 
/** Both spellings are in live use; Gulf official documents tend to مائة. */
export type HundredsForm = 'مائة' | 'مئة';
 
/** 1–9 as they appear when counting a masculine noun (3–9 carry the ة). */
const ONES_M = ['', 'واحد', 'اثنان', 'ثلاثة', 'أربعة', 'خمسة', 'ستة', 'سبعة', 'ثمانية', 'تسعة'];
/** 1–9 as they appear when counting a feminine noun (3–9 are bare). */
const ONES_F = ['', 'واحدة', 'اثنتان', 'ثلاث', 'أربع', 'خمس', 'ست', 'سبع', 'ثماني', 'تسع'];
 
/** The unit half of 11–19. 11 and 12 are irregular and agree rather than reverse. */
const TEEN_UNIT_M = ['عشرة', 'أحد', 'اثنا', 'ثلاثة', 'أربعة', 'خمسة', 'ستة', 'سبعة', 'ثمانية', 'تسعة'];
const TEEN_UNIT_F = ['عشر', 'إحدى', 'اثنتا', 'ثلاث', 'أربع', 'خمس', 'ست', 'سبع', 'ثماني', 'تسع'];
 
const TENS = ['', '', 'عشرون', 'ثلاثون', 'أربعون', 'خمسون', 'ستون', 'سبعون', 'ثمانون', 'تسعون'];
 
export const ZERO = 'صفر';
 
/** 1–99, given the gender of the noun being counted. */
function underHundred(n: number, gender: Gender): string {
  const ones = gender === 'm' ? ONES_M : ONES_F;
  if (n < 10) return ones[n];
 
  if (n < 20) {
    const unit = (gender === 'm' ? TEEN_UNIT_M : TEEN_UNIT_F)[n - 10];
    if (n === 10) return unit;
    // The عشر half agrees with the noun — the inverse of standalone ten.
    return `${unit} ${gender === 'm' ? 'عشر' : 'عشرة'}`;
  }
 
  const ten = TENS[Math.floor(n / 10)];
  const unit = n % 10;
  // Arabic puts the unit before the ten: خمسة وعشرون, not عشرون وخمسة.
  return unit ? `${ones[unit]} و${ten}` : ten;
}

/**
 * Hundreds 100–900.
 *
 * 300–900 are conventionally written as one word (ثلاثمائة), and the unit uses
 * the feminine-noun column because مائة is feminine. 800 contracts to ثمان +
 * مائة rather than taking the standalone ثماني form with a yaa.
 */
function hundredsToWords(h: number, form: HundredsForm, construct = false): string {
  if (h === 0) return '';
  if (h === 1) return form;
  if (h === 2) {
    // The dual loses its nūn in the construct state: مائتا ألف, not مائتان ألف.
    const base = form === 'مائة' ? 'مائت' : 'مئت';
    return base + (construct ? 'ا' : 'ان');
  }
  // 800 contracts — ثمانمائة, not ثمانيمائة.
  return (h === 8 ? 'ثمان' : ONES_F[h]) + form;
}
 
/** 0–999. Returns '' for 0 so callers can drop empty groups. */
export function tripletToWords(
  n: number,
  gender: Gender,
  form: HundredsForm = 'مائة',
  construct = false,
): string {
  if (n === 0) return '';
  const parts: string[] = [];
  // The construct form only applies when the hundreds are the final component,
  // i.e. nothing follows them inside the group.
  const h = hundredsToWords(Math.floor(n / 100), form, construct && n % 100 === 0);
  if (h) parts.push(h);
  const rest = underHundred(n % 100, gender);
  if (rest) parts.push(rest);
  return parts.join(' و');
}

/** Scale words, in singular / dual / plural / accusative-singular forms. */
const SCALES: { one: string; two: string; plural: string; accusative: string }[] = [
  { one: '', two: '', plural: '', accusative: '' }, // units — no scale word
  { one: 'ألف', two: 'ألفان', plural: 'آلاف', accusative: 'ألفًا' },
  { one: 'مليون', two: 'مليونان', plural: 'ملايين', accusative: 'مليونًا' },
  { one: 'مليار', two: 'ملياران', plural: 'مليارات', accusative: 'مليارًا' },
  { one: 'تريليون', two: 'تريليونان', plural: 'تريليونات', accusative: 'تريليونًا' },
];
 
/** Largest value this can express, one short of the next unnamed scale. */
export const MAX_VALUE = 1_000 ** SCALES.length - 1;
 
function scaleGroup(group: number, level: number, form: HundredsForm): string {
  const s = SCALES[level];
  if (group === 1) return s.one;
  if (group === 2) return s.two;
 
  const tail = group % 100;
  // The scale word is a masculine noun, so its multiplier follows the masculine
  // column whatever the final counted noun happens to be.
  const count = tripletToWords(group, 'm', form, tail === 0);
  if (tail === 0) return `${count} ${s.one}`;              // مائة ألف
  if (tail <= 2 && group < 100) return `${count} ${s.one}`;
  if (tail <= 10) return `${count} ${s.plural}`;           // ثلاثة آلاف
  return `${count} ${s.accusative}`;                        // أحد عشر ألفًا
}

export function integerToWords(
  value: number,
  gender: Gender = 'm',
  form: HundredsForm = 'مائة',
): string {
  if (!Number.isFinite(value)) throw new RangeError('Not a finite number');
  const negative = value < 0;
  let n = Math.abs(Math.trunc(value));
  if (n > MAX_VALUE) throw new RangeError(`Number too large for tafqit: max ${MAX_VALUE}`);
  if (n === 0) return ZERO;
 
  // Split into groups of three, least significant first. MAX_VALUE is below
  // Number.MAX_SAFE_INTEGER, so ordinary arithmetic stays exact and there is
  // no need for BigInt.
  const groups: number[] = [];
  while (n > 0) {
    groups.push(n % 1000);
    n = Math.floor(n / 1000);
  }
 
  const parts: string[] = [];
  for (let level = groups.length - 1; level >= 0; level -= 1) {
    const g = groups[level];
    if (g === 0) continue;
    parts.push(level === 0 ? tripletToWords(g, gender, form) : scaleGroup(g, level, form));
  }
 
  const words = parts.join(' و');
  return negative ? `سالب ${words}` : words;
}

// src/currencies.ts
import type { Gender } from './numbers';
 
export type Currency = {
  code: string;
  /** Singular major unit, e.g. ريال سعودي. */
  name: string;
  gender: Gender;
  /** Singular minor unit, e.g. هللة. Absent for currencies with no minor unit. */
  minorName?: string;
  minorGender?: Gender;
  /** Minor units per major. */
  minor: number;
};
 
export const CURRENCIES: Record<string, Currency> = {
  SAR: { code: 'SAR', name: 'ريال سعودي', gender: 'm', minorName: 'هللة', minorGender: 'f', minor: 100 },
  AED: { code: 'AED', name: 'درهم إماراتي', gender: 'm', minorName: 'فلس', minorGender: 'm', minor: 100 },
  KWD: { code: 'KWD', name: 'دينار كويتي', gender: 'm', minorName: 'فلس', minorGender: 'm', minor: 1000 },
  BHD: { code: 'BHD', name: 'دينار بحريني', gender: 'm', minorName: 'فلس', minorGender: 'm', minor: 1000 },
  OMR: { code: 'OMR', name: 'ريال عماني', gender: 'm', minorName: 'بيسة', minorGender: 'f', minor: 1000 },
  JOD: { code: 'JOD', name: 'دينار أردني', gender: 'm', minorName: 'فلس', minorGender: 'm', minor: 1000 },
  TND: { code: 'TND', name: 'دينار تونسي', gender: 'm', minorName: 'مليم', minorGender: 'm', minor: 1000 },
  SYP: { code: 'SYP', name: 'ليرة سورية', gender: 'f', minorName: 'قرش', minorGender: 'm', minor: 100 },
  EGP: { code: 'EGP', name: 'جنيه مصري', gender: 'm', minorName: 'قرش', minorGender: 'm', minor: 100 },
};
 
export function getCurrency(code: string): Currency | undefined {
  return CURRENCIES[code.toUpperCase()];
}

Math.round(parseFloat('1.005') * 100);   // 100 — not 101
Math.round(parseFloat('8.165') * 100);   // 816 — not 817
Math.round(parseFloat('1.15') * 100);    // 115 — this one survives

// src/split.ts
 
/**
 * Split a decimal amount into major and minor units without going through
 * floating point twice. Reading the digits from the string keeps the minor
 * part exact.
 */
export function splitAmount(input: string, minorPer: number): { major: number; minor: number } {
  const [wholeRaw, fracRaw = ''] = input.split('.');
  const digits = String(minorPer).length - 1; // 100 -> 2, 1000 -> 3
  const padded = (fracRaw + '0'.repeat(digits)).slice(0, digits);
  let minor = padded === '' ? 0 : Number(padded);
 
  if ((wholeRaw || '').replace(/^0+/, '').length > 16) {
    throw new RangeError('Number too large for tafqit');
  }
  let major = Number(wholeRaw || '0');
 
  // A fraction longer than the currency's precision rounds into the minor unit,
  // and can carry all the way into the major one: 1.999 SAR is 2 riyals.
  const next = fracRaw[digits];
  if (next && Number(next) >= 5) {
    minor += 1;
    if (minor >= minorPer) {
      minor = 0;
      major += 1;
    }
  }
  return { major, minor };
}

// src/index.ts
import { integerToWords, MAX_VALUE, ZERO, type Gender, type HundredsForm } from './numbers';
import { getCurrency, type Currency } from './currencies';
import { normalizeDigits } from './normalize';
import { splitAmount } from './split';
 
const CLOSING = 'فقط لا غير';
 
export type TafqitOptions = {
  /** Gender of the counted noun. Ignored when `currency` is set. */
  gender?: Gender;
  /** مائة (default, usual in Gulf official documents) or مئة. */
  hundreds?: HundredsForm;
  /** ISO code, e.g. 'SAR'. Adds the unit names and the closing formula. */
  currency?: string;
  /** Override the closing formula. Defaults to on for currency amounts. */
  closing?: boolean | string;
};
 
function unitPhrase(count: number, words: string, name: string): string {
  // The convention in cheques and invoices is to append the unit name
  // uninflected — «ألف وخمسمائة وعشرون ريال سعودي» — rather than decline it.
  return count === 0 ? '' : `${words} ${name}`;
}
 
export function tafqit(value: number | string, options: TafqitOptions = {}): string {
  const { gender = 'm', hundreds = 'مائة' } = options;
  const currency: Currency | undefined = options.currency ? getCurrency(options.currency) : undefined;
  if (options.currency && !currency) {
    throw new Error(`Unknown currency: ${options.currency}`);
  }
 
  const raw = normalizeDigits(String(value).trim()).replace(/[,\s٬]/g, '');
  if (!/^-?\d*(\.\d*)?$/.test(raw) || raw === '' || raw === '-') {
    throw new Error(`Not a number: ${value}`);
  }
  const negative = raw.startsWith('-');
  const body = negative ? raw.slice(1) : raw;
 
  const closingText =
    typeof options.closing === 'string'
      ? options.closing
      : (options.closing ?? Boolean(currency))
        ? CLOSING
        : '';
 
  if (!currency) {
    const [whole] = body.split('.');
    const n = Number(whole || '0');
    if (n > MAX_VALUE) throw new RangeError('Number too large for tafqit');
    const words = integerToWords(negative ? -n : n, gender, hundreds);
    return closingText ? `${words} ${closingText}` : words;
  }
 
  const { major, minor } = splitAmount(body, currency.minor);
  if (major > MAX_VALUE) throw new RangeError('Number too large for tafqit');
 
  const parts: string[] = [];
  if (major > 0 || minor === 0) {
    parts.push(unitPhrase(major, integerToWords(major, currency.gender, hundreds), currency.name));
  }
  if (minor > 0 && currency.minorName) {
    const minorWords = integerToWords(minor, currency.minorGender ?? 'm', hundreds);
    parts.push(unitPhrase(minor, minorWords, currency.minorName));
  }
 
  let out = parts.filter(Boolean).join(' و');
  if (negative) out = `سالب ${out}`;
  return closingText ? `${out} ${closingText}` : out;
}
 
export { ZERO, MAX_VALUE };

// src/invoice.ts
import { tafqit } from './index';
 
type InvoiceLine = { description: string; amountMinor: number };
 
/**
 * Amounts live as integer minor units everywhere inside the system, and are
 * turned into a decimal string exactly once, at the edge, for tafqit. That
 * single boundary is what keeps the words and the figure in agreement.
 */
export function amountInWords(totalMinor: number, currency: string, minorPer = 100): string {
  const major = Math.trunc(totalMinor / minorPer);
  const minor = Math.abs(totalMinor % minorPer);
  const decimals = String(minorPer).length - 1;
  const asString = `${major}.${String(minor).padStart(decimals, '0')}`;
  return tafqit(asString, { currency });
}
 
export function renderTotals(lines: InvoiceLine[], currency = 'SAR', minorPer = 100) {
  const totalMinor = lines.reduce((sum, l) => sum + l.amountMinor, 0);
  const decimals = String(minorPer).length - 1;
  return {
    figure: (totalMinor / minorPer).toFixed(decimals),
    words: amountInWords(totalMinor, currency, minorPer),
  };
}

// src/tafqit.test.ts
import test from 'node:test';
import assert from 'node:assert/strict';
import { tafqit } from './index';
import { integerToWords } from './numbers';
 
test('3–10 reverse the gender of the counted noun', () => {
  assert.equal(integerToWords(3, 'm'), 'ثلاثة');
  assert.equal(integerToWords(3, 'f'), 'ثلاث');
});
 
test('standalone ten is the inverse of the عشر inside a teen', () => {
  assert.equal(integerToWords(10, 'm'), 'عشرة');
  assert.equal(integerToWords(10, 'f'), 'عشر');
  assert.equal(integerToWords(13, 'm'), 'ثلاثة عشر');
  assert.equal(integerToWords(13, 'f'), 'ثلاث عشرة');
});
 
test('the scale word form follows the last component, not the size', () => {
  assert.equal(integerToWords(100000), 'مائة ألف');
  assert.equal(integerToWords(3000), 'ثلاثة آلاف');
  assert.equal(integerToWords(11000), 'أحد عشر ألفًا');
  assert.equal(integerToWords(234000), 'مائتان وأربعة وثلاثون ألفًا');
});
 
test('the minor unit is not always 100', () => {
  assert.match(tafqit('1.5', { currency: 'SAR' }), /خمسون هللة/);
  assert.match(tafqit('1.5', { currency: 'KWD' }), /خمسمائة فلس/);
});
 
test('the decimal does not swallow a halala', () => {
  assert.match(tafqit('1.15', { currency: 'SAR' }), /خمس عشرة هللة/);
  assert.match(tafqit('1.005', { currency: 'SAR' }), /هللة/);
  assert.match(tafqit('8.165', { currency: 'SAR' }), /سبع عشرة هللة/);
});
 
test('the minor unit carries into the major one', () => {
  assert.equal(tafqit('1.999', { currency: 'SAR' }), 'اثنان ريال سعودي فقط لا غير');
});
 
test('the currency carries its own gender', () => {
  assert.equal(tafqit(3, { currency: 'SYP' }), 'ثلاث ليرة سورية فقط لا غير');
});
 
test('Arabic-Indic digits are accepted as pasted', () => {
  assert.equal(tafqit('١٢٣'), tafqit('123'));
});