@puvaanraaj/moneta 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,283 @@
+/**
+ * ISO 4217 currency definitions.
+ * Each entry contains the decimal precision used for minor-unit storage.
+ */
+declare const CURRENCIES: {
+    readonly AED: {
+        readonly code: "AED";
+        readonly decimals: 2;
+        readonly name: "UAE Dirham";
+    };
+    readonly AUD: {
+        readonly code: "AUD";
+        readonly decimals: 2;
+        readonly name: "Australian Dollar";
+    };
+    readonly BRL: {
+        readonly code: "BRL";
+        readonly decimals: 2;
+        readonly name: "Brazilian Real";
+    };
+    readonly CAD: {
+        readonly code: "CAD";
+        readonly decimals: 2;
+        readonly name: "Canadian Dollar";
+    };
+    readonly CHF: {
+        readonly code: "CHF";
+        readonly decimals: 2;
+        readonly name: "Swiss Franc";
+    };
+    readonly CNY: {
+        readonly code: "CNY";
+        readonly decimals: 2;
+        readonly name: "Chinese Yuan";
+    };
+    readonly CZK: {
+        readonly code: "CZK";
+        readonly decimals: 2;
+        readonly name: "Czech Koruna";
+    };
+    readonly DKK: {
+        readonly code: "DKK";
+        readonly decimals: 2;
+        readonly name: "Danish Krone";
+    };
+    readonly EUR: {
+        readonly code: "EUR";
+        readonly decimals: 2;
+        readonly name: "Euro";
+    };
+    readonly GBP: {
+        readonly code: "GBP";
+        readonly decimals: 2;
+        readonly name: "British Pound";
+    };
+    readonly HKD: {
+        readonly code: "HKD";
+        readonly decimals: 2;
+        readonly name: "Hong Kong Dollar";
+    };
+    readonly HUF: {
+        readonly code: "HUF";
+        readonly decimals: 2;
+        readonly name: "Hungarian Forint";
+    };
+    readonly IDR: {
+        readonly code: "IDR";
+        readonly decimals: 2;
+        readonly name: "Indonesian Rupiah";
+    };
+    readonly ILS: {
+        readonly code: "ILS";
+        readonly decimals: 2;
+        readonly name: "Israeli New Shekel";
+    };
+    readonly INR: {
+        readonly code: "INR";
+        readonly decimals: 2;
+        readonly name: "Indian Rupee";
+    };
+    readonly JPY: {
+        readonly code: "JPY";
+        readonly decimals: 0;
+        readonly name: "Japanese Yen";
+    };
+    readonly KRW: {
+        readonly code: "KRW";
+        readonly decimals: 0;
+        readonly name: "South Korean Won";
+    };
+    readonly KWD: {
+        readonly code: "KWD";
+        readonly decimals: 3;
+        readonly name: "Kuwaiti Dinar";
+    };
+    readonly MXN: {
+        readonly code: "MXN";
+        readonly decimals: 2;
+        readonly name: "Mexican Peso";
+    };
+    readonly MYR: {
+        readonly code: "MYR";
+        readonly decimals: 2;
+        readonly name: "Malaysian Ringgit";
+    };
+    readonly NOK: {
+        readonly code: "NOK";
+        readonly decimals: 2;
+        readonly name: "Norwegian Krone";
+    };
+    readonly NZD: {
+        readonly code: "NZD";
+        readonly decimals: 2;
+        readonly name: "New Zealand Dollar";
+    };
+    readonly PHP: {
+        readonly code: "PHP";
+        readonly decimals: 2;
+        readonly name: "Philippine Peso";
+    };
+    readonly PLN: {
+        readonly code: "PLN";
+        readonly decimals: 2;
+        readonly name: "Polish Zloty";
+    };
+    readonly RON: {
+        readonly code: "RON";
+        readonly decimals: 2;
+        readonly name: "Romanian Leu";
+    };
+    readonly SAR: {
+        readonly code: "SAR";
+        readonly decimals: 2;
+        readonly name: "Saudi Riyal";
+    };
+    readonly SEK: {
+        readonly code: "SEK";
+        readonly decimals: 2;
+        readonly name: "Swedish Krona";
+    };
+    readonly SGD: {
+        readonly code: "SGD";
+        readonly decimals: 2;
+        readonly name: "Singapore Dollar";
+    };
+    readonly THB: {
+        readonly code: "THB";
+        readonly decimals: 2;
+        readonly name: "Thai Baht";
+    };
+    readonly TRY: {
+        readonly code: "TRY";
+        readonly decimals: 2;
+        readonly name: "Turkish Lira";
+    };
+    readonly TWD: {
+        readonly code: "TWD";
+        readonly decimals: 2;
+        readonly name: "New Taiwan Dollar";
+    };
+    readonly USD: {
+        readonly code: "USD";
+        readonly decimals: 2;
+        readonly name: "US Dollar";
+    };
+    readonly VND: {
+        readonly code: "VND";
+        readonly decimals: 0;
+        readonly name: "Vietnamese Dong";
+    };
+    readonly ZAR: {
+        readonly code: "ZAR";
+        readonly decimals: 2;
+        readonly name: "South African Rand";
+    };
+};
+type CurrencyCode = keyof typeof CURRENCIES;
+type CurrencyDef = (typeof CURRENCIES)[CurrencyCode];
+
+/**
+ * Immutable, BigInt-precision monetary value.
+ *
+ * The generic parameter `C` brands the currency at the type level so
+ * cross-currency arithmetic is a **compile-time error**.
+ *
+ * @example
+ * const price = money('19.99', 'USD')
+ * const tax   = money('1.60',  'USD')
+ * price.add(tax).format()       // "$21.59"
+ * price.add(money('5', 'EUR'))  // TypeError: currency mismatch
+ */
+declare class Money<C extends CurrencyCode = CurrencyCode> {
+    #private;
+    constructor(amount: string | number | bigint, currency: C);
+    /** Create from raw minor units (e.g. cents). Useful when reading from a database. */
+    static fromMinorUnits<C extends CurrencyCode>(units: bigint, currency: C): Money<C>;
+    /** Raw amount in minor units (e.g. cents). Safe for storage and wire transfer. */
+    get minorUnits(): bigint;
+    get currency(): C;
+    /** Human-readable decimal string, e.g. "19.99". */
+    get decimalValue(): string;
+    add(other: Money<C>): Money<C>;
+    subtract(other: Money<C>): Money<C>;
+    /**
+     * Multiply by a scalar. Uses half-up rounding to the currency's minor unit.
+     * @example money('10.00', 'USD').multiply(1.1)  // $11.00
+     * @example money('10.00', 'USD').multiply('1.5') // $15.00
+     */
+    multiply(factor: number | string): Money<C>;
+    /**
+     * Divide by a scalar. Uses half-up rounding to the currency's minor unit.
+     * @example money('10.00', 'USD').divide(3)  // $3.33
+     */
+    divide(divisor: number | string): Money<C>;
+    /**
+     * Allocate proportionally. The sum of all parts always equals the original —
+     * any rounding remainder is distributed to the first buckets.
+     *
+     * @example
+     * money('10.00', 'USD').allocate([1, 1, 1])
+     * // [Money('3.34'), Money('3.33'), Money('3.33')]
+     */
+    allocate(ratios: readonly number[]): Money<C>[];
+    equals(other: Money<C>): boolean;
+    greaterThan(other: Money<C>): boolean;
+    lessThan(other: Money<C>): boolean;
+    greaterThanOrEqual(other: Money<C>): boolean;
+    lessThanOrEqual(other: Money<C>): boolean;
+    isZero(): boolean;
+    isPositive(): boolean;
+    isNegative(): boolean;
+    abs(): Money<C>;
+    negate(): Money<C>;
+    /**
+     * Format using the platform's `Intl.NumberFormat` — no custom format strings.
+     *
+     * @example
+     * money('19.99', 'USD').format()        // "$19.99"
+     * money('19.99', 'EUR').format('de-DE') // "19,99 €"
+     */
+    format(locale?: string): string;
+    /** Safe to store in JSON — no float representation. */
+    toJSON(): {
+        amount: string;
+        currency: C;
+        minorUnits: string;
+    };
+    toString(): string;
+}
+
+declare class MonetaError extends Error {
+    constructor(message: string);
+}
+declare class CurrencyMismatchError extends MonetaError {
+    readonly expected: string;
+    readonly received: string;
+    constructor(expected: string, received: string);
+}
+declare class InvalidAmountError extends MonetaError {
+    readonly input: unknown;
+    constructor(input: unknown);
+}
+declare class DivisionByZeroError extends MonetaError {
+    constructor();
+}
+declare class UnknownCurrencyError extends MonetaError {
+    readonly currency: string;
+    constructor(currency: string);
+}
+
+/**
+ * Create a Money value. This is the primary entry point.
+ *
+ * @example
+ * import { money } from 'moneta'
+ *
+ * const price = money('19.99', 'USD')
+ * const tax   = money('1.60',  'USD')
+ * price.add(tax).format()  // "$21.59"
+ */
+declare function money<C extends CurrencyCode>(amount: string | number | bigint, currency: C): Money<C>;
+
+export { CURRENCIES, type CurrencyCode, type CurrencyDef, CurrencyMismatchError, DivisionByZeroError, InvalidAmountError, MonetaError, Money, UnknownCurrencyError, money };

