arabic-number-formatter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# Arabic Number Formatter
+
+Convert numbers to Arabic words with full support for:
+
+- Gender: masculine / feminine
+- Case: رفع / نصب
+- Definite: ال
+- Currency (main / sub / special sub-unit)
+- Up to billions
+
+## Example
+
+```js
+import { createArabicNumberFormatter } from "./src/ArabicNumberFormatter";
+
+const formatter = createArabicNumberFormatter({
+  gender: "feminine",
+  case: "nasb",
+});
+console.log(formatter.format(23));
+// ثلاث و عشرين
+
+const dinarFormatter = createArabicNumberFormatter({
+  currency: {
+    main: "دينار اردني",
+    sub: "قرش",
+    subUnder10: "قروش",
+  },
+});
+
+dinarFormatter.format(1234.05);
+// الف و مائتان و أربعة و ثلاثون دينار اردني و خمسة قروش
+
+dinarFormatter.format(1234.75);
+// الف و مائتان و أربعة و ثلاثون دينار اردني و خمسة و سبعون قرش
+```
+
+For ordinal numbers, the current support is up to 19.
+
+<!-- Defaults: Masculine/ Definite:false , Case:rafe3-->

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "arabic-number-formatter",
+  "version": "1.0.0",
+  "description": "Convert numbers to Arabic words with gender, case, definite, and currency support.",
+  "main": "src/ArabicNumberFormatter.js",
+  "type": "module",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "arabic",
+    "numbers",
+    "formatter",
+    "currency",
+    "words",
+    "masculine",
+    "feminine"
+  ],
+  "author": "Alexander",
+  "license": "MIT"
+}

package/src/ArabicNumberFormatter.js

