I18n Formatter Utility

A comprehensive TypeScript utility library for internationalization (i18n) formatting using the native Intl API. This package provides easy-to-use functions for formatting dates, numbers, currencies, and more with full locale support.

Features

• 🌍 Full Locale Support: Uses native Intl API for accurate locale-specific formatting
• 📅 Date & Time Formatting: Comprehensive date, time, and datetime formatting
• 💰 Currency & Numbers: Format currencies, percentages, and numbers with locale awareness
• 📏 File Sizes & Units: Human-readable file sizes and temperature formatting
• ⏱️ Relative Time: "2 hours ago", "in 3 days" style formatting
• 🔧 Utility Functions: Phone masking, email masking, text formatting, and more
• 📦 Zero Dependencies: Built on native browser APIs
• 🏷️ TypeScript Support: Full type definitions included

Installation

npm install simple-formatter-utility

Quick Start

import {
  formatDate,
  formatCurrency,
  formatNumber,
  formatRelativeTime,
} from "simple-formatter-utility";

// Basic usage with default locale (en-US)
console.log(formatDate(new Date())); // "12/25/2023"
console.log(formatCurrency(1234.56, "USD")); // "$1,234.56"
console.log(formatNumber(1234567.89)); // "1,234,567.89"
console.log(formatRelativeTime(new Date(Date.now() - 3600000))); // "1 hour ago"

// With custom locale
console.log(formatDate(new Date(), "id-ID")); // "25/12/2023"
console.log(formatCurrency(1234.56, "IDR", "id-ID")); // "Rp1.234,56"

API Reference

Date & Time Formatting

formatDate(date, locale?, options?)

Formats a date using Intl.DateTimeFormat.

formatDate(new Date(), "en-US"); // "12/25/2023"
formatDate("2023-12-25", "id-ID"); // "25/12/2023"

formatTime(date, locale?, options?)

Formats time only.

formatTime(new Date(), "en-US"); // "2:30 PM"
formatTime("2023-12-25T14:30:00", "id-ID"); // "14.30"

formatDateTime(date, locale?, options?)

Formats date and time together.

formatDateTime(new Date()); // "December 25, 2023 at 2:30:00 PM"

formatISODate(date)

Returns date in YYYY-MM-DD format.

formatISODate(new Date()); // "2023-12-25"

formatISODateTime(date)

Returns datetime in YYYY-MM-DD HH:MM:SS format.

formatISODateTime(new Date()); // "2023-12-25 14:30:00"

formatWeekday(date, locale?, format?)

Returns the weekday name.

formatWeekday("2023-12-25"); // "Monday"
formatWeekday("2023-12-25", "id-ID"); // "Senin"

formatMonth(date, locale?, format?)

Returns the month name.

formatMonth("2023-12-25"); // "December"
formatMonth("2023-12-25", "id-ID"); // "Desember"

formatQuarter(date)

Returns quarter (Q1, Q2, Q3, Q4).

formatQuarter("2023-12-25"); // "Q4"

formatWeekNumber(date)

Returns ISO week number.

formatWeekNumber("2023-12-25"); // 52

formatDayOfYear(date)

Returns day of year (1-366).

formatDayOfYear("2023-12-25"); // 359

Relative Time & Duration

formatRelativeTime(date, baseDate?, locale?)

Formats relative time like "2 hours ago".

formatRelativeTime(new Date(Date.now() - 3600000)); // "1 hour ago"
formatRelativeTime(new Date(Date.now() + 86400000)); // "in 1 day"

formatTimeAgo(date, locale?)

Similar to formatRelativeTime, optimized for past dates.

formatTimeAgo("2023-12-24T14:30:00Z"); // "1 day ago"

formatTimeAgoDetailed(date, locale?)

Detailed time ago with multiple units.

formatTimeAgoDetailed(new Date(Date.now() - 90000000)); // "1 day 1 hour ago"

formatDuration(seconds)

Formats seconds into HH:MM:SS.

formatDuration(3661); // "01:01:01"

formatElapsedTime(seconds)

