Transform ⚡ numbers into Roman numerals (and back again) with no dependencies. Perfect for when X, V, and I are more your style than 1, 2, 3. As battle-tested as a gladiator ⚔️ 🏛️

Install 🔨

With npm, pnpm, or yarn installed, run:

$ npm install romans

Usage 🧮

const romans = require('romans');
romans.romanize(454)
// returns: 'CDLIV'

romans.deromanize('CDLIV')
// returns: 454

romans.allNumerals
// array containing the numeric equivalents of the roman characters
// [ 1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1 ]

romans.allChars
// array containing all roman numeral characters
// [ 'M', 'CM', 'D', 'CD', 'C', 'XC', 'L', 'XL', 'X', 'IX', 'V', 'IV', 'I' ]

Testing 🧪

Test coverage is reported via codecov, and run on every release

$ yarn test

License 📜

MIT

Open source license obligations are tracked via FOSSA scans.

Note: The license obligation check says there are dependencies, they are purely used for dev tests, the core library has no direct dependencies 💪

Security 🔒

I take supply chain security seriously and run socket.dev scans on all PRs and releases. Although there are no dependencies on the library, I value your trust. If you see something, say something.

FAQ 🤔

What, why?

It started as a joke and became an interesting diversion, there are now more tests than library and it has a mind of it's own. Doing this was an interesting coding challenge problem that isn't the easiest to solve, and really, the Superbowl will have to use it eventually 🙃. Also, love a silly thing.

Why is there no 0?

Roman numerals didn't include 0, so it's not included here. Yes, it's pedantry. No, I'm not adding it.

I don't get it, why is this not an ESM module?

On the fence here, but mainly to support in older codebases that are CommonJS based. I value not having a compile step.

Why didn't you build this in Typescript?

I value not having to set up typescript, and really, I do enjoy the simplicity of having a single library file. There are types and extensive JSDoc comments. Eventually, I'll cave and do multiple builds, but for now, this is fine. If you feel strongly about this decision, pull requests are open.

What's new in v3?

Same great taste, API is 💯 identical, more tests, improved efficiency, improved types, vastly improved docs ⚔️

Contributions 🤝

If you'd like to contribute to this library, please send a PR or file a new issue. I aim to get PRs accepted in short order should they align with the goals. Also, be kind, again, this started as a joke.

If you'd like to show appreciation, I love ☕.