country-phone-codes/README.md

[DEPRECATED] A modern, TypeScript-first library providing ISO 3166-1 alpha-2 country codes to international calling codes mapping

# ⚠️ DEPRECATED

**This package is no longer maintained.**

Please use libphonenumber-js instead.
See: https://www.npmjs.com/package/libphonenumber-js

---

Original README below:

---

# country-phone-codes

A modern, TypeScript-first library providing a clean, typed mapping of ISO 3166-1 alpha-2 country codes to their international phone codes (e.g., US → +1, IN → +91). 

## Features

- 🌍 **Complete dataset**: Maps all ISO 3166-1 alpha-2 country codes to their international phone code
- 📖 **Data transparency**: All country-phone code mappings embedded directly in the library
- 🔄 **Bidirectional lookups**: Find phone codes by country or countries by phone code
- 🔍 **Validation & normalization**: Clean and validate phone code strings
- 📦 **Zero runtime dependencies**: Lightweight, embedded dataset
- 🔢 **First-class TypeScript**: Written in TypeScript with comprehensive type definitions
- 📟 **Modern exports**: Supports both ESM and CommonJS
- ⚡ **Tree-shakable**: Import only what you need
- 🧪 **Well-tested**: High test coverage

## Installation

```bash
npm install country-phone-codes
# or
yarn add country-phone-codes
# or
pnpm add country-phone-codes
```

## Usage

```typescript
import {
  countryPhoneCodesMap,
  getPhoneCode,
  getCountriesByPhoneCode,
  getAllPhoneCodes,
  isValidPhoneCode,
  normalizePhoneCode
} from 'country-phone-codes';

// Get a phone code for a country
const usCode = getPhoneCode('US'); // '+1'
const indiaCode = getPhoneCode('in'); // '+91' (case-insensitive)

// Find all countries that use a specific phone code
const plusOneCountries = getCountriesByPhoneCode('+1');
// ['US', 'CA', 'AG', 'AI', 'AS', 'BB', 'BM', 'BS', 'DM', 'DO', ...]

// Normalize phone code inputs
normalizePhoneCode('1'); // '+1'
normalizePhoneCode('+44'); // '+44'
normalizePhoneCode('(0049) 123'); // '+49123'
normalizePhoneCode('0091 12-34-56'); // '+91123456'

// Check if a phone code is valid
isValidPhoneCode('+1'); // true
isValidPhoneCode('44'); // true (auto-normalized)
isValidPhoneCode('+999'); // false

// Get all phone codes
const allCodes = getAllPhoneCodes();
// ['+1', '+7', '+20', '+27', '+30', '+31', '+32', '+33', '+34', ...]

// Access raw data directly
console.log(countryPhoneCodesMap);
// { US: '+1', CA: '+1', GB: '+44', ... }
```

## API Reference

### Data

#### `countryPhoneCodesMap`

The primary data object mapping ISO 3166-1 alpha-2 country codes (keys) to their international phone codes (values).

```typescript
// Type: Readonly<Record<string, string>>
const map = countryPhoneCodesMap;
console.log(map['US']); // '+1'
console.log(map['GB']); // '+44'
```

### Functions

#### `getPhoneCode(countryCode: string): string | undefined`

Gets the international phone code for a given country code.

- **Parameters**: 
  - `countryCode`: ISO 3166-1 alpha-2 country code (case-insensitive)
- **Returns**: The international phone code with '+' prefix, or `undefined` if not found

```typescript
getPhoneCode('US'); // '+1'
getPhoneCode('in'); // '+91'
getPhoneCode('XYZ'); // undefined
```

#### `getCountriesByPhoneCode(phoneCode: string): string[]`

Gets all countries that use a specific phone code.

- **Parameters**:
  - `phoneCode`: The international phone code to look up (automatically normalized)
- **Returns**: Array of ISO 3166-1 alpha-2 country codes that use this phone code, or empty array if none

```typescript
getCountriesByPhoneCode('+1'); // ['US', 'CA', 'AG', ...]
getCountriesByPhoneCode('44'); // ['GB', 'IM']
getCountriesByPhoneCode('+999'); // []
```

#### `getAllPhoneCodes(): string[]`

Gets an array of all unique international phone codes.

- **Returns**: Array of all unique phone codes in the dataset

```typescript
getAllPhoneCodes(); // ['+1', '+7', '+20', '+27', ...]
```

#### `isValidPhoneCode(phoneCode: string): boolean`

Checks if the provided string is a valid international phone code.

- **Parameters**:
  - `phoneCode`: The phone code to validate (automatically normalized)
- **Returns**: `true` if valid, `false` otherwise

```typescript
isValidPhoneCode('+1'); // true
isValidPhoneCode('44'); // true
isValidPhoneCode('+999'); // false
```

#### `normalizePhoneCode(code: string): string | undefined`

Normalizes a phone code to ensure it has the proper format.

- **Parameters**:
  - `code`: The phone code string to normalize
- **Returns**: The normalized phone code or `undefined` if it can't be reasonably normalized

```typescript
normalizePhoneCode('1'); // '+1'
normalizePhoneCode('+44'); // '+44'
normalizePhoneCode('(0049) 123'); // '+49123'
normalizePhoneCode('0091 12-34-56'); // '+91123456'
```

## Types

The library exports the following TypeScript types:

```typescript
type CountryCodeA2 = string; // ISO 3166-1 alpha-2 country code
type InternationalPhoneCode = string; // Phone code with '+' prefix
interface CountryPhoneCodeMapData {
  [countryCode: CountryCodeA2]: InternationalPhoneCode;
}
```

## Use Cases

- 📝 Form validation for international phone numbers
- 🌐 User registration flows with country selection
- 📱 Telecom and communications applications
- 🔍 Data enrichment for contact databases
- 🧩 Integration with other internationalization libraries

## JSON Data

If you need direct access to the JSON data, you can import it:

```typescript
import countryPhoneCodesMap from 'country-phone-codes/json';
```

## License

MIT