Formatica.js

Elegant international format converter with a fluent API. Format phone numbers (with WhatsApp support), currencies, dates, and more across 20+ countries.

Features

• 🌏 Support for 20+ countries
• 📱 Phone number formatting with WhatsApp integration
• 💰 Currency formatting with local conventions
• 📅 Date formatting with localization
• 🔄 Fluent, chainable API
• 🎯 Zero dependencies in browser bundle
• 📦 Support for ESM, CommonJS, and Browser

Installation

NPM (Recommended)

npm install formaticajs

Browser via CDN

<script src="https://unpkg.com/formaticajs/dist/formatica.min.js"></script>

Usage

ES Modules

import { Formatica } from 'formaticajs';

const fmt = new Formatica();

CommonJS

const { Formatica } = require('formaticajs');

const fmt = new Formatica();

Browser

<script src="https://unpkg.com/formaticajs/dist/formatica.min.js"></script>
<script>
  const fmt = new Formatica();
</script>

Examples

Phone Numbers

const phone = fmt.getPhone('8012345678').toJapan();
console.log(phone.value);             // "80-1234-5678"
console.log(phone.meta.countryCode);  // "+81"
console.log(phone.whatsapp.url);      // "https://wa.me/818012345678"

Currency

const price = fmt.getCurrency(1234.56).toFrance();
console.log(price.value);            // "1 234,56 €"
console.log(price.meta.currency);    // "EUR"

Dates

// Standard date format
const date = fmt.getDate('2023-10-15').toChina();
console.log(date.value);             // "2023年10月15日"
console.log(date.meta.timezone);     // "Asia/Shanghai"

// With time (datetime representation)
const datetime = fmt.getDate('2023-10-15', { 
  representation: 'datetime' 
}).toChina();
console.log(datetime.value);         // "2023年10月15日 00:00:00"

// Different countries
fmt.getDate('2023-10-15').toUSA()              // "10/15/2023"
fmt.getDate('2023-10-15').toGermany()          // "15.10.2023"
fmt.getDate('2023-10-15').toJapan()            // "2023年10月15日"

// With time for different countries
fmt.getDate('2023-10-15', { 
  representation: 'datetime' 
}).toGermany()                                 // "15.10.2023 00:00:00"

Return Object Structure

All formatting methods return a consistent object structure:

{
  "value": String,           // The formatted value
  "meta": {                  // Metadata about the formatting
    "locale": String,        // e.g., "en-US", "ja-JP"
    "currency": String,      // e.g., "USD", "EUR" (for currency formatting)
    "timezone": String,      // e.g., "America/New_York" (for date formatting)
    "countryCode": String    // e.g., "+1", "+81" (for phone formatting)
  },
  "whatsapp": {             // Only for phone numbers
    "number": String,        // Full international format
    "url": String           // WhatsApp click-to-chat URL
  }
}

Supported Countries

Phone Number Formatting

• 🇺🇸 United States
• 🇯🇵 Japan
• 🇨🇳 China
• 🇫🇷 France
• 🇩🇪 Germany
• 🇬🇧 United Kingdom
• 🇮🇩 Indonesia
• 🇮🇳 India
• And more...

Currency Formatting

• USD (US Dollar)
• EUR (Euro)
• JPY (Japanese Yen)
• CNY (Chinese Yuan)
• GBP (British Pound)
• And more...

Date Formatting

• US format (MM/DD/YYYY)
• European format (DD/MM/YYYY)
• Asian format (YYYY年MM月DD日)
• ISO format (YYYY-MM-DD)
• And more...

API Reference

Quick Examples

const fmt = new Formatica();

// Phone numbers with WhatsApp
fmt.getPhone('8012345678').toJapan()
// Returns: { 
//   value: "80-1234-5678",
//   whatsapp: { url: "https://wa.me/818012345678" }
// }

// Currency with local format
fmt.getCurrency(1234.56).toFrance()
// Returns: { value: "1 234,56 €" }

// Dates with localization
fmt.getDate('2023-10-15').toChina()
// Returns: { value: "2023年10月15日" }

Phone Numbers

Format phone numbers with WhatsApp support for any country:

// Basic formatting
fmt.getPhone('8012345678').toJapan()
// "80-1234-5678"

// With country code
fmt.getPhone('8012345678', { includeCountryCode: true }).toJapan()
// "+81 80-1234-5678"

// WhatsApp ready format
fmt.getPhone('8012345678', { format: 'whatsapp' }).toJapan()
// "+818012345678"

// Get WhatsApp click-to-chat URL
const phone = fmt.getPhone('8012345678').toJapan();
phone.whatsapp.url  // "https://wa.me/818012345678"

