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

📱 Phone Utilities

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

📱 FIN Utilities

• Validate FIN
• Normalize FIN

📱 Passport Utilities

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

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

📦 Installation

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
}

Supported Prefixes

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