@khgtrn/lib 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Tran Quang Khuong
+
+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,113 @@
+# KLib - Library for TS/JS
+
+[![npm version](https://img.shields.io/npm/v/@khgtrn/klib.svg)](https://www.npmjs.com/package/@khgtrn/klib)
+[![npm downloads](https://img.shields.io/npm/d18m/@khgtrn/klib.svg)](https://www.npmjs.com/package/@khgtrn/klib)
+[![license](https://img.shields.io/github/license/khgtrn/ts-klib.svg)](https://github.com/khgtrn/ts-klib/blob/main/LICENSE)
+
+Shared TypeScript utility library: Java-style enums, common helper functions, number-to-words conversion (Vietnamese/English), and floating-point-safe rounding.
+
+Built as both ESM (`dist/esm`) and CJS (`dist/cjs`), with full type declarations, with no runtime dependency beyond standard Web APIs (`crypto`, `TextEncoder`/`TextDecoder`, `btoa`/`atob` — available in browsers and Node.js >= 19).
+
+## Installation
+
+```bash
+pnpm add @khgtrn/klib
+```
+
+Requires Node.js >= 19 at runtime (needed for `crypto.getRandomValues` as a global — see `engines` in [package.json](package.json)). The shipped `.d.ts` files are compatible down to **TypeScript 2.7**, and the compiled JS itself avoids syntax (`?.`, `??`) that older bundlers can't parse — no separate install/config needed to consume this package from a legacy toolchain (e.g. Angular 6).
+
+## BaseEnum — Java-style enums
+
+`BaseEnum` is a base class for simulating Java enums: each constant is a singleton instance, and subclasses only need to `extends` and declare `static readonly` fields — no constructor to write.
+
+```ts
+import { BaseEnum } from '@khgtrn/klib';
+
+class Role extends BaseEnum<number> {
+  static readonly Admin = new Role(1, 'Administrator');
+  static readonly User = new Role(0, 'User');
+
+  isAdmin(): boolean {
+    return this === Role.Admin;
+  }
+}
+
+Role.Admin.label;                 // 'Administrator'
+Role.Admin === Role.Admin;         // true — identity is preserved
+Role.Admin.equals(1);              // true — compares by value
+Role.values();                     // [Role.Admin, Role.User]
+Role.names();                      // ['Admin', 'User']
+Role.valueOf('Admin');             // Role.Admin (looks up by field name, throws if missing)
+Role.fromValue(1);                 // Role.Admin (looks up by value, returns undefined if missing)
+Role.Admin.name();                 // 'Admin'
+new Role(2, 'x');                  // compile error — constructor is protected
+```
+
+The constructor also accepts an optional `opts?: Record<string, any>` parameter for storing arbitrary extra data per constant.
+
+## Utility functions (`func.ts`)
+
+| Function | Description |
+| --- | --- |
+| `isEmpty(value)` | Checks whether a value is empty (string, `0`, `false`, null/undefined, empty array/object) |
+| `isNumber(value)` | Type-guard: a valid finite number (not NaN/Infinity) |
+| `vi2en(s)` | Strips Vietnamese diacritics (`"Điều chỉnh"` -> `"Dieu chinh"`) |
+| `crlf2lf(value)` | Normalizes `\r\n` -> `\n` |
+| `removeNewline(value)` | Removes all newlines, trims surrounding whitespace |
+| `shuffleArray(array)` | Shuffles an array in place (Fisher-Yates) |
+| `objectValueToArray(obj)` | Collects an object's values into an array |
+| `groupBy(list, fn)` | Groups items by a computed key |
+| `removeByKey(objectOrArray, keys)` | Removes fields by name, recursively through nested structures |
+| `removeEmptyValue(objectOrArray, options?)` | Removes `null`/`undefined`/`""` fields, recursively through nested structures |
+| `randomString(length, opt?, specificChars?)` | Generates a random string, optionally requiring uppercase/lowercase/digit/custom characters |
+| `byte2hex(b)` | Byte (0-255) -> 2-character hex |
+| `uuid7bin()` / `uuid7()` | Generates a UUIDv7 (16 bytes / standard string) |
+| `base64encode(str)` / `base64decode(base64)` | Base64 encode/decode (UTF-8, safe for large strings) |
+| `getObjectValue(object, path)` / `ov(object, path)` | Reads a nested value via a `"a.b.c"` dot path |
+| `toInt(value, defaultValue?)` | Converts to an integer, with a fallback for empty values |
+| `numberToRoman(num)` / `romanToNumber(roman)` | Converts between Roman numerals and numbers (1-3999) |
+| `isRomanNumber(value)` | Validates a Roman numeral string |
+| `base64ToBlob(base64, mimeType, sliceSize?)` | Base64 -> `Blob` (browser) |
+| `downloadFile(fileName, mimeType, base64Content, action?)` | Downloads/opens a file from base64 (browser) |
+| `deepClone(obj)` | Deep-clones an object/array/`Date` |
+
+See the JSDoc in [src/func.ts](src/func.ts) for full parameter/return details.
+
+## numberToWords — spelling out numbers
+
+```ts
+import { numberToWords } from '@khgtrn/klib';
+
+numberToWords(1005);            // "một nghìn không trăm linh năm" (Vietnamese by default)
+numberToWords(1005, 'en');      // "one thousand five"
+numberToWords('1.05', 'vi');    // "một phẩy không năm"
+numberToWords(-123, 'en');      // "negative one hundred twenty-three"
+```
+
+- Integers can be passed as either a `number` or a `string`.
+- Decimals **must be passed as a `string`** (e.g. `'1.05'`), since a `number` can't preserve a leading fractional zero and may pick up floating-point rounding errors — passing a decimal `number` throws with a hint to fix it.
+- Supports up to billion-level magnitude, comfortably covering `Number.MAX_SAFE_INTEGER`.
+- Designed to be easy to extend with more languages: see [src/number-to-words/locales.ts](src/number-to-words/locales.ts).
+
+## round — floating-point-safe rounding
+
+```ts
+import { round } from '@khgtrn/klib';
+
+round(491.66999999999996);      // 491.67 (default precision = 10)
+round(1.23456, 2);              // 1.23
+```
+
+Rounds `value` to `precision` decimal places (default `10`), mainly to clean up binary floating-point noise from arithmetic rather than to reduce genuine precision.
+
+## Development
+
+```bash
+pnpm install
+pnpm run build   # builds dist/esm and dist/cjs
+pnpm run play    # builds then runs tests/a.ts as a quick smoke test
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseEnum = void 0;
+/**
+ * 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`).
+ */
+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;
+    }
+}
+exports.BaseEnum = BaseEnum;
+/**
+ * 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();

package/dist/cjs/func.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Checks whether a value is considered "empty".
+ *
+ * - string: empty after trimming.
+ * - number: equal to `0`.
+ * - boolean: `false`.
+ * - `null`/`undefined`: always empty.
+ * - array: length `0`.
+ * - other objects: no own enumerable keys.
+ * - anything else (function, symbol, ...): never empty.
+ *
+ * @param value - Value to check.
+ * @returns `true` if the value is considered empty.
+ */
+export declare function isEmpty(value: any): boolean;
+/**
+ * Checks whether a value is a valid number (not `NaN`, not `Infinity`).
+ * @param value - Value to check.
+ * @returns Type-guard: `true` if `value` is a finite number.
+ */
+export declare function isNumber(value: any): value is number;
+/**
+ * Converts Vietnamese diacritics to their plain ASCII equivalents
+ * (e.g. `"Điều chỉnh"` -> `"Dieu chinh"`).
+ *
+ * @param s - Input string.
+ * @returns The string with Vietnamese diacritics removed.
+ */
+export declare function vi2en(s: string): string;
+/**
+ * Normalizes Windows-style line endings (`\r\n`) to Unix-style (`\n`).
+ * @param value - Input string.
+ * @returns The string with all `\r\n` replaced by `\n`.
+ */
+export declare function crlf2lf(value: string): string;
+/**
+ * Removes every newline from a string, after normalizing line endings and
+ * trimming surrounding whitespace.
+ * @param value - Input string.
+ * @returns The string with all newlines removed.
+ */
+export declare function removeNewline(value: string): string;
+/**
+ * Shuffles an array in place using the Fisher-Yates algorithm.
+ * @param array - Array to shuffle (mutated directly).
+ * @returns The same array reference, shuffled.
+ */
+export declare function shuffleArray(array: any[]): any[];
+/**
+ * Collects an object's own enumerable values into an array.
+ * @param obj - Source object. `null`/`undefined` yields an empty array.
+ * @returns Array of the object's values.
+ */
+export declare function objectValueToArray(obj: any): any[];
+/**
+ * Groups list items by the key returned from `fn`, similar to Lodash's
+ * `groupBy`. Keys are compared by their JSON representation, so they can be
+ * primitives or plain objects.
+ *
+ * @param list - Array-like list of items to group. `null`/`undefined` yields an empty array.
+ * @param fn - Maps an item to the value used to group it.
+ * @returns Array of groups, each an array of items sharing the same key.
+ */
+export declare function groupBy(list: any, fn: (item: any) => any): any[];
+/**
+ * Remove keys from object or array
+ * @param objectOrArray Object or array
+ * @param keys Keys to remove
+ * @returns Object or array with keys removed
+ */
+export declare function removeByKey<T = any>(objectOrArray: T, keys: string[]): T;
+/**
+ * Remove empty values from object or array
+ * @param objectOrArray Object or array
+ * @param options Options:
+ * - removeNull: Remove null values. Default: true
+ * - removeUndefined: Remove undefined values. Default: true
+ * - removeEmptyString: Remove empty string values. Default: true
+ * @returns Object or array with empty values removed
+ */
+export declare function removeEmptyValue<T = any>(objectOrArray: T, options?: {
+    removeNull?: boolean;
+    removeUndefined?: boolean;
+    removeEmptyString?: boolean;
+}): T;
+/**
+ * Generates a random string of the given length, optionally guaranteeing at
+ * least one character from each requested category ("upper", "lower",
+ * "number", "specific").
+ *
+ * @param length - Desired length of the resulting string.
+ * @param opt - Character categories that must each appear at least once.
+ * `"specific"` only counts as a required category when `specificChars` is
+ * non-empty; otherwise it's silently ignored (as if not requested at all).
+ * @param specificChars - Custom character set used for the `"specific"` category.
+ * @returns A random string of exactly `length` characters. If `opt` is empty
+ * (or every requested category ends up unusable), falls back to alphanumeric
+ * characters rather than returning an empty string.
+ * @throws {Error} If `length` is smaller than the number of required categories,
+ * since the "at least one of each" guarantee couldn't fit otherwise.
+ */
+export declare function randomString(length: number, opt?: ("upper" | "lower" | "number" | "specific")[], specificChars?: string): string;
+/**
+ * Formats a byte value (0-255) as a zero-padded, 2-digit lowercase hex string.
+ * Intended for internal use with well-formed byte values (e.g. from a
+ * `Uint8Array`); values outside 0-255 are not validated.
+ *
+ * @param b - Byte value, expected in the 0-255 range.
+ * @returns 2-character hex string, e.g. `"0f"`.
+ */
+export declare function byte2hex(b: number): string;
+/**
+ * Generates the raw 16 bytes of a UUIDv7 (timestamp + random, RFC 4122
+ * variant). Relies on the Web Crypto `crypto.getRandomValues` API, available
+ * in browsers and modern Node.js.
+ *
+ * @returns 16-byte `Uint8Array` encoding a UUIDv7.
+ */
+export declare function uuid7bin(): Uint8Array;
+/**
+ * Generates a UUIDv7 string (e.g. `"01890a5d-ac96-774b-bcce-b302099a8057"`).
+ * @returns UUIDv7 in the standard 8-4-4-4-12 hex string format.
+ */
+export declare function uuid7(): string;
+/**
+ * Encodes a string to base64 (UTF-8 bytes).
+ * @param str - String to encode.
+ * @returns Base64-encoded string.
+ */
+export declare function base64encode(str: string): string;
+/**
+ * Decodes a base64 string back to its original (UTF-8) string.
+ * @param base64 - Base64-encoded string.
+ * @returns Decoded string.
+ */
+export declare function base64decode(base64: string): string;
+/**
+ * Reads a nested property from an object using a dot-separated path.
+ * Example: `getObjectValue(user, 'abc.def')` returns `user.abc.def`.
+ *
+ * Equivalent to optional chaining (`object?.abc?.def`), for use on
+ * TypeScript versions below 3.7 (e.g. Angular versions below 9). On newer
+ * TypeScript versions, prefer optional chaining directly instead.
+ *
+ * @param object - Source object.
+ * @param path - Dot-separated property path.
+ * @returns The resolved value, or `null`/`undefined` if any segment is missing.
+ * @global
+ */
+export declare function getObjectValue(object: null | undefined | Record<string, any>, path: string): any;
+/**
+ * Short alias for {@link getObjectValue}.
+ * @param object - Source object.
+ * @param path - Dot-separated property path.
+ * @returns The resolved value, or `null`/`undefined` if any segment is missing.
+ */
+export declare function ov(object: null | undefined | Record<string, any>, path: string): any;
+/**
+ * Converts a value to an integer, similar to `parseInt`/`Number` but with an
+ * explicit fallback for empty values (see {@link isEmpty}).
+ *
+ * @param value - Value to convert.
+ * @param defaultValue - Value returned when `value` is empty. Defaults to `0`.
+ * @returns The parsed integer, `defaultValue` if `value` is empty, or `NaN`
+ * if `value` is a non-numeric, non-empty string.
+ */
+export declare function toInt(value: any, defaultValue?: number | null | undefined): number | null | undefined;
+/**
+ * Converts a positive integer to a Roman numeral. Only supports the standard
+ * range (1-3999); larger numbers produce a non-standard repeating "M" prefix.
+ *
+ * @param num - Number to convert.
+ * @returns Roman numeral string, or `""` if `num` is zero or negative.
+ */
+export declare function numberToRoman(num: number): string;
+/**
+ * Converts a Roman numeral string to a number. Does not validate that the
+ * input is a well-formed Roman numeral (use {@link isRomanNumber} first if
+ * that matters) — unrecognized characters make the result `NaN`.
+ *
+ * @param roman - Roman numeral string (case-sensitive, uppercase letters).
+ * @returns The numeric value, or `NaN` if `roman` contains unrecognized characters.
+ */
+export declare function romanToNumber(roman: string): number;
+/**
+ * Checks whether a string is a well-formed Roman numeral (1-3999), matching
+ * the standard subtractive notation. Case-insensitive.
+ *
+ * @param value - String to validate.
+ * @returns `true` if `value` is a valid Roman numeral.
+ */
+export declare function isRomanNumber(value: string): boolean;
+/**
+ * Converts a base64 string to a `Blob`. Browser-only (relies on `atob` and
+ * `Blob`).
+ *
+ * @param base64 - Base64-encoded content.
+ * @param mimeType - MIME type to assign to the resulting `Blob`.
+ * @param sliceSize - Chunk size (in decoded characters) used while building
+ * the byte arrays, to avoid excessive memory allocation for large inputs.
+ * @returns A `Blob` containing the decoded bytes.
+ */
+export declare function base64ToBlob(base64: string, mimeType: string, sliceSize?: number): Blob;
+/**
+ * Triggers a browser download (or opens in a tab) for base64-encoded file
+ * content. Browser-only (relies on `document`, `URL.createObjectURL`).
+ *
+ * @param fileName - Suggested file name for the download.
+ * @param mimeType - MIME type/subtype (a bare subtype like `"pdf"` is
+ * expanded to `"application/pdf"`).
+ * @param base64Content - Base64-encoded file content.
+ * @param action - `"download"` saves the file, `"open"` opens it in the same
+ * tab, `"open_blank"` opens it in a new tab. Defaults to `"download"`.
+ */
+export declare function downloadFile(fileName: string, mimeType: string, base64Content: string, action?: "download" | "open" | "open_blank"): void;
+/**
+ * Recursively clones plain objects, arrays and `Date` instances.
+ *
+ * Note: `Date` has no own enumerable properties, so a plain for-in copy
+ * would silently turn every `Date` into an empty `{}` — it's special-cased
+ * here. Other special object types (`Map`, `Set`, `RegExp`, ...) are not
+ * handled and will also be cloned as plain `{}`.
+ *
+ * @param obj - Value to clone.
+ * @returns A deep copy of `obj` (primitives are returned as-is).
+ */
+export declare function deepClone(obj: any): any;