Number Format 🍀

Utility for formatting numbers for Node and Browser that handles floating point number imprecission.

Instalation

npm install --save @alesmenzel/number-format

Table of Contents

1. Usage
   1. Format
   2. Create Formatter (chainable)
   3. Round
   4. Humanize
   5. Separators
   6. Plus
   7. Percentage
   8. Prefix
   9. Suffix
   10. Custom formatter
2. Request a feature
3. License

Usage

Format

Formatter unifies all of the formating functions into a single interface. Formatter accepts configuration object and returns a formatting function.

Parameters:

Name	Type	Description	Default
options	Object	The configuration object.	See below
options.decimalPoint	String	Decimal point. (e.g. 123.56)	'.' (dot)
options.thousandsSeparator	String	Thousand separators. (e.g. 1 000 000)	'' (empty string)
options.round	Number|Falsy	Precision (e.g. 0.001 for 3 decimal places or 1000 for rounding to thousands, use 1 to round to whole numbers).	false
options.percentage	Boolean	Whether to add _% (space percentage) suffix and times the number by 100. (e.g. 0.124 -> 12.4 %)	false
options.humanize	Object|Falsy	Whether to transform the number into a human readable format. See humanize for available options. The only difference is that the transform() function runs after adding decimal/thousands separators and plus sign.	false
options.plus	Boolean	Whether to append + to numbers greater then zero.	false
options.prefix	String	Prepends the given prefix.	'' (empty string)
options.suffix	String	Appends the given suffix.	'' (empty string)

Default configuration object

{
    decimalPoint = '.',
    thousandsSeparator = '',
    round = false,
    percentage = false,
    humanize = false,
    plus = false,
    prefix = '',
    suffix = '',
  }

import { format: formatter, SI_SUFFIXES } from '@alesmenzel/number-format';

const input = 12345607.55678;
const format = formatter({
  round: 0.1,
  plus: true,
  humanize: {
    suffixes: SI_SUFFIXES,
  },
});
format(input); // '+12.3MB'

Create Formatter

Formatter is just a different interface for format functoin. Instead of passing a single config object, it allows you to configure the formatter by chaining format methods.

import { createFormatter, SI_SUFFIXES } from '@alesmenzel/number-format';

const input = 12345607.55678;
const formatter = createFormatter({
  round: 0.1,
  plus: true,
  humanize: {
    suffixes: SI_SUFFIXES,
  },
});
// Call `fnc()` to get formatting function
const format = formatter.fnc();

format(input); // '+12.3MB'

Round

Round number to given precision. Handles rounding of integers as well as decimals. Precision is given as base 10 number (e.g. 1e3 = 1000 to round to thousands or 1e-2 = 0.01 to round to 2 decimal places). Handles imprecision caused by JavaScript´s floating point system (e.g. formatting 0.1 + 0.2).

Parameters:

Name	Type	Description	Default
precision	Number	The precision to round to. Should be a multiple of 10 (e.g. '1000' or '0.01')	-

import { round } from '@alesmenzel/number-format';

const format = round(1000);
format(12345.123); // 12000

const format = round(1);
format(12345.123); // 12345

const format = round(0.01);
format(12345.12345); // 12345.12

Humanize

Converts number to a human readable format. Handles numbers up to trilions.

Parameters:

Name	Type	Description	Default
options	Object	Options	See defaulto options below
options.transform	Function(Number => Number|String)	Function to transform the number before appending the sufix (e.g. to be used for rounding).	indentity(Number => Number)
options.base	Number	Base for the numbers.	1000
options.suffixes	Object	Suffixes to use after the number.	GENERAL_SUFFIXES
options.suffixes.big	Array	Enable adding suffixes for big numbers (x >= 0). E.g. 12MB	true
options.suffixes.small	Array	Enable adding suffixes for small numbers (x < 0). E.g. 12 nanoseconds	true

Default options

{
    transform = identity,
    suffixes = GENERAL_SUFFIXES,
    base = 1000,
    big = true,
    small = true,
}

Available suffixes

// Numbers: https://en.wikipedia.org/wiki/Order_of_magnitude
const GENERAL_SUFFIXES = {
  big: ['', 'k', 'M', 'B', 'T' /* ... */],
  small: ['m', 'µ', 'n' /* ... */],
};
const GENERAL_NAME_SUFFIXES = {
  big: ['', 'thousand', 'million', 'billion' /* ... */],
  small: ['thousandth', 'millionth', 'billionth' /* ... */],
};

// Bytes: https://en.wikipedia.org/wiki/Orders_of_magnitude_(data)
const SI_SUFFIXES = {
  big: ['', 'KB', 'MB', 'GB', 'TB' /* ... */],
  small: [],
};
const SI_NAME_SUFFIXES = {
  big: ['byte', 'kilobyte', 'megabyte', 'gigabyte' /* ... */],
  small: [],
};

