roman-numerals-js

A lightweight, robust TypeScript library for converting between integers and Roman numerals. Built with modern JavaScript (ES6+) and full TypeScript support.

Powered by roman-numerals.com - Visit for more online conversion tools, historical information, and comprehensive Roman numerals resources.

Features

• 🚀 Fast and efficient conversion algorithms
• 💪 Full TypeScript support with type definitions
• ✅ Comprehensive input validation
• 🎯 Supports numbers from 1 to 3999
• 📦 Zero dependencies
• 🔄 Bidirectional conversion (Integer ↔ Roman)
• ✨ Works in both Node.js and browser environments

Installation

npm install roman-numerals-js

Or using yarn:

yarn add roman-numerals-js

Usage

ES6 Modules

import { toRoman, fromRoman } from 'roman-numerals-js';

// Convert integer to Roman numerals
console.log(toRoman(2024));  // Output: "MMXXIV"
console.log(toRoman(1994));  // Output: "MCMXCIV"

// Convert Roman numerals to integer
console.log(fromRoman('IX'));      // Output: 9
console.log(fromRoman('LVIII'));   // Output: 58

CommonJS

const { toRoman, fromRoman } = require('roman-numerals-js');

console.log(toRoman(42));         // Output: "XLII"
console.log(fromRoman('CDXC'));   // Output: 490

API Reference

toRoman(num: number): string

Converts an integer to Roman numerals.

Parameters:

• num (number): An integer between 1 and 3999

Returns:

• (string): The Roman numeral representation

Throws:

• Error if the number is not an integer or is outside the valid range (1-3999)

Examples:

toRoman(1);     // "I"
toRoman(4);     // "IV"
toRoman(9);     // "IX"
toRoman(58);    // "LVIII"
toRoman(1994);  // "MCMXCIV"
toRoman(3999);  // "MMMCMXCIX"

fromRoman(str: string): number

Converts Roman numerals to an integer.

Parameters:

• str (string): A valid Roman numeral string (case-insensitive)

Returns:

• (number): The integer value

Throws:

• Error if the string contains invalid characters or format

Examples:

fromRoman('I');        // 1
fromRoman('IV');       // 4
fromRoman('ix');       // 9 (case-insensitive)
fromRoman('LVIII');    // 58
fromRoman('MCMXCIV');  // 1994

Validation Rules

• Input numbers must be integers between 1 and 3999
• Roman numeral strings must contain only valid characters: I, V, X, L, C, D, M
• The library automatically handles case conversion (accepts both uppercase and lowercase)
• Leading and trailing whitespace is automatically trimmed

More Resources

For more information about Roman numerals, including:

• Interactive online conversion tools
• Historical background and usage
• Educational materials and examples
• Comprehensive conversion tables

Visit roman-numerals.com - your complete resource for everything related to Roman numerals.

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Build the library
npm run build

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Learn more at roman-numerals.com