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/[email protected]/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:

API Response Schema

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

Operator Mapping (DRC)

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.