package/dist/index.d.ts

@@ -0,0 +1,283 @@
+/**
+ * ISO 4217 currency definitions.
+ * Each entry contains the decimal precision used for minor-unit storage.
+ */
+declare const CURRENCIES: {
+    readonly AED: {
+        readonly code: "AED";
+        readonly decimals: 2;
+        readonly name: "UAE Dirham";
+    };
+    readonly AUD: {
+        readonly code: "AUD";
+        readonly decimals: 2;
+        readonly name: "Australian Dollar";
+    };
+    readonly BRL: {
+        readonly code: "BRL";
+        readonly decimals: 2;
+        readonly name: "Brazilian Real";
+    };
+    readonly CAD: {
+        readonly code: "CAD";
+        readonly decimals: 2;
+        readonly name: "Canadian Dollar";
+    };
+    readonly CHF: {
+        readonly code: "CHF";
+        readonly decimals: 2;
+        readonly name: "Swiss Franc";
+    };
+    readonly CNY: {
+        readonly code: "CNY";
+        readonly decimals: 2;
+        readonly name: "Chinese Yuan";
+    };
+    readonly CZK: {
+        readonly code: "CZK";
+        readonly decimals: 2;
+        readonly name: "Czech Koruna";
+    };
+    readonly DKK: {
+        readonly code: "DKK";
+        readonly decimals: 2;
+        readonly name: "Danish Krone";
+    };
+    readonly EUR: {
+        readonly code: "EUR";
+        readonly decimals: 2;
+        readonly name: "Euro";
+    };
+    readonly GBP: {
+        readonly code: "GBP";
+        readonly decimals: 2;
+        readonly name: "British Pound";
+    };
+    readonly HKD: {
+        readonly code: "HKD";
+        readonly decimals: 2;
+        readonly name: "Hong Kong Dollar";
+    };
+    readonly HUF: {
+        readonly code: "HUF";
+        readonly decimals: 2;
+        readonly name: "Hungarian Forint";
+    };
+    readonly IDR: {
+        readonly code: "IDR";
+        readonly decimals: 2;
+        readonly name: "Indonesian Rupiah";
+    };
+    readonly ILS: {
+        readonly code: "ILS";
+        readonly decimals: 2;
+        readonly name: "Israeli New Shekel";
+    };
+    readonly INR: {
+        readonly code: "INR";
+        readonly decimals: 2;
+        readonly name: "Indian Rupee";
+    };
+    readonly JPY: {
+        readonly code: "JPY";
+        readonly decimals: 0;
+        readonly name: "Japanese Yen";
+    };
+    readonly KRW: {
+        readonly code: "KRW";
+        readonly decimals: 0;
+        readonly name: "South Korean Won";
+    };
+    readonly KWD: {
+        readonly code: "KWD";
+        readonly decimals: 3;
+        readonly name: "Kuwaiti Dinar";
+    };
+    readonly MXN: {
+        readonly code: "MXN";
+        readonly decimals: 2;
+        readonly name: "Mexican Peso";
+    };
+    readonly MYR: {
+        readonly code: "MYR";
+        readonly decimals: 2;
+        readonly name: "Malaysian Ringgit";
+    };
+    readonly NOK: {
+        readonly code: "NOK";
+        readonly decimals: 2;
+        readonly name: "Norwegian Krone";
+    };
+    readonly NZD: {
+        readonly code: "NZD";
+        readonly decimals: 2;
+        readonly name: "New Zealand Dollar";
+    };
+    readonly PHP: {
+        readonly code: "PHP";
+        readonly decimals: 2;
+        readonly name: "Philippine Peso";
+    };
+    readonly PLN: {
+        readonly code: "PLN";
+        readonly decimals: 2;
+        readonly name: "Polish Zloty";
+    };
+    readonly RON: {
+        readonly code: "RON";
+        readonly decimals: 2;
+        readonly name: "Romanian Leu";
+    };
+    readonly SAR: {
+        readonly code: "SAR";
+        readonly decimals: 2;
+        readonly name: "Saudi Riyal";
+    };
+    readonly SEK: {
+        readonly code: "SEK";
+        readonly decimals: 2;
+        readonly name: "Swedish Krona";
+    };
+    readonly SGD: {
+        readonly code: "SGD";
+        readonly decimals: 2;
+        readonly name: "Singapore Dollar";
+    };
+    readonly THB: {
+        readonly code: "THB";
+        readonly decimals: 2;
+        readonly name: "Thai Baht";
+    };
+    readonly TRY: {
+        readonly code: "TRY";
+        readonly decimals: 2;
+        readonly name: "Turkish Lira";
+    };
+    readonly TWD: {
+        readonly code: "TWD";
+        readonly decimals: 2;
+        readonly name: "New Taiwan Dollar";
+    };
+    readonly USD: {
+        readonly code: "USD";
+        readonly decimals: 2;
+        readonly name: "US Dollar";
+    };
+    readonly VND: {
+        readonly code: "VND";
+        readonly decimals: 0;
+        readonly name: "Vietnamese Dong";
+    };
+    readonly ZAR: {
+        readonly code: "ZAR";
+        readonly decimals: 2;
+        readonly name: "South African Rand";
+    };
+};
+type CurrencyCode = keyof typeof CURRENCIES;
+type CurrencyDef = (typeof CURRENCIES)[CurrencyCode];
+
+/**
+ * Immutable, BigInt-precision monetary value.
+ *
+ * The generic parameter `C` brands the currency at the type level so
+ * cross-currency arithmetic is a **compile-time error**.
+ *
+ * @example
+ * const price = money('19.99', 'USD')
+ * const tax   = money('1.60',  'USD')
+ * price.add(tax).format()       // "$21.59"
+ * price.add(money('5', 'EUR'))  // TypeError: currency mismatch
+ */
+declare class Money<C extends CurrencyCode = CurrencyCode> {
+    #private;
+    constructor(amount: string | number | bigint, currency: C);
+    /** Create from raw minor units (e.g. cents). Useful when reading from a database. */
+    static fromMinorUnits<C extends CurrencyCode>(units: bigint, currency: C): Money<C>;
+    /** Raw amount in minor units (e.g. cents). Safe for storage and wire transfer. */
+    get minorUnits(): bigint;
+    get currency(): C;
+    /** Human-readable decimal string, e.g. "19.99". */
+    get decimalValue(): string;
+    add(other: Money<C>): Money<C>;
+    subtract(other: Money<C>): Money<C>;
+    /**
+     * Multiply by a scalar. Uses half-up rounding to the currency's minor unit.
+     * @example money('10.00', 'USD').multiply(1.1)  // $11.00
+     * @example money('10.00', 'USD').multiply('1.5') // $15.00
+     */
+    multiply(factor: number | string): Money<C>;
+    /**
+     * Divide by a scalar. Uses half-up rounding to the currency's minor unit.
+     * @example money('10.00', 'USD').divide(3)  // $3.33
+     */
+    divide(divisor: number | string): Money<C>;
+    /**
+     * Allocate proportionally. The sum of all parts always equals the original —
+     * any rounding remainder is distributed to the first buckets.
+     *
+     * @example
+     * money('10.00', 'USD').allocate([1, 1, 1])
+     * // [Money('3.34'), Money('3.33'), Money('3.33')]
+     */
+    allocate(ratios: readonly number[]): Money<C>[];
+    equals(other: Money<C>): boolean;
+    greaterThan(other: Money<C>): boolean;
+    lessThan(other: Money<C>): boolean;
+    greaterThanOrEqual(other: Money<C>): boolean;
+    lessThanOrEqual(other: Money<C>): boolean;
+    isZero(): boolean;
+    isPositive(): boolean;
+    isNegative(): boolean;
+    abs(): Money<C>;
+    negate(): Money<C>;
+    /**
+     * Format using the platform's `Intl.NumberFormat` — no custom format strings.
+     *
+     * @example
+     * money('19.99', 'USD').format()        // "$19.99"
+     * money('19.99', 'EUR').format('de-DE') // "19,99 €"
+     */
+    format(locale?: string): string;
+    /** Safe to store in JSON — no float representation. */
+    toJSON(): {
+        amount: string;
+        currency: C;
+        minorUnits: string;
+    };
+    toString(): string;
+}
+
+declare class MonetaError extends Error {
+    constructor(message: string);
+}
+declare class CurrencyMismatchError extends MonetaError {
+    readonly expected: string;
+    readonly received: string;
+    constructor(expected: string, received: string);
+}
+declare class InvalidAmountError extends MonetaError {
+    readonly input: unknown;
+    constructor(input: unknown);
+}
+declare class DivisionByZeroError extends MonetaError {
+    constructor();
+}
+declare class UnknownCurrencyError extends MonetaError {
+    readonly currency: string;
+    constructor(currency: string);
+}
+
+/**
+ * Create a Money value. This is the primary entry point.
+ *
+ * @example
+ * import { money } from 'moneta'
+ *
+ * const price = money('19.99', 'USD')
+ * const tax   = money('1.60',  'USD')
+ * price.add(tax).format()  // "$21.59"
+ */
+declare function money<C extends CurrencyCode>(amount: string | number | bigint, currency: C): Money<C>;
+
+export { CURRENCIES, type CurrencyCode, type CurrencyDef, CurrencyMismatchError, DivisionByZeroError, InvalidAmountError, MonetaError, Money, UnknownCurrencyError, money };