Formats seconds into human-readable duration.

formatElapsedTime(3661); // "1h 1m 1s"

formatRelativeDuration(start, end)

Calculates and formats duration between two dates.

formatRelativeDuration("2023-12-24", "2023-12-25"); // "1d"

Numbers & Currency

formatNumber(number, locale?, options?)

Formats numbers with locale-specific separators.

formatNumber(1234567.89, "en-US"); // "1,234,567.89"
formatNumber(1234567.89, "id-ID"); // "1.234.567,89"

formatCurrency(amount, currency?, locale?)

Formats currency amounts.

formatCurrency(1234.56, "USD", "en-US"); // "$1,234.56"
formatCurrency(1234.56, "IDR", "id-ID"); // "Rp1.234,56"

formatPercent(value, locale?)

Formats percentages.

formatPercent(0.85, "en-US"); // "85%"
formatPercent(0.85, "id-ID"); // "85%"

formatCompactNumber(number, locale?, options?)

Formats numbers in compact notation (1.2K, 1.5M).

formatCompactNumber(1250); // "1.3K"
formatCompactNumber(1500000, "id-ID"); // "1,5 jt"

formatOrdinalNumber(number, locale?)

Adds ordinal suffixes (1st, 2nd, 3rd).

formatOrdinalNumber(1); // "1st"
formatOrdinalNumber(22); // "22nd"

File Sizes & Units

formatFileSize(bytes, locale?)

Formats bytes into human-readable file sizes.

formatFileSize(1024); // "1 KB"
formatFileSize(1048576); // "1 MB"

formatFileSizeSI(bytes)

Formats using SI units (1000-based).

formatFileSizeSI(1000); // "1.00 KB"

formatTemperature(value, unit?, locale?)

Formats temperature with units.

formatTemperature(25); // "25°C"
formatTemperature(77, "fahrenheit"); // "77°F"

Time Zones

formatTimeZone(date, timeZone, locale?, options?)

Formats date in specific time zone.

formatTimeZone("2023-12-25T10:00:00Z", "Asia/Jakarta"); // "Dec 25, 2023, 17:00"

formatTimezoneOffset(date?)

Returns timezone offset (UTC+X:XX).

formatTimezoneOffset(); // "UTC+07:00"

getUserTimezone()

Returns user's current timezone.

getUserTimezone(); // "Asia/Jakarta"

convertTimezone(date, timeZone)

Converts date to different timezone.

convertTimezone(new Date(), "America/New_York");

Text & Utility Formatting

formatPhone(phone)

Basic phone number formatting.

formatPhone("081234567890"); // "081-234-567890"

formatBoolean(value, yes?, no?)

Formats boolean to text.

formatBoolean(true); // "Yes"
formatBoolean(false, "Ya", "Tidak"); // "Tidak"

formatRgbToHex(r, g, b)

Converts RGB to hex color.

formatRgbToHex(255, 0, 0); // "#FF0000"

formatCapitalize(text)

Capitalizes first letter.

formatCapitalize("hello world"); // "Hello world"

formatTitleCase(text)

Converts to title case.

formatTitleCase("hello world"); // "Hello World"

formatSlug(text)

Creates URL-friendly slug.

formatSlug("Hello World!"); // "hello-world"

formatTruncate(text, maxLength?, suffix?)

Truncates text with suffix.

formatTruncate("This is a long text", 10); // "This is a …"

formatInitials(name, max?)

Extracts initials from name.

formatInitials("John Doe Smith"); // "JD"

formatMaskEmail(email)

Masks email for privacy.

formatMaskEmail("[email protected]"); // "j***[email protected]"

formatMaskPhone(phone, visible?)

Masks phone number.

formatMaskPhone("081234567890", 4); // "****67890"

formatJsonPretty(value, space?)

Pretty-prints JSON.

formatJsonPretty({ name: "John", age: 30 }, 2);

Date Ranges & Calculations

formatDateRange(start, end, locale?)

Formats date range.

formatDateRange("2023-12-24", "2023-12-25"); // "Dec 24, 2023 - Dec 25, 2023"

