numFmt

The numFmt library formats numbers according to a specifier string as defined in ECMA-376. The library tries its best to emulate the inns and outs of the Excel spreadsheet software does.

The library is written in pure JavaScript and has no dependencies. It is comparable to the SSF with some minor interface exceptions.

Features

Why use this rather than the battle tested SSF? You may have no need to but numFmt is fully open source, has equivalent (if not better) formatting capabilities, built in international support, and may run about twice as fast in most cases.

Included languages are:

• Chinese (Simplified) (zh-CN or zh)
• Chinese (Traditional) (zh-TW)
• Czech (cs)
• Danish (da)
• Dutch (nl)
• English (en)
• Finnish (fi)
• French (fr)
• German (de)
• Greek (el)
• Hungarian (hu)
• Icelandic (is)
• Indonesian (id)
• Italian (it)
• Japanese (ja)
• Korean (ko)
• Norwegian Bokmål (nb)
• Polish (pl)
• Portuguese (pt)
• Russian (ru)
• Slovak (sk)
• Spanish (es)
• Swedish (sv)
• Thai (th)
• Turkish (tr)

The library is made to work with current generation spreadsheets and so it does not support the 1904 date system. It does not have built in tables for formats addressable by offsets, you are expected to maintain those yourself.

Installing

If you don't want to download and build numfmt yourself, the library is conveniently provided as an NPM package:

$ npm install numfmt

Using

import numfmt from "numfmt";

// reusable function
const formatter = numfmt("#,##0.00");
const output = formatter(1234.56)
console.log(output);

// ... or just 
const output = numfmt.format("#,##0.00", 1234.56);
console.log(output);

Format syntax

Microsoft have excellent documentation on how the format works. Here are some quick basics:

A format pattern is divided into 4 sections: <POSITIVE>;<NEGATIVE>;<ZERO>;<TEXT>

Only the first section is mandatory, the others are filled in as needed. The sections consist of symbols to indicate what to emit. The symbols are case insensitive:

API Reference

# numfmt(pattern[, locale[, suppressErrors]])

Constructs a new formatter with the specified format pattern and locale. Pattern must be a string according to the ECMA-376 number format. The locale argument is expected to be a BCP 47 string tag but if not specified it defaults to en-US.

The suppressError argument will prevent the parser and formatter from throwing errors (which they will normally do). Invalid patterns will produce a formatter that only emits ######.

# formatter(value)

Returns a formatted string for the argument value.

# formatter.isDate()

Returns a true or false depending on if the pattern is a date pattern. The pattern is considered a date pattern if any of its sections contain a date symbol (see table above). Each section is restricted to to be either a number or date format.

# formatter.color(value)

If the pattern defines colors this function will emit the color appropriate to the value. If no colors were specified this function returns "black".

import numfmt from "numfmt";

const formatter = numfmt("[green]#,##0;[red]-#,##0");
const color = formatter.color(-10)
console.log(color); // "red"

# numfmt.format(pattern, value[, locale[, suppressErrors]])

Parses the format pattern and formats the value according to the pattern, and optionally, locale. See definition above.

# numfmt.round(number[, places])

Return a value rounded to the specified amount of places. This is the rounding function used by the formatter (symmetric arithmetic rounding).

# numfmt.parseLocale(tag)

Parse a BCP 47 locale tag and emit an object of its parts. Intended for internal use.

# numfmt.getLocale(tag)

Used by the formatter to pull a locate from its registered locales. If subtag isn't available but the base language is, the base language is used. So if en-CA is not found, the formatter tries to find en else it returns a null.

# numfmt.addLocale(data, tag)

Register locale data for a language. The full data object looks like this:

{
  group: "\u00a0", // non-breaking space
  decimal: ".",
  positive: "+",
  negative: "-",
  percent: "%",
  exponent: "E",
  nan: "NaN",
  infinity: "∞",
  ampm: [ "AM", "PM" ],

  // gregorian calendar
  mmmm: [ "January", "February", … ],
  mmm: [ "Jan", "Feb", … ],
  dddd: [ "Sunday", "Monday", … ],
  ddd: [ "Sun", "Mon", … ]

  // islamic calendar
  mmmm6: [ "Muharram", "Safar", … ],
  mmm6: [ "Muh.", "Saf.", … ],
}

The data object does not need to be complete, it will fall back to defaults (mostly English) for any missing properties. Adding support for Faroese you would require only passing the data different from the defaults:

numfmt.addLocale({
  group: ".",
  decimal: ",",
  mmmm: [ "januar", "februar", … ],
  mmm: [ "jan", "feb", … ],
  dddd: [ "sunnudagur", "mánadagur", … ],
  ddd: [ "sun", "mán", … ],
}, "fo-FO");

If the language tag provided has a subtag and a base language does not exit, the locale is register to both. In the Faroese example above both fo and fo-FO will be created.

# numfmt.isDate(format)

Returns a true or false depending on if the pattern is a date pattern. The pattern is considered a date pattern if any of its sections contain a date symbol (see table above). Each section is restricted to to be either a number or date format.

For compatibility reasons, this function is also available as numfmt.is_date(format).