Sanja (pronounced sahn-jah) means "organize", "sort", or "order" in Chichewa - perfectly describing what this package does for phone numbers!
A lightweight Go package for normalizing and organizing international phone numbers. Sanja helps you clean, validate, and standardize phone numbers with country code handling.
- Phone Number Normalization: Convert local numbers to international format
- Country Code Handling: Automatic detection and addition of country codes
- Bulk Processing: Normalize multiple numbers at once
- Flexible Configuration: Set default country for local number handling
- Comprehensive Country Data: 250+ countries with ISO codes and dialing codes
go get github.com/cod3ddy/sanjapackage main
import (
"fmt"
"github.com/cod3ddy/sanja"
)
func main() {
// Create a normalizer with Malawi as default country
norm := sanja.NewNormalizer("MW")
// Normalize a local Malawian number
normalized, err := norm.Normalize("0886392814")
if err != nil {
panic(err)
}
fmt.Println(normalized) // Output: +265886392814
}norm := sanja.NewNormalizer("US")
// Local number gets US country code
normalized, _ := norm.Normalize("555-123-4567")
// Result: +15551234567
// Already international - unchanged
normalized, _ := norm.Normalize("+442079460000")
// Result: +442079460000
// Number with country code but no + prefix
normalized, _ := norm.Normalize("265886392814")
// Result: +265886392814norm := sanja.NewNormalizer("MW")
phones := []string{
"0886392814",
"265886392814",
"+265886392814",
"00886392814",
}
results, errors := norm.NormalizeBulk(phones)
for i, phone := range results {
if errors[i] != nil {
fmt.Printf("Error with %s: %v\n", phones[i], errors[i])
} else {
fmt.Printf("Normalized: %s → %s\n", phones[i], phone)
}
}norm := sanja.NewNormalizer("US")
// Get country by ISO A2 code
country := norm.GetCountryByA2("MW")
fmt.Printf("Malawi dialing code: %s\n", country.DialingCode)
// Output: Malawi dialing code: 265
// Get country by dialing code
country = norm.GetCountryByCode("44")
fmt.Printf("Country with code 44: %s\n", country.Name)
// Output: Country with code 44: United KingdomSanja includes comprehensive country data for 250+ countries and territories with:
- ISO 3166-1 Alpha-2 codes (e.g.,
US,GB,MW) - ISO 3166-1 Alpha-3 codes (e.g.,
USA,GBR,MWI) - ISO 3166-1 Numeric codes (e.g.,
840,826,454) - International dialing codes (e.g.,
1,44,265)
The country data used in this package was sourced from Kaggle - Country 2ISO3UN Digit Code and Dialing Code.
type Country struct {
Name string
A2 string // ISO Alpha-2 code (e.g., "US")
A3 string // ISO Alpha-3 code (e.g., "USA")
NumCode int // ISO Numeric code (e.g., 840)
DialingCode string // International dialing code (e.g., "1")
}
type Normalizer struct {
countries []Country
defaultCountry *Country
codeMap map[string]*Country
}When a number doesn't have an international prefix, Sanja uses the default country:
// With US as default
norm := sanja.NewNormalizer("US")
norm.Normalize("4151234567") // → "+14151234567"
// With Malawi as default
norm := sanja.NewNormalizer("MW")
norm.Normalize("886392814") // → "+265886392814"norm := sanja.NewNormalizer("US")
// Empty string
_, err := norm.Normalize("")
// err: "invalid phone number"
// Invalid default country
norm := sanja.NewNormalizer("INVALID")
_, err := norm.Normalize("123456789")
// err: "no default country set"for testing i used this package by stretchr: Assert
Contributions are welcome! Please feel free to submit pull requests, report bugs, or suggest new features.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Country data sourced from Kaggle
- Name inspired by the Chichewa word "sanja" meaning to organize or put in order