HubSpot/humanize

Humanize Plus

A simple utility library for making the web more humane.

Getting Started

Humanize Plus is available via node package manager.

npm install humanize-plus

Or download the minified version or the full version.

In your web page:

<script src="public/humanize.min.js"></script>
<script>
var capitalized = Humanize.capitalize("ten tiny ducklings.")
// "Ten tiny ducklings."
</script>

In your node package.json:

"dependencies": {
  "humanize-plus": "^1.7.0"
}

For recent changes, see the changelog.

API Methods

Numbers

formatNumber

Formats a number to a human-readable string. Localize by overriding the precision, thousand and decimal arguments.

Humanize.formatNumber(123456789, 2)
// "123,456,789.00"

intComma

Converts an integer to a string containing commas every three digits.

Humanize.intComma(123456789)
// "123,456,789"

intcomma - DEPRECATED - This method will not be present in the next major version.

Alias for intComma

intword - DEPRECATED - This method will not be present in the next major version.

Converts a large integer to a friendly text representation. This method is now a thin wrapper around compactInteger

Humanize.intword(num, ch, de) === Humanize.compactInteger(num, de)

Humanize.intword(123456789, 'nopnopnopnop', 1)
// "123.5M"

Humanize.intword(123456789, 'this is a nop', 3)
// "123.457M"

Humanize.intword(10, 'still a nop', 1)
// "10"

compactInteger

Converts an integer into its most compact representation. Decimal precision is ignored for all integers, n, such that abs(n) < 1000.

Humanize.compactInteger(123456789, 1)
// "123.5M"

// Switch to scientific notation for trillons, because no one knows those abbreviations.
Humanize.compactInteger(-7832186132456328967, 4)
// "-7.8322x10^18"

Humanize.compactInteger(-100, 2)
// "-100"

boundedNumber

Bounds a value from above. Modified values have customizable ending strings ('+' by default)

Humanize.boundedNumber(110, 100)
// "100+"

Humanize.boundedNumber(50, 100)
// "50"

truncatenumber - DEPRECATED - This method will not be present in the next major version.

Alias for boundedNumber

ordinal

Converts an integer to its ordinal as a string.

Humanize.ordinal(22)
// "22nd"

times

Interprets numbers as occurences. Also accepts an optional array/map of overrides.

for (i=0; i<5; i++) {
  Humanize.times(i, {"4": "too many"});
  // Bonus!
  if (i === 1) {
    Humanize.times(1.1);
  }
}
// never
// once
// 1.1 times
// twice
// 3 times
// too many times

pace

Matches a pace (value and interval) with a logical time frame. Very useful for slow paces.

second = 1000
week = 6.048e8
decade = 3.156e11

Humanize.pace(1.5, second, "heartbeat")
// Approximately 2 heartbeats per second

Humanize.pace(4, week)
// Approximately 4 times per week

Humanize.pace(1, decade, "life crisis")
// Less than 1 life crisis per week

fileSize

Formats the value like a 'human-readable' file size (i.e. '13 KB', '4.1 MB', '102 bytes', etc).

Humanize.fileSize(1024 * 20)
// "20 Kb"

Humanize.fileSize(1024 * 2000)
// "1.95 Mb"

Humanize.fileSize(Math.pow(1000, 4))
// "931.32 Gb"

filesize - DEPRECATED - This method will not be present in the next major version.

Alias for fileSize

pluralize

Returns the plural version of a given word if the value is not 1. The default suffix is 's'.

Humanize.pluralize(1, "duck")
// "duck"

Humanize.pluralize(3, "duck")
// "ducks"

Humanize.pluralize(3, "duck", "duckies")
// "duckies"

Strings

truncate

Truncates a string if it is longer than the specified number of characters. Truncated strings will end with a translatable ellipsis sequence ("…").

Humanize.truncate('long text is good for you')
// "long text is good for you"

Humanize.truncate('long text is good for you', 19)
// "long text is goo..."

Humanize.truncate('long text is good for you', 19, '... etc')
// "long text is... etc"

truncateWords

Truncates a string after a certain number of words.

Humanize.truncateWords('long text is good for you', 5)
// "long text is good for ..."

truncatewords - DEPRECATED - This method will not be present in the next major version.

Alias for truncateWords

nl2br and br2nl

Flexible conversion of <br/> tags to newlines and vice versa.

// Use your imagination

capitalize

Capitalizes the first letter in a string, optionally downcasing the tail.

Humanize.capitalize("some boring string")
// "Some boring string"

Humanize.capitalize("wHoOaA!")
// "WHoOaA!"

Humanize.capitalize("wHoOaA!", true)
// "Whooaa!"

capitalizeAll

Captializes the first letter of every word in a string.

Humanize.capitalizeAll("some boring string")
// "Some Boring String"

titleCase

Intelligently capitalizes eligible words in a string and normalizes internal whitespace.

Humanize.titleCase("some of a boring string")
// "Some of a Boring String"

Humanize.titleCase("cool the          iTunes cake, O'Malley!")
// "Cool the iTunes Cake, O'Malley!"

titlecase - DEPRECATED - This method will not be present in the next major version.

Alias for titleCase

Arrays

oxford

Converts a list of items to a human readable string with an optional limit.

items = ['apple', 'orange', 'banana', 'pear', 'pineapple']

Humanize.oxford(items)
// "apple, orange, banana, pear, and pineapple"

Humanize.oxford(items, 3)
// "apple, orange, banana, and 2 others"

// Pluralizes properly too!
Humanize.oxford(items, 4)
// "apple, orange, banana, pear, and 1 other"

Humanize.oxford(items, 3, "and some other fruits")
// "apple, orange, banana, and some other fruits"

frequency

Describes how many times an item appears in a list

catPics = [
  'https://media2.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif',
  'https://media3.giphy.com/media/uzglgIsyY1Cgg/giphy.gif'
]
dogPics = []

"Cats " + Humanize.frequency(catPics, "typed on keyboards")
// "Cats typed on keyboards 3 times"

"Dogs " + Humanize.frequency(docPics, "typed on keyboards")
// "Dogs never typed on keyboards"

Utility methods

toFixed

Fixes binary rounding issues (eg. (0.615).toFixed(2) === "0.61").

Humanize.toFixed(0.615, 2)
// "0.62"

normalizePrecision

Ensures precision value is a positive integer.

Humanize.normalizePrecision(-232.231)
// 232

Important notes

Please don't edit files in the dist subdirectory as they are generated through compilation. You'll find source code in the src subdirectory!

Compiling

npm run install && npm run build

And that's it!

The project will compile the CoffeeScript files into the dist subdirectory.

Testing

npm run test

License

Copyright (c) 2013-2016 HubSpotDev Licensed under the MIT license.