monetra 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,250 @@
+/**
+ * Represents a currency with its metadata.
+ *
+ * This interface defines the structure for currency objects used throughout the library.
+ * It includes the ISO 4217 code, the number of decimal places (precision),
+ * the currency symbol, and an optional default locale for formatting.
+ */
+interface Currency {
+    /**
+     * The ISO 4217 currency code (e.g., "USD", "EUR", "ZAR").
+     */
+    code: string;
+    /**
+     * The number of decimal places for the currency.
+     * This defines the precision of the currency (e.g., 2 for USD, 0 for JPY).
+     */
+    decimals: number;
+    /**
+     * The symbol associated with the currency (e.g., "$", "€", "R").
+     */
+    symbol: string;
+    /**
+     * The default locale to use when formatting amounts in this currency (e.g., "en-US").
+     * If not provided, the formatter may fall back to a default or user-provided locale.
+     */
+    locale?: string;
+}
+
+/**
+ * Enumeration of rounding modes for handling fractional minor units.
+ */
+declare enum RoundingMode {
+    /**
+     * Rounds towards the nearest neighbor. If equidistant, rounds away from zero.
+     * Example: 2.5 -> 3, -2.5 -> -3
+     */
+    HALF_UP = "HALF_UP",
+    /**
+     * Rounds towards the nearest neighbor. If equidistant, rounds towards zero.
+     * Example: 2.5 -> 2, -2.5 -> -2
+     */
+    HALF_DOWN = "HALF_DOWN",
+    /**
+     * Rounds towards the nearest neighbor. If equidistant, rounds towards the nearest even integer.
+     * Also known as Banker's Rounding.
+     * Example: 2.5 -> 2, 3.5 -> 4
+     */
+    HALF_EVEN = "HALF_EVEN",
+    /**
+     * Rounds towards negative infinity.
+     * Example: 2.9 -> 2, -2.1 -> -3
+     */
+    FLOOR = "FLOOR",
+    /**
+     * Rounds towards positive infinity.
+     * Example: 2.1 -> 3, -2.9 -> -2
+     */
+    CEIL = "CEIL"
+}
+
+/**
+ * Represents a monetary value in a specific currency.
+ *
+ * Money objects are immutable and store values in minor units (e.g., cents) using BigInt
+ * to avoid floating-point precision errors.
+ */
+declare class Money {
+    /**
+     * The amount in minor units (e.g., cents).
+     */
+    readonly minor: bigint;
+    /**
+     * The currency of this money value.
+     */
+    readonly currency: Currency;
+    private constructor();
+    /**
+     * 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.
+     * @returns A new Money instance.
+     * @example
+     * const m = Money.fromMinor(100, USD); // $1.00
+     */
+    static fromMinor(minor: bigint | number, currency: Currency): 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.
+     * @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;
+    /**
+     * 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;
+    /**
+     * Adds another Money value to this one.
+     *
+     * @param other - The Money value to add.
+     * @returns A new Money instance representing the sum.
+     * @throws {CurrencyMismatchError} If the currencies do not match.
+     */
+    add(other: Money): Money;
+    /**
+     * Subtracts another Money value from this one.
+     *
+     * @param other - The Money value to subtract.
+     * @returns A new Money instance representing the difference.
+     * @throws {CurrencyMismatchError} If the currencies do not match.
+     */
+    subtract(other: Money): Money;
+    /**
+     * 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.
+     * @throws {RoundingRequiredError} If the result is fractional and no rounding mode is provided.
+     */
+    multiply(multiplier: string | number, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    /**
+     * 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.
+     */
+    allocate(ratios: number[]): Money[];
+    /**
+     * Formats this Money value as a string.
+     *
+     * @param options - Formatting options.
+     * @returns The formatted string.
+     */
+    format(options?: {
+        locale?: string;
+        symbol?: boolean;
+    }): string;
+    /**
+     * Checks if this Money value is equal to another.
+     *
+     * @param other - The other Money value.
+     * @returns True if amounts and currencies are equal.
+     */
+    equals(other: Money): boolean;
+    /**
+     * Checks if this Money value is greater than another.
+     *
+     * @param other - The other Money value.
+     * @returns True if this value is greater.
+     * @throws {CurrencyMismatchError} If the currencies do not match.
+     */
+    greaterThan(other: Money): boolean;
+    /**
+     * Checks if this Money value is less than another.
+     *
+     * @param other - The other Money value.
+     * @returns True if this value is less.
+     * @throws {CurrencyMismatchError} If the currencies do not match.
+     */
+    lessThan(other: Money): boolean;
+    /**
+     * Checks if this Money value is zero.
+     *
+     * @returns True if the amount is zero.
+     */
+    isZero(): boolean;
+    /**
+     * Checks if this Money value is negative.
+     *
+     * @returns True if the amount is negative.
+     */
+    isNegative(): boolean;
+}
+
+/**
+ * United States Dollar (USD).
+ */
+declare const USD: Currency;
+/**
+ * Euro (EUR).
+ */
+declare const EUR: Currency;
+/**
+ * British Pound Sterling (GBP).
+ */
+declare const GBP: Currency;
+/**
+ * Japanese Yen (JPY).
+ */
+declare const JPY: Currency;
+/**
+ * South African Rand (ZAR).
+ */
+declare const ZAR: Currency;
+/**
+ * A collection of common currencies.
+ */
+declare const CURRENCIES: Record<string, Currency>;
+/**
+ * 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.
+ */
+declare function getCurrency(code: string): Currency;
+
+declare function getMinorUnitExponent(currency: Currency): bigint;
+
+declare function divideWithRounding(numerator: bigint, denominator: bigint, mode: RoundingMode): bigint;
+
+declare class MonetraError extends Error {
+    constructor(message: string);
+}
+
+declare class CurrencyMismatchError extends MonetraError {
+    constructor(expected: string, actual: string);
+}
+
+declare class InvalidPrecisionError extends MonetraError {
+    constructor(message: string);
+}
+
+declare class RoundingRequiredError extends MonetraError {
+    constructor();
+}
+
+declare class InsufficientFundsError extends MonetraError {
+    constructor();
+}
+
+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 };

