monetra 2.0.0 → 2.2.0

package/dist/currency/iso4217.d.ts

@@ -0,0 +1,245 @@
+import { Currency } from "./Currency";
+/**
+ * United States Dollar (USD).
+ */
+export declare const USD: Currency;
+/**
+ * Euro (EUR).
+ */
+export declare const EUR: Currency;
+/**
+ * British Pound Sterling (GBP).
+ */
+export declare const GBP: Currency;
+/**
+ * Japanese Yen (JPY).
+ */
+export declare const JPY: Currency;
+/**
+ * Swiss Franc (CHF).
+ */
+export declare const CHF: Currency;
+/**
+ * Canadian Dollar (CAD).
+ */
+export declare const CAD: Currency;
+/**
+ * Australian Dollar (AUD).
+ */
+export declare const AUD: Currency;
+/**
+ * New Zealand Dollar (NZD).
+ */
+export declare const NZD: Currency;
+/**
+ * Chinese Yuan Renminbi (CNY).
+ */
+export declare const CNY: Currency;
+/**
+ * Hong Kong Dollar (HKD).
+ */
+export declare const HKD: Currency;
+/**
+ * Singapore Dollar (SGD).
+ */
+export declare const SGD: Currency;
+/**
+ * South Korean Won (KRW).
+ */
+export declare const KRW: Currency;
+/**
+ * Indian Rupee (INR).
+ */
+export declare const INR: Currency;
+/**
+ * Swedish Krona (SEK).
+ */
+export declare const SEK: Currency;
+/**
+ * Norwegian Krone (NOK).
+ */
+export declare const NOK: Currency;
+/**
+ * Danish Krone (DKK).
+ */
+export declare const DKK: Currency;
+/**
+ * Polish Zloty (PLN).
+ */
+export declare const PLN: Currency;
+/**
+ * Czech Koruna (CZK).
+ */
+export declare const CZK: Currency;
+/**
+ * Hungarian Forint (HUF).
+ */
+export declare const HUF: Currency;
+/**
+ * Romanian Leu (RON).
+ */
+export declare const RON: Currency;
+/**
+ * Bulgarian Lev (BGN).
+ */
+export declare const BGN: Currency;
+/**
+ * Croatian Kuna (HRK).
+ * Note: Croatia adopted EUR on Jan 1, 2023, but HRK may still be needed for historical data.
+ */
+export declare const HRK: Currency;
+/**
+ * Turkish Lira (TRY).
+ */
+export declare const TRY: Currency;
+/**
+ * Russian Ruble (RUB).
+ */
+export declare const RUB: Currency;
+/**
+ * Ukrainian Hryvnia (UAH).
+ */
+export declare const UAH: Currency;
+/**
+ * Israeli New Shekel (ILS).
+ */
+export declare const ILS: Currency;
+/**
+ * Mexican Peso (MXN).
+ */
+export declare const MXN: Currency;
+/**
+ * Brazilian Real (BRL).
+ */
+export declare const BRL: Currency;
+/**
+ * Argentine Peso (ARS).
+ */
+export declare const ARS: Currency;
+/**
+ * Chilean Peso (CLP).
+ */
+export declare const CLP: Currency;
+/**
+ * Colombian Peso (COP).
+ */
+export declare const COP: Currency;
+/**
+ * Peruvian Sol (PEN).
+ */
+export declare const PEN: Currency;
+/**
+ * South African Rand (ZAR).
+ */
+export declare const ZAR: Currency;
+/**
+ * Nigerian Naira (NGN).
+ */
+export declare const NGN: Currency;
+/**
+ * Kenyan Shilling (KES).
+ */
+export declare const KES: Currency;
+/**
+ * Egyptian Pound (EGP).
+ */
+export declare const EGP: Currency;
+/**
+ * Moroccan Dirham (MAD).
+ */
+export declare const MAD: Currency;
+/**
+ * Ghanaian Cedi (GHS).
+ */
+export declare const GHS: Currency;
+/**
+ * Tanzanian Shilling (TZS).
+ */
+export declare const TZS: Currency;
+/**
+ * Ugandan Shilling (UGX).
+ */
+export declare const UGX: Currency;
+/**
+ * Thai Baht (THB).
+ */
+export declare const THB: Currency;
+/**
+ * Malaysian Ringgit (MYR).
+ */
+export declare const MYR: Currency;
+/**
+ * Indonesian Rupiah (IDR).
+ */
+export declare const IDR: Currency;
+/**
+ * Philippine Peso (PHP).
+ */
+export declare const PHP: Currency;
+/**
+ * Vietnamese Dong (VND).
+ */
+export declare const VND: Currency;
+/**
+ * Taiwan Dollar (TWD).
+ */
+export declare const TWD: Currency;
+/**
+ * Pakistani Rupee (PKR).
+ */
+export declare const PKR: Currency;
+/**
+ * Bangladeshi Taka (BDT).
+ */
+export declare const BDT: Currency;
+/**
+ * Sri Lankan Rupee (LKR).
+ */
+export declare const LKR: Currency;
+/**
+ * United Arab Emirates Dirham (AED).
+ */
+export declare const AED: Currency;
+/**
+ * Saudi Riyal (SAR).
+ */
+export declare const SAR: Currency;
+/**
+ * Qatari Riyal (QAR).
+ */
+export declare const QAR: Currency;
+/**
+ * Kuwaiti Dinar (KWD).
+ * Note: 3 decimal places (fils).
+ */
+export declare const KWD: Currency;
+/**
+ * Bahraini Dinar (BHD).
+ * Note: 3 decimal places (fils).
+ */
+export declare const BHD: Currency;
+/**
+ * Omani Rial (OMR).
+ * Note: 3 decimal places (baisa).
+ */
+export declare const OMR: Currency;
+/**
+ * Jordanian Dinar (JOD).
+ * Note: 3 decimal places (fils).
+ */
+export declare const JOD: Currency;
+/**
+ * Icelandic Króna (ISK).
+ * Note: 0 decimal places.
+ */
+export declare const ISK: Currency;
+/**
+ * Mauritanian Ouguiya (MRU).
+ * Note: Uses 2 decimals (khoums), but often displayed without.
+ */
+export declare const MRU: Currency;
+/**
+ * A collection of common currencies.
+ * @deprecated Use registry instead. Import individual currencies or use getCurrency().
+ */
+export declare const CURRENCIES: Record<string, Currency>;

