How timiagama/nigerian-mobile-validator works
Project type and purpose
• This is an open-source, TypeScript‐based NPM library (“nigerian-mobile-validator”) whose sole purpose is to validate Nigerian mobile numbers against the NCC numbering plan. It’s not a full-stack app; it’s a modular tool intended for integration into other applications (fintech, telco, web, serverless, SSR, etc.).
File structure
• Top‐level: configuration files (.eslintrc.json, tsconfig*, jest.config.ts), CI/CD workflows (.github/workflows), docs, package.json
• src/ holds the library code, subdivided into:
• events/ (event emitter)
• logging/ (ILogger interface + implementations)
• number-validation/ (core validator interfaces and result types)
• numbering-plan/ (data model for ranges, network codes, telcos)
• security/ (ValidatorSecurity, rate limiting, sanitization)
• utils/ (runtime detection, general‐purpose utilities)
• index.ts exports public API (NigerianMobileNumberValidator, batchValidate, LoggerFactory, types)
README for additional insights
• Key features:
• Complete NCC compliance (data-driven lookups)
• Enterprise security (input sanitization, rate limiting)
• Reactive API (event emitter)
• Batch processing (array + file)
• Pluggable logging (Winston, Pino, console) with automatic PII masking
• Dual module support (ESM + CJS)
• SSR compatibility
• CI/CD integration with GitHub Actions (CodeQL, Snyk, SonarQube, Dependabot)
Main components
a. Core Validator Module
• NigerianMobileNumberValidator class (validate(), onValidationResult(), dispose())
• Uses sub‐modules in number‐validation/
b. Numbering Plan Data Module
• mobile-numbering-plan.ts, mobile-number-range.ts, network-access-code.ts, telco-number-allocation.ts
• Lazy‐loaded map/dictionary lookups of NCC data (source: docs/*.csv, .ods)
c. Security Module
• ValidatorSecurity: input sanitization, rate limiting, fast‐reject filters
d. Event Emitter
• event-emitter.ts: publishes validation results to listeners (reactive architecture)
e. Logging Module
• ILogger interface + LoggerFactory
• Adapters for console, Winston, Pino with PII masking wrappers
f. Batch Processing
• batchValidate functions (array API + fromFile) + CSV exporter
g. Utilities
• general-utils, runtime-environment detection for SSR vs. browser vs. Node
h. Public API Layer
• index.ts assembling and exporting all public classes, functions, types
Relationships and data flow
• Input (phone string) → Security Module (sanitize + rate limit) → Core Validator →
• Numbering Plan Data Module (look up network code, range, status) →
• Validation logic emits result objects →
• Logger Module (mask PII + output logs)
• Event Emitter (push result to subscribers) →
• Consumer receives result (synchronous return or async via event)
• Batch API: wraps multiple calls to Core Validator + aggregates results → optional CSV export
Architectural patterns and design principles
• Modular layering (Separation of concerns: security, validation logic, data, logging, eventing)
• Dependency Injection (ILogger implementations via LoggerFactory)
• Reactive pattern (Observer via event emitter)
• Data‐driven design (uses NCC data files as authoritative source)
• Strategy pattern (batch vs. single validation, ESM vs. CJS)