npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

formatters

v1.0.3

Published

A javascript library for formatting and manipulating.

Downloads

77

Readme

Formatters


NOTE

For people who don't like read documentation ;)


Installation

> npm i formatters

Import

// es6
import { NumberFormat, ListFormat, DateTimeFormat } from 'formatters';

// es5
const {
    NumberFormat,
    ListFormat,
    DateTimeFormat
} = require('formatters');

NumberFormat

The NumberFormat object enables language-sensitive number formatting.

const { NumberFormat } = require('formatters');

const number = 123456.789;

console.log(NumberFormat('en-US', { style: 'currency', currency: 'EUR' }).format(10000));
// expected output: "€123,456.79"

// the Japanese yen doesn't use a minor unit
console.log(new NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' }).format(number));
// expected output: "¥123,457"

// limit to three significant digits
console.log(new NumberFormat('en-IN', { maximumSignificantDigits: 3 }).format(number));
// expected output: "1,23,000"

Instance methods

format();

The format getter function formats a number into a string according to the locale and formatting options of this NumberFormat object.

Example:

const amount = 654321.987;

const options1 = { style: 'currency', currency: 'RUB' };
const numberFormat1 = new NumberFormat('ru-RU', options1);

console.log(numberFormat1.format(amount));
// expected output: "654 321,99 ₽"

const options2 = { style: 'currency', currency: 'USD' };
const numberFormat2 = new NumberFormat('en-US', options2);

console.log(numberFormat2.format(amount));
// expected output: "$654,321.99"

Parameters

locales Optional

A string with a BCP 47 language tag, or an array of such strings.

options Optional

An object with some or all of the following properties:

compactDisplay Only used when notation is "compact". Takes either "short" (default) or "long".

currency The currency to use in currency formatting. Possible values are the ISO 4217 currency codes, such as "USD" for the US dollar, "EUR" for the euro, or "CNY" for the Chinese RMB — see the Current currency & funds code list. There is no default value; if the style is "currency", the currency property must be provided.

currencyDisplay How to display the currency in currency formatting. Possible values are:

"symbol" to use a localized currency symbol such as €, this is the default value, "narrowSymbol" to use a narrow format symbol ("$100" rather than "US$100"), "code" to use the ISO currency code, "name" to use a localized currency name such as "dollar", currencySign In many locales, accounting format means to wrap the number with parentheses instead of appending a minus sign. You can enable this formatting by setting the currencySign option to "accounting". The default value is "standard".

localeMatcher The locale matching algorithm to use. Possible values are "lookup" and "best fit"; the default is "best fit". For information about this option, see the Intl page.

notation The formatting that should be displayed for the number, the defaults is "standard"

"standard" plain number formatting "scientific" return the order-of-magnitude for formatted number. "engineering" return the exponent of ten when divisible by three "compact" string representing exponent, defaults is using the "short" form. numberingSystem Numbering System. Possible values include: "arab", "arabext", " bali", "beng", "deva", "fullwide", " gujr", "guru", "hanidec", "khmr", " knda", "laoo", "latn", "limb", "mlym", " mong", "mymr", "orya", "tamldec", " telu", "thai", "tibt".

signDisplay When to display the sign for the number; defaults to "auto"

"auto" sign display for negative numbers only "never" never display sign "always" always display sign "exceptZero" sign display for positive and negative numbers, but not zero style The formatting style to use , the default is "decimal".

"decimal" for plain number formatting. "currency" for currency formatting. "percent" for percent formatting "unit" for unit formatting

let amount = 3500;

new NumberFormat('en-US', {style: 'decimal'}).format(amount);
// → '3,500'
new NumberFormat('en-US', {style: 'percent'}).format(amount);
// → '350,000%'

unit The unit to use in unit formatting, Possible values are core unit identifiers, defined in UTS #35, Part 2, Section 6. A subset of units from the full list was selected for use in ECMAScript. Pairs of simple units can be concatenated with "-per-" to make a compound unit. There is no default value; if the style is "unit", the unit property must be provided.

unitDisplay The unit formatting style to use in unit formatting, the defaults is "short".

"long" (e.g., 16 litres) "short" (e.g., 16 l) "narrow" (e.g., 16l) useGrouping Whether to use grouping separators, such as thousands separators or thousand/lakh/crore separators. Possible values are true and false; the default is true.

The following properties fall into two groups: minimumIntegerDigits, minimumFractionDigits, and maximumFractionDigits in one group, minimumSignificantDigits and maximumSignificantDigits in the other. If at least one property from the second group is defined, then the first group is ignored.

minimumIntegerDigits The minimum number of integer digits to use. Possible values are from 1 to 21; the default is 1.

minimumFractionDigits The minimum number of fraction digits to use. Possible values are from 0 to 20; the default for plain number and percent formatting is 0; the default for currency formatting is the number of minor unit digits provided by the ISO 4217 currency code list (2 if the list doesn't provide that information).

maximumFractionDigits The maximum number of fraction digits to use. Possible values are from 0 to 20; the default for plain number formatting is the larger of minimumFractionDigits and 3; the default for currency formatting is the larger of minimumFractionDigits and the number of minor unit digits provided by the ISO 4217 currency code list (2 if the list doesn't provide that information); the default for percent formatting is the larger of minimumFractionDigits and 0.

minimumSignificantDigits The minimum number of significant digits to use. Possible values are from 1 to 21; the default is 1.

maximumSignificantDigits The maximum number of significant digits to use. Possible values are from 1 to 21; the default is 21.

formatToParts();

The formatToParts() method is useful for custom formatting of number strings. It returns an Array of objects containing the locale-specific tokens from which it possible to build custom strings while preserving the locale-specific parts. The structure the formatToParts() method returns example:

const number = 3500;

const formatter = new NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR'
});

formatter.formatToParts(number);


// return value:
[
  { type: "integer",  value: "3"   },
  { type: "group",    value: "."   },
  { type: "integer",  value: "500" },
  { type: "decimal",  value: ","   },
  { type: "fraction", value: "00"  },
  { type: "literal",  value: " "   },
  { type: "currency", value: "€"   }
]

resolvedOptions();

The NumberFormat.prototype.resolvedOptions() method returns a new object with properties reflecting the locale and number formatting options computed during initialization of this

Example:

const numberFormat1 = new NumberFormat('de-DE');
const options1 = numberFormat1.resolvedOptions();

console.log(options1.locale);
// expected output (Firefox / Safari): "de-DE"
// expected output (Chrome): "de"

console.log(options1.numberingSystem);
// expected output: "latn"

console.log(options1.style);
// expected output: "decimal"

The resulting object has the following properties:

locale The BCP 47 language tag for the locale actually used. If any Unicode extension values were requested in the input BCP 47 language tag that led to this locale, the key-value pairs that were requested and are supported for this locale are included in locale.

numberingSystem The value provided for this properties in the options argument, if present, or the value requested using the Unicode extension key "nu" or filled in as a default.

notation The value provided for this property in the options argument, if present, or "standard" filled in as a default.

compactDisplay The value provided for this property in the options argument, or "short" filled in as a default. This property is only present if the notation is set to "compact".

signDisplay The value provided for this property in the options argument, or "auto" filled in as a default.

useGrouping The values provided for these properties in the options argument or filled in as defaults.

currency, currencyDisplay The values provided for these properties in the options argument or filled in as defaults. These properties are only present if style is "currency".

Only one of the following two groups of properties is included:

minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits The values provided for these properties in the options argument or filled in as defaults. These properties are present only if neither minimumSignificantDigits nor maximumSignificantDigits was provided in the options argument.

minimumSignificantDigits, maximumSignificantDigits The values provided for these properties in the options argument or filled in as defaults. These properties are present only if at least one of them was provided in the options argument.

ListFormat

The ListFormat object enables language-sensitive list formatting.

const vehicles = ['Motorcycle', 'Bus', 'Car'];

const formatter = new ListFormat('en', { style: 'long', type: 'conjunction' });
console.log(formatter.format(vehicles));
// expected output: "Motorcycle, Bus, and Car"

const formatter2 = new ListFormat('de', { style: 'short', type: 'disjunction' });
console.log(formatter2.format(vehicles));
// expected output: "Motorcycle, Bus oder Car"

const formatter3 = new ListFormat('en', { style: 'narrow', type: 'unit' });
console.log(formatter3.format(vehicles));
// expected output: "Motorcycle Bus Car"

Instance methods

format();

The format() method returns a string that has been formatted based on parameters provided in the ListFormat object. The locales and options parameters customize the behavior of format() and let applications specify the language conventions that should be used to format the list.

Example:

const list = ['Motorcycle', 'Bus', 'Car'];

 console.log(new ListFormat('en-GB', { style: 'long', type: 'conjunction' }).format(list));
// > Motorcycle, Bus and Car

 console.log(new ListFormat('en-GB', { style: 'short', type: 'disjunction' }).format(list));
// > Motorcycle, Bus or Car

 console.log(new ListFormat('en-GB', { style: 'narrow', type: 'unit' }).format(list));
// > Motorcycle Bus Car

formatToParts();

Whereas ListFormat.prototype.format() returns a string being the formatted version of the list (according to the given locale and style options), formatToParts() returns an array of the different components of the formatted string.

Each element of the resulting array has two properties: type and value. The type property may be either "element", which refers to a value from the list, or "literal" which refers to a linguistic construct. The value property gives the content, as a string, of the token.

The locale and style options used for formatting are given when constructing the ListFormat instance.

Example:

const fruits = ['Apple', 'Orange', 'Pineapple'];
const myListFormat = new ListFormat('en-GB', { style: 'long', type: 'conjunction' });

console.table(myListFormat.formatToParts(fruits));
// [
//  { "type": "element", "value": "Apple" },
//  { "type": "literal", "value": ", " },
//  { "type": "element", "value": "Orange" },
//  { "type": "literal", "value": ", and " },
//  { "type": "element", "value": "Pineapple" }
// ]

DateTimeFormat

The DateTimeFormat object enables language-sensitive date and time formatting.

const date = new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738));
// Results below assume UTC timezone - your results may vary