package/dist/currency/precision.d.ts

@@ -0,0 +1,2 @@
+import { Currency } from "./Currency";
+export declare function getMinorUnitExponent(currency: Currency): bigint;

package/dist/currency/registry.d.ts

@@ -0,0 +1,22 @@
+import { Currency } from "./Currency";
+/**
+ * Registers a currency in the global registry.
+ * @param currency The currency to register.
+ */
+export declare function registerCurrency(currency: Currency): void;
+/**
+ * Retrieves a currency by its code.
+ * @param code The currency code (e.g., "USD").
+ * @returns The Currency object.
+ * @throws Error if the currency is not found.
+ */
+export declare function getCurrency(code: string): Currency;
+/**
+ * Checks if a currency is registered.
+ */
+export declare function isCurrencyRegistered(code: string): boolean;
+/**
+ * Returns all registered currencies as a map.
+ * @internal Use for testing only.
+ */
+export declare function getAllCurrencies(): Record<string, Currency>;

package/dist/errors/BaseError.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Error codes for programmatic handling of Monetra errors.
+ */
+export declare enum MonetraErrorCode {
+    CURRENCY_MISMATCH = "MONETRA_CURRENCY_MISMATCH",
+    INSUFFICIENT_FUNDS = "MONETRA_INSUFFICIENT_FUNDS",
+    INVALID_ARGUMENT = "MONETRA_INVALID_ARGUMENT",
+    INVALID_PRECISION = "MONETRA_INVALID_PRECISION",
+    OVERFLOW = "MONETRA_OVERFLOW",
+    ROUNDING_REQUIRED = "MONETRA_ROUNDING_REQUIRED"
+}
+/**
+ * Base error class for all Monetra errors.
+ * All Monetra errors include an error code for programmatic handling.
+ */
+export declare class MonetraError extends Error {
+    /**
+     * A unique error code for programmatic handling.
+     */
+    readonly code: MonetraErrorCode;
+    constructor(message: string, code: MonetraErrorCode);
+}

