@khgtrn/lib 1.0.0

package/dist/esm/number-to-words/index.js

@@ -0,0 +1,47 @@
+import { convertFractionalPart, convertIntegerPart, normalizeNumericInput } from "./helpers";
+import { definitions } from "./locales";
+/**
+ * Spells out a number as words, following Vietnamese or English reading
+ * conventions (e.g. `1005` -> `"một nghìn không trăm linh năm"` in Vietnamese,
+ * `"one thousand five"` in English).
+ *
+ * Decimals are supported by passing `num` as a numeric **string** (e.g.
+ * `"1.05"`) rather than a `number` — a JS `number` can only exactly
+ * represent an integer here, so a non-integer `number` is rejected rather
+ * than silently read out with floating-point rounding artifacts (e.g.
+ * `0.1 + 0.2`). The fractional part is read one digit at a time after the
+ * locale's decimal separator word (e.g. `"1.05"` -> `"một phẩy không năm"`,
+ * `"one point zero five"`), keeping `1.05` distinct from `1.5` since a
+ * leading fractional zero changes the value. Trailing fractional zeros
+ * don't (`1.50 === 1.5`), so they're dropped — `"1.50"` reads the same as
+ * `"1.5"`.
+ *
+ * @param num - Number to convert, as an integer `number` or a numeric string
+ * (optionally with a decimal point, e.g. `"1.05"`). The integer part must be
+ * finite and within the supported range (currently up to just under 10^18,
+ * comfortably covering `Number.MAX_SAFE_INTEGER`).
+ * @param locale - Target language. Defaults to `"vi"`. To support another
+ * language, add an entry to the `definitions` registry in `locales.ts`.
+ * @returns The number spelled out in words.
+ * @throws {Error} If `num` is a non-integer `number`, an invalid numeric
+ * string, `locale` isn't registered, or the integer part exceeds the
+ * locale's supported range.
+ */
+export function numberToWords(num, locale = "vi") {
+    const definition = definitions[locale];
+    if (!definition) {
+        throw new Error(`numberToWords: unsupported locale "${locale}"`);
+    }
+    const normalized = normalizeNumericInput(num);
+    const isNegative = normalized.startsWith("-");
+    const numStr = isNegative ? normalized.slice(1) : normalized;
+    const [integerStr, rawFractionalStr] = numStr.split(".");
+    // Trailing zeros never change the fractional value (1.50 === 1.5), unlike
+    // leading zeros (0.05 !== 0.5), so only trailing zeros are safe to drop.
+    const fractionalStr = rawFractionalStr === null || rawFractionalStr === void 0 ? void 0 : rawFractionalStr.replace(/0+$/, "");
+    const integerWords = convertIntegerPart(Number(integerStr), definition, num, locale);
+    const words = fractionalStr
+        ? `${integerWords} ${definition.decimalSeparator} ${convertFractionalPart(fractionalStr, definition)}`
+        : integerWords;
+    return isNegative ? `${definition.negativePrefix}${words}` : words;
+}

package/dist/esm/number-to-words/locales.d.ts

@@ -0,0 +1,7 @@
+import { NumberToWordsDefinition, NumberToWordsLocale } from "./types";
+/**
+ * Registry of per-language spelling rules. Add a new language by adding a
+ * key here (and, if its word lists warrant it, a dedicated block above) —
+ * no other file needs to change.
+ */
+export declare const definitions: Record<NumberToWordsLocale, NumberToWordsDefinition>;

package/dist/esm/number-to-words/locales.js

