Quaney

Usage

Few examples:

import { Money, $ } from 'quaney'
// Money = $; $ is just an alias for the Money class

const amount1 = $(42, 'USD')
const amount2 = amount1.add(10) // returns a new Money class instance with amount = 52 and currency = USD
const amount3 = amount1.sub(2, 'USD') // return a new Money class instance with amunt = 44 and currency = USD
amount1.format() // returns a string: $42
amount1.format({ symbol: false }) // returns a string without the symbol: 42

Reference

The Money class is a JavaScript/TypeScript class designed for handling monetary values. It provides various methods for performing arithmetic operations, formatting, and currency conversion. Below is the documentation for the Money class:

Class: Money

Constructor

constructor(amount: MoneyAmount, currency: string, precision?: number)

• Parameters:

  • amount (MoneyAmount): The amount of money, which can be a number, string, bigint, or BigInt.
  • currency (string): The currency code (e.g., 'USD', 'EUR').
  • precision (optional, number): The precision (number of decimal places) for the money amount. Defaults to 0.

• Throws:

  • Error if the precision is a negative number or if the currency is not a valid string.

Methods

add

add(addends: Array<number | string | Money>): Money
add(...addends: Array<number | string | Money>): Money
add(...addends: Array<number | string | Money>[]): Money

• Parameters:

  • addends (array or variadic): An array or variadic list of values to add to the current Money instance.

• Returns:

  • A new Money instance representing the sum of the current instance and the provided addends.

• Throws:

  • TypeError if the provided addends have different currencies.

sub

sub(subtractors: Array<number | string | Money>): Money
sub(...subtractors: Array<number | string | Money>): Money
sub(...subtractors: Array<number | string | Money>[]): Money

• Parameters:

  • subtractors (array or variadic): An array or variadic list of values to subtract from the current Money instance.

• Returns:

  • A new Money instance representing the result of subtracting the provided subtractors from the current instance.

• Throws:

  • TypeError if the provided subtractors have different currencies.

mul

mul(scalar: number | string | bigint): Money

• Parameters:

  • scalar (number | string | bigint): The scalar value to multiply the current Money instance by.

• Returns:

  • A new Money instance representing the result of multiplying the current instance by the provided scalar.

div

div(scalar: number | string | bigint): Money

• Parameters:

  • scalar (number | string | bigint): The scalar value to divide the current Money instance by.

• Returns:

  • A new Money instance representing the result of dividing the current instance by the provided scalar.

round

round(precision: number, roundType: RoundType = 'HALF_AWAY_FROM_ZERO'): Money

• Parameters:

  • precision (number): The precision (number of decimal places) to round the Money instance to.
  • roundType (optional, enum 'HALF_AWAY_FROM_ZERO'): The rounding method to use. Defaults to 'HALF_AWAY_FROM_ZERO'.

• Returns:

  • A new Money instance representing the rounded value.

compare

compare(money2: number | string | Money): -1 | 0 | 1

• Parameters:

  • money2 (number | string | Money): The value to compare to the current Money instance.

• Returns:

  • -1 if the current instance is less than money2.
  • 0 if the current instance is equal to money2.
  • 1 if the current instance is greater than money2.

• Throws:

  • TypeError if the currencies of the two Money instances are different.

Comparison Methods

The following methods return a boolean value indicating the result of the respective comparison operation:

• lesserThan(rightHandSide: number | string | Money): boolean
• lesserThanOrEqual(rightHandSide: number | string | Money): boolean
• equal(rightHandSide: number | string | Money): boolean
• notEqual(rightHandSide: number | string | Money): boolean
• greaterThan(rightHandSide: number | string | Money): boolean
• greaterThanOrEqual(rightHandSide: number | string | Money): boolean

clone

clone(): Money

• Returns:
  • A new Money instance that is a copy of the current instance.

format

format(params: { precision?: number; symbol?: boolean; commas?: boolean; commaSeparated?: boolean } = {}): string

• Parameters:

  • params (optional, object): Formatting options.
    • precision (optional, number): The precision (number of decimal places) for formatting. Defaults to the precision of the Money instance.
    • symbol (optional, boolean): Whether to include the currency symbol. Defaults to false.
    • commas (optional, boolean): Whether to use commas as thousands separators. Defaults to false.
    • commaSeparated (optional, boolean): Whether to use a comma as the decimal separator. Defaults to false.

• Returns:

  • A string representing the formatted Money amount.

toString

toString(): string

• Returns:
  • A string representation of the Money instance, without currency symbol and commas.

toJSON

toJSON(): string

• Returns:
  • A JSON-serializable representation of the Money instance, without currency symbol and commas.

Static Methods

setGlobalConversionRateFetcher

static setGlobalConversionRateFetcher(conversionRateFetcher: ConversionRateFetcher | null)

• Parameters:
  • conversionRateFetcher (ConversionRateFetcher | null): A function for fetching conversion rates or null to unset the global fetcher.

convert

static async convert(money: Money, targetCurrency: string, conversionRateFetcher?: ConversionRateFetcher): Promise<Money>

• Parameters:

  • money (Money): The Money instance to convert.
  • targetCurrency (string): The target currency code to convert to.
  • conversionRateFetcher (optional, ConversionRateFetcher): A function for fetching conversion rates.

• Returns:

  • A new Money instance representing the converted amount in the target currency.

• Throws:

  • Error if targetCurrency is not a valid string or if a conversion rate fetcher is not provided.

exchange

static async exchange(money: Money, currency: string): Promise<Money>

• Parameters:

  • money (Money): The Money instance to exchange.
  • currency (string): The target currency code to exchange to.

• Returns:

  • A new Money instance representing the exchanged amount in the specified currency.

getExchangeRate

static async getExchangeRate(fromCurrency: string, toCurrency: string, conversionRateFetcher?: ConversionRateFetcher): Promise

License

MIT