0.1.2 • Published 8 months ago

formaticajs v0.1.2

Weekly downloads
-
License
MIT
Repository
-
Last release
8 months ago

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.

formatinternationali18nphonewhatsappcurrencydateformatterconverterlocale
date-fnsdate-fns-tz
0.1.2

8 months ago

0.1.1

8 months ago

0.1.0

8 months ago

0.0.3

8 months ago