// Bytes: https://en.wikipedia.org/wiki/Orders_of_magnitude_(data)
const IT_SUFFIXES = {
  big: ['', 'Kb', 'Mb', 'Gb' /* ... */],
  small: [],
};
const IT_NAME_SUFFIXES = {
  big: ['byte', 'kibibyte', 'mebibyte', 'gibibyte' /* ... */],
  small: [],
};

// Time: https://en.wikipedia.org/wiki/Orders_of_magnitude_(time)
const TIME_SUFFIXES = {
  big: ['', 'ks', 'Ms', 'Gs' /* ... */],
  small: ['ms', 'µs', 'ns' /* ... */],
};
const TIME_NAME_SUFFIXES = {
  big: ['', 'kilosecond', 'megasecond', 'gigasecond' /* ... */],
  small: ['millisecond', 'microsecond', 'nanosecond' /* ... */],
};

Sample usage

import { humanize, round } from '@alesmenzel/number-format';

const format = humanize();

format(123000); // 123k
format(123456789); // 123.456789M
format(-123456789); // -123.456789M
format(100); // 100

const formatAndRound = humanize({
  transform: round(0.01),
});

formatAndRound(123456789); // 123.46M

const formatBytes = humanize({
  transform: round(0.01),
  base: 1024,
  suffixes: {
    // Custom suffixes or you can use any of the predeffined (or combine them)
    big: ['', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'],
    small: [],
  },
  big: true,
  small: false,
});

formatBytes(156949847); // 149.68MB

Separators

Change decimal and thousands separators.

Parameters:

Name	Type	Description	Default
thousandsSeparator	String	Symbol for separating thousands.	'' (empty string)
decimalSeparator	String	Symbol for separating decimals.	. (dot)

import { changeSeparators } from '@alesmenzel/number-format';

const czechFormat = changeSeparators(' ', '.');
czechFormat(1596849.19); // '1 596 849.19'

const usFormat = changeSeparators(',', '.');
usFormat(1596849.19); // '1,596,849.19'

const norwegianFormat = changeSeparators('.', ',');
norwegianFormat(1596849.19); // '1.596.849,19'

Percentage

Simply times the value by 100.

import { percentage } from '@alesmenzel/number-format';

percentage()(0.12); // 12
percentage()(0); // 0
percentage()(-1.23); // -123

Plus

Simply adds a plus for positive numbers.

import { plus } from '@alesmenzel/number-format';

plus()(123456); // +123456
plus()(0); // 0
plus()(-123456); // -123456

Prefix

Simply adds a prefix.

Parameters:

Name	Type	Description	Default
prefix	String	Prepends a given prefix and returns a string. Number|String => String	-

import { prefix } from '@alesmenzel/number-format';

prefix('$')(123456); // $123456
prefix('$')(0); // $0
prefix('$')(-123456); // $-123456

Suffix

Simply adds a suffix.

Parameters:

Name	Type	Description	Default
suffix	String	Appends a given suffix and returns a string. Number|String => String	-

import { suffix } from '@alesmenzel/number-format';

suffix('€')(123456); // 123456€
suffix('€')(0); // 0€
suffix('€')(-123456); // -123456€

Compose

You can also compose formatters into a single one with the compose function.

Parameters:

Name	Type	Description	Default
...functions	Function[]	Array of formatter functions. A formatter function accepts single value (Number or String) and returns a single value (Number or String). Number|String => Number|String	-

import { compose, round, changeSeparators } from '@alesmenzel/number-format';

const czechFormat = compose(round(0.1), changeSeparators(' ', '.'));
czechFormat(1596849.19); // '1 596 849.2'

const usFormat = compose(round(0.1), changeSeparators(',', '.'));
usFormat(1596849.19); // '1,596,849.2'

const norwegianFormat = compose(round(0.1), changeSeparators('.', ','));
norwegianFormat(1596849.19); // '1.596.849,2'

Custom formatter

Any formatter should be of type Number|String => Number|String.

import { compose, round, changeSeparators } from '@alesmenzel/number-format';

// Here we define our custom formatter that returns specified number of last digits
const lastDigits = options => {
  const { length } = options;

  return number => {
    return `${number}`.slice(-length);
  };
};

const format = lastDigits({ length: 3 });

format(123456789); // 789

// Use it in composition
const format = compose(round(10), lastDigits({ length: 3 }));

format(123456789); // 790

Request a feature

If you are missing a feature, please open a new issue with the feature request. PRs are welcome as well.

License

This project is licensed under the terms of the MIT license.