@khgtrn/lib 1.0.0

package/dist/cjs/number-to-words/index.d.ts

@@ -0,0 +1,30 @@
+import { NumberToWordsLocale } from "./types";
+export { NumberToWordsLocale };
+/**
+ * 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 declare function numberToWords(num: number | string, locale?: NumberToWordsLocale): string;

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.numberToWords = numberToWords;
+const helpers_1 = require("./helpers");
+const locales_1 = require("./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.
+ */
+function numberToWords(num, locale = "vi") {
+    const definition = locales_1.definitions[locale];
+    if (!definition) {
+        throw new Error(`numberToWords: unsupported locale "${locale}"`);
+    }
+    const normalized = (0, helpers_1.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 = (0, helpers_1.convertIntegerPart)(Number(integerStr), definition, num, locale);
+    const words = fractionalStr
+        ? `${integerWords} ${definition.decimalSeparator} ${(0, helpers_1.convertFractionalPart)(fractionalStr, definition)}`
+        : integerWords;
+    return isNegative ? `${definition.negativePrefix}${words}` : words;
+}

package/dist/cjs/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/cjs/number-to-words/locales.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definitions = void 0;
+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.
+ */
+exports.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/cjs/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/cjs/number-to-words/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/package.json

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

package/dist/cjs/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/cjs/round.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.round = round;
+/**
+ * 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.
+ */
+function round(value, precision = 10) {
+    const factor = Math.pow(10, precision);
+    return Math.round(value * factor) / factor;
+}

package/dist/esm/base-enum.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Base class for simulating Java-style enums in TypeScript.
+ *
+ * Subclasses only need to `extends BaseEnum<...>` and declare constants as
+ * `static readonly Xxx = new SubClass(value, label, opts?)`, without
+ * redeclaring a constructor. Because `BaseEnum`'s constructor is `protected`,
+ * subclasses inherit it while keeping the same protection — instances can't
+ * be `new`-ed from outside the class, which preserves enum singleton/identity
+ * semantics (`===` comparisons always work as expected).
+ *
+ * @typeParam T - Type of the `value` field (defaults to `number`).
+ */
+export declare abstract class BaseEnum<T = number> {
+    readonly value: T;
+    readonly label: string;
+    readonly opts?: Record<string, any> | undefined;
+    /**
+     * Registry of every instance created, keyed per subclass and per `value`.
+     * The outer key is the subclass constructor (so each subclass has its own
+     * list), the inner key is each constant's `value`. Backs `values()`,
+     * `fromValue()` and `equals()`.
+     */
+    private static readonly registry;
+    /**
+     * Creates an enum constant. Only callable from within a subclass
+     * (the constructor is `protected`), typically from a `static readonly`
+     * field declaration.
+     *
+     * @param value - Identifying value of the constant (used by `fromValue()`, `equals()`).
+     * @param label - Display label/description of the constant.
+     * @param opts - Optional extra data, freely defined by the subclass as needed.
+     */
+    protected constructor(value: T, label: string, opts?: Record<string, any> | undefined);
+    /**
+     * Returns the names of the `static readonly` fields declared on the
+     * subclass, in declaration order. Mirrors the idea of an enum constant's
+     * name in Java, but here returns the names for every constant at once.
+     *
+     * @returns Array of constant names, e.g. `['Admin', 'User']`.
+     */
+    static names(this: Function): string[];
+    /**
+     * Returns every instance (constant) created on the subclass, similar to
+     * Java's `Enum.values()`.
+     *
+     * @returns Array of the subclass's instances, in creation order.
+     */
+    static values<T extends BaseEnum<any>>(this: Function & {
+        prototype: T;
+    }): T[];
+    /**
+     * Looks up a constant by its declared field name (matches Java's standard
+     * `Enum.valueOf(String)`). Unlike `fromValue()`, which looks up by `value`,
+     * this looks up by the static field's name (key).
+     *
+     * @param name - Name of the constant to look up, e.g. `'Admin'`.
+     * @returns The matching instance.
+     * @throws {Error} If no constant with that name exists.
+     */
+    static valueOf<T extends BaseEnum<any>>(this: Function & {
+        prototype: T;
+    }, name: string): T;
+    /**
+     * Looks up a constant by its `value` field.
+     *
+     * Note: `value`'s type isn't tied to the subclass's own `value` type
+     * parameter (unlike a conditional type would give) — that syntax requires
+     * TypeScript 2.8+, and this library targets TypeScript 2.7 and up.
+     *
+     * @param value - Value to look up (of the subclass's `T` type).
+     * @returns The matching instance, or `undefined` if none is found.
+     */
+    static fromValue<T extends BaseEnum<any>>(this: Function & {
+        prototype: T;
+    }, value: any): T | undefined;
+    /**
+     * Compares this constant against an arbitrary value.
+     *
+     * - If `other` is a `BaseEnum` instance: compares identity (`===`)
+     *   directly, even if `other` belongs to a different enum class (always
+     *   `false` in that case).
+     * - If `other` is a raw value (number/string/...): looks up the matching
+     *   constant by `value` within this instance's own subclass, then compares
+     *   identity.
+     * - Anything else (wrong type, no match, `null`/`undefined`...): returns
+     *   `false`.
+     *
+     * @param other - Value or enum instance to compare against.
+     * @returns `true` if both refer to the same enum constant, otherwise `false`.
+     */
+    equals(other: any): boolean;
+    /**
+     * Returns the field name this instance was assigned to, similar to Java's
+     * `Enum.name()`.
+     *
+     * @returns The constant's name, e.g. `'Admin'`; an empty string if not
+     * found (a theoretical case that shouldn't occur under normal usage).
+     */
+    name(): string;
+    /**
+     * Converts the constant to a display string, defaulting to `label`.
+     *
+     * @returns The constant's display label.
+     */
+    toString(): string;
+}

package/dist/esm/base-enum.js

@@ -0,0 +1,133 @@
+/**
+ * Base class for simulating Java-style enums in TypeScript.
+ *
+ * Subclasses only need to `extends BaseEnum<...>` and declare constants as
+ * `static readonly Xxx = new SubClass(value, label, opts?)`, without
+ * redeclaring a constructor. Because `BaseEnum`'s constructor is `protected`,
+ * subclasses inherit it while keeping the same protection — instances can't
+ * be `new`-ed from outside the class, which preserves enum singleton/identity
+ * semantics (`===` comparisons always work as expected).
+ *
+ * @typeParam T - Type of the `value` field (defaults to `number`).
+ */
+export class BaseEnum {
+    /**
+     * Creates an enum constant. Only callable from within a subclass
+     * (the constructor is `protected`), typically from a `static readonly`
+     * field declaration.
+     *
+     * @param value - Identifying value of the constant (used by `fromValue()`, `equals()`).
+     * @param label - Display label/description of the constant.
+     * @param opts - Optional extra data, freely defined by the subclass as needed.
+     */
+    constructor(value, label, opts) {
+        this.value = value;
+        this.label = label;
+        this.opts = opts;
+        let map = BaseEnum.registry.get(this.constructor);
+        if (!map) {
+            map = new Map();
+            BaseEnum.registry.set(this.constructor, map);
+        }
+        map.set(value, this);
+    }
+    /**
+     * Returns the names of the `static readonly` fields declared on the
+     * subclass, in declaration order. Mirrors the idea of an enum constant's
+     * name in Java, but here returns the names for every constant at once.
+     *
+     * @returns Array of constant names, e.g. `['Admin', 'User']`.
+     */
+    static names() {
+        return Object.getOwnPropertyNames(this).filter((key) => key !== "prototype" && this[key] instanceof BaseEnum);
+    }
+    /**
+     * Returns every instance (constant) created on the subclass, similar to
+     * Java's `Enum.values()`.
+     *
+     * @returns Array of the subclass's instances, in creation order.
+     */
+    static values() {
+        var _a;
+        return Array.from(((_a = BaseEnum.registry.get(this)) !== null && _a !== void 0 ? _a : new Map()).values());
+    }
+    /**
+     * Looks up a constant by its declared field name (matches Java's standard
+     * `Enum.valueOf(String)`). Unlike `fromValue()`, which looks up by `value`,
+     * this looks up by the static field's name (key).
+     *
+     * @param name - Name of the constant to look up, e.g. `'Admin'`.
+     * @returns The matching instance.
+     * @throws {Error} If no constant with that name exists.
+     */
+    static valueOf(name) {
+        const constant = this[name];
+        if (!(constant instanceof BaseEnum)) {
+            throw new Error(`No enum constant ${this.name}.${name}`);
+        }
+        return constant;
+    }
+    /**
+     * Looks up a constant by its `value` field.
+     *
+     * Note: `value`'s type isn't tied to the subclass's own `value` type
+     * parameter (unlike a conditional type would give) — that syntax requires
+     * TypeScript 2.8+, and this library targets TypeScript 2.7 and up.
+     *
+     * @param value - Value to look up (of the subclass's `T` type).
+     * @returns The matching instance, or `undefined` if none is found.
+     */
+    static fromValue(value) {
+        var _a;
+        return (_a = BaseEnum.registry.get(this)) === null || _a === void 0 ? void 0 : _a.get(value);
+    }
+    /**
+     * Compares this constant against an arbitrary value.
+     *
+     * - If `other` is a `BaseEnum` instance: compares identity (`===`)
+     *   directly, even if `other` belongs to a different enum class (always
+     *   `false` in that case).
+     * - If `other` is a raw value (number/string/...): looks up the matching
+     *   constant by `value` within this instance's own subclass, then compares
+     *   identity.
+     * - Anything else (wrong type, no match, `null`/`undefined`...): returns
+     *   `false`.
+     *
+     * @param other - Value or enum instance to compare against.
+     * @returns `true` if both refer to the same enum constant, otherwise `false`.
+     */
+    equals(other) {
+        var _a;
+        if (other instanceof BaseEnum) {
+            return this === other;
+        }
+        return ((_a = BaseEnum.registry.get(this.constructor)) === null || _a === void 0 ? void 0 : _a.get(other)) === this;
+    }
+    /**
+     * Returns the field name this instance was assigned to, similar to Java's
+     * `Enum.name()`.
+     *
+     * @returns The constant's name, e.g. `'Admin'`; an empty string if not
+     * found (a theoretical case that shouldn't occur under normal usage).
+     */
+    name() {
+        const ctor = this.constructor;
+        const key = Object.getOwnPropertyNames(ctor).find((k) => k !== "prototype" && ctor[k] === this);
+        return key !== null && key !== void 0 ? key : "";
+    }
+    /**
+     * Converts the constant to a display string, defaulting to `label`.
+     *
+     * @returns The constant's display label.
+     */
+    toString() {
+        return this.label;
+    }
+}
+/**
+ * Registry of every instance created, keyed per subclass and per `value`.
+ * The outer key is the subclass constructor (so each subclass has its own
+ * list), the inner key is each constant's `value`. Backs `values()`,
+ * `fromValue()` and `equals()`.
+ */
+BaseEnum.registry = new Map();