Back

Currency Master

A versatile npm package for currency operations, including arithmetic, formatting, number-to-word conversion, and mapping currencies to country codes.

Tech Stack :
Source Code
|
Live Demo
Currency Master
is a comprehensive TypeScript library that provides utilities for working with various currency-related tasks, such as formatting currency strings, converting amounts between different currencies, converting numerical values to words, and mapping country codes to their respective currency codes.

Table of Contents

Installation

To install the package, use npm:

Usage

You can use any of the four classes provided by Currency Master to perform various currency-related tasks.

Class

The
class provides a comprehensive set of utilities for handling currency values with various operations such as addition, subtraction, multiplication, division, formatting, and converting values to words. This class is designed to handle different currency formats and supports customizable settings.

Features

  • Arithmetic Operations: Add, subtract, multiply, and divide currency values.
  • Formatting: Convert currency values to formatted strings.
  • Distribution: Evenly distribute a currency value into parts.
  • Conversion to Words: Convert currency values to their word representation.
  • Customizable Settings: Configure symbol, decimal separator, precision, grouping, and more.

Constructor

Initializes a new instance of the
class.
  • : The initial value for the currency. It can be a number, string, or another
    instance.
  • : An optional configuration object to customize currency settings.
Example

Methods

Adds a specified amount to the currency value.
Example:
Subtracts a specified amount from the currency value.
Example:
Multiplies the currency value by a specified factor.
Example:
Divides the currency value by a specified divisor.
Example:
Distributes the currency value evenly into an array of
instances.
Example:
Returns the dollar portion of the currency value.
Example:
Returns the cent portion of the currency value.
Example:
Formats the currency value as a string according to the specified settings.
Example:
Converts the currency value to a string.
Example:
Converts the currency value into its word representation.
Default Behavior:
By default, the
method converts the currency amount to words using US dollars:
Customizing Currency Type:
You can customize the currency type and locale in the constructor by passing
options:
Support for Multiple Locales:
The
method supports various locales for diverse languages and regions:
Urdu (Pakistan):
Hindi (India):
The
method is highly versatile and supports various locales, enabling you to format numbers into words in different languages and regional formats.

Configuration

The
class supports various configuration options through the
type:
  • : Currency symbol (default:
    ).
  • : Thousands separator (default:
    ).
  • : Decimal separator (default:
    ).
  • : Whether to throw an error on invalid input (default:
    ).
  • : Number of decimal places (default:
    ).
  • : Format pattern for positive values (default:
    ).
  • : Format pattern for negative values (default:
    ).
  • : Whether the initial value is in cents (default:
    ).
  • : Regular expression for grouping digits (default:
    ).
  • : Function to format the currency object (default:
    ).
  • : Custom settings for currency to words (optional).

Example: Using Custom Currency Settings

In this example, we'll create a
instance with custom settings and perform various operations.

Custom Settings

Let's define custom settings for the
class:

Creating a Currency Instance with Custom Settings

Now we'll create a
instance using the custom settings and perform some operations:

ToWords

The
class provides methods to convert numerical values to their word representations.

Example

Options can be set at instance level, or along with individual call to
method.

Config Options

The
class suppose following custom options
  • (LocaleEnum, default:
    ):
    • Sets the locale for internationalization (i18n), determining the language and regional formatting for the words.
  • (boolean, default:
    ):
    • Indicates if the number should be converted into words formatted as currency.
    • When set to
      , the number will be rounded to two decimal places before conversion.
    • Includes currency symbols and adjusts pluralization of currency units.
  • (boolean, default:
    ):
    • Determines whether to disregard the fractional (decimal) part of the number during conversion.
    • When
      , only the integer part is converted to words, ignoring the decimal portion.
  • (boolean, default:
    ):
    • Specifies whether to omit zero value in the currency portion of the words.
    • When
      , zero currency units will not be included in the output, avoiding redundant mentions.
  • (boolean, default:
    ):
    • Controls whether to append the word "only" at the end of the converted currency words.
    • Works only when
      is
      . When
      , "only" is not included in the output.
  • (object, default:
    ):
    • Allows customization of currency options while retaining the language settings from the locale.
    • Useful for specifying different currencies (e.g., using EUR instead of USD) while converting to words in a specific language.
    • Supports dynamic currency changes for each conversion call, applicable only when
      is
      .

Supported Locales

CountryLanguageLocale
UAEEnglishen-AE
BangladeshEnglishen-BD
UKEnglishen-GB
GhanaEnglishen-GH
IrelandEnglishen-IE
IndiaEnglishen-IN
MyanmarEnglishen-MM
MauritiusEnglishen-MU
NigeriaEnglishen-NG
NepalEnglishen-NP
USAEnglishen-US (default)
PhilippinesEnglishen-PH
EstoniaEstonianee-EE
IranPersianfa-IR
BelgiumFrenchfr-BE
FranceFrenchfr-FR
IndiaGujaratigu-IN
IndiaHindihi-IN
IndiaMarathimr-IN
SurinameDutchnl-SR
BrazilPortuguesept-BR
TurkeyTurkishtr-TR
Korean, RepublicHangulko-KR
PakistanEnglishen-PK
PakistanUrduur-PK

CountryCurrencyCode

The
class provides utility methods to map country codes to their respective currency codes.

Example

CurrencyConversion

The
class provides methods for fetching real-time or historical exchange rates and converting currency from one type to another. It interacts with the Fawaz Ahmed Currency API to retrieve exchange rates.

Fetching Currency Rates

You can fetch the latest exchange rates for a specific currency, or fetch historical rates by specifying a date in the
format.

Fetching Latest Rates

Fetching Historical Rates

Converting Currency

You can convert a specific amount from one currency to another using either real-time or historical exchange rates.
Real-Time Conversion
Historical Conversion

API Reference

    • currency: Base currency (e.g.,
      ).
    • date (optional): Historical date in
      format. If omitted, the latest rates will be fetched.
    • Returns: A promise that resolves to the exchange rates for the base currency.
    • from: Base currency.
    • to: Target currency.
    • amount: Amount to convert.
    • date (optional): Historical date for conversion. If omitted, the latest exchange rates will be used.
    • Returns: A promise that resolves to the converted amount (as a string with two decimal places).

Useful Enums

It contains a set of predefined currency codes to be used with the
class.
Example:

It contains a mapping of country codes to currency codes.
Example:

Contributing

Contributions are welcome! Please see the Contributing Guidelines for more details.

License

This project is licensed under the MIT License. See the LICENSE file for more information.

Credits

I would like to acknowledge the following resources that were instrumental in the development of this package:
  • currency.js: This library provided valuable insights and inspiration for handling currency formatting and conversion.
  • to-words: A useful package for converting numbers to words, which served as a reference for implementing similar functionality.
  • country-to-currency: A helpful resource for mapping countries to their respective currencies.
  • exchange-api: An open-source API used for currency exchange rates, which guided the implementation of currency conversion features.
Thank you to these projects for their contributions to the open-source community!