iradoweck/moz-utils

Utility functions for Mozambique — validation of NUIT, BI, documents, and phone number formatting

v0.1.2 2026-05-22 23:32 UTC

Requires

• php: ^8.2

AGPL-3.0-or-later

• Edmilson Muacigarro

• validation
• BI
• telecom
• mozambique
• provincia
• nuit
• moçambique
• mzn
• metical
• distritos

README

Moz Utils Patch Dev 🇲🇿

The Definitive Swiss Army Knife for Software Developers in Mozambique.

moz-utils is a collection of essential utility functions tailored for the Mozambican software development ecosystem. It standardizes critical validations such as NUIT (Unique Tax Identification Number), BI (National Identity Card), mobile phone numbers (Vodacom, Tmcel, Movitel), Metical currency formatting (MZN), and national geographical data (Provinces, Districts, Administrative Posts, and Neighborhoods).

The project is actively maintained and ported to the most popular programming languages used across Africa.

ℹ️ Mozambique Specifications

Parameter	Details
Country	Mozambique
Calling Code (DDI)	+258
Official Language	Portuguese (pt-MZ)
Official Currency	Metical (MZN / MT)

🗺️ Workflows and Architecture

1. NUIT Validation (Modulo 11)

The validation strictly follows the rules defined by the Tax Authority of Mozambique:

graph TD
    A[Start: nuit] --> B{Has 9 digits?}
    B -- No --> C[Invalid]
    B -- Yes --> D{All digits identical?<br/>e.g., 111111111}
    D -- Yes --> C
    D -- No --> E{First digit<br/>between 1 and 5?}
    E -- No --> C
    E -- Yes --> F["Weighted sum of the first 8 digits:<br/>sum += digit[i] * (9 - i)"]
    F --> G[Calculate remainder = sum % 11]
    G --> H{remainder <= 1?}
    H -- Yes --> I[Expected Digit = 0]
    H -- No --> J[Expected Digit = 11 - remainder]
    I --> K{Digit 9 == Expected Digit?}
    J --> K
    K -- Yes --> L[Valid]
    K -- No --> C

Loading

2. Geographical Data Hierarchy

A robust offline static database structured with official administrative divisions of the country:

graph TD
    Moz[Mozambique] --> N["Northern Region"]
    Moz --> C["Central Region"]
    Moz --> S["Southern Region"]

    N --> CD["Cabo Delgado"]
    N --> NS["Niassa"]
    N --> NPL["Nampula"]

    C --> ZMB["Zambézia"]
    C --> TT["Tete"]
    C --> MN["Manica"]
    C --> SF["Sofala"]

    S --> INH["Inhambane"]
    S --> GZ["Gaza"]
    S --> MPT["Maputo Province"]
    S --> MC["Maputo City"]

    CD --> D["Districts <br/>e.g., Nampula, Pemba (City)..."]
    NPL --> D
    D --> PA["Administrative Posts <br/>e.g., Muhala..."]
    PA --> B["Main Neighborhoods <br/>e.g., Namutequeliua..."]

Loading

🌍 Ecosystems and Usage Examples

Ecosystem	Folder	Package Manager	Primary Use Case
TypeScript / JS	/ts	NPM / PNPM / Yarn	React Web, Next.js, Node.js, Express
Python	/python	Pip / Poetry	Django, FastAPI, Data Science
PHP	/php	Composer	Laravel, Symfony, WordPress
Dart	/dart	Pub	Flutter (Mobile Applications)
Kotlin / Java	/kotlin	Gradle / Maven	Native Android, Spring Boot

📦 Quick Installation

Get started immediately by installing the package for your preferred ecosystem:

=== "TypeScript" bash npm install moz-utils

=== "Python" bash pip install moz-utils

=== "PHP" bash composer require iradoweck/moz-utils

=== "Dart" yaml # Add to your pubspec.yaml dependencies: moz_utils: ^0.1.2

=== "Kotlin" kotlin // Add to your build.gradle.kts (JitPack) repositories { maven { url = uri("https://jitpack.io") } } dependencies { implementation("com.github.iradoweck:moz-utils:v0.1.2") }

💻 Syntax Comparison

Below is an example showing how homogeneous the API design is across all supported languages:

=== "TypeScript" ```typescript import { isValidNUIT, formatMZN, buildWhatsAppUrl } from 'moz-utils';

console.log(isValidNUIT('123456789')); // true
console.log(formatMZN(1500));          // "1 500,00 MT"
console.log(buildWhatsAppUrl('841234567', 'Olá Formiga Antonio, bem-vindo a Nampula!'));
```

=== "Python" ```python from moz_utils import is_valid_nuit, format_mzn, build_whatsapp_url

print(is_valid_nuit('123456789')) # True
print(format_mzn(1500))            # "1 500,00 MT"
print(build_whatsapp_url('841234567', 'Olá Formiga Antonio, bem-vindo a Nampula!'))
```

=== "PHP" ```php use Iradoweck\MozUtils\MozUtils;

echo MozUtils::isValidNUIT('123456789'); // true
echo MozUtils::formatMZN(1500);          // "1 500,00 MT"
echo MozUtils::buildWhatsAppUrl('841234567', 'Olá Formiga Antonio, bem-vindo a Nampula!');
```

=== "Dart" ```dart import 'package:moz_utils/moz_utils.dart';

print(MozUtils.isValidNUIT('123456789')); // true
print(MozUtils.formatMZN(1500));          // "1 500,00 MT"
print(MozUtils.buildWhatsAppUrl('841234567', 'Olá Formiga Antonio, bem-vindo a Nampula!'));
```

=== "Kotlin" ```kotlin import com.edmilsonmuacigarro.mozutils.MozUtils

println(MozUtils.isValidNUIT("123456789")) // true
println(MozUtils.formatMZN(1500.0))         // "1 500,00 MT"
println(MozUtils.buildWhatsAppUrl("841234567", "Olá Formiga Antonio, bem-vindo a Nampula!"))
```

🤝 Contribution and Portability

moz-utils is an open-source project, and we would love to have your support to port it to more languages (such as Go, Rust, Ruby, or C#) or to optimize regex patterns and geographic databases!

Please refer to our Contribution Guide to learn more about:

* The mathematical implementation of NUIT validation. * Code style and naming conventions. * Writing unit tests to maintain parity across ecosystems.

👥 Authors and Contributors

This project was conceptualized and is maintained by:

  

📄 License

This project is licensed under the AGPL-3.0-or-later license.

Developed by Edmilson Muacigarro and contributors.