package/dist/errors/CurrencyMismatchError.d.ts

@@ -0,0 +1,12 @@
+import { MonetraError } from "./BaseError";
+export declare class CurrencyMismatchError extends MonetraError {
+    /**
+     * The expected currency code.
+     */
+    readonly expected: string;
+    /**
+     * The received currency code.
+     */
+    readonly received: string;
+    constructor(expected: string, received: string);
+}

package/dist/errors/InsufficientFundsError.d.ts

@@ -0,0 +1,4 @@
+import { MonetraError } from "./BaseError";
+export declare class InsufficientFundsError extends MonetraError {
+    constructor(message?: string);
+}

package/dist/errors/InvalidArgumentError.d.ts

@@ -0,0 +1,4 @@
+import { MonetraError } from "./BaseError";
+export declare class InvalidArgumentError extends MonetraError {
+    constructor(message: string);
+}

package/dist/errors/InvalidPrecisionError.d.ts

@@ -0,0 +1,4 @@
+import { MonetraError } from "./BaseError";
+export declare class InvalidPrecisionError extends MonetraError {
+    constructor(message: string);
+}

package/dist/errors/OverflowError.d.ts

@@ -0,0 +1,4 @@
+import { MonetraError } from "./BaseError";
+export declare class OverflowError extends MonetraError {
+    constructor(message?: string);
+}

package/dist/errors/RoundingRequiredError.d.ts

@@ -0,0 +1,4 @@
+import { MonetraError } from "./BaseError";
+export declare class RoundingRequiredError extends MonetraError {
+    constructor(operation?: string, result?: number);
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./BaseError";
+export * from "./CurrencyMismatchError";
+export * from "./InvalidPrecisionError";
+export * from "./RoundingRequiredError";
+export * from "./InsufficientFundsError";
+export * from "./InvalidArgumentError";
+export * from "./OverflowError";

package/dist/financial/compound.d.ts

@@ -0,0 +1,20 @@
+import { Money } from "../money/Money";
+import { RoundingMode } from "../rounding/strategies";
+export interface CompoundOptions {
+    rate: number;
+    years: number;
+    compoundingPerYear?: number;
+    rounding?: RoundingMode;
+}
+/**
+ * Calculates future value with compound interest.
+ * FV = PV * (1 + r/n)^(n*t)
+ */
+export declare function futureValue(presentValue: Money, options: CompoundOptions): Money;
+/**
+ * Calculates present value (discounting).
+ * PV = FV / (1 + r/n)^(n*t)
+ */
+export declare function presentValue(futureVal: Money, options: CompoundOptions): Money;
+export declare const compound: typeof futureValue;
+export declare const discount: typeof presentValue;

package/dist/financial/depreciation.d.ts

@@ -0,0 +1,30 @@
+import { Money } from "../money/Money";
+import { RoundingMode } from "../rounding/strategies";
+export interface DepreciationOptions {
+    cost: Money;
+    salvageValue: Money;
+    usefulLife: number;
+    rounding?: RoundingMode;
+}
+export interface DepreciationResult {
+    annualDepreciation: Money;
+    bookValueAtYear(year: number): Money;
+    schedule(): {
+        year: number;
+        depreciation: Money;
+        bookValue: Money;
+    }[];
+}
+/**
+ * Calculates straight-line depreciation for an asset.
+ *
+ * Formula:
+ * Annual Depreciation = (Cost - Salvage Value) / Useful Life
+ * Book Value at Year N = Cost - (Annual Depreciation × N)
+ *
+ * @param options - Configuration for depreciation calculation
+ * @returns Object containing annual depreciation, book value calculator, and schedule generator
+ * @throws {CurrencyMismatchError} If cost and salvage value currencies differ
+ * @throws {InvalidArgumentError} If useful life is not positive or salvage value > cost
+ */
+export declare function straightLineDepreciation(options: DepreciationOptions): DepreciationResult;

package/dist/financial/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./loan";
+export * from "./compound";
+export * from "./investment";
+export * from "./rate";
+export * from "./simple";
+export * from "./leverage";
+export * from "./depreciation";