formatAge(birthDate)

Calculates age from birth date.

formatAge("1990-12-25"); // 33 (depending on current date)

Parsing Functions

parseCurrency(value, locale?)

Parses formatted currency string to number.

parseCurrency("$1,234.56"); // 1234.56

parseNumber(value)

Parses formatted number string to number.

parseNumber("1,234.56"); // 1234.56

parseBoolean(value)

Parses various formats to boolean.

parseBoolean("true"); // true
parseBoolean("1"); // true

Utility Functions

formatTwoDigit(number)

Pads number with leading zero.

formatTwoDigit(5); // "05"

formatClampNumber(value, min, max)

Clamps number within range.

formatClampNumber(15, 0, 10); // 10

Examples

Multi-language Support

import {
  formatCurrency,
  formatDate,
  formatNumber,
} from "simple-formatter-utility";

const amount = 1234567.89;
const date = new Date();

console.log("English:", formatCurrency(amount, "USD", "en-US")); // "$1,234,567.89"
console.log("Indonesian:", formatCurrency(amount, "IDR", "id-ID")); // "Rp1.234.567,89"
console.log("German:", formatCurrency(amount, "EUR", "de-DE")); // "1.234.567,89 €"

console.log("English date:", formatDate(date, "en-US")); // "12/25/2023"
console.log("Indonesian date:", formatDate(date, "id-ID")); // "25/12/2023"
console.log("Japanese date:", formatDate(date, "ja-JP")); // "2023/12/25"

Building a User Profile Display

import {
  formatDate,
  formatAge,
  formatInitials,
  formatMaskEmail,
  formatCapitalize,
} from "simple-formatter-utility";

const user = {
  firstName: "john",
  lastName: "doe",
  email: "[email protected]",
  birthDate: "1990-05-15",
  joinDate: "2020-03-10",
};

console.log(`Welcome ${formatInitials(`${user.firstName} ${user.lastName}`)}!`);
console.log(
  `Name: ${formatCapitalize(user.firstName)} ${formatCapitalize(user.lastName)}`,
);
console.log(`Age: ${formatAge(user.birthDate)}`);
console.log(`Email: ${formatMaskEmail(user.email)}`);
console.log(
  `Member since: ${formatDate(user.joinDate, "en-US", { year: "numeric", month: "long" })}`,
);

File Upload Progress

import { formatFileSize, formatElapsedTime } from "simple-formatter-utility";

function displayUploadProgress(
  uploadedBytes: number,
  totalBytes: number,
  elapsedSeconds: number,
) {
  const percentage = ((uploadedBytes / totalBytes) * 100).toFixed(1);
  const speed = uploadedBytes / elapsedSeconds;

  console.log(
    `Uploaded: ${formatFileSize(uploadedBytes)} / ${formatFileSize(totalBytes)} (${percentage}%)`,
  );
  console.log(`Time elapsed: ${formatElapsedTime(elapsedSeconds)}`);
  console.log(`Speed: ${formatFileSize(speed)}/s`);
}

Browser Support

This library uses the native Intl API which is supported in all modern browsers:

• Chrome 24+
• Firefox 29+
• Safari 10+
• Edge 12+

For older browsers, consider using a polyfill like intl-polyfill.

What's Next

Potential next features for this utility library:

1. createFormatter() factory for setting default locale, timeZone, and currency once
2. More robust locale-aware parsing for parseCurrency() and parseNumber()
3. Safer helpers like isValidDate(), safeParseDate(), and safeFormatDate()
4. Native formatDateRange() support using Intl.DateTimeFormat.formatRange()
5. Expanded timezone utilities like listAvailableTimeZones() and getTimezoneOffsetString()
6. Configurable duration formatting for short, long, and compact output
7. Better international support for ordinals, phone formatting, and slug transliteration
8. Batch formatting helpers for arrays of dates, numbers, and currencies

Pick one of these and I can help implement it next.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Repository

https://github.com/fajriyan/simple-formatter-utility

Thanks!