@transferwise/formatting

Usage

Number formatting

formatNumber is for only formatting numeric values and only alphanumeric strings. If you would like to format a currency related amount, use formatAmount - which uses formatNumber under the hood.

import { formatNumber } from '@transferwise/formatting';

const number = 123456;

console.log(formatNumber(number, 'en-GB' /* Optional, defaults to en-GB */));
// --> '123,456'
console.log(formatNumber(number, 'es-ES', 0 /* Optional precision, defaults to 0 */));
// --> '123.456'
console.log(
  formatNumber(
    number,
    'hu-HU',
    0,
    'FractionDigits' /* Optional precision type (FractionDigits or SignificantDigits), defaults to 'FractionDigits' */,
  ),
);
// --> '123 456'

formatNumberToSignificantDigits performs the same localization as formatNumber, but provides precision to significant digits instead of decimal precision. Used under the hood for localizing rates in getRateInAllFormats.

import { formatNumberToSignificantDigits } from '@transferwise/formatting';

const number = 123456;

console.log(formatNumberToSignificantDigits(number, 'en-GB' /* Optional, defaults to en-GB */));
// --> '123,456'
console.log(
  formatNumberToSignificantDigits(number, 'es-ES', 8 /* Optional precision, defaults to 6 */),
);
// --> '123.456,00'
console.log(formatNumberToSignificantDigits(number, 'hu-HU', 8));
// --> '123 456,00'

Amount formatting

import { formatAmount } from '@transferwise/formatting';

console.log(formatAmount(1234.56, 'EUR', 'en-GB' /* Optional, defaults to en-GB */));
// --> '1,234.56'

Money formatting

import { formatMoney } from '@transferwise/formatting';

console.log(formatMoney(1234.56, 'EUR', 'en-GB' /* Optional, defaults to en-GB */));
// --> '1,234.56 EUR'

Rate formatting

getDisplayRate(rate, sourceCurrency, targetCurrency, locale)

Use this function when you need to display rates to customers. It will round rates to the correct number of decimal places and will invert rates that are best displayed in the other direction. For example if a rate is very low we invert the rate so that it's easier for customers to understand.

const display = getDisplayRate({
  rate: 1.2345,
  sourceCurrency: 'BRL',
  targetCurrency: 'EUR',
  locale: 'de',
});

In most cases you should use display.equation to get a string such as 1 EUR = 4.5678 BRL.

In calculators you may wish to show the rate directly using display.decimal. You must have some UI component to specify if the rate has been inverted or not, based on display.inverted; for example a multiply/divide icon.

In a rate graph first call getDisplayRate to determine if the rates should be displayed inverted or not. Then call either formatRate(rate, locale) or formatRate(1 / rate, locale) on each data point in the graph.

formatRate(rate, locale)

formatRate(0.08682346801, 'de') === '0,0868';

Limits a rate to a certain amount of precision for display (4 decimal places).

This is a dumb, low-level formatter for just the rate number value, and it's only for specific rate implementations. For typical rate display purposes, you should use getDisplayRate.

Percentage formatting

import { formatPercentage } from '@transferwise/formatting';

console.log(formatPercentage(0.23456789));
// --> '23.46%'
console.log(formatPercentage(0.234));
// --> '23.4%'
console.log(formatPercentage(0.23));
// --> '23%'

Date formatting

import { formatDate } from '@transferwise/formatting';

const date = new Date(2018, 11, 1);

console.log(formatDate(date, 'en-GB' /* Optional, defaults to en-GB */));
// --> '01/12/2018'
console.log(formatDate(date, 'en-GB', { weekday: 'short' }));
// --> 'Sat'
console.log(formatDate(date, 'en-GB', { month: 'long', year: 'numeric' }));
// --> 'December 2018'

For third parameter pass in the same options as for Intl.DateTimeFormat and for best performance use the same object (pass in reference), for example:

const options = { weekday: 'short' };
formatDate(new Date(), 'en-GB', options);
formatDate(new Date(), 'en-GB', options);

Relative Date formatting

Formats future dates using a relative description of time, e.g. 'in seconds'. A relative description will be used as long as the instant of time being formatted is on the same calendar date as today in the clients timezone and the time is within 12 hours (inclusive).

import { formatRelativeDate } from '@transferwise/formatting';

console.log(formatRelativeDate(new Date(Date.now() + 1000))); // --> 'in seconds'

Same Calendar Date	Time Range (inclusive)	Sample Output
Yes	In the past	''
Yes	00:00:00.000 -> 00:00:59.000	'in seconds'
Yes	00:00:59.001 -> 00:01:00.000	'in 1 minute'
Yes	00:01:00.001 -> 00:02:00.000	'in 2 minutes'
Yes	00:02:00.001 -> 00:58:00.000	'in x minutes' (3-58)
Yes	00:58:00.001 -> 00:59:00.000	'in 59 minutes'
Yes	00:59:00.001 -> 01:00:00.000	'in 1 hour'
Yes	01:00:00.001 -> 02:00:00.000	'in 2 hours'
Yes	02:00:00.001 -> 10:00:00.000	'in x hours' (3-10)
Yes	10:00:00.001 -> 11:00:00.000	'in 11 hours'
Yes	11:00:00.001 -> 12:00:00.000	'in 12 hours'
Yes	12:00:00.001 -> End of calendar date	'by Aug 23'
No	Any	'by Aug 23'

Developing

As usual, yarn install --frozen-lockfile to install dependencies. Then, use yarn test:watch to work with live-reloading tests or yarn dev for live-reloading type checking.