Options:

• format: 'standard' (default), 'whatsapp', or 'e164'
• includeCountryCode: true/false (default: false)
• removeSpaces: true/false (default: false)

Currency

Format monetary values according to local conventions:

// Basic currency formatting
fmt.getCurrency(1234.56).toFrance()
// "1 234,56 €"

// Without decimals
fmt.getCurrency(1234.56, { minimumFractionDigits: 0 }).toJapan()
// "¥1,235"

// Compact notation for large numbers
fmt.getCurrency(1234567).toUSA({ notation: 'compact' })
// "$1.2M"

Options:

• minimumFractionDigits: number (default: 2)
• maximumFractionDigits: number (default: 2)
• notation: 'standard' (default) or 'compact'
• grouping: true/false (default: true)

Dates

Format dates in local styles with timezone support:

// Standard date format
const date = fmt.getDate('2023-10-15').toChina();
console.log(date.value);             // "2023年10月15日"
console.log(date.meta.timezone);     // "Asia/Shanghai"

// With time (datetime representation)
const datetime = fmt.getDate('2023-10-15', { 
  representation: 'datetime' 
}).toChina();
console.log(datetime.value);         // "2023年10月15日 00:00:00"

// Different countries
fmt.getDate('2023-10-15').toUSA()              // "10/15/2023"
fmt.getDate('2023-10-15').toGermany()          // "15.10.2023"
fmt.getDate('2023-10-15').toJapan()            // "2023年10月15日"

// With time for different countries
fmt.getDate('2023-10-15', { 
  representation: 'datetime' 
}).toGermany()                                 // "15.10.2023 00:00:00"

Options:

• format: date-fns format string
• representation: 'date' (default), 'time', or 'datetime'
• timezone: IANA timezone (e.g., 'Asia/Tokyo')
• weekStartsOn: 0 (Sunday) or 1 (Monday)

Date Formatting Options

Representation Types

• standard: Default format for dates (e.g., "2023年10月15日", "15.10.2023")
• datetime: Date with time (e.g., "2023年10月15日 00:00:00")
• short: Shorter date format (e.g., "23-10-15", "15.10.23")

Country-Specific Formats

East Asia

• 🇯🇵 Japan
  • Standard: "yyyy年MM月dd日"
  • Datetime: "yyyy年MM月dd日 HH:mm:ss"
• 🇨🇳 China
  • Standard: "yyyy年MM月dd日"
  • Datetime: "yyyy年MM月dd日 HH:mm:ss"
• 🇰🇷 Korea
  • Standard: "yyyy년MM월dd일"
  • Datetime: "yyyy년MM월dd일 HH:mm:ss"

Europe

• 🇩🇪 Germany
  • Standard: "dd.MM.yyyy"
  • Datetime: "dd.MM.yyyy HH:mm:ss"
• 🇫🇷 France
  • Standard: "dd/MM/yyyy"
  • Datetime: "dd/MM/yyyy HH:mm:ss"

Americas

• 🇺🇸 USA
  • Standard: "MM/dd/yyyy"
  • Datetime: "MM/dd/yyyy HH:mm:ss"
• 🇧🇷 Brazil
  • Standard: "dd/MM/yyyy"
  • Datetime: "dd/MM/yyyy HH:mm:ss"

All date formats respect the country's timezone and locale settings.

Utility Functions

Helper methods to work with countries and formats:

// Get list of supported countries
fmt.getSupportedCountries()
// ["USA", "Japan", "France", ...]

// Check if a country is supported
fmt.isCountrySupported('Japan')  // true
fmt.isCountrySupported('Mars')   // false

// Get country settings
fmt.getCountryConfig('Japan')
// {
//   locale: "ja-JP",
//   currency: "JPY",
//   timezone: "Asia/Tokyo"
// }

Method Chaining

Chain methods for more complex formatting:

// Phone formatting with multiple options
fmt.getPhone('8012345678')
  .removeSpaces()           // Remove spaces
  .addCountryCode()         // Add +81
  .toJapan();              // Format for Japan

// Currency with specific settings
fmt.getCurrency(1234.56)
  .withDecimals(0)         // No decimals
  .useGrouping(true)       // Use thousand separators
  .toFrance();             // Format for France

Error Handling

Handle formatting errors gracefully:

try {
  fmt.getPhone('invalid').toJapan();
} catch (error) {
  if (error.name === 'FormaticaError') {
    console.log(error.message);  // "Invalid phone number format"
  }
}

Common error codes:

• INVALID_PHONE: Invalid phone number format
• INVALID_COUNTRY: Unsupported country
• INVALID_FORMAT: Invalid format option
• INVALID_DATE: Invalid date string

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.