monetra 1.0.0 → 1.1.0

package/dist/index.d.mts

@@ -74,50 +74,82 @@ declare class Money {
      */
     readonly currency: Currency;
     private constructor();
+    private static resolveCurrency;
     /**
      * Creates a Money instance from minor units (e.g., cents).
      *
      * @param minor - The amount in minor units. Can be a number or BigInt.
-     * @param currency - The currency of the money.
+     * @param currency - The currency of the money (object or code string).
      * @returns A new Money instance.
      * @example
      * const m = Money.fromMinor(100, USD); // $1.00
+     * const m2 = Money.fromMinor(100, 'USD'); // $1.00
      */
-    static fromMinor(minor: bigint | number, currency: Currency): Money;
+    static fromMinor(minor: bigint | number, currency: Currency | string): Money;
     /**
      * Creates a Money instance from major units (e.g., "10.50").
      *
      * @param amount - The amount as a string. Must be a valid decimal number.
-     * @param currency - The currency of the money.
+     * @param currency - The currency of the money (object or code string).
      * @returns A new Money instance.
      * @throws {InvalidPrecisionError} If the amount has more decimal places than the currency allows.
      * @example
      * const m = Money.fromMajor("10.50", USD); // $10.50
      */
-    static fromMajor(amount: string, currency: Currency): Money;
+    static fromMajor(amount: string, currency: Currency | string): Money;
+    /**
+     * Creates a Money instance from a floating-point number.
+     *
+     * ⚠️ WARNING: Floating-point numbers can have precision issues.
+     * Prefer `Money.fromMajor("10.50", currency)` for exact values.
+     *
+     * @param amount - The float amount in major units.
+     * @param currency - The currency.
+     * @param options - Options for handling precision.
+     * @returns A new Money instance.
+     */
+    static fromFloat(amount: number, currency: Currency | string, options?: {
+        rounding?: RoundingMode;
+        suppressWarning?: boolean;
+    }): Money;
+    /**
+     * Returns the minimum of the provided Money values.
+     * @param values - Money values to compare (must all be same currency).
+     * @returns The Money with the smallest amount.
+     * @throws {CurrencyMismatchError} If currencies don't match.
+     */
+    static min(...values: Money[]): Money;
+    /**
+     * Returns the maximum of the provided Money values.
+     * @param values - Money values to compare (must all be same currency).
+     * @returns The Money with the largest amount.
+     * @throws {CurrencyMismatchError} If currencies don't match.
+     */
+    static max(...values: Money[]): Money;
     /**
      * Creates a Money instance representing zero in the given currency.
      *
      * @param currency - The currency.
      * @returns A new Money instance with value 0.
      */
-    static zero(currency: Currency): Money;
+    static zero(currency: Currency | string): Money;
+    private resolveOther;
     /**
      * Adds another Money value to this one.
      *
-     * @param other - The Money value to add.
+     * @param other - The value to add (Money, minor units as number/bigint, or major units as string).
      * @returns A new Money instance representing the sum.
      * @throws {CurrencyMismatchError} If the currencies do not match.
      */
-    add(other: Money): Money;
+    add(other: Money | number | bigint | string): Money;
     /**
      * Subtracts another Money value from this one.
      *
-     * @param other - The Money value to subtract.
+     * @param other - The value to subtract (Money, minor units as number/bigint, or major units as string).
      * @returns A new Money instance representing the difference.
      * @throws {CurrencyMismatchError} If the currencies do not match.
      */
-    subtract(other: Money): Money;
+    subtract(other: Money | number | bigint | string): Money;
     /**
      * Multiplies this Money value by a scalar.
      *
@@ -129,6 +161,28 @@ declare class Money {
     multiply(multiplier: string | number, options?: {
         rounding?: RoundingMode;
     }): Money;
+    /**
+     * Divides this Money value by a divisor.
+     *
+     * @param divisor - The number to divide by.
+     * @param options - Options for rounding if the result is not an integer.
+     * @returns A new Money instance representing the quotient.
+     * @throws {RoundingRequiredError} If the result is fractional and no rounding mode is provided.
+     * @throws {Error} If divisor is zero.
+     */
+    divide(divisor: number | string, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    /**
+     * Returns the absolute value of this Money.
+     * @returns A new Money instance with the absolute value.
+     */
+    abs(): Money;
+    /**
+     * Returns the negated value of this Money.
+     * @returns A new Money instance with the negated value.
+     */
+    negate(): Money;
     /**
      * Allocates (splits) this Money value according to a list of ratios.
      *
@@ -148,30 +202,71 @@ declare class Money {
     format(options?: {
         locale?: string;
         symbol?: boolean;
+        display?: "symbol" | "code" | "name";
     }): string;
     /**
      * Checks if this Money value is equal to another.
      *
-     * @param other - The other Money value.
+     * @param other - The other Money value (Money, minor units as number/bigint, or major units as string).
      * @returns True if amounts and currencies are equal.
      */
-    equals(other: Money): boolean;
+    equals(other: Money | number | bigint | string): boolean;
     /**
      * Checks if this Money value is greater than another.
      *
-     * @param other - The other Money value.
+     * @param other - The other Money value (Money, minor units as number/bigint, or major units as string).
      * @returns True if this value is greater.
      * @throws {CurrencyMismatchError} If the currencies do not match.
      */
-    greaterThan(other: Money): boolean;
+    greaterThan(other: Money | number | bigint | string): boolean;
     /**
      * Checks if this Money value is less than another.
      *
-     * @param other - The other Money value.
+     * @param other - The other Money value (Money, minor units as number/bigint, or major units as string).
      * @returns True if this value is less.
      * @throws {CurrencyMismatchError} If the currencies do not match.
      */
-    lessThan(other: Money): boolean;
+    lessThan(other: Money | number | bigint | string): boolean;
+    /**
+     * Checks if this Money value is greater than or equal to another.
+     */
+    greaterThanOrEqual(other: Money | number | bigint | string): boolean;
+    /**
+     * Checks if this Money value is less than or equal to another.
+     */
+    lessThanOrEqual(other: Money | number | bigint | string): boolean;
+    /**
+     * Checks if this Money value is positive (greater than zero).
+     */
+    isPositive(): boolean;
+    /**
+     * Compares this Money to another, returning -1, 0, or 1.
+     * Useful for sorting.
+     */
+    compare(other: Money | number | bigint | string): -1 | 0 | 1;
+    /**
+     * Calculates a percentage of the money.
+     * @param percent - The percentage (e.g., 50 for 50%).
+     * @param rounding - Rounding mode (defaults to HALF_EVEN).
+     */
+    percentage(percent: number, rounding?: RoundingMode): Money;
+    /**
+     * Adds a percentage to the money.
+     * @param percent - The percentage to add.
+     * @param rounding - Rounding mode.
+     */
+    addPercent(percent: number, rounding?: RoundingMode): Money;
+    /**
+     * Subtracts a percentage from the money.
+     * @param percent - The percentage to subtract.
+     * @param rounding - Rounding mode.
+     */
+    subtractPercent(percent: number, rounding?: RoundingMode): Money;
+    /**
+     * Splits the money into equal parts.
+     * @param parts - Number of parts.
+     */
+    split(parts: number): Money[];
     /**
      * Checks if this Money value is zero.
      *
@@ -184,6 +279,92 @@ declare class Money {
      * @returns True if the amount is negative.
      */
     isNegative(): boolean;
+    /**
+     * Returns a JSON representation of the Money object.
+     *
+     * @returns An object with amount (string), currency (code), and precision.
+     */
+    toJSON(): {
+        amount: string;
+        currency: string;
+        precision: number;
+    };
+    /**
+     * Returns a string representation of the Money object (formatted).
+     */
+    toString(): string;
+}
+
+declare function assertSameCurrency(a: Money, b: Money): void;
+declare function assertNonNegative(money: Money): void;
+
+/**
+ * Handles currency conversion using exchange rates.
+ */
+declare class Converter {
+    private rates;
+    private base;
+    /**
+     * Creates a new Converter.
+     *
+     * @param base - The base currency code (e.g., "USD").
+     * @param rates - A map of currency codes to exchange rates relative to the base.
+     *                Example: { "EUR": 0.85, "GBP": 0.75 } (where 1 Base = 0.85 EUR).
+     */
+    constructor(base: string, rates: Record<string, number>);
+    /**
+     * Converts a Money object to a target currency.
+     *
+     * @param money - The Money object to convert.
+     * @param toCurrency - The target currency (code or object).
+     * @returns A new Money object in the target currency.
+     * @throws {Error} If exchange rates are missing.
+     */
+    convert(money: Money, toCurrency: Currency | string): Money;
+}
+
+/**
+ * A collection of Money objects in different currencies.
+ * Useful for representing a wallet or portfolio.
+ */
+declare class MoneyBag {
+    private contents;
+    /**
+     * Adds a Money amount to the bag.
+     * @param money The money to add.
+     */
+    add(money: Money): void;
+    /**
+     * Subtracts a Money amount from the bag.
+     * @param money The money to subtract.
+     */
+    subtract(money: Money): void;
+    /**
+     * Gets the amount for a specific currency.
+     * @param currency The currency to retrieve.
+     * @returns The Money amount in that currency (or zero if not present).
+     */
+    get(currency: Currency | string): Money;
+    /**
+     * Calculates the total value of the bag in a specific currency.
+     *
+     * @param targetCurrency The currency to convert everything to.
+     * @param converter The converter instance with exchange rates.
+     * @returns The total amount in the target currency.
+     */
+    total(targetCurrency: Currency | string, converter: Converter): Money;
+    /**
+     * Returns a list of all Money objects in the bag.
+     */
+    getAll(): Money[];
+    /**
+     * Returns a JSON representation of the bag.
+     */
+    toJSON(): {
+        amount: string;
+        currency: string;
+        precision: number;
+    }[];
 }
 
 /**
@@ -208,18 +389,28 @@ declare const JPY: Currency;
 declare const ZAR: Currency;
 /**
  * A collection of common currencies.
+ * @deprecated Use registry instead.
  */
 declare const CURRENCIES: Record<string, Currency>;
+
+declare function getMinorUnitExponent(currency: Currency): bigint;
+
 /**
- * Retrieves a Currency object by its ISO 4217 code.
- *
- * @param code - The currency code (case-insensitive).
- * @returns The Currency object corresponding to the code.
- * @throws {Error} If the currency code is not found in the registry.
+ * Registers a currency in the global registry.
+ * @param currency The currency to register.
+ */
+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.
  */
 declare function getCurrency(code: string): Currency;
-
-declare function getMinorUnitExponent(currency: Currency): bigint;
+/**
+ * Checks if a currency is registered.
+ */
+declare function isCurrencyRegistered(code: string): boolean;
 
 declare function divideWithRounding(numerator: bigint, denominator: bigint, mode: RoundingMode): bigint;
 
@@ -228,7 +419,7 @@ declare class MonetraError extends Error {
 }
 
 declare class CurrencyMismatchError extends MonetraError {
-    constructor(expected: string, actual: string);
+    constructor(expected: string, received: string);
 }
 
 declare class InvalidPrecisionError extends MonetraError {
@@ -236,7 +427,7 @@ declare class InvalidPrecisionError extends MonetraError {
 }
 
 declare class RoundingRequiredError extends MonetraError {
-    constructor();
+    constructor(operation?: string, result?: number);
 }
 
 declare class InsufficientFundsError extends MonetraError {
@@ -247,4 +438,15 @@ declare class OverflowError extends MonetraError {
     constructor(message?: string);
 }
 
-export { CURRENCIES, type Currency, CurrencyMismatchError, EUR, GBP, InsufficientFundsError, InvalidPrecisionError, JPY, MonetraError, Money, OverflowError, RoundingMode, RoundingRequiredError, USD, ZAR, divideWithRounding, getCurrency, getMinorUnitExponent };
+/**
+ * Helper function to create Money instances.
+ *
+ * If amount is a number or BigInt, it is treated as minor units.
+ * If amount is a string, it is treated as major units.
+ *
+ * @param amount - The amount (minor units if number/bigint, major units if string).
+ * @param currency - The currency code or object.
+ */
+declare function money(amount: number | bigint | string, currency: string | Currency): Money;
+
+export { CURRENCIES, Converter, type Currency, CurrencyMismatchError, EUR, GBP, InsufficientFundsError, InvalidPrecisionError, JPY, MonetraError, Money, MoneyBag, OverflowError, RoundingMode, RoundingRequiredError, USD, ZAR, assertNonNegative, assertSameCurrency, divideWithRounding, getCurrency, getMinorUnitExponent, isCurrencyRegistered, money, registerCurrency };