nhb-toolbox 4.20.91 → 4.21.0

package/CHANGELOG.md

@@ -6,6 +6,15 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.21.0] - 2025-10-12
+
+- **Renamed** `RomanNumeralCap` type to `RomanCapital` and allow only strict `1-3999` and `RomanNumeral` type to `LooseRomanNumeral`.
+- **Removed** all _Roman numeral type helpers_ and **recreated** a _strict_ `RomanNumeral` with other _internal types_.
+
+## [4.20.92] - 2025-10-12
+
+- **Fixed** `RomanNumeralCap` type and **added** _@remarks_ section.
+
 ## [4.20.91] - 2025-10-12
 
 - **Updated** _tsdoc_ for `fromNow()` `Chronos` method: modified _@remarks_ section.

package/dist/cjs/number/convert.js

@@ -37,8 +37,8 @@ function numberToWords(num) {
 }
 const convertToRomanNumerals = (value) => {
     let num = (0, utilities_1.normalizeNumber)(value);
-    if (!num || num <= 0 || num >= 4000) {
-        throw new RangeError('Number must be between 1 and 3999');
+    if (!(0, primitives_1.isInteger)(num) || num <= 0 || num >= 4000) {
+        throw new RangeError('Value must be an integer and between 1 and 3999');
     }
     const romanMap = [
         [1000, 'M'],

package/dist/dts/number/convert.d.ts

@@ -1,5 +1,5 @@
 import type { Numeric } from '../types/index';
-import type { RomanNumeral, RomanNumeralCap } from './types';
+import type { LooseRomanNumeral, RomanCapital } from './types';
 /**
  * * Converts a numeric value into its corresponding English word representation.
  * @warning ***Supports numeric values up to `10e19` or `10^20` (one hundred quintillion).***
@@ -9,23 +9,23 @@ import type { RomanNumeral, RomanNumeralCap } from './types';
  */
 export declare function numberToWords(num: Numeric): string;
 /**
- * * Converts a number to a Roman numeral.
- * @param value - The number to convert. Number must be `between 1 and 3999`.
- * @returns The Roman numeral representation.
+ * * Converts a number to an uppercase Roman numeral.
+ * @param value - The number to convert. Number must be an integer and `between 1 and 3999`.
+ * @returns The Roman numeral representation in uppercase.
  *
- * @example convertToRomanNumerals(29) → "XXIX"
+ * @example convertToRomanNumerals(29) // → "XXIX"
  */
-export declare const convertToRomanNumerals: (value: Numeric) => RomanNumeralCap;
+export declare const convertToRomanNumerals: (value: Numeric) => RomanCapital;
 /**
  * * Converts a Roman numeral to its Arabic numeric representation.
- * @param roman - The Roman numeral to convert. Case-insensitive but must represent a valid Roman numeral (I–MMMCMXCIX) otherwise throws error.
- * @returns The numeric (Arabic) representation.
+ * @param roman - The Roman numeral to convert. Case-insensitive but must represent a valid Roman numeral (`I`–`MMMCMXCIX`) otherwise throws runtime error.
+ * @returns The numeric (Arabic) representation of the Roman numeral.
  *
  * @example
- * romanToInteger("XXIX") → 29
- * romanToInteger("mmxxv") → 2025
+ * romanToInteger("XXIX") // → 29
+ * romanToInteger("mmxxv") // → 2025
  */
-export declare const romanToInteger: (roman: RomanNumeral) => number;
+export declare const romanToInteger: (roman: LooseRomanNumeral) => number;
 /**
  * * Converts a number, numeric string, or cardinal word string into its ordinal word representation.
  *

package/dist/dts/number/types.d.ts

@@ -1,4 +1,4 @@
-import type { LooseLiteral, Repeat } from '../utils/types';
+import type { LooseLiteral } from '../utils/types';
 import type { CURRENCY_CODES, CURRENCY_LOCALES, LOCALE_CODES, PREFIX_MULTIPLIERS, SUPPORTED_CURRENCIES, UNITS } from './constants';
 import type { Unit } from './Unit';
 /** Enumerate & Enumerate Internal: builds a union of all numbers from 0 to N - 1 */
@@ -166,60 +166,49 @@ export type UnitKey = keyof typeof UNITS;
 export type UnitLabel = (typeof UNITS)[UnitKey];
 /** - Prefixes for SI units */
 export type SIPrefix = keyof typeof PREFIX_MULTIPLIERS;
+/** Roman numerals representing only the thousand (1000, 2000 and 3000) */
+type $Thousands = '' | 'M' | 'MM' | 'MMM';
+/** Roman numerals representing only the hundreds (100, 200, ... 900) */
+type $Hundreds = '' | 'C' | 'CC' | 'CCC' | 'CD' | 'D' | 'DC' | 'DCC' | 'DCCC' | 'CM';
+/** Roman numerals representing only the tens (10, 20, ... 90) */
+type $Tens = '' | 'X' | 'XX' | 'XXX' | 'XL' | 'L' | 'LX' | 'LXX' | 'LXXX' | 'XC';
+/** Roman numerals representing only the ones (1-9) */
+type $Ones = '' | 'I' | 'II' | 'III' | 'IV' | 'V' | 'VI' | 'VII' | 'VIII' | 'IX';
+/** Roman numerals representing the combination of thousands, hundreds, tens and ones */
+type $RawRoman = `${$Thousands}${$Hundreds}${$Tens}${$Ones}`;
 /**
- * * Roman numeral base letters (upper-case only).
+ * * Literal type representing every valid Roman numeral (uppercase) from 1 to 3999 (I .. MMMCMXCIX).
  *
- * Includes:
- * - `I` → 1
- * - `V` → 5
- * - `X` → 10
- * - `L` → 50
- * - `C` → 100
- * - `D` → 500
- * - `M` → 1000
+ * @example
+ *   const a: RomanCapital = "MMXXV"; // ✅ OK
+ *   const b: RomanCapital = "MMMM";  // 🛑 Error (4000 not allowed)
+ *   const c: RomanCapital = "";      // 🛑 Error (0 not allowed)
  */
-export type $RomanBase = 'I' | 'V' | 'X' | 'L' | 'C' | 'D' | 'M';
+export type RomanCapital = Exclude<$RawRoman, ''>;
 /**
- * * Represents repeated Roman numeral sequences (1–5 characters long), enabling IntelliSense autocompletion for sequential Roman characters.
- *
- * - Suggests Roman base letters after each character.
- * - Supports up to 5-character combinations for performance.
- * - Does **not** validate Roman numeral correctness (e.g., `VVVV` is allowed).
+ * * Strict Roman numeral in both literal lower and uppercase (1-3999).
  *
  * @example
  * ```ts
- * // ✅ Valid according to type (even if not a real Roman numeral)
- * const a: $RomanRepeated = 'MMXII';
- * const b: $RomanRepeated = 'VVVV';
+ * 	const a: RomanNumeral = 'xiv';   // ✅ Lowercase: OK
+ * 	const b: RomanNumeral = 'MMX';   // ✅ Uppercase: OK
+ * 	const c: RomanNumeral = 'xyz';   // 🛑 Invalid: Error (xyz not allowed)
  * ```
- *
- * @remarks
- * **Limitations:**
- * - Only supports up to **5-character** combinations (`Repeat<$RomanBase, 5>`) using {@link Repeat}.
- * - Increasing beyond 5 leads to TypeScript recursion/union complexity issues.
- * - Designed purely for **editor IntelliSense**, not runtime validation.
  */
-export type $RomanNumeralCap = $RomanBase | Repeat<$RomanBase, 2> | Repeat<$RomanBase, 3> | Repeat<$RomanBase, 4> | Repeat<$RomanBase, 5>;
-/** * Represents repeated Roman numeral sequences (1–5 characters long) in uppercase letters and any string */
-export type RomanNumeralCap = Uppercase<LooseLiteral<$RomanNumeralCap>>;
+export type RomanNumeral = RomanCapital | Lowercase<RomanCapital>;
 /**
- * * Comprehensive Roman numeral string type.
- *
- * Includes both upper and lowercase Roman letters, with support for loose
- * literal fallbacks (via {@link LooseLiteral}) to accept arbitrary strings
- * while still providing IntelliSense suggestions for known Roman combinations.
+ * * Comprehensive valid Roman numeral in both literal lower and uppercase (1-3999) & any string type.
  *
  * @example
  * ```ts
- * const a: RomanNumeral = 'xiv';   // ✅ IntelliSense suggests Roman letters
- * const b: RomanNumeral = 'MMX';   // ✅ Supported
- * const c: RomanNumeral = 'xyz';   // ⚠️ Allowed only via LooseLiteral fallback
+ * 	const a: LooseRomanNumeral = 'xiv';   // ✅ IntelliSense suggests Roman letters
+ * 	const b: LooseRomanNumeral = 'MMX';   // ✅ Supported
+ * 	const c: LooseRomanNumeral = 'xyz';   // ⚠️ Allowed only via LooseLiteral fallback
  * ```
  *
  * @remarks
- * - Combines {@link $RomanNumeralCap} and its lowercase variants.
+ * - Combines {@link RomanCapital} and its lowercase variants, see {@link RomanNumeral}.
  * - The {@link LooseLiteral} wrapper allows non-literal strings (e.g., variables) without losing IntelliSense for literals.
- * - Does not enforce valid Roman numeral formation.
  */
-export type RomanNumeral = LooseLiteral<$RomanNumeralCap | Lowercase<$RomanNumeralCap>>;
+export type LooseRomanNumeral = LooseLiteral<RomanNumeral>;
 export {};

package/dist/esm/number/convert.js

@@ -1,4 +1,4 @@
-import { isNonEmptyString, isNumber } from '../guards/primitives.js';
+import { isInteger, isNonEmptyString, isNumber } from '../guards/primitives.js';
 import { isNumericString } from '../guards/specials.js';
 import { ONES, ORDINAL_TO_CARDINAL, ORDINAL_UNDER_TEEN, TEENS, TENS, THOUSANDS, } from './constants.js';
 import { _convertLessThanThousand } from './helpers.js';
@@ -31,8 +31,8 @@ export function numberToWords(num) {
 }
 export const convertToRomanNumerals = (value) => {
     let num = normalizeNumber(value);
-    if (!num || num <= 0 || num >= 4000) {
-        throw new RangeError('Number must be between 1 and 3999');
+    if (!isInteger(num) || num <= 0 || num >= 4000) {
+        throw new RangeError('Value must be an integer and between 1 and 3999');
     }
     const romanMap = [
         [1000, 'M'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.20.91",
+  "version": "4.21.0",
   "description": "A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",