utilitify-core 1.0.0

package/dist/index-Cl26FrAZ.d.ts

@@ -0,0 +1,362 @@
+/**
+ * Country information interface
+ */
+interface Country {
+    /** Country name */
+    name: string;
+    /** Official country name */
+    officialName?: string;
+    /** ISO 3166-1 alpha-2 code */
+    alpha2: string;
+    /** ISO 3166-1 alpha-3 code */
+    alpha3: string;
+    /** ISO 3166-1 numeric code */
+    numeric: string;
+    /** Continent */
+    continent: string;
+    /** Capital city */
+    capital?: string;
+    /** Languages spoken */
+    languages: string[];
+    /** Currency code */
+    currency: string;
+    /** Dialing code */
+    dialCode: string;
+    /** Flag emoji */
+    flag: string;
+}
+/**
+ * Currency information
+ */
+interface CurrencyInfo {
+    /** ISO 4217 currency code */
+    code: string;
+    /** Currency symbol */
+    symbol: string;
+    /** Currency name */
+    name: string;
+    /** Number of decimal places */
+    decimals: number;
+    /** Symbol position */
+    symbolPosition: 'before' | 'after';
+    /** Thousands separator */
+    thousandsSeparator: string;
+    /** Decimal separator */
+    decimalSeparator: string;
+}
+/**
+ * Timezone information
+ */
+interface TimezoneInfo {
+    /** IANA timezone name */
+    name: string;
+    /** UTC offset in hours */
+    offset: number;
+    /** UTC offset string (e.g., "+05:00") */
+    offsetString: string;
+    /** Whether DST is currently active */
+    isDST: boolean;
+    /** Abbreviation (e.g., "PST", "EST") */
+    abbreviation: string;
+}
+/**
+ * Phone format information by country
+ */
+interface PhoneFormat {
+    /** Country code */
+    countryCode: string;
+    /** Dialing code with + */
+    dialCode: string;
+    /** National number length(s) */
+    lengths: number[];
+    /** Mobile prefixes */
+    mobilePrefixes: string[];
+    /** Landline prefixes */
+    landlinePrefixes: string[];
+    /** Format pattern */
+    pattern: string;
+    /** Example number */
+    example: string;
+    /** Area codes for NANP countries (US, Canada, Caribbean) */
+    areaCodes?: string[];
+}
+/**
+ * Country code conversion types
+ */
+type CountryCodeFormat = 'alpha2' | 'alpha3' | 'numeric';
+
+/**
+ * Get country by alpha-2 code (e.g., "US", "PK")
+ *
+ * @param code - ISO 3166-1 alpha-2 code
+ * @returns Country or null
+ */
+declare function getCountryByAlpha2(code: string): Country | null;
+/**
+ * Get country by alpha-3 code (e.g., "USA", "PAK")
+ *
+ * @param code - ISO 3166-1 alpha-3 code
+ * @returns Country or null
+ */
+declare function getCountryByAlpha3(code: string): Country | null;
+/**
+ * Get country by numeric code (e.g., "840", "586")
+ *
+ * @param code - ISO 3166-1 numeric code
+ * @returns Country or null
+ */
+declare function getCountryByNumeric(code: string | number): Country | null;
+/**
+ * Get country by any code format (alpha-2, alpha-3, or numeric)
+ *
+ * @param code - Country code in any format (e.g., 'US', 'USA', '840')
+ * @returns Country object with details or null if not found
+ *
+ * @example
+ * ```typescript
+ * getCountry('US');   // returns { name: 'United States', ... }
+ * getCountry('USA');  // returns { name: 'United States', ... }
+ * getCountry(840);    // returns { name: 'United States', ... }
+ * ```
+ */
+declare function getCountry(code: string | number): Country | null;
+/**
+ * Convert country code between formats
+ *
+ * @param code - Source country code
+ * @param to - Target format
+ * @returns Converted code or null
+ */
+declare function convertCountryCode(code: string | number, to: CountryCodeFormat): string | null;
+/**
+ * Get all countries
+ *
+ * @returns Array of all countries
+ */
+declare function getAllCountries(): Country[];
+/**
+ * Get countries by continent
+ *
+ * @param continent - Continent name
+ * @returns Array of countries
+ */
+declare function getCountriesByContinent(continent: string): Country[];
+/**
+ * Get countries by language
+ *
+ * @param language - Language code
+ * @returns Array of countries
+ */
+declare function getCountriesByLanguage(language: string): Country[];
+/**
+ * Search countries by name
+ *
+ * @param query - Search query
+ * @returns Array of matching countries
+ */
+declare function searchCountries(query: string): Country[];
+/**
+ * Check if country code is valid
+ *
+ * @param code - Country code
+ * @returns true if valid
+ */
+declare function isValidCountryCode(code: string | number): boolean;
+
+/**
+ * Get all timezones for a country
+ *
+ * @param countryCode - ISO country code
+ * @returns Array of timezone names
+ */
+declare function getTimezonesByCountry(countryCode: string): string[];
+/**
+ * Get default timezone for a country
+ *
+ * @param countryCode - ISO country code
+ * @returns Default timezone or null
+ */
+declare function getDefaultTimezone(countryCode: string): string | null;
+/**
+ * Get current time in a country's timezone
+ *
+ * @param countryCode - ISO country code
+ * @returns Date in country's timezone
+ */
+declare function getCurrentTimeInCountry(countryCode: string): Date | null;
+/**
+ * Get timezone offset for a country
+ *
+ * @param countryCode - ISO country code
+ * @returns Offset string (e.g., "+05:00") or null
+ */
+declare function getTimezoneOffset(countryCode: string): string | null;
+/**
+ * Convert time between timezones
+ *
+ * @param date - Date to convert
+ * @param fromCountry - Source country code
+ * @param toCountry - Target country code
+ * @returns Converted date or null
+ */
+declare function convertTimeBetweenCountries(date: Date, _fromCountry: string, toCountry: string): Date | null;
+/**
+ * Format time for a specific timezone
+ *
+ * @param date - Date to format
+ * @param countryCode - Country code
+ * @param options - Intl.DateTimeFormat options
+ * @returns Formatted time string
+ */
+declare function formatTimeForCountry(date: Date, countryCode: string, options?: Partial<Intl.DateTimeFormatOptions>): string;
+
+/**
+ * Get currency info by currency code
+ *
+ * @param currencyCode - ISO 4217 currency code
+ * @returns Currency info or null
+ */
+declare function getCurrency(currencyCode: string): CurrencyInfo | null;
+/**
+ * Get currency by country code
+ *
+ * @param countryCode - ISO country code
+ * @returns Currency info or null
+ */
+declare function getCurrencyByCountry(countryCode: string): CurrencyInfo | null;
+/**
+ * Format currency amount
+ *
+ * @param amount - Amount to format
+ * @param currencyCode - Currency code or country code
+ * @returns Formatted currency string
+ */
+declare function formatCurrency(amount: number, currencyCode: string): string;
+/**
+ * Parse currency string to number
+ *
+ * @param value - Currency string
+ * @param currencyCode - Currency code
+ * @returns Parsed number or NaN
+ */
+declare function parseCurrency(value: string, currencyCode: string): number;
+/**
+ * Get all supported currencies
+ *
+ * @returns Array of currency info
+ */
+declare function getAllCurrencies(): CurrencyInfo[];
+/**
+ * Get currency symbol
+ *
+ * @param currencyCode - Currency code
+ * @returns Symbol or null
+ */
+declare function getCurrencySymbol(currencyCode: string): string | null;
+/**
+ * Convert amount between currencies (requires exchange rate)
+ *
+ * @param amount - Amount to convert
+ * @param fromCurrency - Source currency code
+ * @param toCurrency - Target currency code
+ * @param exchangeRate - Exchange rate (from -> to)
+ * @returns Converted amount
+ */
+declare function convertCurrency(amount: number, _fromCurrency: string, toCurrency: string, exchangeRate: number): number;
+
+/**
+ * Get flag emoji for a country code
+ *
+ * @param countryCode - ISO alpha-2 country code
+ * @returns Flag emoji or null if invalid
+ *
+ * @example
+ * ```typescript
+ * getFlagEmoji('US'); // '🇺🇸'
+ * getFlagEmoji('PK'); // '🇵🇰'
+ * ```
+ */
+declare function getFlagEmoji(countryCode: string): string | null;
+/**
+ * Get country code from flag emoji
+ *
+ * @param emoji - Flag emoji
+ * @returns ISO alpha-2 country code or null
+ *
+ * @example
+ * ```typescript
+ * getCountryFromEmoji('🇺🇸'); // 'US'
+ * getCountryFromEmoji('🇵🇰'); // 'PK'
+ * ```
+ */
+declare function getCountryFromEmoji(emoji: string): string | null;
+/**
+ * Check if string is a valid flag emoji
+ *
+ * @param str - String to check
+ * @returns true if valid flag emoji
+ */
+declare function isFlagEmoji(str: string): boolean;
+/**
+ * Get all flag emojis
+ *
+ * @returns Record of country code to flag emoji
+ */
+declare function getAllFlags(): Record<string, string>;
+
+/**
+ * Get dialing code for a country
+ *
+ * @param countryCode - ISO alpha-2 country code
+ * @returns Dialing code (e.g., "+1", "+92") or null
+ */
+declare function getDialingCode(countryCode: string): string | null;
+/**
+ * Get country code from dialing code
+ *
+ * @param dialCode - Dialing code (with or without +)
+ * @returns Array of possible country codes
+ */
+declare function getCountriesByDialingCode(dialCode: string): string[];
+/**
+ * Format phone number with dialing code
+ *
+ * @param nationalNumber - National phone number
+ * @param countryCode - ISO country code
+ * @returns Formatted international number
+ */
+declare function formatWithDialingCode(nationalNumber: string, countryCode: string): string;
+/**
+ * Check if phone number includes valid dialing code
+ *
+ * @param phone - Phone number
+ * @returns true if has valid dialing code
+ */
+declare function hasValidDialingCode(phone: string): boolean;
+
+/**
+ * Comprehensive country data - ISO 3166-1
+ * Includes all major countries with complete metadata
+ */
+declare const COUNTRIES: Country[];
+
+/**
+ * Currency information by currency code
+ */
+declare const CURRENCIES: Record<string, CurrencyInfo>;
+
+/**
+ * Phone format data by country
+ * Includes dial codes, number lengths, and prefixes
+ */
+declare const PHONE_FORMATS: Record<string, PhoneFormat>;
+/**
+ * Get phone format for a country
+ */
+declare function getPhoneFormat(countryCode: string): PhoneFormat | null;
+/**
+ * Get all supported country codes
+ */
+declare function getSupportedPhoneCountries(): string[];
+
+export { getCountryFromEmoji as A, isFlagEmoji as B, type Country as C, getAllFlags as D, getDialingCode as E, getCountriesByDialingCode as F, formatWithDialingCode as G, hasValidDialingCode as H, COUNTRIES as I, CURRENCIES as J, PHONE_FORMATS as K, getPhoneFormat as L, getSupportedPhoneCountries as M, type PhoneFormat as P, type TimezoneInfo as T, type CurrencyInfo as a, type CountryCodeFormat as b, getCountryByAlpha3 as c, getCountryByNumeric as d, getCountry as e, convertCountryCode as f, getCountryByAlpha2 as g, getAllCountries as h, getCountriesByContinent as i, getCountriesByLanguage as j, isValidCountryCode as k, getTimezonesByCountry as l, getDefaultTimezone as m, getCurrentTimeInCountry as n, getTimezoneOffset as o, convertTimeBetweenCountries as p, formatTimeForCountry as q, getCurrency as r, searchCountries as s, getCurrencyByCountry as t, formatCurrency as u, parseCurrency as v, getAllCurrencies as w, getCurrencySymbol as x, convertCurrency as y, getFlagEmoji as z };