package/dist/index.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Represents a currency with its metadata.
+ *
+ * This interface defines the structure for currency objects used throughout the library.
+ * It includes the ISO 4217 code, the number of decimal places (precision),
+ * the currency symbol, and an optional default locale for formatting.
+ */
+interface Currency {
+    /**
+     * The ISO 4217 currency code (e.g., "USD", "EUR", "ZAR").
+     */
+    code: string;
+    /**
+     * The number of decimal places for the currency.
+     * This defines the precision of the currency (e.g., 2 for USD, 0 for JPY).
+     */
+    decimals: number;
+    /**
+     * The symbol associated with the currency (e.g., "$", "€", "R").
+     */
+    symbol: string;
+    /**
+     * The default locale to use when formatting amounts in this currency (e.g., "en-US").
+     * If not provided, the formatter may fall back to a default or user-provided locale.
+     */
+    locale?: string;
+}
+
+/**
+ * Enumeration of rounding modes for handling fractional minor units.
+ */
+declare enum RoundingMode {
+    /**
+     * Rounds towards the nearest neighbor. If equidistant, rounds away from zero.
+     * Example: 2.5 -> 3, -2.5 -> -3
+     */
+    HALF_UP = "HALF_UP",
+    /**
+     * Rounds towards the nearest neighbor. If equidistant, rounds towards zero.
+     * Example: 2.5 -> 2, -2.5 -> -2
+     */
+    HALF_DOWN = "HALF_DOWN",
+    /**
+     * Rounds towards the nearest neighbor. If equidistant, rounds towards the nearest even integer.
+     * Also known as Banker's Rounding.
+     * Example: 2.5 -> 2, 3.5 -> 4
+     */
+    HALF_EVEN = "HALF_EVEN",
+    /**
+     * Rounds towards negative infinity.
+     * Example: 2.9 -> 2, -2.1 -> -3
+     */
+    FLOOR = "FLOOR",
+    /**
+     * Rounds towards positive infinity.
+     * Example: 2.1 -> 3, -2.9 -> -2
+     */
+    CEIL = "CEIL"
+}
+
+/**
+ * Represents a monetary value in a specific currency.
+ *
+ * Money objects are immutable and store values in minor units (e.g., cents) using BigInt
+ * to avoid floating-point precision errors.
+ */
+declare class Money {
+    /**
+     * The amount in minor units (e.g., cents).
+     */
+    readonly minor: bigint;
+    /**
+     * The currency of this money value.
+     */
+    readonly currency: Currency;
+    private constructor();
+    /**
+     * 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.
+     * @returns A new Money instance.
+     * @example
+     * const m = Money.fromMinor(100, USD); // $1.00
+     */
+    static fromMinor(minor: bigint | number, currency: Currency): 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.
+     * @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;
+    /**
+     * 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;
+    /**
+     * Adds another Money value to this one.
+     *
+     * @param other - The Money value to add.
+     * @returns A new Money instance representing the sum.
+     * @throws {CurrencyMismatchError} If the currencies do not match.
+     */
+    add(other: Money): Money;
+    /**
+     * Subtracts another Money value from this one.
+     *
+     * @param other - The Money value to subtract.
+     * @returns A new Money instance representing the difference.
+     * @throws {CurrencyMismatchError} If the currencies do not match.
+     */
+    subtract(other: Money): Money;
+    /**
+     * 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.
+     * @throws {RoundingRequiredError} If the result is fractional and no rounding mode is provided.
+     */
+    multiply(multiplier: string | number, options?: {
+        rounding?: RoundingMode;
+    }): Money;
+    /**
+     * 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.
+     */
+    allocate(ratios: number[]): Money[];
+    /**
+     * Formats this Money value as a string.
+     *
+     * @param options - Formatting options.
+     * @returns The formatted string.
+     */
+    format(options?: {
+        locale?: string;
+        symbol?: boolean;
+    }): string;
+    /**
+     * Checks if this Money value is equal to another.
+     *
+     * @param other - The other Money value.
+     * @returns True if amounts and currencies are equal.
+     */
+    equals(other: Money): boolean;
+    /**
+     * Checks if this Money value is greater than another.
+     *
+     * @param other - The other Money value.
+     * @returns True if this value is greater.
+     * @throws {CurrencyMismatchError} If the currencies do not match.
+     */
+    greaterThan(other: Money): boolean;
+    /**
+     * Checks if this Money value is less than another.
+     *
+     * @param other - The other Money value.
+     * @returns True if this value is less.
+     * @throws {CurrencyMismatchError} If the currencies do not match.
+     */
+    lessThan(other: Money): boolean;
+    /**
+     * Checks if this Money value is zero.
+     *
+     * @returns True if the amount is zero.
+     */
+    isZero(): boolean;
+    /**
+     * Checks if this Money value is negative.
+     *
+     * @returns True if the amount is negative.
+     */
+    isNegative(): boolean;
+}
+
+/**
+ * United States Dollar (USD).
+ */
+declare const USD: Currency;
+/**
+ * Euro (EUR).
+ */
+declare const EUR: Currency;
+/**
+ * British Pound Sterling (GBP).
+ */
+declare const GBP: Currency;
+/**
+ * Japanese Yen (JPY).
+ */
+declare const JPY: Currency;
+/**
+ * South African Rand (ZAR).
+ */
+declare const ZAR: Currency;
+/**
+ * A collection of common currencies.
+ */
+declare const CURRENCIES: Record<string, Currency>;
+/**
+ * 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.
+ */
+declare function getCurrency(code: string): Currency;
+
+declare function getMinorUnitExponent(currency: Currency): bigint;
+
+declare function divideWithRounding(numerator: bigint, denominator: bigint, mode: RoundingMode): bigint;
+
+declare class MonetraError extends Error {
+    constructor(message: string);
+}
+
+declare class CurrencyMismatchError extends MonetraError {
+    constructor(expected: string, actual: string);
+}
+
+declare class InvalidPrecisionError extends MonetraError {
+    constructor(message: string);
+}
+
+declare class RoundingRequiredError extends MonetraError {
+    constructor();
+}
+
+declare class InsufficientFundsError extends MonetraError {
+    constructor();
+}
+
+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 };