degachejs/README.md

A Tunisian utility library for working with CIN, phone numbers, addresses, and more

# 🌴 degache.js

Tunisian Developer's Essential Utility Library

## Why degache.js? 🤔

Tired of rewriting validation code for Tunisian CIN, phone numbers, and tax IDs? `degache.js` is your go-to utility library for all things Tunisian! Named after the beautiful oasis city of Degache, this library brings the same refreshing relief to your development workflow.

## 🚀 Features

### CIN (Carte d'Identité Nationale) 🆔
```typescript
import { validateCIN } from 'degachejs';

// Simple validation
const isValid = validateCIN('12345678'); // true
```

### Phone Numbers 📱
- ✅ Support for all Tunisian carriers (Ooredoo, Orange, Tunisie Telecom)
- 🔄 International format conversion
- 📞 Smart formatting with country code
- 🏢 Carrier detection

```typescript
import { validatePhoneNumber, formatPhoneNumber, getCarrierInfo } from 'degachejs';

// Validate phone number
const isValid = validatePhoneNumber('20123456'); // true

// Format phone number
const formatted = formatPhoneNumber('20123456');
console.log(formatted); // +216 20 123 456

// Get carrier information
const carrier = getCarrierInfo('20123456');
console.log(carrier); // { name: 'Ooredoo', prefixes: ['2'] }
```

### Tax ID (Matricule Fiscal) 💼
```typescript
import { validateTaxID } from 'degachejs';

const isValid = validateTaxID('1234567A/P/M/000');
```

### Currency Formatting 💰
```typescript
import { formatCurrency } from 'degachejs';

const amount = formatCurrency(1234.56);
console.log(amount); // 1.234,560 دينار تونسي
```

### Postal Codes 📮
```typescript
import { validatePostalCode } from 'degachejs';

const isValid = validatePostalCode('1000'); // true for Tunis
```

### Bank Account (RIB) Validation 🏦
```typescript
import { validateRIB, getBankFromRIB } from 'degachejs';

// Validate RIB
const isValid = validateRIB('12345678901234567890');

// Get bank information
const bank = getBankFromRIB('12345678901234567890');
console.log(bank); // { name: 'Bank Name', code: '12' }
```

### Date Formatting 📅
```typescript
import { formatDate } from 'degachejs';

const formatted = formatDate(new Date());
console.log(formatted); // Formatted date in Tunisian style
```

### Constants 📋
```typescript
import { BANKS, CARRIERS, GOVERNORATES } from 'degachejs';

// Access list of Tunisian banks
console.log(BANKS);

// Access list of mobile carriers
console.log(CARRIERS);

// Access list of governorates
console.log(GOVERNORATES);
```

## 📦 Installation

```bash
npm install degachejs
# or
yarn add degachejs
# or
pnpm add degachejs
```

## 🛠️ Usage

```typescript
import { 
  validateCIN,
  formatPhoneNumber,
  validateTaxID,
  formatCurrency,
  validateRIB,
  getBankFromRIB,
  formatDate
} from 'degachejs';

// Validate CIN
const isCINValid = validateCIN('12345678');

// Format phone number
const phoneNumber = formatPhoneNumber('20123456');

// Validate Tax ID
const isTaxIDValid = validateTaxID('1234567A/P/M/000');

// Format currency
const price = formatCurrency(1234.56, { symbol: true });

// Validate RIB
const isRIBValid = validateRIB('12345678901234567890');

// Get bank information
const bankInfo = getBankFromRIB('12345678901234567890');

// Format date
const formattedDate = formatDate(new Date());
```

## 🤝 Contributing

We welcome contributions from the Tunisian developer community! Whether it's:

- 🐛 Bug fixes
- ✨ New features
- 📚 Documentation improvements
- 🧪 Test cases
- 💡 Feature suggestions

Check out our [Contributing Guide](CONTRIBUTING.md) to get started.

## 🔒 Security

All validation and formatting functions are designed with security in mind, following best practices for handling sensitive data.

## 📄 License

degache.js is MIT licensed. See the [LICENSE](LICENSE) file for details.

## 🏆 Production Ready

- ✅ Comprehensive input validation
- ⚡ Optimized performance
- 🧪 High test coverage
- 📚 Detailed documentation
- 🔒 Type-safe APIs

---

Built with ❤️ for the Tunisian developer community 🇹🇳