kalpak-js 1.0.0 → 1.1.0

package/README.md

@@ -1,50 +1,46 @@
 # Kalpak.js 🧢
 
-A lightweight, accurate JavaScript library for transliterating **Karakalpak** text between Latin and Cyrillic scripts.
-Built by [**Ishipiskenler**](https://github.com/ishipiskenler) (The Doers).
+Karakalpak language tools for JavaScript.
 
-> **Note:** This library follows the official Karakalpak alphabet tables (Yellow Table standards).
+## Install
 
-## ✨ Features
+```bash
+npm install kalpak-js
+```
 
-- **Latin ➡️ Cyrillic**: Handles complex digraphs (Sh, Ch, etc.) correctly.
-- **Cyrillic ➡️ Latin**: Supports official mappings (e.g., И→I, Ы→Í).
-- **Zero Dependencies**: Pure JavaScript. Fast and simple.
+## Features
 
-## 📦 Installation
+### 1. Transliteration
 
-```bash
-# Clone the repository
-git clone https://github.com/ishipiskenler/karakalpak-translit-js.git
+Convert text between Latin and Cyrillic scripts.
+
+```javascript
+const { latinToCyrillic, cyrillicToLatin } = require("kalpak-js");
+
+latinToCyrillic("Sálem"); // "Сәлем"
+cyrillicToLatin("Сәлем"); // "Sálem"
 ```
 
-_(NPM package coming soon!)_
+### 2. Number to Text
 
-## 🚀 Usage
+Convert numbers to Karakalpak words (0 to 1 trillion).
 
 ```javascript
-const { latinToCyrillic, cyrillicToLatin } = require("./index");
+const { numberToText } = require("kalpak-js");
 
-// 1. Latin to Cyrillic
-const cyrillic = latinToCyrillic("Sálem, Qaraqalpaqstan!");
-console.log(cyrillic);
-// Output: "Сәлем, Қарақалпақстан!"
-
-// 2. Cyrillic to Latin
-const latin = cyrillicToLatin("Мен сeни жақсы көремен ❤️");
-console.log(latin);
-// Output: "Men seni jaqsı kóremen"
+numberToText(42); // "qırıq eki"
+numberToText(2026); // "eki miń jigirma altı"
+numberToText(1000000); // "bir million"
 ```
 
-## 🤝 Contributing
-
-We welcome contributions!
+## API
 
-1. Fork the repo
-2. Create your feature branch
-3. Commit your changes
-4. Open a Pull Request
+| Function                | Input                   | Output           |
+| ----------------------- | ----------------------- | ---------------- |
+| `latinToCyrillic(text)` | Latin string            | Cyrillic string  |
+| `cyrillicToLatin(text)` | Cyrillic string         | Latin string     |
+| `numberToText(num)`     | Number (0 - 1 trillion) | Karakalpak words |
 
----
+## License
 
-© 2026 **Ishipiskenler**. Open Source.
+MIT © [Ishipiskenler](https://github.com/ishipiskenler)

package/index.js

@@ -1,218 +1,8 @@
-const latinToCyrillicMap = {
-  // Basic letters
-  A: "А",
-  a: "а",
-  B: "Б",
-  b: "б",
-  D: "Д",
-  d: "д",
-  E: "Е",
-  e: "е",
-  F: "Ф",
-  f: "ф",
-  G: "Г",
-  g: "г",
-  H: "Ҳ",
-  h: "ҳ",
-  X: "Х",
-  x: "х",
-  J: "Ж",
-  j: "ж",
-  K: "К",
-  k: "к",
-  Q: "Қ",
-  q: "қ",
-  L: "Л",
-  l: "л",
-  M: "М",
-  m: "м",
-  N: "Н",
-  n: "н",
-  O: "О",
-  o: "о",
-  P: "П",
-  p: "п",
-  R: "Р",
-  r: "р",
-  S: "С",
-  s: "с",
-  T: "Т",
-  t: "т",
-  U: "У",
-  u: "у",
-  V: "В",
-  v: "в",
-  Z: "З",
-  z: "з",
-
-  // Special Karakalpak letters
-  Á: "Ә",
-  á: "ә",
-  Ó: "Ө",
-  ó: "ө",
-  Ú: "Ү",
-  ú: "ү",
-  I: "И",
-  i: "и",
-  Í: "Ы",
-  ı: "ы",
-  Ǵ: "Ғ",
-  ǵ: "ғ",
-  Ń: "Ң",
-  ń: "ң",
-
-  // Extra letters
-  Y: "Й",
-  y: "й",
-  W: "Ў",
-  w: "ў",
-
-  // Digraphs
-  Sh: "Ш",
-  sh: "ш",
-  SH: "Ш",
-  Yu: "Ю",
-  yu: "ю",
-  Ya: "Я",
-  ya: "я",
-  Yo: "Ё",
-  yo: "ё",
-
-  Ch: "Ч",
-  ch: "ч",
-  CH: "Ч",
-
-  // Optional / borrowed letters
-  C: "Ц",
-  c: "ц",
-};
-
-const cyrillicToLatinMap = {
-  А: "A",
-  а: "a",
-  Ә: "Á",
-  ә: "á",
-  Б: "B",
-  б: "b",
-  В: "V",
-  в: "v",
-  Г: "G",
-  г: "g",
-  Ғ: "Ǵ",
-  ғ: "ǵ",
-  Д: "D",
-  д: "d",
-  Е: "E",
-  е: "e",
-  Ё: "Yo",
-  ё: "yo",
-  Ж: "J",
-  ж: "j",
-  З: "Z",
-  з: "z",
-  И: "I",
-  и: "i",
-  Й: "Y",
-  й: "y",
-  К: "K",
-  к: "k",
-  Қ: "Q",
-  қ: "q",
-  Л: "L",
-  л: "l",
-  М: "M",
-  м: "m",
-  Н: "N",
-  н: "n",
-  Ң: "Ń",
-  ң: "ń",
-  О: "O",
-  о: "o",
-  Ө: "Ó",
-  ө: "ó",
-  П: "P",
-  п: "p",
-  Р: "R",
-  р: "r",
-  С: "S",
-  с: "s",
-  Т: "T",
-  т: "t",
-  У: "U",
-  у: "u",
-  Ү: "Ú",
-  ү: "ú",
-  Ў: "W",
-  ў: "w",
-  Ф: "F",
-  ф: "f",
-  Х: "X",
-  х: "x",
-  Ҳ: "H",
-  ҳ: "h",
-  Ш: "Sh",
-  ш: "sh",
-  Ч: "Ch",
-  ч: "ch",
-  Щ: "Sh",
-  щ: "sh", // optional
-  Ы: "Í",
-  ы: "ı",
-
-  // Borrowed/Russian letters
-  Ц: "C",
-  ц: "c",
-  Э: "E",
-  э: "e",
-  Ю: "Yu",
-  ю: "yu",
-  Я: "Ya",
-  я: "ya",
-  Ъ: "",
-  ъ: "",
-  Ь: "",
-  ь: "",
-};
-
-function latinToCyrillic(text) {
-  let result = "";
-
-  for (let i = 0; i < text.length; i++) {
-    let twoChars = text[i] + (text[i + 1] || "");
-    if (latinToCyrillicMap[twoChars]) {
-      result += latinToCyrillicMap[twoChars];
-      i++;
-      continue;
-    }
-
-    let oneChar = text[i];
-    if (latinToCyrillicMap[oneChar]) {
-      result += latinToCyrillicMap[oneChar];
-    } else {
-      result += oneChar;
-    }
-  }
-
-  return result;
-}
-
-function cyrillicToLatin(text) {
-  let result = "";
-
-  for (let i = 0; i < text.length; i++) {
-    const char = text[i];
-
-    if (cyrillicToLatinMap[char] !== undefined) {
-      result += cyrillicToLatinMap[char];
-    } else {
-      result += char;
-    }
-  }
-
-  return result;
-}
+const { latinToCyrillic, cyrillicToLatin } = require("./src/transliterate");
+const { numberToText } = require("./src/numbers");
 
 module.exports = {
   latinToCyrillic,
   cyrillicToLatin,
+  numberToText,
 };

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "kalpak-js",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "description": "A lightweight JavaScript library for Karakalpak Cyrillic-Latin transliteration.",
+  "description": "Karakalpak language tools: transliteration (Latin/Cyrillic) and number-to-text conversion.",
   "keywords": [
     "karakalpak",
     "transliteration",
     "cyrillic",
     "latin",
     "qaraqalpaq",
-    "language"
+    "language",
+    "numbers",
+    "karakalpakstan",
+    "uzbekistan"
   ],
   "author": "Ishipiskenler",
   "license": "MIT",

package/src/numbers.js

@@ -0,0 +1,145 @@
+// 1. Define the building blocks
+const digits = [
+  "nól",
+  "bir",
+  "eki",
+  "úsh",
+  "tórt",
+  "bes",
+  "altı",
+  "jeti",
+  "segiz",
+  "toǵız",
+];
+
+const tens = {
+  10: "on",
+  20: "jigirma",
+  30: "otız",
+  40: "qırıq",
+  50: "eliw",
+  60: "alpıs",
+  70: "jetpis",
+  80: "seksen",
+  90: "toqsan",
+};
+
+const hundreds = {
+  100: "bir júz",
+  200: "eki júz",
+  300: "úsh júz",
+  400: "tórt júz",
+  500: "bes júz",
+  600: "altı júz",
+  700: "jeti júz",
+  800: "segiz júz",
+  900: "toǵız júz",
+};
+
+function numberToText(num) {
+  // 0. Safety check (Validation)
+  if (typeof num !== "number") return "Error: Not a number";
+  if (num < 0 || num > 1000000000000)
+    return "Error: Only 0-1000000000000 (up to one trillion) supported for now";
+
+  // 1. Handle exact whole numbers
+  if (num === 100) return "júz";
+  if (num === 1000) return "miń";
+  if (num === 10000) return "on miń";
+  if (num === 100000) return "júz miń";
+  if (num === 1000000) return "bir million";
+  if (num === 10000000) return "on million";
+  if (num === 100000000) return "júz million";
+  if (num === 1000000000) return "bir milliard";
+  if (num === 10000000000) return "on milliard";
+  if (num === 100000000000) return "júz milliard";
+  if (num === 1000000000000) return "bir trillion";
+
+  // 2. Handle 0-9
+  if (num < 10) {
+    return digits[num];
+  }
+
+  // 3. Handle 10-99
+  if (num > 9 && num < 100) {
+    const tenPart = Math.floor(num / 10) * 10; // e.g. 42 -> 40
+    const onePart = num % 10; // e.g. 42 -> 2
+
+    const tenText = tens[tenPart];
+
+    // If perfectly 20, 30, 40... (onePart is 0), just return the tenText
+    if (onePart === 0) {
+      return tenText;
+    }
+
+    // Otherwise combine them: "qırıq" + " " + "eki"
+    const oneText = digits[onePart];
+    return `${tenText} ${oneText}`;
+  }
+
+  // Handle 100-999
+  if (num >= 100 && num < 1000) {
+    const hundredsPart = Math.floor(num / 100) * 100;
+    const tenPart = Math.floor((num % 100) / 10) * 10;
+    const onePart = (num % 100) % 10;
+
+    const hundredsText = hundreds[hundredsPart];
+    const tenText = tens[tenPart];
+    const oneText = digits[onePart];
+
+    if (tenPart === 0 && onePart === 0) {
+      return `${hundreds[num]}`;
+    }
+
+    // If the ten-part is zero, return hundreds and one-part only (101,102, ...)
+    if (tenPart === 0) {
+      return `${hundredsText} ${oneText}`;
+    }
+
+    // If the one-part is zero, return hundreds-part and tens-part only (110,120, ...)
+    if (onePart === 0) {
+      return `${hundredsText} ${tenText}`;
+    }
+
+    // You know this broo :)
+    return `${hundredsText} ${tenText} ${oneText}`;
+  }
+
+  // Handle (1000 - 999999) (thousands)
+  if (num >= 1000 && num < 1000000) {
+    const thousandsPart = Math.floor(num / 1000);
+    const remainder = num % 1000;
+
+    if (remainder === 0) {
+      return `${numberToText(thousandsPart)} miń`;
+    }
+
+    return `${numberToText(thousandsPart)} miń ${numberToText(remainder)}`;
+  }
+
+  // Handle (million - billion) (millions)
+  if (num >= 1000000 && num < 1000000000) {
+    const millionsPart = Math.floor(num / 1000000);
+    const remainder = num % 1000000;
+
+    if (remainder === 0) {
+      return `${numberToText(millionsPart)} million`;
+    }
+
+    return `${numberToText(millionsPart)} million ${numberToText(remainder)}`;
+  }
+
+  // Handle (billion - trillion) (billions)
+  if (num >= 1000000000 && num < 1000000000000) {
+    const billionsPart = Math.floor(num / 1000000000);
+    const remainder = num % 1000000000;
+
+    if (remainder === 0) {
+      return `${numberToText(billionsPart)} milliard`;
+    }
+
+    return `${numberToText(billionsPart)} milliard ${numberToText(remainder)}`;
+  }
+}
+
+module.exports = { numberToText };

package/src/transliterate.js

@@ -0,0 +1,215 @@
+const latinToCyrillicMap = {
+  // Basic letters
+  A: "А",
+  a: "а",
+  B: "Б",
+  b: "б",
+  D: "Д",
+  d: "д",
+  E: "Е",
+  e: "е",
+  F: "Ф",
+  f: "ф",
+  G: "Г",
+  g: "г",
+  H: "Ҳ",
+  h: "ҳ",
+  X: "Х",
+  x: "х",
+  J: "Ж",
+  j: "ж",
+  K: "К",
+  k: "к",
+  Q: "Қ",
+  q: "қ",
+  L: "Л",
+  l: "л",
+  M: "М",
+  m: "м",
+  N: "Н",
+  n: "н",
+  O: "О",
+  o: "о",
+  P: "П",
+  p: "п",
+  R: "Р",
+  r: "р",
+  S: "С",
+  s: "с",
+  T: "Т",
+  t: "т",
+  U: "У",
+  u: "у",
+  V: "В",
+  v: "в",
+  Z: "З",
+  z: "з",
+
+  // Special letters
+  Á: "Ә",
+  á: "ә",
+  Ó: "Ө",
+  ó: "ө",
+  Ú: "Ү",
+  ú: "ү",
+  I: "И",
+  i: "и",
+  Í: "Ы",
+  ı: "ы",
+  Ǵ: "Ғ",
+  ǵ: "ғ",
+  Ń: "Ң",
+  ń: "ң",
+
+  // Extra letters
+  Y: "Й",
+  y: "й",
+  W: "Ў",
+  w: "ў",
+
+  // Digraphs
+  Sh: "Ш",
+  sh: "ш",
+  SH: "Ш",
+  Yu: "Ю",
+  yu: "ю",
+  Ya: "Я",
+  ya: "я",
+  Yo: "Ё",
+  yo: "ё",
+
+  Ch: "Ч",
+  ch: "ч",
+  CH: "Ч",
+
+  // Optional / borrowed letters
+  C: "Ц",
+  c: "ц",
+};
+
+const cyrillicToLatinMap = {
+  А: "A",
+  а: "a",
+  Ә: "Á",
+  ә: "á",
+  Б: "B",
+  б: "b",
+  В: "V",
+  в: "v",
+  Г: "G",
+  г: "g",
+  Ғ: "Ǵ",
+  ғ: "ǵ",
+  Д: "D",
+  д: "d",
+  Е: "E",
+  е: "e",
+  Ё: "Yo",
+  ё: "yo",
+  Ж: "J",
+  ж: "j",
+  З: "Z",
+  з: "z",
+  И: "I",
+  и: "i",
+  Й: "Y",
+  й: "y",
+  К: "K",
+  к: "k",
+  Қ: "Q",
+  қ: "q",
+  Л: "L",
+  л: "l",
+  М: "M",
+  м: "m",
+  Н: "N",
+  н: "n",
+  Ң: "Ń",
+  ң: "ń",
+  О: "O",
+  о: "o",
+  Ө: "Ó",
+  ө: "ó",
+  П: "P",
+  п: "p",
+  Р: "R",
+  р: "r",
+  С: "S",
+  с: "s",
+  Т: "T",
+  т: "t",
+  У: "U",
+  у: "u",
+  Ү: "Ú",
+  ү: "ú",
+  Ў: "W",
+  ў: "w",
+  Ф: "F",
+  ф: "f",
+  Х: "X",
+  х: "x",
+  Ҳ: "H",
+  ҳ: "h",
+  Ш: "Sh",
+  ш: "sh",
+  Ч: "Ch",
+  ч: "ch",
+  Щ: "Sh",
+  щ: "sh", // optional
+  Ы: "Í",
+  ы: "ı",
+
+  // Borrowed/Russian letters
+  Ц: "C",
+  ц: "c",
+  Э: "E",
+  э: "e",
+  Ю: "Yu",
+  ю: "yu",
+  Я: "Ya",
+  я: "ya",
+  Ъ: "",
+  ъ: "",
+  Ь: "",
+  ь: "",
+};
+
+function latinToCyrillic(text) {
+  let result = "";
+
+  for (let i = 0; i < text.length; i++) {
+    let twoChars = text[i] + (text[i + 1] || "");
+    if (latinToCyrillicMap[twoChars]) {
+      result += latinToCyrillicMap[twoChars];
+      i++;
+      continue;
+    }
+
+    let oneChar = text[i];
+    if (latinToCyrillicMap[oneChar]) {
+      result += latinToCyrillicMap[oneChar];
+    } else {
+      result += oneChar;
+    }
+  }
+
+  return result;
+}
+
+function cyrillicToLatin(text) {
+  let result = "";
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+
+    if (cyrillicToLatinMap[char] !== undefined) {
+      result += cyrillicToLatinMap[char];
+    } else {
+      result += char;
+    }
+  }
+
+  return result;
+}
+
+module.exports = { latinToCyrillic, cyrillicToLatin };