SimuJS

🇹🇿 Tanzanian phone number detection & classification library

SimuJS is a lightweight TypeScript library that identifies Tanzanian phone numbers and determines their mobile network, service type, and validity — based on official TCRA's National Numbering and Signaling Point Codes Plans.

📄 Disclaimer

Important Notice

This package is not affiliated with, endorsed by, or officially supported by the Tanzania Communications Regulatory Authority (TCRA).

The data and logic used in this library are derived from publicly available information contained in the following official document:

Document Title: National Numbering and Signaling Point Codes Plans Institution: Tanzania Communications Regulatory Authority (TCRA) Document Number: TCRA/DICT/CRTM/PLA-GUD/001 Version: 1.15 Release Date: July 2025 Classification: Public

This package is an independent implementation created for developer convenience and educational use. While reasonable effort has been made to ensure accuracy, no guarantee is provided that the information is complete, current, or suitable for regulatory or commercial decision-making.

For official and authoritative information, always refer directly to publications issued by the Tanzania Communications Regulatory Authority (TCRA).

✨ Features

• ✅ Detect Tanzanian mobile operators (Vodacom, Airtel, Yas, Halotel, TTCL, etc.)
• ✅ Supports M2M, toll-free & special services
• ✅ Normalizes phone numbers safely
• ✅ Predictable, typed results (no throwing)
• ✅ Built on official TCRA allocations as of July 2025
• ✅ TypeScript-first

📦 Installation

Using npm:

npm install simujs

Via yarn:

yarn add simujs

🚀 Usage

Basic usage

import { simu } from 'simujs';

const result = simu('0754123456');

if (result.ok) {
    console.log(result.operator.name);
    // Vodacom Tanzania
} else {
    console.error(result.reason);
}

🧠 Return Type

simu() never throws — it always returns a predictable result:

type SimuResult = { ok: true; operator: Operator } | { ok: false; reason: 'INVALID_NUMBER' | 'UNKNOWN_OPERATOR' };

📱 Supported Number Formats

All of the following are accepted:

• +255754123456
• 0754123456
• 754123456

The number must belong to Tanzania.

🧾 Example Output

{
  ok: true,
  operator: {
    name: "Vodacom Tanzania",
    company: "Vodacom Tanzania PLC",
    service: "Mobile",
    financialService: "M-Pesa",
    status: "Operational"
  }
}

🔍 Supported Operators

| Operator | Service | | ----------------- | --------------------- | | Vodacom Tanzania | Mobile / M-Pesa | | Airtel Tanzania | Mobile / Airtel Money | | Yas Tanzania | Mobile / Mixx | | Halotel | Mobile / HaloPesa | | TTCL | Mobile / T-Pesa | | M2M Services | Machine-to-Machine | | Toll-Free Numbers | Special Services |

🧪 Validation & Errors

simu('123');
// { ok: false, reason: "INVALID_NUMBER" }

simu('0700000000');
// { ok: false, reason: "UNKNOWN_OPERATOR" }

🧰 Advanced Usage

Normalize a number

import { normalize } from 'simu';

normalize('+255754123456'); // "754123456"

📦 Package Info

• Fully typed
• Tree-shakeable
• ESM compatible
• Zero runtime dependencies (except google-libphonenumber)

🧱 Built With

• google-libphonenumber
• TypeScript

🧑‍💻 Author

Adeodatus Ludan

🔄 Changelog

v2.0.0

• New result-based API ({ ok, operator })
• Improved normalization
• Support for M2M and special services
• Safer error handling
• Full test coverage

📄 License

MIT