algeria-wilayas/README.md

A comprehensive package for handling Algerian administrative divisions

# AlgerianWilayas

A comprehensive Node.js package providing data and utilities for Algerian administrative divisions (Wilayas, Daïras, and Communes).

## Features

- Complete data for all 58 Algerian Wilayas (provinces)
- Detailed information about all Daïras (districts) and Communes (municipalities)
- Support for multiple languages (Arabic, French, and ASCII/Latin)
- Easy-to-use API for querying and filtering administrative divisions
- TypeScript support with full type definitions

## Installation

```bash
npm install algerian-wilayas
```

Or using yarn:

```bash
yarn add algerian-wilayas
```

## Usage

### Basic Usage

```typescript
import algerianWilayas from 'algerian-wilayas';

// Get all wilayas
const allWilayas = algerianWilayas.getAllWilayas();

// Get a specific wilaya by code
const wilaya = algerianWilayas.getWilayaByCode('16'); // Alger/Algiers

// Get all daïras in a wilaya
const dairas = algerianWilayas.getDairasByWilaya('16');

// Get all communes in a wilaya
const communes = algerianWilayas.getCommunesByWilaya('16');

// Get communes in a specific daïra
const communesInDaira = algerianWilayas.getCommunesByDaira('daira_id');

// Get wilaya name in a specific language
const wilayaNameArabic = algerianWilayas.getWilayaName('16', 'arabic');
const wilayaNameFrench = algerianWilayas.getWilayaName('16', 'french');
const wilayaNameAscii = algerianWilayas.getWilayaName('16', 'ascii');
```

### Getting Statistics

```typescript
// Get statistics for a wilaya
const stats = algerianWilayas.getWilayaStats('16');
console.log(stats);
/* Output:
{
  totalCommunes: 13,
  totalDairas: 4,
  communesPerDaira: [
    { daira: { arabic: "...", french: "...", ascii: "..." }, communeCount: 3 },
    ...
  ]
}
*/
```

### Formatting Wilaya Codes

```typescript
// Format wilaya code to ensure 2 digits
const formattedCode = algerianWilayas.formatWilayaCode(1); // Returns "01"
```

## Data Structure

### Wilaya

```typescript
interface Wilaya {
  code: string;
  name: BilingualName;
}

interface BilingualName {
  arabic: string;
  french: string;
  ascii: string;
}
```

### Daïra

```typescript
interface Daira {
  id: string;
  wilaya_code: string;
  name: BilingualName;
}
```

### Commune

```typescript
interface Commune {
  id: string;
  wilaya_code: string;
  daira_name_ascii: string;
  name: BilingualName;
}
```

## Language Support

The package supports three languages for names:
- `arabic`: Names in Arabic script
- `french`: Names in French
- `ascii`: Latinized/ASCII names (default)

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request