sanja

README

Sanja

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.

Features

• 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

Installation

go get github.com/cod3ddy/sanja

Quick Start

package 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
}

Usage Examples

Basic Normalization

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: +265886392814

Bulk Processing

norm := 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)
    }
}

Country Information

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 Kingdom

Supported Countries

Sanja 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)

Data Source

The country data used in this package was sourced from Kaggle - Country 2ISO3UN Digit Code and Dialing Code.

API Reference

Types

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
}

Testing

Handling Local Numbers

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"

Error Handling

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"

Testing

for testing i used this package by stretchr: Assert

Contributing

Contributions are welcome! Please feel free to submit pull requests, report bugs, or suggest new features.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Country data sourced from Kaggle
• Name inspired by the Chichewa word "sanja" meaning to organize or put in order

Documentation

Overview

Package sanja provides phone number normalization and formatting.

Overview: Sanja helps normalize phone numbers to international format with country code handling. It supports 250+ countries and bulk processing.

Example:

norm := sanja.NewNormalizer("US")
normalized, err := norm.Normalize("555-123-4567")
// Result: "+15551234567"

Features:

• Local to international number conversion
• Bulk phone number processing
• Country code detection
• Comprehensive country data

Index

• Constants
• Variables
• type Country
• type Normalizer
  • func NewNormalizer(defaultCountryA2 string) *Normalizer
  • func (n *Normalizer) GetCountryByA2(a2 string) *Country
  • func (n *Normalizer) GetCountryByCode(code string) *Country
  • func (n *Normalizer) Normalize(phone string) (string, error)
  • func (n *Normalizer) NormalizeBulk(phones []string) ([]string, []error)
  • func (n *Normalizer) ValidatePhoneNumber(phone, countryA2 string) error

Constants

const (
	MinimumLocalDigitsLength int = 7
	MaximumLocalDigitsLength int = 12
)

Variables

var ErrDefaultCountryNotFound = errors.New("no default country set")

var ErrInvalidPhoneNumber = errors.New("invalid phone number")

var ErrPhoneNumberAndCountryCodeMismatch = errors.New("phone number does not match country code")

var ErrUnknownCountry = errors.New("invalid or unknown country")

Types

type Country

type Country struct {
	Name        string
	A2          string
	A3          string
	NumCode     int
	DialingCode string
}

Country represents a country with its dialing codes

type Normalizer

type Normalizer struct {
	// contains filtered or unexported fields
}

Normalizer hanldes phone numbder normalization

func NewNormalizer

func NewNormalizer(defaultCountryA2 string) *Normalizer

NewNormalizer creatres a new phone number normalizer

func (*Normalizer) GetCountryByA2

func (n *Normalizer) GetCountryByA2(a2 string) *Country

GetCountryByA2 returns a countyr by its A2 code

func (*Normalizer) GetCountryByCode

func (n *Normalizer) GetCountryByCode(code string) *Country

GetCountryByCode returns a country by its dialing code

func (*Normalizer) Normalize

func (n *Normalizer) Normalize(phone string) (string, error)

Normalize adds the country code prefix to a phone number if missing

func (*Normalizer) NormalizeBulk

func (n *Normalizer) NormalizeBulk(phones []string) ([]string, []error)

NormalizeBulk normalizes multiple phone numbers

func (*Normalizer) ValidatePhoneNumber

func (n *Normalizer) ValidatePhoneNumber(phone, countryA2 string) error

ValidatePhoneNumber validates if a phone number matches a specific country