import { type ISO4217Code } from "./money.js"; /** * Serializable representation of a MoneyPrimitive. * Used for persistence drivers and JSON round-trips. */ export interface MoneyJSON { amount: number; currencyCode: string; scale: number; } /** * Immutable Value Object that encapsulates a monetary amount, its currency, * and the scale (number of decimal places). * * Amounts are always stored in minor units (e.g., cents for USD, centavos for MXN). * The scale is derived from the currency's exponent in CURRENCY_MAP. * * @example * ```ts * const price = MoneyPrimitive.fromMajor(12.99, "USD"); * price.minor; // 1299 * price.major; // 12.99 * price.format("en-US"); // "$12.99" * * const json = price.toJSON(); * const restored = MoneyPrimitive.fromJSON(json); * ``` */ export declare class MoneyPrimitive { /** Raw amount in minor units (e.g., cents). */ readonly amount: number; /** ISO 4217 currency code. */ readonly currencyCode: string; /** Number of decimal places for this currency (e.g., 2 for USD, 0 for JPY). */ readonly scale: number; private constructor(); /** * Create a MoneyPrimitive from a minor-unit integer amount. * @param amount - Amount in minor units (e.g., 1299 for $12.99) * @param currencyCode - ISO 4217 currency code */ static fromMinor( amount: number, currencyCode: ISO4217Code | string, ): MoneyPrimitive; /** * Create a MoneyPrimitive from a major-unit float amount. * @param amount - Amount in major units (e.g., 12.99 for $12.99) * @param currencyCode - ISO 4217 currency code */ static fromMajor( amount: number, currencyCode: ISO4217Code | string, ): MoneyPrimitive; /** * Restore a MoneyPrimitive from its JSON representation. */ static fromJSON(json: MoneyJSON): MoneyPrimitive; /** Amount in minor units (alias for `amount`). */ get minor(): number; /** Amount in major units (e.g., 12.99 for 1299 cents). */ get major(): number; /** * Format this monetary value as a locale-aware currency string. * @param locale - BCP 47 locale string (default: "en-US") */ format(locale?: string): string; /** * Add another MoneyPrimitive (must be same currency). * Returns a new MoneyPrimitive. */ add(other: MoneyPrimitive): MoneyPrimitive; /** * Subtract another MoneyPrimitive (must be same currency). * Returns a new MoneyPrimitive. */ subtract(other: MoneyPrimitive): MoneyPrimitive; /** * Multiply by a scalar factor. Returns a new MoneyPrimitive. */ multiply(factor: number): MoneyPrimitive; /** * Value equality — two MoneyPrimitives are equal if they have the same * amount, currency code, and scale. */ equals(other: MoneyPrimitive): boolean; /** * Returns true if this amount is zero. */ isZero(): boolean; /** * Returns true if this amount is negative. */ isNegative(): boolean; /** * Serialize to a plain JSON-compatible object. */ toJSON(): MoneyJSON; toString(): string; private assertSameCurrency; /** * Resolves the scale (exponent) for a currency code from CURRENCY_MAP. * Throws if the currency is not registered. */ private static resolveScale; }