Open Source · npm Package

@tushar_rayamajhi/roman_converter

A complete, zero-dependency Roman numeral library for JavaScript & TypeScript. 8 feature categories — the only package on npm with extended numerals up to 3,999,999, classical Latin words, and base-12 Roman fractions.

npm install @tushar_rayamajhi/roman_converter

v2.1.2Zero DependenciesTypeScriptReact HooksCLIESMISC License

View on npm Source code

Live npm stats — refreshed every hour

📦3Weekly Downloads

📈20Monthly Downloads

🏷️2.1.2Latest Version

✅0Dependencies

What's inside

8 Feature Categories

From core conversion to React hooks — everything you need to work with Roman numerals.

🔄

Core Conversion

toRoman, fromRoman, validation — integers 1–3,999 ↔ Roman strings

➕

Arithmetic

add, subtract, multiply, divide — accepts Roman strings or integers, or mixed

🛠️

Utilities

range, sort, compare, batch convert, breakdown into additive components

🏛️

Extended Numerals

Parenthetical vinculum notation for 1–3,999,999 (unique on npm)

⏰

Clock / Time

Convert any time to Roman numerals, live clock, 12h/24h, seconds, meridiem

📜

Latin Words

Classical Latin number names, e.g. "quadraginta duo" — unique on npm

⅛

Fractions (Uncia)

Ancient base-12 Roman fraction system with dots and S symbols — unique on npm

⚛️

React Hooks + CLI

useRoman, useRomanClock hooks + full CLI with 20+ commands

One of a kind

3 Features Not Found Anywhere Else on npm

🏛️

Extended Numerals up to 3,999,999

Uses parenthetical vinculum notation — (V)=5,000, (M)=1,000,000. Parse and generate numbers well beyond the standard 3,999 limit.

toExtendedRoman(1999999)

→ "(M)(CM)(XC)(IX)CMXCIX"

📜

Classical Latin Number Words

Convert integers (1–3,999) to their classical Latin names, using proper subtraction forms (duodeviginti for 18) and correct thousand plurals.

toWords(1999)

→ "mille nongenti nonaginta novem"

⅛

Roman Fractions (Uncia System)

The ancient base-12 fraction system used by Roman merchants. Convert decimal fractions to uncia symbols (·, S, AS) with names and twelfths.

toUncia(0.75)

→ "S···"

Try it live

Interactive Playground

Uses the actual installed package — every output you see is a real function call.

Integer (1–3,999)

—

🔄 Core Conversion

import { toRoman, fromRoman, isValidRoman, isValidNumber } from '@tushar_rayamajhi/roman_converter'

toRoman(2024)                     // "MMXXIV"
toRoman(42, { lowercase: true })  // "xlii"
fromRoman('MCMXCIV')              // 1994
isValidRoman('IIII')              // false  (invalid form)
isValidNumber(4000)               // false

toRoman(2024)→ "MMXXIV"

toRoman(42)→ "XLII"

toRoman(1994)→ "MCMXCIV"

fromRoman('MCMXCIV')→ "1994"

fromRoman('xlii')→ "42"

➕ Arithmetic

import { add, subtract, multiply, divide } from '@tushar_rayamajhi/roman_converter'

// Mix Roman strings and integers freely
add('XIV', 'III')      // "XVII"
add(10, 'V')           // "XV"
subtract('X', 'IV')   // "VI"
multiply('V', 'III')  // "XV"
divide('X', 'III')    // "III" (floor division)

add('XIV', 'III')→ "XVII"

subtract('X', 'IV')→ "VI"

multiply('V', 'III')→ "XV"

divide('X', 'III')→ "III"

🛠️ Utilities

import { range, compare, sort, breakdown, batchToRoman } from '@tushar_rayamajhi/roman_converter'

range(1, 5)                   // ["I","II","III","IV","V"]
range(10, 1, -3)              // ["X","VII","IV","I"]
compare('X', 'V')             // 1  (X > V)
sort(['X', 'V', 'I', 'M'])  // ["I","V","X","M"]
breakdown('MCMXCIX')          // [{numeral:"M",value:1000}, {numeral:"CM",value:900}, ...]

range(1, 5)→ "I, II, III, IV, V"

range(10, 1, -3)→ "X, VII, IV, I"

breakdown('MCMXCIX')→ "M=1000, CM=900, XC=90, IX=9"

batchToRoman([1,5,10,50,100])→ "I, V, X, L, C"

🏛️ Extended Numerals (up to 3,999,999)

import { toExtendedRoman, fromExtendedRoman } from '@tushar_rayamajhi/roman_converter'

// (V)=5000  (X)=10000  (L)=50000  (C)=100000  (D)=500000  (M)=1000000
toExtendedRoman(4000)     // "(IV)"
toExtendedRoman(1000000)  // "(M)"
toExtendedRoman(1999999)  // "(M)(CM)(XC)(IX)CMXCIX"
fromExtendedRoman('(M)')  // 1000000

toExtendedRoman(4000)→ "(IV)"

toExtendedRoman(1000000)→ "(M)"

toExtendedRoman(1999999)→ "(M)(CM)(XC)(IX)CMXCIX"

