subunit-money 2.0.0

package/currencymap.json

@@ -0,0 +1,536 @@
+{
+   "AED": {
+      "decimal_digits": 2
+   },
+   "AFN": {
+      "decimal_digits": 2
+   },
+   "ALL": {
+      "decimal_digits": 2
+   },
+   "AMD": {
+      "decimal_digits": 2
+   },
+   "AOA": {
+      "decimal_digits": 2
+   },
+   "ARS": {
+      "decimal_digits": 2
+   },
+   "AUD": {
+      "decimal_digits": 2
+   },
+   "AWG": {
+      "decimal_digits": 2
+   },
+   "AZN": {
+      "decimal_digits": 2
+   },
+   "BAM": {
+      "decimal_digits": 2
+   },
+   "BBD": {
+      "decimal_digits": 2
+   },
+   "BDT": {
+      "decimal_digits": 2
+   },
+   "BHD": {
+      "decimal_digits": 3
+   },
+   "BIF": {
+      "decimal_digits": 0
+   },
+   "BMD": {
+      "decimal_digits": 2
+   },
+   "BND": {
+      "decimal_digits": 2
+   },
+   "BOB": {
+      "decimal_digits": 2
+   },
+   "BOV": {
+      "decimal_digits": 2
+   },
+   "BRL": {
+      "decimal_digits": 2
+   },
+   "BSD": {
+      "decimal_digits": 2
+   },
+   "BTN": {
+      "decimal_digits": 2
+   },
+   "BWP": {
+      "decimal_digits": 2
+   },
+   "BYN": {
+      "decimal_digits": 2
+   },
+   "BZD": {
+      "decimal_digits": 2
+   },
+   "CAD": {
+      "decimal_digits": 2
+   },
+   "CDF": {
+      "decimal_digits": 2
+   },
+   "CHE": {
+      "decimal_digits": 2
+   },
+   "CHF": {
+      "decimal_digits": 2
+   },
+   "CHW": {
+      "decimal_digits": 2
+   },
+   "CLF": {
+      "decimal_digits": 4
+   },
+   "CLP": {
+      "decimal_digits": 0
+   },
+   "CNY": {
+      "decimal_digits": 2
+   },
+   "COP": {
+      "decimal_digits": 2
+   },
+   "COU": {
+      "decimal_digits": 2
+   },
+   "CRC": {
+      "decimal_digits": 2
+   },
+   "CUP": {
+      "decimal_digits": 2
+   },
+   "CVE": {
+      "decimal_digits": 2
+   },
+   "CZK": {
+      "decimal_digits": 2
+   },
+   "DJF": {
+      "decimal_digits": 0
+   },
+   "DKK": {
+      "decimal_digits": 2
+   },
+   "DOP": {
+      "decimal_digits": 2
+   },
+   "DZD": {
+      "decimal_digits": 2
+   },
+   "EGP": {
+      "decimal_digits": 2
+   },
+   "ERN": {
+      "decimal_digits": 2
+   },
+   "ETB": {
+      "decimal_digits": 2
+   },
+   "EUR": {
+      "decimal_digits": 2
+   },
+   "FJD": {
+      "decimal_digits": 2
+   },
+   "FKP": {
+      "decimal_digits": 2
+   },
+   "GBP": {
+      "decimal_digits": 2
+   },
+   "GEL": {
+      "decimal_digits": 2
+   },
+   "GHS": {
+      "decimal_digits": 2
+   },
+   "GIP": {
+      "decimal_digits": 2
+   },
+   "GMD": {
+      "decimal_digits": 2
+   },
+   "GNF": {
+      "decimal_digits": 0
+   },
+   "GTQ": {
+      "decimal_digits": 2
+   },
+   "GYD": {
+      "decimal_digits": 2
+   },
+   "HKD": {
+      "decimal_digits": 2
+   },
+   "HNL": {
+      "decimal_digits": 2
+   },
+   "HTG": {
+      "decimal_digits": 2
+   },
+   "HUF": {
+      "decimal_digits": 2
+   },
+   "IDR": {
+      "decimal_digits": 2
+   },
+   "ILS": {
+      "decimal_digits": 2
+   },
+   "INR": {
+      "decimal_digits": 2
+   },
+   "IQD": {
+      "decimal_digits": 3
+   },
+   "IRR": {
+      "decimal_digits": 2
+   },
+   "ISK": {
+      "decimal_digits": 0
+   },
+   "JMD": {
+      "decimal_digits": 2
+   },
+   "JOD": {
+      "decimal_digits": 3
+   },
+   "JPY": {
+      "decimal_digits": 0
+   },
+   "KES": {
+      "decimal_digits": 2
+   },
+   "KGS": {
+      "decimal_digits": 2
+   },
+   "KHR": {
+      "decimal_digits": 2
+   },
+   "KMF": {
+      "decimal_digits": 0
+   },
+   "KPW": {
+      "decimal_digits": 2
+   },
+   "KRW": {
+      "decimal_digits": 0
+   },
+   "KWD": {
+      "decimal_digits": 3
+   },
+   "KYD": {
+      "decimal_digits": 2
+   },
+   "KZT": {
+      "decimal_digits": 2
+   },
+   "LAK": {
+      "decimal_digits": 2
+   },
+   "LBP": {
+      "decimal_digits": 2
+   },
+   "LKR": {
+      "decimal_digits": 2
+   },
+   "LRD": {
+      "decimal_digits": 2
+   },
+   "LSL": {
+      "decimal_digits": 2
+   },
+   "LYD": {
+      "decimal_digits": 3
+   },
+   "MAD": {
+      "decimal_digits": 2
+   },
+   "MDL": {
+      "decimal_digits": 2
+   },
+   "MGA": {
+      "decimal_digits": 2
+   },
+   "MKD": {
+      "decimal_digits": 2
+   },
+   "MMK": {
+      "decimal_digits": 2
+   },
+   "MNT": {
+      "decimal_digits": 2
+   },
+   "MOP": {
+      "decimal_digits": 2
+   },
+   "MRU": {
+      "decimal_digits": 2
+   },
+   "MUR": {
+      "decimal_digits": 2
+   },
+   "MVR": {
+      "decimal_digits": 2
+   },
+   "MWK": {
+      "decimal_digits": 2
+   },
+   "MXN": {
+      "decimal_digits": 2
+   },
+   "MXV": {
+      "decimal_digits": 2
+   },
+   "MYR": {
+      "decimal_digits": 2
+   },
+   "MZN": {
+      "decimal_digits": 2
+   },
+   "NAD": {
+      "decimal_digits": 2
+   },
+   "NGN": {
+      "decimal_digits": 2
+   },
+   "NIO": {
+      "decimal_digits": 2
+   },
+   "NOK": {
+      "decimal_digits": 2
+   },
+   "NPR": {
+      "decimal_digits": 2
+   },
+   "NZD": {
+      "decimal_digits": 2
+   },
+   "OMR": {
+      "decimal_digits": 3
+   },
+   "PAB": {
+      "decimal_digits": 2
+   },
+   "PEN": {
+      "decimal_digits": 2
+   },
+   "PGK": {
+      "decimal_digits": 2
+   },
+   "PHP": {
+      "decimal_digits": 2
+   },
+   "PKR": {
+      "decimal_digits": 2
+   },
+   "PLN": {
+      "decimal_digits": 2
+   },
+   "PYG": {
+      "decimal_digits": 0
+   },
+   "QAR": {
+      "decimal_digits": 2
+   },
+   "RON": {
+      "decimal_digits": 2
+   },
+   "RSD": {
+      "decimal_digits": 2
+   },
+   "RUB": {
+      "decimal_digits": 2
+   },
+   "RWF": {
+      "decimal_digits": 0
+   },
+   "SAR": {
+      "decimal_digits": 2
+   },
+   "SBD": {
+      "decimal_digits": 2
+   },
+   "SCR": {
+      "decimal_digits": 2
+   },
+   "SDG": {
+      "decimal_digits": 2
+   },
+   "SEK": {
+      "decimal_digits": 2
+   },
+   "SGD": {
+      "decimal_digits": 2
+   },
+   "SHP": {
+      "decimal_digits": 2
+   },
+   "SLE": {
+      "decimal_digits": 2
+   },
+   "SOS": {
+      "decimal_digits": 2
+   },
+   "SRD": {
+      "decimal_digits": 2
+   },
+   "SSP": {
+      "decimal_digits": 2
+   },
+   "STN": {
+      "decimal_digits": 2
+   },
+   "SVC": {
+      "decimal_digits": 2
+   },
+   "SYP": {
+      "decimal_digits": 2
+   },
+   "SZL": {
+      "decimal_digits": 2
+   },
+   "THB": {
+      "decimal_digits": 2
+   },
+   "TJS": {
+      "decimal_digits": 2
+   },
+   "TMT": {
+      "decimal_digits": 2
+   },
+   "TND": {
+      "decimal_digits": 3
+   },
+   "TOP": {
+      "decimal_digits": 2
+   },
+   "TRY": {
+      "decimal_digits": 2
+   },
+   "TTD": {
+      "decimal_digits": 2
+   },
+   "TWD": {
+      "decimal_digits": 2
+   },
+   "TZS": {
+      "decimal_digits": 2
+   },
+   "UAH": {
+      "decimal_digits": 2
+   },
+   "UGX": {
+      "decimal_digits": 0
+   },
+   "USD": {
+      "decimal_digits": 2
+   },
+   "USN": {
+      "decimal_digits": 2
+   },
+   "UYI": {
+      "decimal_digits": 0
+   },
+   "UYU": {
+      "decimal_digits": 2
+   },
+   "UYW": {
+      "decimal_digits": 4
+   },
+   "UZS": {
+      "decimal_digits": 2
+   },
+   "VED": {
+      "decimal_digits": 2
+   },
+   "VES": {
+      "decimal_digits": 2
+   },
+   "VND": {
+      "decimal_digits": 0
+   },
+   "VUV": {
+      "decimal_digits": 0
+   },
+   "WST": {
+      "decimal_digits": 2
+   },
+   "XAD": {
+      "decimal_digits": 2
+   },
+   "XAF": {
+      "decimal_digits": 0
+   },
+   "XAG": {
+      "decimal_digits": 0
+   },
+   "XAU": {
+      "decimal_digits": 0
+   },
+   "XBA": {
+      "decimal_digits": 0
+   },
+   "XBB": {
+      "decimal_digits": 0
+   },
+   "XBC": {
+      "decimal_digits": 0
+   },
+   "XBD": {
+      "decimal_digits": 0
+   },
+   "XCD": {
+      "decimal_digits": 2
+   },
+   "XCG": {
+      "decimal_digits": 2
+   },
+   "XDR": {
+      "decimal_digits": 0
+   },
+   "XOF": {
+      "decimal_digits": 0
+   },
+   "XPD": {
+      "decimal_digits": 0
+   },
+   "XPF": {
+      "decimal_digits": 0
+   },
+   "XPT": {
+      "decimal_digits": 0
+   },
+   "XSU": {
+      "decimal_digits": 0
+   },
+   "XTS": {
+      "decimal_digits": 0
+   },
+   "XUA": {
+      "decimal_digits": 0
+   },
+   "XXX": {
+      "decimal_digits": 0
+   },
+   "YER": {
+      "decimal_digits": 2
+   },
+   "ZAR": {
+      "decimal_digits": 2
+   },
+   "ZMW": {
+      "decimal_digits": 2
+   },
+   "ZWG": {
+      "decimal_digits": 2
+   }
+}

