Minorly

Minorly is a TypeScript toolkit for safe money handling, currency formatting, major/minor unit conversion, and financial calculations.

Overview

A major-unit value is the amount people usually read, such as GHS 19.78. Its minor-unit equivalent is the integer 1978 pesewas. Financial APIs frequently use minor-unit integers because they are unambiguous to store, transmit, and compare, and avoid treating formatted display text as data.

Minorly currently focuses on conversion and formatting. It is designed to mature into a broader money toolkit while keeping monetary behavior explicit and predictable.

Installation

npm install minorly

pnpm add minorly
yarn add minorly

Quick start

import {
  formatToCurrency,
  toMinorUnit,
  toMajorUnit,
} from "minorly";

formatToCurrency(1250, "GHS");
// "GH₵1,250.00"

toMinorUnit(19.78, "GHS");
// 1978

toMajorUnit(1978, "GHS");
// 19.78

Exact currency-symbol placement and spacing can vary with the runtime's ICU locale data.

API

formatToCurrency(amount, currency, locale?)

Formats a major-unit MoneyInput (number | string) for display. currency is a SupportedCurrency; the optional locale overrides that currency's default locale. It returns a localized string and does not convert minor units.

formatToCurrency("1,250.50", "USD"); // "$1,250.50"
formatToCurrency(1250, "USD", "en-GB"); // "US$1,250.00"

It throws MoneyError for an invalid amount or unsupported currency. Intl.NumberFormat may also throw RangeError for an invalid locale.

toMinorUnit(amount, currency)

Converts a major-unit MoneyInput to a safe-integer minor-unit number, using the configured digits for currency.

toMinorUnit("1,250.50", "GHS"); // 125050
toMinorUnit(1250, "JPY"); // 1250

It throws MoneyError for invalid input, an unsupported currency, excess fractional precision, or a result outside JavaScript's safe-integer range. It does not silently round.

toMajorUnit(amount, currency)

Converts a minor-unit number to a major-unit number. amount must be a safe integer.

toMajorUnit(1978, "GHS"); // 19.78
toMajorUnit(1250, "JPY"); // 1250

It throws MoneyError when the amount is not a safe integer or the currency is unsupported.

MoneyError

The error class used for Minorly validation and conversion failures. It extends JavaScript's Error and has the name "MoneyError".

CURRENCIES

The read-only runtime currency configuration object. Each entry contains its ISO-style code, default locale, and number of minorUnit digits.

Public types

• SupportedCurrency is the union of keys in CURRENCIES.
• MoneyInput is number | string.
• Money is a read-only { amount: MoneyInput; currency: SupportedCurrency } interface.
• CurrencyConfig is a read-only { code: string; locale: string; minorUnit: number } interface.

These types are declarations only and produce no runtime exports.

Precision and design notes

JavaScript uses binary floating-point numbers, so decimal arithmetic can be inexact. toMinorUnit avoids directly calculating values such as 19.78 * 100: it normalizes the amount, splits its decimal components, assembles the minor-unit integer with BigInt, verifies the safe-integer range, and then returns a number.

String input is preferred when exact external textual precision matters; number input remains supported for convenience. Excess fractional precision is rejected instead of silently rounded. formatToCurrency uses a number only at the display boundary required by Intl.NumberFormat. toMajorUnit expects a safe-integer minor-unit amount.

Supported currencies

| Code | Default locale | Minor-unit digits | | --- | --- | ---: | | USD | en-US | 2 | | EUR | de-DE | 2 | | GBP | en-GB | 2 | | GHS | en-GH | 2 | | NGN | en-NG | 2 | | JPY | ja-JP | 0 |

This table reflects the current CURRENCIES object.

Fintech integration pattern

Convert at the provider boundary and keep the currency beside the amount:

const amountMinor = toMinorUnit("19.78", "GHS");

const paymentPayload = {
  amount: amountMinor,
  currency: "GHS",
};

Applications should never send formatted strings to payment APIs, should compare both webhook amount and currency with expected values, and should use idempotency keys plus internal transaction references. Always verify each provider's currency and minor-unit requirements; they are not universal.

Error handling

import { MoneyError, toMinorUnit } from "minorly";

try {
  toMinorUnit("19.999", "GHS");
} catch (error) {
  if (error instanceof MoneyError) {
    console.error(error.message);
  }
}

Development

npm install
npm test
npm run test:watch
npm run typecheck
npm run build

Roadmap

Possible future ideas, with no promised delivery dates, include:

• explicit rounding strategies
• percentage and basis-point fee calculations
• amount allocation
• additional currency metadata
• decimal-safe FX helpers
• richer immutable money objects

Contributing

Contributions are welcome. Open an issue before significant behavioral changes, add or update tests, and run type-checking, tests, and the build before submitting a pull request. Avoid silent monetary rounding or breaking public behavior without prior discussion. See CONTRIBUTING.md for details.

License

MIT © Gerald Amankwah