ValiNum (v1.0.4)

ValiNum is a lightweight, universal JavaScript library designed to validate and identify mobile phone numbers. The current version is specifically optimized for the Democratic Republic of the Congo (DRC).

---

Features

• Operator Identification: Instantly detects if a number belongs to Vodacom, Orange, Airtel, or Africell including recent network allocation expansions like the 86 block.
• Geographical Metadata Extraction: Resolves National Destination Codes (NDC) to their historical native delivery regions (such as Kinshasa, Grand Katanga, Grand Kivu) for behavioral localization.
• Line Type Classification: Automatically distinguishes between traditional landlines (Fixe networks like legacy Orange 80 systems) and cellular architectures (Mobile).
• Real-time Validation: Detects if a number is incomplete, too long, or valid.
• Smart Sanitization: Automatically handles spaces, dashes, parentheses, and prefixes like +243, 243, or the initial 0.
• Exception & Service Handling: Intercepts and flags official carrier short codes (customer care lines) and financial USSD strings (M-Pesa, Orange Money, Airtel Money, AfriMoney) to prevent them from altering standard subscriber registration forms.
• Strict vs Tolerant Modes: Gives developers the choice between flexible user inputs (allowing local formatting like leading 0) or strict infrastructural conformity (enforcing the +243 country prefix and preventing post-indicatif zero bugs).
• Universal: Compatible with React, React Native, Vue, Node.js, TypeScript, PHP, and Django.

Installation

Via NPM (For React, Vite, Node.js, etc.)

npm install valinum

Via CDN (For Classic HTML, PHP, Django)

Add this script tag before the closing </body> tag:

<script src="https://cdn.jsdelivr.net/gh/fomadev/valinum@v1.0.4/dist/valinum.js"

Usage

1. Basic Integration / Metadata Extraction (Standard JS / CDN)

The schema delivers extended regional insights instantly along with core operator verification properties.

const result = ValiNum.validateDRC("080 123-456");

console.log(result.isValid);   // true
console.log(result.operator);  // "Orange"
console.log(result.lineType);  // "Fixe"
console.log(result.region);    // "National"

2. Modern Integration (ES6 / TypeScript)

import { validateDRC } from 'valinum';

const { isValid, operator, lineType, region } = validateDRC("+243 86 000 0000");

if (isValid) {
    console.log(`Identified ${operator} (${lineType}) allocated in: ${region}`);
    // Output: Identified Vodacom (Mobile) allocated in: National / Extension
}

3. Strict Mode Configuration

For critical backend integrations or strict validation fields (such as SMS OTP gateways), you can pass { strict: true } in options. This enforces the international country code prefix and rejects local leading zeros.

import { validateDRC } from 'valinum';

// This will fail in strict mode because it lacks the +243 / 243 prefix
const localCheck = validateDRC("081234567", { strict: true });
console.log(localCheck.isValid); // false
console.log(localCheck.error);   // "Indicatif international (+243) obligatoire en mode strict"

// This will fail because the 0 after the country code is invalid structure
const zeroCheck = validateDRC("+243081234567", { strict: true });
console.log(zeroCheck.isValid);  // false
console.log(zeroCheck.error);   // "Le chiffre 0 après l'indicatif international est interdit"

// This passes perfectly (spaces and hyphens are still sanitized)
const validCheck = validateDRC("+243 812-34-56-78", { strict: true });
console.log(validCheck.isValid); // true

4. Special Service & USSD Detection

By default, official platform short codes or financial menus return isValid: false to avoid polluting user profile setups.

import { validateDRC } from 'valinum';

// Testing a Mobile Money USSD string
const resultUSSD = validateDRC("*1122#");
console.log(resultUSSD.isServiceNumber); // true
console.log(resultUSSD.serviceType);     // "USSD"
console.log(resultUSSD.operator);        // "Vodacom"
console.log(resultUSSD.isValid);         // false (blocked by default)

// Bypassing restriction using options
const customResult = validateDRC("1111", { allowServices: true });
console.log(customResult.isValid);       // true

5. Real-time UX Shield

To prevent users from typing invalid characters while preserving USSD capabilities, update your input filter as follows:

const input = document.getElementById('phone');

input.addEventListener('input', (e) => {
    // Block characters that are not digits, +, -, spaces, parentheses, * or #
    e.target.value = e.target.value.replace(/[^\d+ \-()*#]/g, '');
    
    const res = ValiNum.validateDRC(e.target.value);
    // Apply your UI logic (badges, colors, etc.) here
});

API Parameter Options

The validateDRC function accepts an optional secondary configuration object:

Option	Type	Default	Description
forceCountry	boolean	false	Considers the entry as part of the local country context even without explicit data declaration.
allowServices	boolean	false	Set to true if your specific application explicitly permits or collects utility short codes or active USSD strings.
strict	boolean	false	Enforces structural validation requiring +243 or 243 and flags programmatic errors such as leading zero combinations.

API Response Schema

The object returned by validateDRC() contains the following fields:

Field	Type	Description
isValid	boolean	True if the number is standard, structure-compliant, and belongs to a known operator.
operator	string | null	Returns "Vodacom", "Orange", "Airtel", or "Africell".
formatted	string	Normalized international format string prefixed with +243, or the clean USSD expression.
error	string | null	Explicit localized error string describing validation failure reasons.
isServiceNumber	boolean	True if the string matches an ARPTC-regulated system node (USSD code or customer service short dial).
serviceType	string | null	Explicitly returns "USSD" or "ShortCode" if a service pattern matches, otherwise null.

Operator Mapping (DRC)

Operator	Prefixes (NDC)
Vodacom	81, 82, 83, 86
Orange	80, 84, 85, 89
Airtel	97, 98, 99
Africell	90, 91

License

This project is licensed under the FomaDev Public License (FPL).

• Free for personal and educational use.

• Free for integration into commercial projects (compiled version).

• Paid License required for selling modified versions or creating competing derivative works. See the LICENSE file for full details.

Contributing

Contributions to add support for other countries are welcome! Please read the CONTRIBUTING.md file before submitting a merge request.