npm package: @phragon-util/phone-state
Description: `@phragon-util/phone-state` is a library for handling user-entered phone numbers, taking country codes into account. It provides convenient methods for working with phone numbers, including validation, formatting, country detection by code, and retrieving
Author: phragon@websoftlab.com
Latest version: 0.0.4

# @phragon-util/phone-state

`@phragon-util/phone-state` is a library for handling user-entered phone numbers, taking country codes into account. It provides convenient methods for working with phone numbers, including validation, formatting, country detection by code, and retrieving additional country information.

## Installation

```sh
npm install @phragon-util/phone-state
```

## Key Features

- Processing and validating phone numbers
- Auto-detecting country code
- Formatting phone numbers
- Retrieving additional country information (flag, code, name)
- Checking the existence of a country code

**Code verification logic:**

If the phone code starts with the `+` symbol, the library attempts to determine the country by code. If the `+` symbol is not specified, the library tries to determine the country based on the default country setting.

## Usage

### Creating a phone number state

```ts
import { createPhoneState } from "@phragon-util/phone-state";

const phoneState = createPhoneState("+14155552671");

console.log(phoneState);

// { 
//   input: "111 123-6969",
//   value: "+1 111 123-6969",
//   valid: true,
//   country: "US",
//   countryCallingCode: "+1"
// }
```

### Updating the phone number state

As the first argument, the function can accept an `input` value, which is what the user enters without considering the country code.

```ts
import { reloadPhoneState } from "@phragon-util/phone-state";

const phoneState = reloadPhoneState("1111232671", phoneState);
console.log(phoneState);
```

### Checking the existence of a country code

```ts
import { hasCountryCode } from "@phragon-util/phone-state";

console.log(hasCountryCode("US")); // true
console.log(hasCountryCode("XX")); // false
```

### Retrieving country information by code

```ts
import { getPhoneTool } from "@phragon-util/phone-state";

const countryInfo = getPhoneTool("US");
console.log(countryInfo);
```

## API

### `createPhoneState(phoneNumber: string, defaultCode?: string): PhoneState`

Creates a phone number state, determining the country code and performing validation.

### `reloadPhoneState(phoneNumber: string, state: PhoneState): PhoneState`

Updates the phone number state considering the current state.

### `hasCountryCode(value: string, strict?: boolean): boolean`

Checks if the country code exists in the database.

### `getPhoneTool(code: string): PhoneTool | null`

Returns country information (code, name, flag, phone code) by its code.

## Types

`PhoneState`

Represents the state of a phone number, including country, calling code, input, value, and validity.

`EmptyStateOptions`

Options for creating an empty phone state.

`PhoneTool`

Represents detailed information about a country's phone number format.

## Dependencies

```
libphonenumber-js: For parsing and formatting phone numbers.
iso-3166-1: For country code and name data.
```

## Support

If you have any questions or suggestions, create an issue in the project repository.

## License

MIT