!pipeline status
!npm version
!license

az-utils 🇦🇿

A lightweight, TypeScript-first utility library providing Azerbaijan-specific helpers commonly needed in backend development.

This package focuses on validation, normalization, and parsing of data formats frequently used in Azerbaijan-based systems.

> Initial release focuses on Azerbaijan mobile phone utilities
> Added support for FIN and local ID utilities

---

✨ Features

$3

- Validate Azerbaijan mobile phone numbers
- Normalize phone numbers to a standard local format
- Detect mobile operator (Azercell, Bakcell, Nar)

$3

- Validate FIN
- Normalize FIN

$3

- Validate local ID series
- Normalize ID series
- Supported series (AZE,AA,AB)

More utilities (IBAN, addresses) will be added incrementally.

---

📦 Installation

``bash
npm install @caucasus/az-utils

`

Usage

`
import {
isValidAzPhone,
normalizeAzPhone,
getAzMobileOperator,
IsAzPhone,
TransformAzPhone
...etc
} from "az-utils";

`

✅ Validate Phone Number

`
isValidAzPhone("+994 (50) 123-45-67"); // true
isValidAzPhone("0501234567"); // true
isValidAzPhone("0401234567"); // false
`

Supported input formats:

- 0501234567
- 050 123 45 67
- (050) 123-45-67
- 994501234567
- +994501234567

🔄Normalize Phone Number

`
normalizeAzPhone("+994701112233");
// "0701112233"

normalizeAzPhone("(050) 123-45-67");
// "0501234567"

`

🏷 Detect Mobile Operator

`
getAzMobileOperator("0501234567");
// "Azercell"

getAzMobileOperator("0551234567");
// "Bakcell"

getAzMobileOperator("0771234567");
// "Nar"

`

Decorator support (DTO)

`
class TestDto {
@IsAzPhone()
phone!: string;

@IsFin()
fin!: string

@IsSeries()
idSeries!: string
}
``

$3

Mobile phones

| Prefix | Operator |
| ------------ | -------- |
| 050, 051,010 | Azercell |
| 055, 099 | Bakcell |
| 070, 077 | Nar |

Local ID series

AZE, AA, AB

---

🛣 Roadmap

Planned additions:

- Azerbaijan IBAN validation

- Address parsing utilities

- Localization helpers (AZ / EN / RU)

🤝 Contributing

Contributions are welcome.

Please:

- Keep changes small and focused

- Add tests for new functionality

- Avoid breaking changes without discussion

📄 License

MIT License © Contributors

---