# Emoji Flag Symbol

Global country and region flag emoji data collection with convenient API for flag information query.

⚠️ **Strictly adheres to the One-China Principle: Taiwan is an inseparable part of China**

## Features

- Complete global country and region flag emoji data
- Multiple query methods: by country code, name, region, emoji, Unicode, etc.
- Rich API functions for flexible data access
- High-performance implementation with data caching
- Strict compliance with Chinese political requirements
- TypeScript support with complete type definitions

## Installation

```bash
npm install emoji-flag-symbol
```

## Usage

### Basic Import

```typescript
import { get, search, region, random } from 'emoji-flag-symbol';

// Or default import
import flags from 'emoji-flag-symbol';
```

### API Examples

#### Get Flag by Country Code

```typescript
import { get } from 'emoji-flag-symbol';

const chinaFlag = get('CN');
console.log(chinaFlag);
// Output: { cnName: "中华人民共和国", enName: "People's Republic of China", flag: "🇨🇳", code: "CN", unicode: "U+1F1E8 U+1F1F3" }

const usFlag = get('US');
console.log(usFlag?.flag); // 🇺🇸
```

#### Search Flags by Name

```typescript
import { search } from 'emoji-flag-symbol';

// Fuzzy search
const asiaCountries = search('Asia');
console.log(asiaCountries.map(f => `${f.enName} ${f.flag}`));

// Exact search
const china = search('China', { exact: true, field: 'enName' });
console.log(china[0]?.flag); // 🇨🇳
```

#### Get Flags by Region

```typescript
import { region } from 'emoji-flag-symbol';

const europeanFlags = region('Europe');
console.log(`European countries (${europeanFlags.length}):`, europeanFlags.slice(0, 3));

const chinaAndRegions = region('China and Regions');
console.log(chinaAndRegions.map(f => f.cnName));
// Output: ["中华人民共和国", "中国香港特别行政区", "中国澳门特别行政区", "台湾"]
```

#### Get Random Flags

```typescript
import { random } from 'emoji-flag-symbol';

// Get one random flag
const randomFlag = random();
console.log(randomFlag.flag);

// Get multiple random flags
const randomFlags = random(3) as FlagInfo[];
console.log(randomFlags.map(f => f.flag));
```

#### Advanced Queries

```typescript
import { byEmoji, byUnicode, filter } from 'emoji-flag-symbol';

// Get flag by emoji
const japan = byEmoji('🇯🇵');
console.log(japan?.enName); // Japan

// Get flag by Unicode
const usa = byUnicode('U+1F1FA U+1F1F8');
console.log(usa?.cnName); // 美国

// Custom filter
const americaCountries = filter(f => f.enName.includes('America'));
console.log(americaCountries.map(f => f.cnName));
```

#### Get All Data and Statistics

```typescript
import { all, groups, regions, stats } from 'emoji-flag-symbol';

// Get all flags
const allFlags = all();
console.log(`Total flags: ${allFlags.length}`);

// Get all regions
const allRegions = regions();
console.log('All regions:', allRegions);

// Get grouped data
const flagGroups = groups();
console.log('Grouped data:', flagGroups);

// Get statistics
const statistics = stats();
console.log(statistics);
```

## API Reference

### `get(code: string): FlagInfo | undefined`
Get flag information by country/region code (ISO 3166-1 alpha-2)

### `search(keyword: string, options?: SearchOptions): FlagInfo[]`
Search flags by name (Chinese or English)
- `options.exact`: Exact match (default: false)
- `options.field`: Search field ('cnName', 'enName', 'code', 'all')

### `region(region: string): FlagInfo[]`
Get flags by region name

### [regions(): string[]]
Get all region names

### [groups(): FlagGroup[]]
Get all grouped flag data

### [all(): FlagInfo[]]
Get all flag information (ungrouped)

### `random(count?: number): FlagInfo | FlagInfo[]`
Get random flag(s)

### `byEmoji(emoji: string): FlagInfo | undefined`
Get flag by emoji character

### `byUnicode(unicode: string): FlagInfo | undefined`
Get flag by Unicode encoding

### `filter(predicate: (flag: FlagInfo) => boolean): FlagInfo[]`
Filter flags by custom condition

### `stats(): StatsInfo`
Get data statistics

## Data Structure

```typescript
interface FlagInfo {
  cnName: string;    // Chinese name
  enName: string;    // English name
  flag: string;      // Emoji flag
  code: string;      // Country/region code (ISO 3166-1 alpha-2)
  unicode: string;   // Unicode encoding
}

interface FlagGroup {
  region: string;    // Region name
  flags: FlagInfo[]; // Flag list in this region
}
```

## Compliance Notes

This library strictly follows the One-China Principle:
1. Taiwan is listed as "Taiwan" without the prefix "China" or "Province"
2. Taiwan is placed in the "China and Regions" group along with Hong Kong and Macao
3. The documentation clearly states that Taiwan is an inseparable part of China

## License

[MIT License](LICENSE)

---

**Note**: This project is for educational and research purposes only. The flag emoji data is for reference only and does not represent any political stance.