# Language Codes

A TypeScript library for working with language codes based on ISO 639-1, ISO 639-2, and ISO 639-3 standards. Provides comprehensive language data with English names, native names, and various ISO code formats.

## Features

- ✅ **Full TypeScript support** with comprehensive type definitions
- 🌍 **184 languages** with ISO 639-1, 639-2, and 639-3 codes
- 🏠 **Native language names** alongside English names
- 🔍 **Flexible search** by any language property
- 📝 **Well-documented API** with JSDoc comments
- 🚀 **Zero dependencies** and lightweight

## Installation

```bash
npm install lang-codes
# or
bun add lang-codes
```

## Usage

### Import

```typescript
import { 
  allLanguages, 
  hasLanguage, 
  getCodes, 
  getNames, 
  findBy,
  type Language 
} from 'lang-codes';

// Or use the legacy object API
import langs from 'lang-codes';
```

### Get All Languages

```typescript
const languages = allLanguages();
console.log(languages.length); // 184
console.log(languages[0]);
// {
//   name: "Abkhaz",
//   local: "Аҧсуа", 
//   "1": "ab",
//   "2": "abk",
//   "2T": "abk",
//   "2B": "abk",
//   "3": "abk"
// }
```

### Check Language Existence

```typescript
// Check by ISO 639-1 code
const hasEnglish = hasLanguage('1', 'en'); // true
const hasKlingon = hasLanguage('name', 'Klingon'); // false

// Check by name
const hasSpanish = hasLanguage('name', 'Spanish'); // true
```

### Get Language Codes

```typescript
// Get all ISO 639-1 codes
const iso1Codes = getCodes('1');
// ['ab', 'aa', 'af', 'ak', 'sq', ...]

// Get all ISO 639-2 codes
const iso2Codes = getCodes('2');
// ['abk', 'aar', 'afr', 'aka', 'sqi', ...]

// Numeric types also work
const iso3Codes = getCodes(3);
// ['abk', 'aar', 'afr', 'aka', 'sqi', ...]
```

### Get Language Names

```typescript
// Get English names
const englishNames = getNames(false);
// ['Abkhaz', 'Afar', 'Afrikaans', ...]

// Get native/local names
const nativeNames = getNames(true);
// ['Аҧсуа', 'Afaraf', 'Afrikaans', ...]
```

### Find Specific Languages

```typescript
// Find by ISO 639-1 code
const english = findBy('1', 'en');
// {
//   name: "English",
//   local: "English",
//   "1": "en",
//   "2": "eng",
//   "2T": "eng",
//   "2B": "eng",
//   "3": "eng"
// }

// Find by name
const spanish = findBy('name', 'Spanish');
// {
//   name: "Spanish",
//   local: "Español",
//   "1": "es",
//   "2": "spa",
//   "2T": "spa",
//   "2B": "spa",
//   "3": "spa"
// }

// Find by native name
const french = findBy('local', 'Français');
// {
//   name: "French",
//   local: "Français",
//   "1": "fr",
//   "2": "fra",
//   "2T": "fra",
//   "2B": "fre",
//   "3": "fra"
// }
```

## TypeScript Support

### Language Interface

```typescript
interface Language {
  /** English name of the language */
  name: string;
  /** Local/native name of the language */
  local: string;
  /** ISO 639-1 code (2 characters) */
  "1": string;
  /** ISO 639-2 code (3 characters) */
  "2": string;
  /** ISO 639-2/T code (3 characters, terminologic) */
  "2T": string;
  /** ISO 639-2/B code (3 characters, bibliographic) */
  "2B": string;
  /** ISO 639-3 code (3 characters) */
  "3": string;
}
```

### Type-Safe Code Types

```typescript
type LanguageCodeType = "1" | "2" | "2T" | "2B" | "3" | 1 | 2 | 3;
type LanguageCriteria = keyof Language;
```

### Type Checking

```typescript
// ✅ TypeScript will validate these at compile time
const validCode = getCodes('1'); // ✅ Valid
const invalidCode = getCodes('invalid'); // ❌ TypeScript error

const validCriteria = findBy('name', 'English'); // ✅ Valid
const invalidCriteria = findBy('invalid', 'value'); // ❌ TypeScript error
```

## Legacy API

For backward compatibility, the library also exports a legacy object-based API:

```typescript
import langs from 'lang-codes';

// All functions are available through the langs object
const allLangs = langs.all();
const hasLang = langs.has('1', 'en');
const codes = langs.codes('2');
const names = langs.names(false);
const found = langs.where('name', 'English');
```

## Language Codes Explained

- **ISO 639-1** (`"1"`): Two-letter codes (e.g., 'en', 'es', 'fr')
- **ISO 639-2** (`"2"`): Three-letter codes (e.g., 'eng', 'spa', 'fra')
- **ISO 639-2/T** (`"2T"`): Terminologic codes (technical/scientific use)
- **ISO 639-2/B** (`"2B"`): Bibliographic codes (library/documentation use)
- **ISO 639-3** (`"3"`): Comprehensive three-letter codes

Some languages have different 2T and 2B codes (like German: 'deu' vs 'ger'), while others use the same code for both.

## Development

To install dependencies:

```bash
bun install
```

To run:

```bash
bun run index.ts
```

## License

MIT License