package/dist/currency.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Currency registry and types.
+ * Manages ISO 4217 currency definitions and custom currencies.
+ */
+export interface CurrencyDefinition {
+    code: string;
+    decimalDigits: number;
+}
+/**
+ * Register a new currency or update an existing one.
+ * @param code - ISO 4217 currency code (e.g., 'USD', 'EUR', 'BTC')
+ * @param decimalDigits - Number of decimal places (e.g., 2 for USD, 8 for BTC)
+ */
+export declare function registerCurrency(code: string, decimalDigits: number): void;
+/**
+ * Get a currency definition by code.
+ * @returns The currency definition, or undefined if not registered
+ */
+export declare function getCurrency(code: string): CurrencyDefinition | undefined;
+/**
+ * Check if a currency is registered.
+ */
+export declare function hasCurrency(code: string): boolean;
+/**
+ * Get all registered currencies, sorted by code.
+ */
+export declare function getAllCurrencies(): CurrencyDefinition[];
+/**
+ * Load currencies from the legacy currencymap.json format.
+ * @param map - Object with currency codes as keys and {decimal_digits: number} as values
+ */
+export declare function loadCurrencyMap(map: Record<string, {
+    decimal_digits: number;
+}>): void;
+/**
+ * Clear all registered currencies. Useful for testing.
+ */
+export declare function clearCurrencies(): void;

