@verzonix/conversion v0.0.13

Verzonix Conversion

Verzonix Conversion is a TypeScript-based React library that provides localized conversion and formatting utilities for currency, dates, numbers, percentages, phone numbers, and geographical data (countries, states, and cities).

Note:
The library supports the following locales: en-US, en-GB, and en-IN.
The locale is determined by: 1. navigator.language 2. A local storage key: LOCALIZATION_STORAGE_KEY 3. A language prop passed to the ConversionProvider

Important: Ensure that the options used for formatting match those used for parsing.

Table of Contents

• Installation
• Usage
  • 1. Number Formatting
  • 2. Percentage Formatting
  • 3. Currency Formatting
  • 4. Date and Time Formatting
  • 5. Phone Number Formatting
  • 6. Geographical Data
    • Country Functions
    • State Functions
    • City Functions
    • Additional Helpers (Readers)
• License

Installation

To install Verzonix Conversion in your project, run:

# Using npm
npm install verzonix-conversion

# Or using Yarn
yarn add verzonix-conversion

Usage

After installation, import and use the conversion functions in your React components. Both formatters and parsers are provided.

The locale is determined from: 1. navigator.language 2. Local storage key: LOCALIZATION_STORAGE_KEY 3. The language prop passed to the ConversionProvider

1. Number Formatting

Functions

FormatNumberExtraParams

Usage Example

import { getFormattedNumber, getParsedFormattedNumber } from '@verzonix/conversion';

const value = 1234567.89;
const options = { decimalPlaces: 2, useGrouping: true };

const formattedNumber = getFormattedNumber(value, options);
console.log(formattedNumber); // e.g., "1,234,567.89"

const parsedNumber = getParsedFormattedNumber(formattedNumber, options);
console.log(parsedNumber); // 1234567.89

2. Percentage Formatting

Functions

FormatPercentageOptions

Usage Example

import { getFormattedPercentage, getParsedPercentage } from '@verzonix/conversion';

const value = 0.1234;
const options = { decimalPlaces: 2, useGrouping: true };

const formattedPercentage = getFormattedPercentage(value, options);
console.log(formattedPercentage); // "12.34%"

const parsedPercentage = getParsedPercentage(formattedPercentage, options);
console.log(parsedPercentage); // 0.1234

3. Currency Formatting

Functions

FormatCurrencyExtraParams

Usage Example

import { getFormattedCurrency, getParsedFormattedCurrency, getCurrencySymbol } from '@verzonix/conversion';

const value = 1234.56;
const options = { decimalPlaces: 2, useGrouping: true };

const formattedCurrency = getFormattedCurrency(value, options);
console.log(formattedCurrency); // e.g., "$1,234.56"

const parsedCurrency = getParsedFormattedCurrency(formattedCurrency, options);
console.log(parsedCurrency); // 1234.56

const currencySymbol = getCurrencySymbol();
console.log(currencySymbol); // e.g., "$"

4. Date and Time Formatting

Functions

FormatDateAndTimeExtraParams

Usage Example

import { getFormattedDateAndTime, getTimeStampFromDateString } from '@verzonix/conversion';

const date = new Date('2023-05-15T14:30:00');
const options = { showDate: true, showTime: true, is12Hour: true, showSeconds: true };

const formattedDate = getFormattedDateAndTime(date, options);
console.log(formattedDate); // e.g., "Monday, May 15, 2023, 2:30:00 PM"

const timestamp = getTimeStampFromDateString('2023-05-15T14:30:00');
console.log(timestamp); // e.g., 1684159800000

5. Phone Number Formatting

Functions

FormatPhoneNumberOptions

ParsedPhoneNumber Structure

Usage Example

import { getFormattedPhoneNumber, getParsedPhoneNumber, getDefaultCountryCode, PHONE_NUMBER_FORMAT_TYPE } from '@verzonix/conversion';

const phoneNumber = '1234567890';
const options = { formatType: PHONE_NUMBER_FORMAT_TYPE.NATIONAL };

const formattedPhoneNumber = getFormattedPhoneNumber(phoneNumber, options);
console.log(formattedPhoneNumber); // e.g., { countryCode: '1', phoneNumber: '2345678901' }

const parsedPhoneNumber = getParsedPhoneNumber(formattedPhoneNumber, options);
console.log(parsedPhoneNumber);
// e.g., { countryCode: '1', nationalNumber: '2345678901', extension: undefined, regionCode: 'US' }

const defaultCountryCode = getDefaultCountryCode();
console.log(defaultCountryCode); // e.g., "US"

6. Geographical Data

These functions leverage the country-state-city npm package to provide country, state, and city data.

Country Functions

Usage Example:

import { Country } from "country-state-city";

const countries = Country.getAllCountries();
console.log("Countries:", countries);
// Sample Output:
// [
//   {
//     name: "United States",
//     isoCode: "US",
//     phonecode: "1",
//     flag: "🇺🇸",
//     currency: "USD",
//     latitude: "38.0000",
//     longitude: "-97.0000"
//   },
//   ...more countries
// ]

const country = Country.getCountryByCode("US");
console.log("Country (US):", country);
// Sample Output:
// {
//   name: "United States",
//   isoCode: "US",
//   phonecode: "1",
//   flag: "🇺🇸",
//   currency: "USD",
//   latitude: "38.0000",
//   longitude: "-97.0000"
// }

State Functions

Usage Example:

import { State } from "country-state-city";

const states = State.getStatesOfCountry("US");
console.log("States in US:", states);
// Sample Output:
// [
//   {
//     name: "California",
//     isoCode: "CA",
//     countryCode: "US",
//     latitude: "36.7783",
//     longitude: "-119.4179"
//   },
//   ...more states
// ]

const state = State.getStateByCodeAndCountry("US", "CA");
console.log("State CA in US:", state);
// Sample Output:
// {
//   name: "California",
//   isoCode: "CA",
//   countryCode: "US",
//   latitude: "36.7783",
//   longitude: "-119.4179"
// }

City Functions

Usage Example:

import { City } from "country-state-city";

const citiesCountry = City.getCitiesOfCountry("US");
console.log("Cities in US:", citiesCountry);
// Sample Output:
// [
//   {
//     name: "New York City",
//     stateCode: "NY",
//     countryCode: "US",
//     latitude: "40.7128",
//     longitude: "-74.0060"
//   },
//   ...more cities
// ]

const citiesState = City.getCitiesOfState("US", "CA");
console.log("Cities in CA, US:", citiesState);
// Sample Output:
// [
//   {
//     name: "Los Angeles",
//     stateCode: "CA",
//     countryCode: "US",
//     latitude: "34.0522",
//     longitude: "-118.2437"
//   },
//   ...more cities
// ]

Additional Helpers (Readers)

Readers are helper functions that extract specific data fields from the raw geographical data.

Example Implementation:

// Extract key fields from a Country object
COUNTRY_READER 

// Extract key fields from a State object
STATE_READER 

// Extract key fields from a City object
CITY_READER

// For example, to extract time zone info (if available)
TIME_ZONE_READER

Usage Example:

import { COUNTRY_READER, STATE_READER, CITY_READER } from './yourHelpersModule';
import { Country, State, City } from "country-state-city";

const country = Country.getCountryByCode("US");
console.log("Country Data: Name", COUNTRY_READER.name(country));

const state = State.getStateByCodeAndCountry("US", "CA");
console.log("State Data: isoCode", STATE_READER.isoCode(state));

const cities = City.getCitiesOfState("US", "CA");
if (cities.length > 0) {
  console.log("City Data: countryCode", CITY_READER.countryCode(cities[0]));
}

License

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