feat: Comprehensive improvements with tiny-lru caching

[meabed]

Summary

• 🚀 Enhanced error handling and input validation
• 💾 Integrated high-performance tiny-lru caching with configurable size limits
• ♻️ Refactored code to eliminate duplication and improve maintainability
• ✅ Added 27 comprehensive test cases covering edge cases, performance, and cache management
• 🔧 New API functions for cache management: clearCache(), getCacheSize(), setCacheSize()

Key Improvements

Performance

• O(1) cache operations for get, set, and delete using tiny-lru
• LRU eviction prevents unbounded memory growth
• <1ms lookups after initial cache population
• Configurable cache size for memory management in long-running processes

Code Quality

• Better error handling with proper logging in development mode
• Unified helper functions eliminate code duplication between geocoder and carrier
• Improved TypeScript types with explicit return types and null safety
• Input validation for edge cases like undefined, empty strings, invalid numbers

Testing

• 35 total tests (27 new) covering:
  • Input validation edge cases
  • Cache management functionality
  • Locale fallback behavior
  • Performance benchmarks
  • Concurrent operations
  • Various phone number formats

Breaking Changes

None - all improvements are backward compatible.

Test Results

Test Suites: 3 passed, 3 total
Tests:       35 passed, 35 total
Snapshots:   0 total

Documentation

Added comprehensive IMPROVEMENTS.md file documenting all changes and new API usage.