Format Numbers, Dates, Bytes & Text - humanize-this

AuthorShuklax

Last UpdateOctober 28, 2026

LicenseMIT

Features

File sizes use 1024-based units with two decimal places.
Indian currency amounts use K, L, and Cr abbreviations.
Other built-in currencies use K, M, and B abbreviations.
Number grouping follows a configurable locale.
Duration and date helpers create readable time labels.
Text tools handle slugs, URL breadcrumbs, and word limits.
Global defaults control locale and currency selection.

How To Use It

Installation

Install the package in your JavaScript or TypeScript project:

npm install humanize-this

Basic Usage

import { bytes, currency, timeAgo } from 'humanize-this';
bytes(1048576);                          // "1.00 MB"
currency(150000);                        // "₹1.50L"
timeAgo(new Date(Date.now() - 300000));  // "5 min ago"

Load the Browser Module

You can also use the library directly in your HTML document:

<p>Attachment size: <span id="attachment-size"></span></p>
<script type="module">
  import { bytes } from 'https://cdn.jsdelivr.net/npm/humanize-this/+esm';
  document.querySelector('#attachment-size').textContent = bytes(1536);
  // Displays "1.50 KB"
</script>

Configure Number and Currency Formats

import { number, currency, setConfig, getConfig } from 'humanize-this';
setConfig({ locale: 'en-US', currency: 'USD' });
number(1234567);                     // "1,234,567"
currency(150000);                    // "$150.00K"
currency(150000, undefined, 'INR');  // "₹1.50L"
getConfig();
// { locale: 'en-US', currency: 'USD' }

The second currency() argument accepts a symbol such as $ or €. Specify the currency code as the third argument.

import { currency } from 'humanize-this';
currency(1500, '$', 'USD');        // "$1.50K"
currency(1500, undefined, 'EUR'); // "€1.50K"

Create Slugs and Breadcrumb Labels

import { slug, underscoreSlug, unSlug, words, url } from 'humanize-this';
slug('CSS & JavaScript Tools');           // "css-javascript-tools"
underscoreSlug('CSS & JavaScript Tools'); // "css_javascript_tools"
unSlug('css-javascript_tools');           // "css javascript tools"
words('One compact label for a long message', 4);
// "One compact label for..."
url('https://example.com/docs/getting-started');
// "example.com › docs › getting-started"

Complete Public API Reference

Number and Currency Functions

Function	Description
`bytes(input)`	Takes a non-negative numeric byte count and returns a string using powers of 1024 (`B` through `YB`). Results have two decimal places, except `bytes(0)` returns `"0 B"`.
`currency(num, localeOrSymbol?, currencyCode?)`	Formats a numeric amount using a symbol and compact suffix. The default currency is `INR`, with `K`, `L`, and `Cr` suffixes. Built-in `USD`, `EUR`, and `GBP` use `K`, `M`, and `B`. The optional second argument overrides the symbol when it matches the function’s symbol rules; it does not apply locale formatting. The third argument chooses the currency code.
`number(num, locale?)`	Formats a number using `toLocaleString()`. The optional locale overrides the configured default (`en-IN`).
`ordinal(n, locale?)`	Appends English ordinal suffixes (`st`, `nd`, `rd`, `th`) to an integer. The locale defaults to `en-IN`. Non-English locales return a fallback message rather than a localized ordinal.
`pluralize(word, count, locale?)`	Returns the count and the singular or plural form of a non-empty English word, including a fixed collection of irregular forms. The optional locale is accepted but does not change the English pluralization rules.

Time Functions

Function	Description
`time(seconds)`	Converts a non-negative numeric duration in seconds to `hr`, `min`, and `sec` parts. For example, `time(3661)` returns `"1 hr 1 min 1 sec"`.
`timeAgo(date, locale?)`	Accepts a valid past `Date` object. Values less than a minute old return `"just now"`; more recent dates under seven days use English relative labels. Dates at least seven days old use `toLocaleDateString()` with the supplied or configured locale. Future dates throw an error.
`diff(date1, date2)`	Returns the largest whole elapsed-time unit between two valid `Date` objects, regardless of their order. Uses 30-day months and 360-day years. The function has no locale argument.

Text Functions

Function	Description
`slug(str)`	Converts non-empty text to lowercase ASCII with hyphen separators.
`underscoreSlug(str)`	Converts non-empty text to lowercase ASCII with underscore separators.
`unSlug(str)`	Replaces hyphens and underscores with spaces and collapses extra spaces. Original capitalization is not restored.
`words(str, limit)`	Returns up to `limit` whitespace-separated words and adds `...` if the input is longer. The limit must be a non-negative number.
`url(urlString)`	Creates a hostname and path breadcrumb separated by `›`, removing query parameters and fragments. A missing protocol is treated as HTTPS. A root-only URL produces a trailing breadcrumb separator.

Configuration and Imports

Export	Description
`humanize`	Namespace containing all 13 formatting functions and both configuration helpers.
`getConfig()`	Returns a copy of the current configuration object `{ locale: string, currency: string }`. Initial values are `en-IN` and `INR`.
`setConfig(newConfig)`	Accepts an object with optional `locale` and `currency` string properties. Updates module-wide defaults and returns `void`.

Format Numbers, Dates, Bytes & Text – humanize-this