// Specify default date formatting for language (locale)
console.log(new DateTimeFormat('en-US').format(date));
// expected output: "12/20/2020"

// Specify default date formatting for language with a fallback language (in this case Indonesian)
console.log(new DateTimeFormat(['ban', 'id']).format(date));
// expected output: "20/12/2020"

// Specify date and time format using "style" options (i.e. full, long, medium, short)
console.log(new DateTimeFormat('en-GB', { dateStyle: 'full', timeStyle: 'long' }).format(date));
// Expected output "Sunday, 20 December 2020 at 14:23:16 GMT+11"

Instance methods

format();

The format getter formats a date into a string according to the locale and formatting options of this DateTimeFormat object.

Example:

const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
const dateTimeFormat = new DateTimeFormat('sr-RS', options);

console.log(dateTimeFormat.format(new Date()));

formatRange();

The DateTimeFormat.prototype.formatRange() formats a date range in the most concise way based on the locale and options provided when instantiating DateTimeFormat object.

Example:

const options1 = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
const options2 = { year: '2-digit', month: 'numeric', day: 'numeric' };

const startDate = new Date(Date.UTC(2007, 0, 10, 10, 0, 0));
const endDate = new Date(Date.UTC(2008, 0, 10, 11, 0, 0));

const dateTimeFormat = new DateTimeFormat('en', options1);
console.log(dateTimeFormat.formatRange(startDate, endDate));
// expected output: Wednesday, January 10, 2007 – Thursday, January 10, 2008

