@munny/parser

A zero-dependency smart currency parser that should be able to work with minimal to no configuration.

Installation

yarn add @munny/parser
# or if using npm
npm install @munny/parser

Usage

import { parse } from '@munny/parser';

const brazilianReal = parse('R$ 150,00');
//=> {
//=>   amount: 15000,
//=>   raw: 'R$ 150,00',
//=>   symbol: 'R$',
//=>   currency: undefined,
//=>   separators: { thousands: undefined, decimal: ',' },
//=>   precision: 2,
//=>   thousandsSeparator: undefined,
//=>   decimalSeparator: ',',
//=>   isNegative: false
//=> }

Parsing currency by "guessing"

If you pass no options to the parser, it will try to guess most of the details for the given string. The parser is able to identify negative numbers, including numbers that are parenthesized, currency code, currency symbol, thousands separator, decimal separator and decimal precision for currencies with up to 2 decimal places. Currencies with no decimals (like Yen) are also supported by the guessing system.

Examples

import { parse } from '@munny/parser';

const brazilianReal = parse('R$ 150,00');
//=> {
//=>   amount: 15000,
//=>   raw: 'R$ 150,00',
//=>   symbol: 'R$',
//=>   currency: undefined,
//=>   separators: { thousands: undefined, decimal: ',' },
//=>   precision: 2,
//=>   thousandsSeparator: undefined,
//=>   decimalSeparator: ',',
//=>   isNegative: false
//=> }
const poundSterling = parse('£ 150,000.00');
//=> {
//=>   amount: 15000000,
//=>   raw: '£ 150,000.00',
//=>   symbol: '£',
//=>   currency: undefined,
//=>   separators: { thousands: ',', decimal: '.' },
//=>   precision: 2,
//=>   thousandsSeparator: ',',
//=>   decimalSeparator: '.',
//=>   isNegative: false
//=> }
const yen = parse('¥5000');
//=> {
//=>   amount: 5000,
//=>   raw: '¥5000',
//=>   symbol: '¥',
//=>   currency: undefined,
//=>   separators: { thousands: undefined, decimal: undefined },
//=>   precision: 0,
//=>   thousandsSeparator: undefined,
//=>   decimalSeparator: undefined,
//=>   isNegative: false
//=> }

The returned result of the parse function is always an object that matches the interface MunnyParsedCurrency, with the following properties:

export type MunnyParsedCurrency = {
  raw: string;
  amount: number;
  currency?: string;
  symbol?: string;
  separators: {
    thousands?: string;
    decimal?: string;
  };
  precision: number;
  thousandsSeparator?: string;
  decimalSeparator?: string;
  isNegative: boolean;
};

The properties decimalSeparator and thousandsSeparator on the object root are just an alias to the properties found inside the separator property of the object.

The amount will always be the value as an integer. If you need the value to be a float, there's a utility function to help you with that:

import { parse, integerToFloat } from '@munny/parser';

const currencyBRL = parse('R$ 150,45');
integerToFloat(currencyBRL.amount, currencyBRL.precision);
//=> 150.45

This function operates on numbers and not on the parsed JSON object. You can use this with any number you wish to convert to a float.

Parsing with options

If the guessing from the parser doesn't seem to be correct, you can pass one or more options to tell the parser how it should behave. The second argument to the parse function is an options object that has the following structure:

export type MunnyParseOptions = {
  currency?: string | false;
  precision?: number;
  symbol?: string;
  decimalSeparator?: string;
  thousandSeparator?: string;
};

These options are meant to change the regular expression used by the parser, to improve accuracy. This can also be used to parse numbers with more than 2 decimal places (for example, crypto currencies like Bitcoin, that have 8 decimal places).

import { parse } from '@munny/parser';

const bitcoinValue = '₿ 0.001';
const guessBitcoin = parse(bitcoinValue);
//=> {
//=>   amount: 1,
//=>   raw: '₿ 0.001',
//=>   symbol: '₿',
//=>   currency: undefined,
//=>   separators: { thousands: '.', decimal: undefined },
//=>   precision: 0,
//=>   thousandsSeparator: '.',
//=>   decimalSeparator: undefined,
//=>   isNegative: false
//=> }
const optionsBitcoin = parse(bitcoinValue, {
  precision: 8,
});
//=> {
//=>   amount: 100000,
//=>   raw: '₿ 0.001',
//=>   symbol: '₿',
//=>   currency: undefined,
//=>   separators: { thousands: undefined, decimal: '.' },
//=>   precision: 8,
//=>   thousandsSeparator: undefined,
//=>   decimalSeparator: '.',
//=>   isNegative: false
//=> }

