npm package: @iamqitmeer/country-x
Description: A blazing-fast, lightweight, and tree-shakable utility for international country data, including ISO codes, phone formats, flags, currencies, and fuzzy search.
Author: Your Name
Latest version: 1.0.0


# country-x

A blazing-fast, lightweight, and tree-shakable utility for international country data, including ISO codes, phone formats, flags, currencies, and fuzzy search.

![country-x banner](https://user-images.githubusercontent.com/10996838/200133983-491b6e4e-862a-43eb-8e01-8664b9d0739c.png) 

## Why `country-x`?

-   🚀 **Blazing Fast**: All lookups are O(1) time complexity using pre-computed hash maps. No more slow array searches.
-   🌲 **Tree-shakable**: Core logic and React components are separate. Only import what you need, keeping your bundle size minimal.
-   💡 **Smart Search**: Built-in, zero-dependency fuzzy search to find countries even with typos.
-   📞 **Advanced Phone Handling**: Format phone numbers to local standards and validate them.
-   🇦🇺 **Flags & More**: Includes currency data, timezones, and a ready-to-use React `<Flag />` component.
-   🔒 **Fully Typed**: Written entirely in TypeScript for a great developer experience.

## Installation

```bash
npm install country-x
# or
yarn add country-x
```

If using React components, make sure `react` is installed in your project.

## API

### Core Utilities

Import core functions directly from `country-x`.

```javascript
import { getCountryByIso, searchCountries, formatPhoneNumber } from 'country-x';

// O(1) Lookup
const pakistan = getCountryByIso('PK');
console.log(pakistan.currency.code); // PKR

// Fuzzy Search
const results = searchCountries('pakitan'); // notice the typo
console.log(results[0].name); // 'Pakistan'

// Phone Formatting
const formatted = formatPhoneNumber('3121234567', 'PK');
console.log(formatted); // 312-1234567
```

-   `getAllCountries(): Country[]`
-   `getCountryByIso(iso: string): Country | undefined`
-   `getCountryByCode(code: string): Country | undefined`
-   `getCountryByName(name: string): Country | undefined`
-   `searchCountries(query: string): Country[]`
-   `formatPhoneNumber(phone: string, isoOrCode: string): string`
-   `isValidPhoneNumber(phone: string, isoOrCode: string): boolean`

### React Hooks & Components

Import React-specific utilities from `country-x/react`.

```jsx
import React, { useState } from 'react';
import { useCountry, Flag } from 'country-x/react';

function CountryPicker() {
  const [query, setQuery] = useState('');
  const { countries } = useCountry({ searchQuery: query });

  return (
    <div>
      <input 
        type="text" 
        value={query} 
        onChange={(e) => setQuery(e.target.value)} 
        placeholder="Search for a country..."
      />
      <ul>
        {countries.slice(0, 5).map(country => (
          <li key={country.iso2}>
            <Flag iso2={country.iso2} size={20} style={{ marginRight: '8px' }} />
            {country.name} ({country.callingCode})
          </li>
        ))}
      </ul>
    </div>
  );
}
```

-   `useCountry({ searchQuery: string })`: Hook to get a list of countries, filtered by a search query.
-   `<Flag iso2={string} size={number} />`: A simple, efficient component to display a country's flag.

## Build

To build the package from source:

```bash
npm install
npm run build
```

This generates the `dist` folder with CJS, ESM, and TypeScript declaration files.