monetra 1.0.0 → 1.1.0

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CURRENCIES: () => CURRENCIES,
+  Converter: () => Converter,
   CurrencyMismatchError: () => CurrencyMismatchError,
   EUR: () => EUR,
   GBP: () => GBP,
@@ -29,17 +30,49 @@ __export(index_exports, {
   JPY: () => JPY,
   MonetraError: () => MonetraError,
   Money: () => Money,
+  MoneyBag: () => MoneyBag,
   OverflowError: () => OverflowError,
   RoundingMode: () => RoundingMode,
   RoundingRequiredError: () => RoundingRequiredError,
   USD: () => USD,
   ZAR: () => ZAR,
+  assertNonNegative: () => assertNonNegative,
+  assertSameCurrency: () => assertSameCurrency,
   divideWithRounding: () => divideWithRounding,
   getCurrency: () => getCurrency,
-  getMinorUnitExponent: () => getMinorUnitExponent
+  getMinorUnitExponent: () => getMinorUnitExponent,
+  isCurrencyRegistered: () => isCurrencyRegistered,
+  money: () => money,
+  registerCurrency: () => registerCurrency
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/currency/registry.ts
+var registry = /* @__PURE__ */ new Map();
+function registerCurrency(currency) {
+  registry.set(currency.code, currency);
+}
+function getCurrency(code) {
+  const currency = registry.get(code);
+  if (!currency) {
+    throw new Error(`Currency '${code}' not found in registry.`);
+  }
+  return currency;
+}
+function isCurrencyRegistered(code) {
+  return registry.has(code);
+}
+
+// src/rounding/strategies.ts
+var RoundingMode = /* @__PURE__ */ ((RoundingMode3) => {
+  RoundingMode3["HALF_UP"] = "HALF_UP";
+  RoundingMode3["HALF_DOWN"] = "HALF_DOWN";
+  RoundingMode3["HALF_EVEN"] = "HALF_EVEN";
+  RoundingMode3["FLOOR"] = "FLOOR";
+  RoundingMode3["CEIL"] = "CEIL";
+  return RoundingMode3;
+})(RoundingMode || {});
+
 // src/errors/BaseError.ts
 var MonetraError = class extends Error {
   constructor(message) {
@@ -51,8 +84,13 @@ var MonetraError = class extends Error {
 
 // src/errors/CurrencyMismatchError.ts
 var CurrencyMismatchError = class extends MonetraError {
-  constructor(expected, actual) {
-    super(`Currency mismatch: expected ${expected}, got ${actual}`);
+  constructor(expected, received) {
+    super(
+      `Currency mismatch: expected ${expected}, received ${received}.
+\u{1F4A1} Tip: Use a Converter to convert between currencies:
+   const converter = new Converter('USD', { ${received}: rate });
+   const converted = converter.convert(money, '${expected}');`
+    );
   }
 };
 
@@ -65,8 +103,15 @@ var InvalidPrecisionError = class extends MonetraError {
 
 // src/errors/RoundingRequiredError.ts
 var RoundingRequiredError = class extends MonetraError {
-  constructor() {
-    super("Rounding is required for this operation but was not provided.");
+  constructor(operation, result) {
+    let message = "Rounding is required for this operation but was not provided.";
+    if (operation && result !== void 0) {
+      message = `Rounding required for ${operation}: result ${result} is not an integer.
+\u{1F4A1} Tip: Provide a rounding mode:
+   money.${operation}(value, { rounding: RoundingMode.HALF_UP })
+   Available modes: HALF_UP, HALF_DOWN, HALF_EVEN, FLOOR, CEIL`;
+    }
+    super(message);
   }
 };
 
@@ -90,16 +135,11 @@ function assertSameCurrency(a, b) {
     throw new CurrencyMismatchError(a.currency.code, b.currency.code);
   }
 }
-
-// src/rounding/strategies.ts
-var RoundingMode = /* @__PURE__ */ ((RoundingMode3) => {
-  RoundingMode3["HALF_UP"] = "HALF_UP";
-  RoundingMode3["HALF_DOWN"] = "HALF_DOWN";
-  RoundingMode3["HALF_EVEN"] = "HALF_EVEN";
-  RoundingMode3["FLOOR"] = "FLOOR";
-  RoundingMode3["CEIL"] = "CEIL";
-  return RoundingMode3;
-})(RoundingMode || {});
+function assertNonNegative(money2) {
+  if (money2.isNegative()) {
+    throw new Error("Money value must be non-negative");
+  }
+}
 
 // src/rounding/index.ts
 function divideWithRounding(numerator, denominator, mode) {
@@ -160,10 +200,24 @@ function multiply(amount, multiplier, rounding) {
     return product / denominator;
   }
   if (!rounding) {
-    throw new RoundingRequiredError();
+    throw new RoundingRequiredError(
+      "multiply",
+      Number(product) / Number(denominator)
+    );
   }
   return divideWithRounding(product, denominator, rounding);
 }
+function divide(amount, divisor, rounding) {
+  const { numerator, denominator } = parseMultiplier(divisor);
+  const product = amount * denominator;
+  if (product % numerator === 0n) {
+    return product / numerator;
+  }
+  if (!rounding) {
+    throw new RoundingRequiredError("divide", Number(product) / Number(numerator));
+  }
+  return divideWithRounding(product, numerator, rounding);
+}
 function parseMultiplier(multiplier) {
   const s = multiplier.toString();
   if (/[eE]/.test(s)) {
@@ -252,11 +306,12 @@ function parseToMinor(amount, currency) {
 }
 
 // src/format/formatter.ts
-function format(money, options) {
-  const locale = options?.locale || money.currency.locale || "en-US";
+function format(money2, options) {
+  const locale = options?.locale || money2.currency.locale || "en-US";
   const showSymbol = options?.symbol ?? true;
-  const decimals = money.currency.decimals;
-  const minor = money.minor;
+  const display = options?.display || "symbol";
+  const decimals = money2.currency.decimals;
+  const minor = money2.minor;
   const absMinor = minor < 0n ? -minor : minor;
   const divisor = 10n ** BigInt(decimals);
   const integerPart = absMinor / divisor;
@@ -277,7 +332,8 @@ function format(money, options) {
   }
   const templateParts = new Intl.NumberFormat(locale, {
     style: "currency",
-    currency: money.currency.code
+    currency: money2.currency.code,
+    currencyDisplay: display
   }).formatToParts(minor < 0n ? -1 : 1);
   let result = "";
   let numberInserted = false;
@@ -302,66 +358,135 @@ var Money = class _Money {
     this.minor = minor;
     this.currency = currency;
   }
+  static resolveCurrency(currency) {
+    if (typeof currency === "string") {
+      return getCurrency(currency);
+    }
+    return currency;
+  }
   /**
    * 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, currency) {
-    return new _Money(BigInt(minor), currency);
+    return new _Money(BigInt(minor), _Money.resolveCurrency(currency));
   }
   /**
    * 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, currency) {
-    const minor = parseToMinor(amount, currency);
-    return new _Money(minor, currency);
+    const resolvedCurrency = _Money.resolveCurrency(currency);
+    const minor = parseToMinor(amount, resolvedCurrency);
+    return new _Money(minor, resolvedCurrency);
+  }
+  /**
+   * 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, currency, options) {
+    if (!options?.suppressWarning && process.env.NODE_ENV !== "production") {
+      console.warn(
+        '[monetra] Money.fromFloat() may lose precision. Consider using Money.fromMajor("' + amount + '", currency) instead.'
+      );
+    }
+    const resolvedCurrency = _Money.resolveCurrency(currency);
+    const factor = 10 ** resolvedCurrency.decimals;
+    const minorUnits = Math.round(amount * factor);
+    return new _Money(BigInt(minorUnits), resolvedCurrency);
+  }
+  /**
+   * 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) {
+    if (values.length === 0)
+      throw new Error("At least one Money value required");
+    return values.reduce((min, current) => {
+      assertSameCurrency(min, current);
+      return current.lessThan(min) ? current : min;
+    });
+  }
+  /**
+   * 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) {
+    if (values.length === 0)
+      throw new Error("At least one Money value required");
+    return values.reduce((max, current) => {
+      assertSameCurrency(max, current);
+      return current.greaterThan(max) ? current : max;
+    });
   }
   /**
    * 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) {
-    return new _Money(0n, currency);
+    return new _Money(0n, _Money.resolveCurrency(currency));
+  }
+  resolveOther(other) {
+    if (other instanceof _Money) {
+      return other;
+    }
+    if (typeof other === "string") {
+      return _Money.fromMajor(other, this.currency);
+    }
+    return _Money.fromMinor(other, this.currency);
   }
   /**
    * 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) {
-    assertSameCurrency(this, other);
-    return new _Money(add(this.minor, other.minor), this.currency);
+    const otherMoney = this.resolveOther(other);
+    assertSameCurrency(this, otherMoney);
+    return new _Money(add(this.minor, otherMoney.minor), this.currency);
   }
   /**
    * 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) {
-    assertSameCurrency(this, other);
-    return new _Money(subtract(this.minor, other.minor), this.currency);
+    const otherMoney = this.resolveOther(other);
+    assertSameCurrency(this, otherMoney);
+    return new _Money(subtract(this.minor, otherMoney.minor), this.currency);
   }
   /**
    * Multiplies this Money value by a scalar.
-   * 
+   *
    * @param multiplier - The number to multiply by.
    * @param options - Options for rounding if the result is not an integer.
    * @returns A new Money instance representing the product.
@@ -371,12 +496,45 @@ var Money = class _Money {
     const result = multiply(this.minor, multiplier, options?.rounding);
     return new _Money(result, this.currency);
   }
+  /**
+   * 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, options) {
+    if (divisor === 0 || divisor === "0") {
+      throw new Error("Division by zero");
+    }
+    const result = divide(this.minor, divisor, options?.rounding);
+    return new _Money(result, this.currency);
+  }
+  /**
+   * Returns the absolute value of this Money.
+   * @returns A new Money instance with the absolute value.
+   */
+  abs() {
+    return new _Money(
+      this.minor < 0n ? -this.minor : this.minor,
+      this.currency
+    );
+  }
+  /**
+   * Returns the negated value of this Money.
+   * @returns A new Money instance with the negated value.
+   */
+  negate() {
+    return new _Money(-this.minor, this.currency);
+  }
   /**
    * Allocates (splits) this Money value according to a list of ratios.
-   * 
+   *
    * The sum of the parts will always equal the original amount.
    * Remainders are distributed to the parts with the largest fractional remainders.
-   * 
+   *
    * @param ratios - A list of numbers representing the ratios to split by.
    * @returns An array of Money instances.
    */
@@ -386,7 +544,7 @@ var Money = class _Money {
   }
   /**
    * Formats this Money value as a string.
-   * 
+   *
    * @param options - Formatting options.
    * @returns The formatted string.
    */
@@ -395,38 +553,106 @@ var Money = class _Money {
   }
   /**
    * 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) {
-    return this.currency.code === other.currency.code && this.minor === other.minor;
+    const otherMoney = this.resolveOther(other);
+    return this.currency.code === otherMoney.currency.code && this.minor === otherMoney.minor;
   }
   /**
    * 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) {
-    assertSameCurrency(this, other);
-    return this.minor > other.minor;
+    const otherMoney = this.resolveOther(other);
+    assertSameCurrency(this, otherMoney);
+    return this.minor > otherMoney.minor;
   }
   /**
    * 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) {
-    assertSameCurrency(this, other);
-    return this.minor < other.minor;
+    const otherMoney = this.resolveOther(other);
+    assertSameCurrency(this, otherMoney);
+    return this.minor < otherMoney.minor;
+  }
+  /**
+   * Checks if this Money value is greater than or equal to another.
+   */
+  greaterThanOrEqual(other) {
+    const otherMoney = this.resolveOther(other);
+    assertSameCurrency(this, otherMoney);
+    return this.minor >= otherMoney.minor;
+  }
+  /**
+   * Checks if this Money value is less than or equal to another.
+   */
+  lessThanOrEqual(other) {
+    const otherMoney = this.resolveOther(other);
+    assertSameCurrency(this, otherMoney);
+    return this.minor <= otherMoney.minor;
+  }
+  /**
+   * Checks if this Money value is positive (greater than zero).
+   */
+  isPositive() {
+    return this.minor > 0n;
+  }
+  /**
+   * Compares this Money to another, returning -1, 0, or 1.
+   * Useful for sorting.
+   */
+  compare(other) {
+    const otherMoney = this.resolveOther(other);
+    assertSameCurrency(this, otherMoney);
+    if (this.minor < otherMoney.minor) return -1;
+    if (this.minor > otherMoney.minor) return 1;
+    return 0;
+  }
+  /**
+   * 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, rounding = "HALF_EVEN" /* HALF_EVEN */) {
+    return this.multiply(percent / 100, { rounding });
+  }
+  /**
+   * Adds a percentage to the money.
+   * @param percent - The percentage to add.
+   * @param rounding - Rounding mode.
+   */
+  addPercent(percent, rounding = "HALF_EVEN" /* HALF_EVEN */) {
+    return this.add(this.percentage(percent, rounding));
+  }
+  /**
+   * Subtracts a percentage from the money.
+   * @param percent - The percentage to subtract.
+   * @param rounding - Rounding mode.
+   */
+  subtractPercent(percent, rounding = "HALF_EVEN" /* HALF_EVEN */) {
+    return this.subtract(this.percentage(percent, rounding));
+  }
+  /**
+   * Splits the money into equal parts.
+   * @param parts - Number of parts.
+   */
+  split(parts) {
+    const ratios = Array(parts).fill(1);
+    return this.allocate(ratios);
   }
   /**
    * Checks if this Money value is zero.
-   * 
+   *
    * @returns True if the amount is zero.
    */
   isZero() {
@@ -434,12 +660,149 @@ var Money = class _Money {
   }
   /**
    * Checks if this Money value is negative.
-   * 
+   *
    * @returns True if the amount is negative.
    */
   isNegative() {
     return this.minor < 0n;
   }
+  /**
+   * Returns a JSON representation of the Money object.
+   *
+   * @returns An object with amount (string), currency (code), and precision.
+   */
+  toJSON() {
+    return {
+      amount: this.minor.toString(),
+      currency: this.currency.code,
+      precision: this.currency.decimals
+    };
+  }
+  /**
+   * Returns a string representation of the Money object (formatted).
+   */
+  toString() {
+    return this.format();
+  }
+};
+
+// src/money/Converter.ts
+var Converter = class {
+  /**
+   * 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, rates) {
+    this.base = base;
+    this.rates = { ...rates };
+    if (this.rates[base] === void 0) {
+      this.rates[base] = 1;
+    }
+  }
+  /**
+   * 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(money2, toCurrency) {
+    const targetCurrency = typeof toCurrency === "string" ? getCurrency(toCurrency) : toCurrency;
+    if (money2.currency.code === targetCurrency.code) {
+      return money2;
+    }
+    const fromRate = this.rates[money2.currency.code];
+    const toRate = this.rates[targetCurrency.code];
+    if (fromRate === void 0 || toRate === void 0) {
+      throw new Error(
+        `Exchange rate missing for conversion from ${money2.currency.code} to ${targetCurrency.code}`
+      );
+    }
+    const ratio = toRate / fromRate;
+    const decimalAdjustment = 10 ** (targetCurrency.decimals - money2.currency.decimals);
+    const multiplier = ratio * decimalAdjustment;
+    const convertedAmount = money2.multiply(multiplier, {
+      rounding: "HALF_EVEN" /* HALF_EVEN */
+    });
+    return Money.fromMinor(convertedAmount.minor, targetCurrency);
+  }
+};
+
+// src/money/MoneyBag.ts
+var MoneyBag = class {
+  constructor() {
+    this.contents = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Adds a Money amount to the bag.
+   * @param money The money to add.
+   */
+  add(money2) {
+    const code = money2.currency.code;
+    const existing = this.contents.get(code);
+    if (existing) {
+      this.contents.set(code, existing.add(money2));
+    } else {
+      this.contents.set(code, money2);
+    }
+  }
+  /**
+   * Subtracts a Money amount from the bag.
+   * @param money The money to subtract.
+   */
+  subtract(money2) {
+    const code = money2.currency.code;
+    const existing = this.contents.get(code);
+    if (existing) {
+      this.contents.set(code, existing.subtract(money2));
+    } else {
+      const zero = Money.zero(money2.currency);
+      this.contents.set(code, zero.subtract(money2));
+    }
+  }
+  /**
+   * 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) {
+    const code = typeof currency === "string" ? currency : currency.code;
+    return this.contents.get(code) || Money.zero(
+      typeof currency === "string" ? getCurrency(currency) : currency
+    );
+  }
+  /**
+   * 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, converter) {
+    const target = typeof targetCurrency === "string" ? getCurrency(targetCurrency) : targetCurrency;
+    let total = Money.zero(target);
+    for (const money2 of this.contents.values()) {
+      const converted = converter.convert(money2, target);
+      total = total.add(converted);
+    }
+    return total;
+  }
+  /**
+   * Returns a list of all Money objects in the bag.
+   */
+  getAll() {
+    return Array.from(this.contents.values());
+  }
+  /**
+   * Returns a JSON representation of the bag.
+   */
+  toJSON() {
+    return this.getAll().map((m) => m.toJSON());
+  }
 };
 
 // src/currency/iso4217.ts
@@ -449,6 +812,7 @@ var USD = {
   symbol: "$",
   locale: "en-US"
 };
+registerCurrency(USD);
 var EUR = {
   code: "EUR",
   decimals: 2,
@@ -456,24 +820,28 @@ var EUR = {
   locale: "de-DE"
   // Default locale, can be overridden
 };
+registerCurrency(EUR);
 var GBP = {
   code: "GBP",
   decimals: 2,
   symbol: "\xA3",
   locale: "en-GB"
 };
+registerCurrency(GBP);
 var JPY = {
   code: "JPY",
   decimals: 0,
   symbol: "\xA5",
   locale: "ja-JP"
 };
+registerCurrency(JPY);
 var ZAR = {
   code: "ZAR",
   decimals: 2,
   symbol: "R",
   locale: "en-ZA"
 };
+registerCurrency(ZAR);
 var CURRENCIES = {
   USD,
   EUR,
@@ -481,21 +849,23 @@ var CURRENCIES = {
   JPY,
   ZAR
 };
-function getCurrency(code) {
-  const currency = CURRENCIES[code.toUpperCase()];
-  if (!currency) {
-    throw new Error(`Unknown currency code: ${code}`);
-  }
-  return currency;
-}
 
 // src/currency/precision.ts
 function getMinorUnitExponent(currency) {
   return 10n ** BigInt(currency.decimals);
 }
+
+// src/index.ts
+function money(amount, currency) {
+  if (typeof amount === "string") {
+    return Money.fromMajor(amount, currency);
+  }
+  return Money.fromMinor(amount, currency);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CURRENCIES,
+  Converter,
   CurrencyMismatchError,
   EUR,
   GBP,
@@ -504,13 +874,19 @@ function getMinorUnitExponent(currency) {
   JPY,
   MonetraError,
   Money,
+  MoneyBag,
   OverflowError,
   RoundingMode,
   RoundingRequiredError,
   USD,
   ZAR,
+  assertNonNegative,
+  assertSameCurrency,
   divideWithRounding,
   getCurrency,
-  getMinorUnitExponent
+  getMinorUnitExponent,
+  isCurrencyRegistered,
+  money,
+  registerCurrency
 });
 //# sourceMappingURL=index.js.map