@@ -0,0 +1,103 @@
+const enOnes = [
+    "zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine",
+];
+const enTeens = [
+    "ten", "eleven", "twelve", "thirteen", "fourteen",
+    "fifteen", "sixteen", "seventeen", "eighteen", "nineteen",
+];
+const enTens = [
+    "", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety",
+];
+function convertGroupEn(n) {
+    const hundredsDigit = Math.floor(n / 100);
+    const remainder = n % 100;
+    const parts = [];
+    if (hundredsDigit > 0) {
+        parts.push(`${enOnes[hundredsDigit]} hundred`);
+    }
+    if (remainder > 0) {
+        if (remainder < 10) {
+            parts.push(enOnes[remainder]);
+        }
+        else if (remainder < 20) {
+            parts.push(enTeens[remainder - 10]);
+        }
+        else {
+            const tensDigit = Math.floor(remainder / 10);
+            const unitDigit = remainder % 10;
+            parts.push(unitDigit === 0 ? enTens[tensDigit] : `${enTens[tensDigit]}-${enOnes[unitDigit]}`);
+        }
+    }
+    return parts.join(" ");
+}
+const viOnes = [
+    "không", "một", "hai", "ba", "bốn", "năm", "sáu", "bảy", "tám", "chín",
+];
+function convertGroupVi(n, isLeadingGroup) {
+    const hundredsDigit = Math.floor(n / 100);
+    const remainder = n % 100;
+    const tensDigit = Math.floor(remainder / 10);
+    const unitDigit = remainder % 10;
+    const parts = [];
+    if (hundredsDigit > 0) {
+        parts.push(`${viOnes[hundredsDigit]} trăm`);
+    }
+    else if (!isLeadingGroup) {
+        // A zero hundreds digit is still read out ("không trăm") in every group
+        // except the leading one, e.g. 1005 -> "một nghìn không trăm linh năm".
+        parts.push("không trăm");
+    }
+    if (remainder === 0) {
+        // Nothing more to add; a fully-zero group is filtered out by the caller.
+    }
+    else if (tensDigit === 0) {
+        // "linh" (roughly "and") introduces a lone unit digit whenever a tens
+        // (or hundreds) part was already read, e.g. "trăm linh năm" (105) or
+        // "không trăm linh năm" (...005); a bare leading unit needs no "linh".
+        parts.push(hundredsDigit > 0 || !isLeadingGroup ? `linh ${viOnes[unitDigit]}` : viOnes[unitDigit]);
+    }
+    else if (tensDigit === 1) {
+        // 10-19: "mười" [+ unit], with the "năm" -> "lăm" exception for 15.
+        parts.push(unitDigit === 0 ? "mười" : unitDigit === 5 ? "mười lăm" : `mười ${viOnes[unitDigit]}`);
+    }
+    else {
+        // 20-99: "{tensDigit} mươi" [+ unit], with "một" -> "mốt" and "năm" -> "lăm".
+        const tensWord = `${viOnes[tensDigit]} mươi`;
+        if (unitDigit === 0) {
+            parts.push(tensWord);
+        }
+        else if (unitDigit === 1) {
+            parts.push(`${tensWord} mốt`);
+        }
+        else if (unitDigit === 5) {
+            parts.push(`${tensWord} lăm`);
+        }
+        else {
+            parts.push(`${tensWord} ${viOnes[unitDigit]}`);
+        }
+    }
+    return parts.join(" ");
+}
+/**
+ * Registry of per-language spelling rules. Add a new language by adding a
+ * key here (and, if its word lists warrant it, a dedicated block above) —
+ * no other file needs to change.
+ */
+export const definitions = {
+    en: {
+        zero: "zero",
+        negativePrefix: "negative ",
+        decimalSeparator: "point",
+        digits: enOnes,
+        scaleWords: ["", "thousand", "million", "billion", "trillion", "quadrillion"],
+        convertGroup: convertGroupEn,
+    },
+    vi: {
+        zero: "không",
+        negativePrefix: "âm ",
+        decimalSeparator: "phẩy",
+        digits: viOnes,
+        scaleWords: ["", "nghìn", "triệu", "tỷ", "nghìn tỷ", "triệu tỷ"],
+        convertGroup: convertGroupVi,
+    },
+};