package/dist/currency.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Currency registry and types.
+ * Manages ISO 4217 currency definitions and custom currencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCurrency = registerCurrency;
+exports.getCurrency = getCurrency;
+exports.hasCurrency = hasCurrency;
+exports.getAllCurrencies = getAllCurrencies;
+exports.loadCurrencyMap = loadCurrencyMap;
+exports.clearCurrencies = clearCurrencies;
+// Internal registry - mutable for registerCurrency()
+const currencies = new Map();
+/**
+ * Register a new currency or update an existing one.
+ * @param code - ISO 4217 currency code (e.g., 'USD', 'EUR', 'BTC')
+ * @param decimalDigits - Number of decimal places (e.g., 2 for USD, 8 for BTC)
+ */
+function registerCurrency(code, decimalDigits) {
+    currencies.set(code, { code, decimalDigits });
+}
+/**
+ * Get a currency definition by code.
+ * @returns The currency definition, or undefined if not registered
+ */
+function getCurrency(code) {
+    return currencies.get(code);
+}
+/**
+ * Check if a currency is registered.
+ */
+function hasCurrency(code) {
+    return currencies.has(code);
+}
+/**
+ * Get all registered currencies, sorted by code.
+ */
+function getAllCurrencies() {
+    return Array.from(currencies.values()).sort((a, b) => a.code.localeCompare(b.code));
+}
+/**
+ * Load currencies from the legacy currencymap.json format.
+ * @param map - Object with currency codes as keys and {decimal_digits: number} as values
+ */
+function loadCurrencyMap(map) {
+    for (const [code, data] of Object.entries(map)) {
+        registerCurrency(code, data.decimal_digits);
+    }
+}
+/**
+ * Clear all registered currencies. Useful for testing.
+ */
+function clearCurrencies() {
+    currencies.clear();
+}