@@ -0,0 +1,236 @@
+/* ===================================================== */
+/* ARABIC NUMBER FORMATTER ENGINE                       */
+/* ===================================================== */
+
+const dictionaries = {
+    masculine: [
+        "",
+        "واحد",
+        "اثنان",
+        "ثلاثة",
+        "أربعة",
+        "خمسة",
+        "ستة",
+        "سبعة",
+        "ثمانية",
+        "تسعة",
+    ],
+    feminine: [
+        "",
+        "واحدة",
+        "اثنتان",
+        "ثلاث",
+        "أربع",
+        "خمس",
+        "ست",
+        "سبع",
+        "ثمان",
+        "تسع",
+    ],
+};
+
+const ordinals = {
+    masculine: [
+        "",
+        "الأول",
+        "الثاني",
+        "الثالث",
+        "الرابع",
+        "الخامس",
+        "السادس",
+        "السابع",
+        "الثامن",
+        "التاسع",
+        "العاشر",
+    ],
+    feminine: [
+        "",
+        "الأولى",
+        "الثانية",
+        "الثالثة",
+        "الرابعة",
+        "الخامسة",
+        "السادسة",
+        "السابعة",
+        "الثامنة",
+        "التاسعة",
+        "العاشرة",
+    ],
+};
+
+const tens = [
+    "",
+    "عشر",
+    "عشرون",
+    "ثلاثون",
+    "أربعون",
+    "خمسون",
+    "ستون",
+    "سبعون",
+    "ثمانون",
+    "تسعون",
+];
+
+const hundreds = [
+    "",
+    "مائة",
+    "مائتان",
+    "ثلاثمائة",
+    "أربعمائة",
+    "خمسمائة",
+    "ستمائة",
+    "سبعمائة",
+    "ثمانمائة",
+    "تسعمائة",
+];
+
+const sectors = [
+    "", // units
+    { singular: "الف", dual: "الفان", plural: "الاف" },
+    { singular: "مليون", dual: "مليونان", plural: "ملايين" },
+    { singular: "مليار", dual: "ملياران", plural: "مليارات" },
+];
+
+/* ===================================================== */
+/* FACTORY FUNCTION                                     */
+/* ===================================================== */
+
+export const createArabicNumberFormatter = (defaultOptions = {}) => {
+    const {
+        gender = "masculine",
+        grammaticalCase = "raf3", // raf3 | nasb
+        definite = false,
+        ordinal = false, // true = positions
+        currency = null, // { main, sub, subUnder10 }
+    } = defaultOptions;
+
+    const ones = ordinal ? ordinals[gender] : dictionaries[gender];
+
+    if (!ones) throw new Error("Invalid gender option");
+
+    const adjustCase = (word) => {
+        if (!word) return word;
+        if (grammaticalCase === "nasb") {
+            if (word.endsWith("ون")) return word.replace("ون", "ين");
+            if (word.endsWith("ان")) return word.replace("ان", "ين");
+        }
+        return word;
+    };
+
+    const applyDefinite = (word) => {
+        if (!definite || !word) return word;
+        if (word.startsWith("ال")) return word;
+        return "ال" + word;
+    };
+
+    const numberToTriplets = (num) => {
+        return num
+            .toString()
+            .padStart(Math.ceil(num.toString().length / 3) * 3, "0")
+            .match(/.{1,3}/g)
+            .map((g) => g.split("").map(Number));
+    };
+
+    const convertTriplet = ([h = 0, t = 0, u = 0]) => {
+        if (ordinal) {
+            // 1–10 → direct ordinal
+            if (h === 0 && t === 0 && u > 0 && u <= 10) return ones[u];
+
+            // 11–19 → special ordinal
+            if (h === 0 && t === 1 && u > 0) {
+                if (gender === "masculine") {
+                    if (u === 1) return "الحادي عشر";
+                    if (u === 2) return "الثاني عشر";
+                    return ordinals.masculine[u] + " عشر";
+                } else {
+                    if (u === 1) return "الحادية عشرة";
+                    if (u === 2) return "الثانية عشرة";
+                    return ordinals.feminine[u] + " عشرة";
+                }
+            }
+        }
+
+        // Regular cardinal numbers
+        let parts = [];
+        if (h) parts.push(hundreds[h]);
+
+        if (t === 1 && u > 0) {
+            if (u === 1) parts.push("أحد عشر");
+            else if (u === 2) parts.push("اثنا عشر");
+            else parts.push(dictionaries[gender][u] + " عشر");
+        } else {
+            if (u) parts.push(dictionaries[gender][u]);
+            if (t) parts.push(adjustCase(tens[t]));
+        }
+
+        return parts.join(" و ");
+    };
+
+    const getSectorLabel = (value, sectorIndex) => {
+        if (sectorIndex === 0) return "";
+
+        let label;
+
+        if (value === 1) label = sectors[sectorIndex].singular;
+        else if (value === 2) label = sectors[sectorIndex].dual;
+        else if (value >= 3 && value <= 10) label = sectors[sectorIndex].plural;
+        else label = sectors[sectorIndex].singular;
+
+        label = adjustCase(label);
+        label = applyDefinite(label);
+
+        return label;
+    };
+
+    const formatNumber = (num) => {
+        if (num === 0) return "صفر";
+
+        const triplets = numberToTriplets(num);
+        let result = [];
+
+        for (let i = 0; i < triplets.length; i++) {
+            const sectorIndex = triplets.length - 1 - i;
+            const value = parseInt(triplets[i].join(""));
+            if (value === 0) continue;
+
+            const words = convertTriplet(triplets[i]);
+            const label = getSectorLabel(value, sectorIndex);
+
+            if ((value === 1 || value === 2) && sectorIndex > 0) {
+                result.push(label);
+            } else {
+                result.push(words + (label ? " " + label : ""));
+            }
+        }
+
+        return result.join(" و ");
+    };
+
+    const formatCurrency = (amount) => {
+        const [mainPart, subPartStr] = amount.toFixed(2).split(".");
+        const mainNum = parseInt(mainPart);
+        const subNum = parseInt(subPartStr);
+
+        const mainText = formatNumber(mainNum);
+
+        let subText = "";
+        if (subNum > 0) {
+            const subLabel =
+                subNum <= 10 && currency.subUnder10
+                    ? currency.subUnder10
+                    : currency.sub;
+
+            subText = `${formatNumber(subNum)} ${subLabel}`;
+        }
+
+        if (subText) return `${mainText} ${currency.main} و ${subText}`;
+        return `${mainText} ${currency.main}`;
+    };
+
+    return {
+        format: (num) => {
+            if (currency) return formatCurrency(num);
+            return formatNumber(num);
+        },
+    };
+};