⏰ Roman Clock / Time

import { toRomanTime, fromRomanTime, nowInRoman } from '@tushar_rayamajhi/roman_converter'

toRomanTime('14:30')                         // "XIV:XXX"
toRomanTime('09:05', { format: '12h' })      // "IX:V"
toRomanTime('00:00')                         // "XII:·"  (midnight)
toRomanTime('14:30:45', { seconds: true })   // "XIV:XXX:XLV"
fromRomanTime('XIV:XXX')  // { hours: 14, minutes: 30, formatted: '14:30' }
nowInRoman()              // current system time as Roman numerals

toRomanTime('14:30')→ "XIV:XXX"

toRomanTime('09:05', { format: '12h' })→ "IX:V"

toRomanTime('00:00')→ "XII:·"

toRomanTime('14:30:45', { seconds: true })→ "XIV:XXX:XLV"

📜 Classical Latin Words

import { toWords, fromWords } from '@tushar_rayamajhi/roman_converter'

toWords(1)     // "unus"
toWords(18)    // "duodeviginti"  (subtraction form)
toWords(42)    // "quadraginta duo"
toWords(1999)  // "mille nongenti nonaginta novem"
toWords(2000)  // "duo milia"  (neuter nominative plural)
fromWords('quadraginta duo')  // 42

toWords(1)→ "unus"

toWords(18)→ "duodeviginti"

toWords(42)→ "quadraginta duo"

toWords(1999)→ "mille nongenti nonaginta novem"

toWords(2000)→ "duo milia"

⅛ Roman Fractions (Uncia)

import { toUncia, fromUncia, unciaInfo, listUncia } from '@tushar_rayamajhi/roman_converter'

toUncia(0.5)    // "S"  (semis)
toUncia(0.25)   // "···"  (quadrans)
toUncia(2/3)    // "S··"  (bes)
toUncia(1/12)   // "·"  (uncia)
fromUncia('S')  // 0.5
unciaInfo('S')  // { twelfths: 6, symbol: 'S', name: 'semis', decimal: 0.5 }

toUncia(0.5)→ "S"

toUncia(0.25)→ "···"

toUncia(2/3)→ "S··"

toUncia(1/12)→ "·"

toUncia(1)→ "AS"

Symbol	Name	Twelfths	Decimal
·	uncia	1/12	0.0833
··	sextans	2/12	0.1667
···	quadrans	3/12	0.2500
····	triens	4/12	0.3333
·····	quincunx	5/12	0.4167
S	semis	6/12	0.5000
S·	septunx	7/12	0.5833
S··	bes	8/12	0.6667
S···	dodrans	9/12	0.7500
S····	dextans	10/12	0.8333
S·····	deunx	11/12	0.9167
AS	as	12/12	1.0000

⚛️ React Hooks

import { useRoman, useRomanClock } from '@tushar_rayamajhi/roman_converter/react'

// Synchronized integer ↔ Roman state
function RomanCounter() {
  const { roman, integer, increment, decrement, set } = useRoman(1)
  return (
    <div>
      <span>{roman} ({integer})</span>   {/* "I" (1) → "II" (2) → … */}
      <button onClick={() => increment()}>+</button>
      <button onClick={() => decrement()}>−</button>
      <button onClick={() => set('X')}>Jump to X</button>
    </div>
  )
}

// Live clock — updates every second
function RomanClock() {
  const { time } = useRomanClock({ format: '24h', seconds: true })
  return <span>{time}</span>   {/* "XIV:XXX:XLV" */}
}

💻 CLI Reference

npx @tushar_rayamajhi/roman_converter 2024   # MMXXIV
npx @tushar_rayamajhi/roman_converter XLII  # 42

Command	Description
roman <number>	Convert integer to Roman (e.g. roman 2024 → MMXXIV)
roman <ROMAN>	Convert Roman to integer (e.g. roman XLII → 42)
roman add <a> <b>	Add two values (Roman or integers)
roman sub <a> <b>	Subtract b from a
roman mul <a> <b>	Multiply two values
roman div <a> <b>	Floor divide a by b
roman range <s> <e> [step]	Generate Roman range
roman sort [desc] ...values	Sort Roman numerals / integers
roman breakdown <ROMAN>	Decompose a Roman numeral
roman ext <number\|ROMAN>	Extended numeral conversion (1–3,999,999)
roman time [HH:MM]	Current or specified time in Roman
roman words <number>	Convert to classical Latin words
roman uncia <decimal>	Decimal to uncia symbol
roman uncia list	List all 12 uncia entries

Get started

Installation

npmnpm install @tushar_rayamajhi/roman_converter

yarnyarn add @tushar_rayamajhi/roman_converter

pnpmpnpm add @tushar_rayamajhi/roman_converter

// Quick start
import { toRoman, fromRoman, toWords, toRomanTime } from '@tushar_rayamajhi/roman_converter'

console.log(toRoman(2024))          // MMXXIV
console.log(fromRoman('XLII'))      // 42
console.log(toWords(42))            // quadraginta duo
console.log(toRomanTime('14:30'))   // XIV:XXX

npm page GitHub Read the blog post