Skip to main content

Humanizer.ts

Humanizer meets all your TypeScript needs for manipulating and displaying strings, dates, times, timespans, numbers and quantities.

GitHub code size in bytes GitHub GitHub last commit GitHub Workflow Status

Table of contents

Usage

Import the Extensions:

import "https://deno.land/x/humanizer/byteSize.ts"
import "https://deno.land/x/humanizer/vocabularies.ts"
import "https://deno.land/x/humanizer/ordinalize.ts"
import "https://deno.land/x/humanizer/toQuantity.ts"
import "https://deno.land/x/humanizer/numberToNumbers.ts"
import "https://deno.land/x/humanizer/numberToWords.ts"
import "https://deno.land/x/humanizer/romanNumerals.ts"
import "https://deno.land/x/humanizer/metricNumerals.ts"

Examples

import "https://deno.land/x/humanizer/byteSize.ts"

let result = (10).megabytes().toString()
console.log(result) // -> 10 MB

ByteSize

Humanizer includes a port of the brilliant ByteSize library. Quite a few changes and additions are made on ByteSize to make the interaction with ByteSize easier and more consistent with the Humanizer API. Here is a few examples of how you can convert from numbers to byte sizes and between size magnitudes:

import "https://deno.land/x/humanizer/byteSize.ts"

let fileSize = (10).kilobytes()
console.log(fileSize.bits)          // -> 81920
console.log(fileSize.bytes)         // -> 10240
console.log(fileSize.kilobytes)     // -> 10
console.log(fileSize.megabytes)     // -> 0.009765625
console.log(fileSize.gigabytes)     // -> 0.0000095367431640625
console.log(fileSize.terabytes)     // -> 9.313225746154785e-9

There are a few extension methods that allow you to turn a number into a ByteSize instance:

(3).bits();
(5).bytes();
(10.5).kilobytes();
(2.5).megabytes();
(10.2).gigabytes();
(4.7).terabytes();

You can also add/subtract the values

let f = (4).gigabytes().add((22).megabytes()).subtract((980).kilobytes()).addGigabytes(1)
console.log(f.toString()) // -> 5.020549774169922 GB

Vocabularies

Pluralize

Pluralize pluralizes the provided input while taking irregular and uncountable words into consideration:

import "https://deno.land/x/humanizer/vocabularies.ts"

"Man".pluralize()       // -> Men
"string".pluralize()    // -> "strings"

Singularize

Singularize singularizes the provided input while taking irregular and uncountable words into consideration:

"Men".singularize()     //-> "Man"
"strings".singularize() //-> "string"

Ordinalize

import "https://deno.land/x/humanizer/ordinalize.ts"

(1).ordinalize() => "1st"
(5).ordinalize() => "5th"

ToQuantity

import "https://deno.land/x/humanizer/toQuantity.ts"

"case".toQuantity(0) => "0 cases"
"case".toQuantity(1) => "1 case"
"case".toQuantity(5) => "5 cases"
"man".toQuantity(0) => "0 men"
"man".toQuantity(1) => "1 man"
"man".toQuantity(2) => "2 men"

ToQuantity can figure out whether the input word is singular or plural and will singularize or pluralize as necessary:

"men".toQuantity(2) => "2 men"
"process".toQuantity(2) => "2 processes"
"process".toQuantity(1) => "1 process"
"processes".toQuantity(2) => "2 processes"
"processes".toQuantity(1) => "1 process"

You can also pass a second argument, ShowQuantityAs, to toQuantity to specify how you want the provided quantity to be outputted. The default value is ShowQuantityAs.Numeric which is what we saw above. The other two values are ShowQuantityAs.Words and ShowQuantityAs.None.

"case".toQuantity(5, ShowQuantityAs.Words) => "five cases"
"case".toQuantity(5, ShowQuantityAs.None) => "cases"

Number to numbers

Humanizer provides a fluent API that produces (usually big) numbers in a clearer fashion:

import "https://deno.land/x/humanizer/numberToNumbers.ts"

(1.25).Billions() => 1250000000
(3).Hundreds().Thousands() => 300000

Number to words

Humanizer can change numbers to words using the toWords extension:

import "https://deno.land/x/humanizer/numberToWords.ts"

(1).toWords() => "one"
(10).toWords() => "ten"
(11).toWords() => "eleven"
(122).toWords() => "one hundred and twenty-two"
(3501).toWords() => "three thousand five hundred and one"

Number to ordinal words

import "https://deno.land/x/humanizer/numberToWords.ts"

(0).toOrdinalWords() => "zeroth"
(1).toOrdinalWords() => "first"
(2).toOrdinalWords() => "second"
(8).toOrdinalWords() => "eighth"
(10).toOrdinalWords() => "tenth"
(11).toOrdinalWords() => "eleventh"
(12).toOrdinalWords() => "twelfth"
(20).toOrdinalWords() => "twentieth"
(21).toOrdinalWords() => "twenty first"
(121).toOrdinalWords() => "hundred and twenty first"

Roman Numerals

Humanizer can change numbers to Roman numerals using the toRoman extension. The numbers 1 to 10 can be expressed in Roman numerals as follows:

import "https://deno.land/x/humanizer/romanNumerals.ts"

(1).toRoman() => "I"
(2).toRoman() => "II"
(3).toRoman() => "III"
(4).toRoman() => "IV"
(5).toRoman() => "V"
(6).toRoman() => "VI"
(7).toRoman() => "VII"
(8).toRoman() => "VIII"
(9).toRoman() => "IX"
(10).toRoman() => "X"

Also the reverse operation using the fromRoman extension.

"I".fromRoman() => 1
"II".fromRoman() => 2
"III".fromRoman() => 3
"IV".fromRoman() => 4
"V".fromRoman() => 5

Metric numerals

Humanizer can change numbers to Metric numerals using the toMetric extension. The numbers 1, 1230 and 0.1 can be expressed in Metric numerals as follows:

import "https://deno.land/x/humanizer/metricNumerals.ts"

(1).toMetric() => "1"
(1230).toMetric() => "1.23k"
(0.1).toMetric() => "100m"

Also the reverse operation using the fromMetric extension.

"1".fromMetric() => 1
"1.23k".fromMetric() => 1230
"100m".fromMetric() => 0.1

License

FOSSA Status