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 ID), DIRE (Foreign Resident ID), Passports, Driving Licenses, mobile phone numbers (Vodacom, Tmcel, Movitel / M-Pesa, e-Mola, mKesh), Metical currency formatting (MZN), and national geographical data (including the New Postal Code System - CEP).
The project is actively maintained and ported to the most popular programming languages used across Africa.
| Parameter | Details |
|---|---|
| Country | Mozambique |
| Calling Code (DDI) | +258 |
| Official Language | Portuguese (pt-MZ) |
| Official Currency | Metical (MZN / MT) |
The moz-utils ecosystem follows a rigorous Stable/LTS/EOL policy to ensure enterprise-grade reliability, alongside the Base 10 versioning dogma.
| Version | Status | Release Date | End of Life (EOL) |
|---|---|---|---|
| 0.3.x | 🟢 Stable | May 27, 2026 | Until 0.4.0 is released |
| 0.2.x | 🔴 EOL | May 26, 2026 | Immediate (Replaced rapidly) |
| 0.1.x | 🔴 EOL | May 20, 2026 | Immediate (Replaced rapidly) |
Note: Future LTS (Long Term Support) versions will be supported for a minimum of 3 to 6 months. The ecosystem retains a maximum of 2 active LTS lines simultaneously. An automatic deprecation warning will trigger when an LTS reaches its final 5% lifespan.
All heavy technical logic (NUIT mathematics, document Regex validation, and Mozambique maps) has been isolated. To read detailed technical documentation on how algorithms work and the structure of Mozambican geographical databases, check out our official document: 👉 Mozambique Kiwi Docs (Validations & Maps)
Identification and validation of Mozambican 9-digit numbers (starting with 82, 83, 84, 85, 86, 87, 88). Robustly identifies if the number supports M-Pesa (Vodacom), e-Mola (Movitel), or mKesh (Tmcel).
The ecosystem implements the New Mozambican CEP System (6 digits XXXX-XX).
More than just a list, we built an intelligent suggestion logic:
- If a user inputs an old postal code (e.g.,
3100), the library automatically translates and suggests an array of corresponding New CEPs (e.g.,0909-01,0909-02), allowing you to build perfect frontend dropdown menus for the end user to choose the exact neighborhood.
To test how this library behaves "in production" without needing to write code, we included a CLI Emulator.
Simply run this in the root of your project:
npx tsx emulator.tsThis will launch an interactive menu where you can type NUITs, phones, BIs, or CEPs and check the library's real-time response!
| 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 |
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.3.8
=== "Kotlin"
kotlin // Add to your build.gradle.kts (JitPack) repositories { maven { url = uri("https://jitpack.io") } } dependencies { implementation("com.github.iradoweck:moz-utils:v0.3.8") }
Ao contrário do NIF de Portugal (que usa multiplicadores de 9 a 2), a Autoridade Tributária de Moçambique utiliza a seguinte matriz de pesos para calcular o Módulo 11 do NUIT.
A Fórmula e os Pesos Oficiais:
NUIT a Validar: 401626638
Posição: 1 2 3 4 5 6 7 8
Dígitos: 4 0 1 6 2 6 6 3
Pesos: 8 9 4 5 6 7 8 9
| | | | | | | |
Mult: 32 + 0 + 4 +30 +12 +42 +48 +27 = 195 (Soma)
Cálculo do Módulo 11:
1. Resto = Soma % 11
195 % 11 = 8
2. O "Resto" é o Índice (Posição 0 a 10) na string de controlo "01234567891".
3. A 8ª posição de "01234567891" é '8'.
4. Como o 9º dígito do NUIT (Dígito de Controlo) é '8', o NUIT é Válido!
Below is an example showing how homogeneous the API design is across all supported languages (TypeScript example with new features):
=== "TypeScript" ```typescript import { isValidNUIT, isValidDIRE, isValidMozambicanPhone, suggestCEPs, formatMZN, parseMZN } from 'moz-utils';
// NUIT e Documentos
console.log(isValidNUIT('401626638')); // true (Algoritmo Moz-Mod11)
console.log(isValidDIRE(' 00008312-c ')); // true (auto-sanitized)
// Tratamento de Dinheiro de "Sujo" para "BD" e depois para "UI"
const dbValue = parseMZN('1.500,00 MT'); // 1500.00 (float puro para a BD)
console.log(formatMZN(dbValue)); // "1 500,00 MT" (padrão oficial de exibição)
// Auto-fallback and suggestions for legacy postal codes
const suggestions = suggestCEPs('3100');
console.log(suggestions[0]); // { cep: '0909-09', locality: 'Namutequeliua', district: 'Nampula', province: 'Nampula' }
```
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.We have a dedicated Community Portal integrated directly into our official website. Whether you have questions, ideas, want to showcase your projects, or propose B2B partnerships, everything happens there natively through GitHub Discussions.
👉 Join the Community Discussions
This project was conceptualized and is maintained by:
This project is licensed under the Apache License 2.0. See the LICENSE file for more details.
If this library has saved you hours of parsing obscure algorithms and geographic data, consider supporting its continuous development!
- PayPal: Donate via PayPal (Add your link here)
- Binance (Crypto): Donate via Binance Pay (Add your ID/link here)
Developed by Open Source Contributors & supported by Edmilson Muacigarro