package/dist/esm/number-to-words/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Locale code supported by {@link numberToWords}. Extend by adding a new key
+ * to the `definitions` registry in `locales.ts` (see
+ * {@link NumberToWordsDefinition}) — no changes to `numberToWords` itself
+ * are needed to add a language.
+ */
+export type NumberToWordsLocale = "vi" | "en";
+/**
+ * Per-locale rules needed to spell out numbers.
+ *
+ * Numbers are split into groups of 3 digits (thousands grouping), most
+ * significant group first. `scaleWords[i]` is the word placed after a group
+ * at position `i` counting from the right (`0` = units group, which gets no
+ * scale word; `1` = thousand-level; `2` = million-level; and so on).
+ */
+export interface NumberToWordsDefinition {
+    /** Word for the number `0` on its own. */
+    zero: string;
+    /** Prefix used for negative numbers (including trailing space, if any). */
+    negativePrefix: string;
+    /** Word placed between the integer and fractional parts, e.g. "phẩy"/"point". */
+    decimalSeparator: string;
+    /** Word for each digit `0`-`9`, used to read the fractional part one digit at a time. */
+    digits: string[];
+    /** Scale words indexed by group position: `["", "thousand", "million", ...]`. */
+    scaleWords: string[];
+    /**
+     * Spells out a single 0-999 group.
+     * @param n - Group value, `1`-`999` (the caller never invokes this for `0`).
+     * @param isLeadingGroup - `true` for the most significant non-zero group of
+     * the whole number. Some languages (e.g. Vietnamese) read a zero hundreds
+     * digit explicitly ("không trăm") in every group except the leading one.
+     */
+    convertGroup(n: number, isLeadingGroup: boolean): string;
+}

package/dist/esm/number-to-words/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": false
+}

package/dist/esm/round.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Rounds `value` to `precision` decimal places, mainly to clean up binary
+ * floating-point noise from arithmetic (e.g. `491.66999999999996` instead of
+ * `491.67`) rather than to reduce genuine precision. `precision` defaults to
+ * 10, which is generous enough to preserve real fractional input while still
+ * clearing noise that typically appears around the 15th-17th significant
+ * digit.
+ *
+ * @param value - Number to round.
+ * @param precision - Number of decimal places to keep. Defaults to `10`.
+ * @returns `value` rounded to `precision` decimal places.
+ */
+export declare function round(value: number, precision?: number): number;

package/dist/esm/round.js

@@ -0,0 +1,16 @@
+/**
+ * Rounds `value` to `precision` decimal places, mainly to clean up binary
+ * floating-point noise from arithmetic (e.g. `491.66999999999996` instead of
+ * `491.67`) rather than to reduce genuine precision. `precision` defaults to
+ * 10, which is generous enough to preserve real fractional input while still
+ * clearing noise that typically appears around the 15th-17th significant
+ * digit.
+ *
+ * @param value - Number to round.
+ * @param precision - Number of decimal places to keep. Defaults to `10`.
+ * @returns `value` rounded to `precision` decimal places.
+ */
+export function round(value, precision = 10) {
+    const factor = Math.pow(10, precision);
+    return Math.round(value * factor) / factor;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@khgtrn/lib",
+  "version": "1.0.0",
+  "description": "Library for Typescript",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/cjs/index.d.ts",
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=19"
+  },
+  "keywords": [
+    "typescript",
+    "ts",
+    "lib",
+    "library",
+    "klib"
+  ],
+  "author": "khgtrn",
+  "license": "MIT",
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.3.4",
+      "onFail": "download"
+    }
+  },
+  "devDependencies": {
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build:esm": "tsc -p tsconfig.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "postbuild": "cp config/package-cjs.json dist/cjs/package.json && cp config/package-esm.json dist/esm/package.json",
+    "build": "pnpm run clean && pnpm run build:esm && pnpm run build:cjs && pnpm run postbuild",
+    "test": "tsx tests/index.ts"
+  }
+}