Simply passing { precision: 8 } is enough for the parser to treat the . as a decimal separator instead of thousands.

The parser is not restricted to actual currencies, being able to support virtually any currency, fictional or not, as long as the structure is consistent. Here are a few examples:

import { parse } from '@munny/parser';

// Combining $ and ₩ to create a fictional currency symbol
const starWarsCreds = parse('$₩ 5,000');
//=> {
//=>   amount: 5000,
//=>   raw: '$₩ 5,000',
//=>   symbol: '$₩',
//=>   currency: undefined,
//=>   separators: { thousands: ',', decimal: undefined },
//=>   precision: 0,
//=>   thousandsSeparator: ',',
//=>   decimalSeparator: undefined,
//=>   isNegative: false
//=> }

// Using letters as currency symbol
const pokeDollars = parse('PK 500,000');
//=> {
//=>   amount: 500000,
//=>   raw: 'PK 500,000',
//=>   symbol: 'PK',
//=>   currency: undefined,
//=>   separators: { thousands: ',', decimal: undefined },
//=>   precision: 0,
//=>   thousandsSeparator: ',',
//=>   decimalSeparator: undefined,
//=>   isNegative: false
//=> }

// Using an unicode character as a symbol
const triangles = parse('⟁ 5000');
//=> {
//=>   amount: 5000,
//=>   raw: '⟁ 5000',
//=>   symbol: '⟁',
//=>   currency: undefined,
//=>   separators: { thousands: undefined, decimal: undefined },
//=>   precision: 0,
//=>   thousandsSeparator: undefined,
//=>   decimalSeparator: undefined,
//=>   isNegative: false
//=> }

// Using an emoji as curency symbol
const octobits = parse('🐙  5000');
//=> {
//=>   amount: 5000,
//=>   raw: '🐙  5000',
//=>   symbol: '🐙',
//=>   currency: undefined,
//=>   separators: { thousands: undefined, decimal: undefined },
//=>   precision: 0,
//=>   thousandsSeparator: undefined,
//=>   decimalSeparator: undefined,
//=>   isNegative: false
//=> }

// Using a double width emoji
const likes = parse('👍🏻LKS 500');
//=> {
//=>   amount: 500,
//=>   raw: '👍🏻 500',
//=>   symbol: '👍🏻',
//=>   currency: undefined,
//=>   separators: { thousands: undefined, decimal: undefined },
//=>   precision: 0,
//=>   thousandsSeparator: undefined,
//=>   decimalSeparator: undefined,
//=>   isNegative: false
//=> }

// Using three latin letters as a symbol, just pass `false` to currency
const pieces = parse('PCS 500', { currency: false });
//=> {
//=>   amount: 500,
//=>   raw: 'PCS 500',
//=>   symbol: 'PCS',
//=>   currency: undefined,
//=>   separators: { thousands: undefined, decimal: undefined },
//=>   precision: 0,
//=>   thousandsSeparator: undefined,
//=>   decimalSeparator: undefined,
//=>   isNegative: false
//=> }

API

parse(currencyToParse, [MunnyParseOptions])

currencyToParse

Type: string

The string from which you want to parse a currency.

MunnyParseOptions

Type: object

The options for the parser

type MunnyParseOptions = {
  currency?: string | false;
  precision?: number;
  symbol?: string;
  decimalSeparator?: string;
  thousandSeparator?: string;
};

currency

Required: No

Type: string or false

The currency code is an ISO 4217 three-letter code and, if not passed, that's what the parser will try to guess.

The parser will always assume the currency code comes before the currency symbol. If you wish to use a three letter symbol (for a fictional currency, for example), you may pass false so the currency will be ignored

precision

Required: No

Type: number

How many decimal places the currency should use. If you need unusual precisions (like 8 for Bitcoin, for example), just pass this options and the parser should be able to handle it as usual.

const bitcoin = parse('₿ 0.001', {
  precision: 8,
});
//=> {
//=>   amount: 100000,
//=>   raw: '₿ 0.001',
//=>   symbol: '₿',
//=>   currency: undefined,
//=>   separators: { thousands: undefined, decimal: '.' },
//=>   precision: 8,
//=>   thousandsSeparator: undefined,
//=>   decimalSeparator: '.',
//=>   isNegative: false
//=> }

symbol

Required: No

Type: string

The symbol for the current currency.

decimalSeparator

Required: No

Type: string

The string used as a decimal separator

thousandsSeparator

Required: No

Type: string

The string used as a thousands separator