package/dist/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Custom error types for Money operations.
+ * All errors extend built-in Error types for proper instanceof checks.
+ */
+/**
+ * Thrown when attempting operations between different currencies.
+ * @example
+ * new Money('USD', 10).add(new Money('EUR', 5)) // throws CurrencyMismatchError
+ */
+export declare class CurrencyMismatchError extends TypeError {
+    readonly fromCurrency: string;
+    readonly toCurrency: string;
+    constructor(fromCurrency: string, toCurrency: string);
+}
+/**
+ * Thrown when using an unregistered currency code.
+ * @example
+ * new Money('FAKE', 10) // throws CurrencyUnknownError
+ */
+export declare class CurrencyUnknownError extends TypeError {
+    readonly currency: string;
+    constructor(currency: string);
+}
+/**
+ * Thrown when an amount has more decimal places than the currency allows.
+ * @example
+ * new Money('USD', '1.234') // throws SubunitError (USD only allows 2 decimals)
+ */
+export declare class SubunitError extends RangeError {
+    readonly currency: string;
+    readonly maxDecimals: number;
+    constructor(currency: string, maxDecimals: number);
+}
+/**
+ * Thrown when an amount cannot be parsed as a valid number.
+ * @example
+ * new Money('USD', 'abc') // throws AmountError
+ */
+export declare class AmountError extends TypeError {
+    readonly amount: unknown;
+    constructor(amount: unknown);
+}
+/**
+ * Thrown when an exchange rate is not available.
+ * @example
+ * converter.convert(usdMoney, 'XYZ') // throws ExchangeRateError if no USD->XYZ rate
+ */
+export declare class ExchangeRateError extends Error {
+    readonly fromCurrency: string;
+    readonly toCurrency: string;
+    constructor(fromCurrency: string, toCurrency: string);
+}