const dateTimeFormat2 = new DateTimeFormat('en', options2);
console.log(dateTimeFormat2.formatRange(startDate, endDate));
// expected output: 1/10/07 – 1/10/08
let date1 = new Date(Date.UTC(2007, 0, 10, 10, 0, 0));
let date2 = new Date(Date.UTC(2007, 0, 10, 11, 0, 0));
let date3 = new Date(Date.UTC(2007, 0, 20, 10, 0, 0));
// > 'Wed, 10 Jan 2007 10:00:00 GMT'
// > 'Wed, 10 Jan 2007 11:00:00 GMT'
// > 'Sat, 20 Jan 2007 10:00:00 GMT'

let fmt1 = new DateTimeFormat("en", {
    year: '2-digit',
    month: 'numeric',
    day: 'numeric',
    hour: 'numeric',
    minute: 'numeric'
});
console.log(fmt1.format(date1));
console.log(fmt1.formatRange(date1, date2));
console.log(fmt1.formatRange(date1, date3));
// > '1/10/07, 10:00 AM'
// > '1/10/07, 10:00 – 11:00 AM'
// > '1/10/07, 10:00 AM – 1/20/07, 10:00 AM'

let fmt2 = new DateTimeFormat("en", {
    year: 'numeric',
    month: 'short',
    day: 'numeric'
});
console.log(fmt2.format(date1));
console.log(fmt2.formatRange(date1, date2));
console.log(fmt2.formatRange(date1, date3));
// > 'Jan 10, 2007'
// > 'Jan 10, 2007'
// > 'Jan 10 – 20, 2007'