@payafter/currency

Shared currency utilities for PayAfter applications supporting RWF (Rwandan Franc) and XOF (West African CFA Franc).

Features

• ✅ Precise monetary calculations using Dinero.js
• ✅ RWF rounding constraint - All installments (except last) are multiples of 100
• ✅ Multi-currency support - RWF and XOF
• ✅ Type-safe - Full TypeScript support
• ✅ Well-tested - >90% code coverage

Installation

npm install @payafter/currency dinero.js

Note: dinero.js is a peer dependency and must be installed separately.

Usage

Calculate Installments

import { calculateInstallments } from '@payafter/currency';

// RWF - with rounding to multiples of 100
const installments = calculateInstallments(100000, 3, 'RWF');
// [33300, 33300, 33400]

// XOF - no rounding constraint
const installments = calculateInstallments(100000, 3, 'XOF');
// [33333, 33333, 33334]

Format Money

import { formatMoney } from '@payafter/currency';

// Format RWF
const formatted = formatMoney(100000, 'RWF');
// "RWF 100,000"

// Format XOF with French locale
const formatted = formatMoney(100000, 'XOF', 'fr-FR');
// "100 000 XOF"

Calculate Monthly Repayment

import { calculateMonthlyRepayment } from '@payafter/currency';

const result = calculateMonthlyRepayment(
  100000,  // amountFunded
  20000,   // expectedProfit
  6,       // paymentLength (months)
  'RWF'    // currency
);

console.log(result);
// {
//   monthlyReturn: 20000,
//   monthlyPrincipal: 16700,
//   monthlyProfit: 3300
// }

Round to Minimum Unit

import { roundToMinimumUnit } from '@payafter/currency';

// RWF - rounds to nearest 100
roundToMinimumUnit(33333, 'RWF'); // 33300
roundToMinimumUnit(33350, 'RWF'); // 33400

// XOF - no rounding
roundToMinimumUnit(33333, 'XOF'); // 33333

API Reference

Types

type Currency = 'RWF' | 'XOF';
type Locale = 'rw' | 'ci';

interface CurrencyConfig {
  currency: Currency;
  minimumUnit: number;
  locale: string;
}

Constants

CURRENCY_CONFIGS: Record<Currency, CurrencyConfig>
LOCALE_TO_CURRENCY: Record<string, Currency>

Functions

calculateInstallments(totalPrice: number, count: number, currency: Currency): number[]

Calculates installment amounts with precise distribution.

• RWF: Each installment (except last) is rounded to multiples of 100
• XOF: No rounding constraint
• Last installment absorbs any remainder to ensure sum = totalPrice

formatMoney(amount: number | Dinero.Dinero, currency: Currency, locale?: string): string

Formats money for display.

roundToMinimumUnit(amount: number, currency: Currency): number

Rounds amount to the currency's minimum unit.

calculateMonthlyRepayment(amountFunded: number, expectedProfit: number, paymentLength: number, currency: Currency)

Calculates monthly repayment details for investors.

createMoney(amount: number, currency: Currency): Dinero.Dinero

Creates a Dinero money object.

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

Testing

The package has comprehensive test coverage (>90%) including:

• Installment calculations for both currencies
• Rounding constraints for RWF
• Money formatting
• Edge cases (zero count, single installment, etc.)

Run tests:

npm test

License

UNLICENSED - Private package for PayAfter

Support

For issues or questions, contact the PayAfter development team.