humanize-this

A lightweight, zero-dependency, tree-shakeable utility package that transforms machine-readable data into human-friendly formats. Perfect for dashboards, logs, CLIs, and user interfaces.

Features

All functions are available under the humanize namespace and can be imported individually:

1// Import everything
2import { humanize } from "humanize-this";
3
4// Or import specific functions (tree-shakeable)
5import { bytes, currency, timeAgo } from "humanize-this";

Number Formatting

bytes(number)

Format file sizes with appropriate units

1humanize.bytes(2048)      // "2 KB"
2humanize.bytes(1500000)   // "1.5 MB"
3humanize.bytes(1500000000) // "1.5 GB"

currency(number, symbol?, currencyCode?, locale?)

Smart currency formatting (locale-aware)

1// Indian currency (INR)
2humanize.currency(1500)        // "₹1.50K"
3humanize.currency(150000)      // "₹1.50L"
4humanize.currency(15000000)    // "₹1.50Cr"
5
6// Other currencies
7humanize.currency(1500, "$", "USD", "en-US")    // "$1.50K"
8humanize.currency(1500000, "€", "EUR", "de-DE") // "€1.50M"
9humanize.currency(1500000000, "£", "GBP", "en-GB") // "£1.50B"

number(number, locale?)

Format numbers with Indian or international digit grouping

1humanize.number(123456)           // "1,23,456"
2humanize.number(1234567, "en-US") // "1,234,567"
3humanize.number(1234567, "de-DE") // "1.234.567"

ordinal(number, locale?)

Add ordinal suffixes to numbers

1humanize.ordinal(1)        // "1st"
2humanize.ordinal(2)        // "2nd"
3humanize.ordinal(3)        // "3rd"
4humanize.ordinal(11)       // "11th"
5humanize.ordinal(2, "fr")  // "2e"

Time Formatting

time(seconds)

Convert seconds to human-readable time

1humanize.time(90)          // "1 min 30 sec"
2humanize.time(3600)        // "1 hr"
3humanize.time(3661)        // "1 hr 1 min 1 sec"

timeAgo(date, locale?)

Format relative time

1humanize.timeAgo(new Date())                    // "just now"
2humanize.timeAgo(Date.now() - 300000)           // "5 min ago"
3humanize.timeAgo(Date.now() - 3600000)          // "1 hr ago"
4humanize.timeAgo(Date.now() - 60000, "fr-FR")   // "il y a 1 minute"

diff(date1, date2, locale?)

Calculate time difference

1humanize.diff(new Date("2020"), new Date("2023"))           // "3 years"
2humanize.diff(new Date(), new Date(Date.now() - 86400000))  // "1 day"

Text Formatting

slug(string)

Convert text to URL-safe slugs

1humanize.slug("Hello World!")  // "hello-world"
2humanize.slug("Let's Code")    // "lets-code"

url(string)

Simplify URLs to clean breadcrumbs

1humanize.url("https://github.com/user/repo/path")  // "github.com › user › repo › path"

pluralize(word, count, locale?)

Smart pluralization (locale-aware)

1humanize.pluralize("apple", 1)        // "1 apple"
2humanize.pluralize("apple", 2)        // "2 apples"
3humanize.pluralize("box", 2)          // "2 boxes"
4humanize.pluralize("person", 2, "en") // "2 people"

words(string, limit)

Limit text by word count

1humanize.words("Hello world this is a test", 3)  // "Hello world this..."

Localization & i18n

All formatting functions in humanize-this support multiple locales using JavaScript's native Intl API.

Examples

1// Number formatting
2humanize.number(1234567, "en-US")  // "1,234,567"
3humanize.number(1234567, "de-DE")  // "1.234.567"
4
5// Currency formatting
6humanize.currency(1234.56, "$", "USD", "en-US")  // "$1.23K"
7humanize.currency(1234.56, "€", "EUR", "de-DE")  // "€1.23K"
8
9// Ordinal numbers
10humanize.ordinal(2, "en-US")  // "2nd"
11humanize.ordinal(2, "fr-FR")  // "2e"
12
13// Pluralization
14humanize.pluralize("person", 2, "en")  // "2 people"
15
16// Relative time
17humanize.timeAgo(Date.now() - 60000, "fr-FR")  // "il y a 1 minute"

You can also globally configure locale:

1import { humanizeConfig } from "humanize-this";
2humanizeConfig.locale = "fr-FR";

Installation

1npm install humanize-this
2# or
3pnpm add humanize-this
4# or
5yarn add humanize-this

Usage

1// Import everything
2import { humanize } from "humanize-this";
3
4// Or import only what you need (recommended for smaller bundles)
5import { bytes, currency, timeAgo } from "humanize-this";
6
7// Use the functions
8bytes(2048);           // "2 KB"
9currency(1500);        // "₹1.50K"
10timeAgo(new Date());   // "just now"

Key Features

• Zero Dependencies: Lightweight and fast
• Tree-Shakeable: Import only what you need, unused functions are removed from your bundle
• TypeScript Native: Full type support out of the box
• Consistent Formatting: Predictable output across all functions
• Indian Number System: Special support for Indian currency and number formatting
• Customizable: Flexible options for different use cases
• Error Handling: Graceful handling of invalid inputs
• Browser & Node.js: Works in both environments
• ESM & CommonJS: Supports both module systems

Bundle Size

The package is designed to be tree-shakeable, meaning you only pay for what you use. Here's an approximate size breakdown:

• Full package: ~5KB (minified + gzipped)
• Individual functions: ~0.5-1KB each (minified + gzipped)

Example of tree-shaking in action:

1// This import will only include the bytes function in your bundle
2import { bytes } from "humanize-this";
3
4// This import will only include bytes and currency
5import { bytes, currency } from "humanize-this";

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Feedbacks are most welcome! Feel free to write to me at Shuklax@proton.me

License

MIT © Shuklax