[Feature/55] :: flexibility improvements

README.md

@@ -21,11 +21,11 @@ The name Mocaí is a tribute to the Brazilian initiative behind the library. It
 
 ## 📦 Supported Entities
 - Person (with gender, age, CPF)
+- Gender (standalone generation)
 - Address (street, number, city, state, UF, ZIP)
 - Phone (area code, number)
 - Company (name, CNPJ)
 - CPF (Brazilian individual taxpayer registry)
-- CNPJ (Brazilian company registry)
 - Certificates (Birth, Marriage, Death)
 - National ID (RG)
 - Voter Registration (Título de Eleitor)
@@ -64,54 +64,90 @@ import (
 
 func main() {
     // Create a Mocker instance for Brazilian Portuguese
-    mocker := mocai.NewMocker("ptbr", true, nil) // isFormatted: true for formatted docs (e.g., CPF/CNPJ)
+    mocker := mocai.NewMocker(
+        mocai.WithLanguage("ptbr"),
+        mocai.WithFormatted(true),
+    )
 
     // Generate a mock address
     address, err := mocker.NewAddress()
     if err != nil {
-        // Error messages are localized where translation keys are available
         log.Fatal(err)
     }
     fmt.Printf("Address: %s, %d - %s, %s (%s) - %s\n", address.Street, address.Number, address.City, address.State, address.UF, address.ZIP)
 
     // Generate a mock person
     person, err := mocker.NewPerson()
     if err != nil {
-        // Error messages are localized where translation keys are available
         log.Fatal(err)
     }
     fmt.Printf("Person: %s %s, Gender: %s, Age: %d, CPF: %s\n", person.FirstNameMale, person.LastName, person.Gender.Identity, person.Age, person.CPF.Number)
 
     // Generate a mock company
     company, err := mocker.NewCompany()
     if err != nil {
-        // Error messages are localized where translation keys are available
         log.Fatal(err)
     }
     fmt.Printf("Company: %s, CNPJ: %s\n", company.BrazilianCompany.Name, company.BrazilianCompany.CNPJ)
 }
-
 ```
 
 ### Error Messages & Localization
 
 Error messages are localized where translation keys are available. When an error occurs (e.g., invalid data, unsupported language, or generation failure), the error message will be presented in the language configured for the `Mocker` instance, if a translation exists. In some cases, fallback or hardcoded errors may occur if translation coverage is incomplete.
 
 You do not need to perform any extra steps for error localization — Mocai handles this automatically for all supported languages where translation keys are present.
-```
 
 > **Note:** Each call to a method like `NewPerson()` or `NewAddress()` generates a new mock with random data. The `Mocker` instance is immutable regarding its configuration (language, formatting, random source).
 
 #### About Languages
 Currently, only "ptbr" is implemented. To support other languages, contribute with new translation and mock data files.
 
 #### About Formatting
-The `isFormatted` parameter controls whether documents like CPF/CNPJ are returned formatted (e.g., `123.456.789-00`) or as plain numbers (`12345678900`).
+The `WithFormatted` option controls whether documents like CPF/CNPJ are returned formatted (e.g., `123.456.789-00`) or as plain numbers (`12345678900`).
+
+### Advanced Usage
+
+#### MockGenerator Interface
+The `MockGenerator` interface defines the contract for generating mock data. Use it for dependency injection in your tests:
+
+```go
+func CreateUser(generator mocai.MockGenerator) (*User, error) {
+    person, err := generator.NewPerson()
+    if err != nil {
+        return nil, err
+    }
+    return &User{Name: person.FirstNameMale + " " + person.LastName}, nil
+}
+```
+
+#### Custom Providers
+You can inject custom providers for Address, Person, and Company to integrate with external APIs or databases:
+
+```go
+mocker := mocai.NewMocker(
+    mocai.WithLanguage("ptbr"),
+    mocai.WithAddressProvider(myCustomAddressProvider),
+    mocai.WithPersonProvider(myCustomPersonProvider),
+    mocai.WithCompanyProvider(myCustomCompanyProvider),
+)
+```
+
+#### Deterministic Generation
+Use `WithRandSource` to provide a custom random source for reproducible test data:
+
+```go
+rnd := translations.NewSafeRandSource(myFixedRand)
+mocker := mocai.NewMocker(
+    mocai.WithLanguage("ptbr"),
+    mocai.WithRandSource(rnd),
+)
+```
 
 ### Examples
 The ***examples*** folder contains usage samples:
 
-- `mocker/`: Example using the main entry point `mocai.NewMocker(lang string, isFormatted bool, rnd RandSource)` to generate mocks in a fluent and simplified way.
+- `mocker/`: Example using the main entry point `mocai.NewMocker(opts ...Option)` with functional options to generate mocks in a fluent and simplified way.
 
 To run an example:
 ```sh

docs/localization/pt/README-PT.md

@@ -2,6 +2,8 @@
 
 ![mocai](../../.././img/mocai.svg)
 
+#### [README (English)](/README.md)
+
 Uma biblioteca Go para geração de dados de teste, permitindo criar mocks de entidades de forma simples e eficiente.
 
 ## 📖 Descrição
@@ -19,11 +21,11 @@ O nome Mocai é uma homenagem à iniciativa brasileira por trás da biblioteca.
 
 ## 📦 Entidades Suportadas
 - Pessoa (com gênero, idade, CPF)
+- Gênero (geração independente)
 - Endereço (rua, número, cidade, estado, UF, CEP)
 - Telefone (DDD, número)
 - Empresa (nome, CNPJ)
 - CPF (Cadastro de Pessoa Física)
-- CNPJ (Cadastro Nacional de Pessoa Jurídica)
 - Certidões (Nascimento, Casamento, Óbito)
 - RG (Identidade)
 - Título de Eleitor
@@ -62,54 +64,90 @@ import (
 
 func main() {
     // Cria uma instância do Mocker para português do Brasil
-    mocker := mocai.NewMocker("ptbr", true, nil) // isFormatted: true para documentos formatados (ex: CPF/CNPJ)
+    mocker := mocai.NewMocker(
+        mocai.WithLanguage("ptbr"),
+        mocai.WithFormatted(true),
+    )
 
     // Gera um endereço fictício
     address, err := mocker.NewAddress()
     if err != nil {
-        // As mensagens de erro são localizadas quando há chave de tradução disponível
         log.Fatal(err)
     }
     fmt.Printf("Endereço: %s, %d - %s, %s (%s) - %s\n", address.Street, address.Number, address.City, address.State, address.UF, address.ZIP)
 
     // Gera uma pessoa fictícia
     person, err := mocker.NewPerson()
     if err != nil {
-        // As mensagens de erro são localizadas quando há chave de tradução disponível
         log.Fatal(err)
     }
     fmt.Printf("Pessoa: %s %s, Gênero: %s, Idade: %d, CPF: %s\n", person.FirstNameMale, person.LastName, person.Gender.Identity, person.Age, person.CPF.Number)
 
     // Gera uma empresa fictícia
     company, err := mocker.NewCompany()
     if err != nil {
-        // As mensagens de erro são localizadas quando há chave de tradução disponível
         log.Fatal(err)
     }
     fmt.Printf("Empresa: %s, CNPJ: %s\n", company.BrazilianCompany.Name, company.BrazilianCompany.CNPJ)
 }
-
 ```
 
 ### Mensagens de Erro e Localização
 
 As mensagens de erro são localizadas quando há chave de tradução disponível. Quando ocorre um erro (ex: dados inválidos, idioma não suportado ou falha na geração), a mensagem será apresentada no idioma configurado para a instância do `Mocker`, se houver tradução. Em alguns casos, mensagens fixas podem aparecer caso a cobertura de traduções não seja completa.
 
 Não é necessário realizar nenhuma etapa extra para a localização das mensagens de erro — o Mocai faz isso automaticamente para todos os idiomas suportados onde há chave de tradução.
-```
 
 > **Nota:** Cada chamada de método como `NewPerson()` ou `NewAddress()` gera um novo mock com dados aleatórios. A instância do `Mocker` é imutável quanto à configuração (idioma, formatação, fonte de aleatoriedade).
 
 #### Sobre Idiomas
 Atualmente, apenas "ptbr" está implementado. Para suportar outros idiomas, contribua com novos arquivos de tradução e mocks.
 
 #### Sobre Formatação
-O parâmetro `isFormatted` controla se documentos como CPF/CNPJ são retornados formatados (ex: `123.456.789-00`) ou apenas números (`12345678900`).
+A opção `WithFormatted` controla se documentos como CPF/CNPJ são retornados formatados (ex: `123.456.789-00`) ou apenas números (`12345678900`).
+
+### Uso Avançado
+
+#### Interface MockGenerator
+A interface `MockGenerator` define o contrato para geração de dados fictícios. Use-a para injeção de dependência nos seus testes:
+
+```go
+func CreateUser(generator mocai.MockGenerator) (*User, error) {
+    person, err := generator.NewPerson()
+    if err != nil {
+        return nil, err
+    }
+    return &User{Name: person.FirstNameMale + " " + person.LastName}, nil
+}
+```
+
+#### Providers Customizados
+Você pode injetar providers customizados para Address, Person e Company, integrando com APIs externas ou bancos de dados:
+
+```go
+mocker := mocai.NewMocker(
+    mocai.WithLanguage("ptbr"),
+    mocai.WithAddressProvider(meuProviderDeEndereco),
+    mocai.WithPersonProvider(meuProviderDePessoa),
+    mocai.WithCompanyProvider(meuProviderDeEmpresa),
+)
+```
+
+#### Geração Determinística
+Use `WithRandSource` para fornecer uma fonte de aleatoriedade customizada para dados reproduzíveis em testes:
+
+```go
+rnd := translations.NewSafeRandSource(meuRandFixo)
+mocker := mocai.NewMocker(
+    mocai.WithLanguage("ptbr"),
+    mocai.WithRandSource(rnd),
+)
+```
 
 ### Exemplos
 O diretório ***examples*** contém exemplos de uso:
 
-- `mocker/`: Exemplo usando o ponto de entrada principal `mocai.NewMocker(lang string, isFormatted bool, rnd RandSource)` para gerar mocks de maneira fluida e simplificada.
+- `mocker/`: Exemplo usando o ponto de entrada principal `mocai.NewMocker(opts ...Option)` com functional options para gerar mocks de maneira fluida e simplificada.
 
 Para executar um exemplo:
 ```sh

examples/mocker/main.go

@@ -2,28 +2,87 @@ package main
 
 import (
 	"fmt"
+	"log"
 
 	"github.com/brazzcore/mocai/internal/cli"
 	"github.com/brazzcore/mocai/pkg/mocai"
 )
 
 func main() {
-
 	fmt.Println(cli.HeaderMain)
 	fmt.Println(cli.SubHeader)
 
-	m := mocai.NewMocker("ptbr", true, nil)
+	// Create a Mocker using functional options
+	m := mocai.NewMocker(
+		mocai.WithLanguage("ptbr"),
+		mocai.WithFormatted(true),
+	)
+
+	// Generate a mock person
+	p, err := m.NewPerson()
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("Person: %s %s, Gender: %s, Age: %d, CPF: %s\n",
+		p.FirstNameMale, p.LastName, p.Gender.Identity, p.Age, p.CPF.Number)
+
+	// Generate a mock address
+	addr, err := m.NewAddress()
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("Address: %s, %d - %s, %s (%s) - %s\n",
+		addr.Street, addr.Number, addr.City, addr.State, addr.UF, addr.ZIP)
+
+	// Generate a mock company
+	comp, err := m.NewCompany()
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("Company: %s, CNPJ: %s\n", comp.BrazilianCompany.Name, comp.BrazilianCompany.CNPJ)
+
+	// Generate a mock CPF
+	cpfVal, err := m.NewCPF()
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("CPF: %s\n", cpfVal.Number)
+
+	// Generate a mock certificate
+	cert, err := m.NewCertificate()
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("Birth Certificate: %s\n", cert.Brazil.BirthCertificate.Number)
+
+	// Generate a mock national ID (RG)
+	nid, err := m.NewNationalID()
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("RG: %s - %s/%s\n", nid.BrazilianRG.Number, nid.BrazilianRG.IssuingBody, nid.BrazilianRG.State)
+
+	// Generate a mock voter registration
+	vr, err := m.NewVoteRegistration()
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("Voter Registration: %s (Section: %s, Zone: %s)\n",
+		vr.BrazilianVoteRegistration.Number, vr.BrazilianVoteRegistration.Section, vr.BrazilianVoteRegistration.Zone)
 
-	address, err := m.NewAddress()
+	// Generate a mock phone
+	ph, err := m.NewPhone()
 	if err != nil {
-		fmt.Println(err)
-	} else {
-		fmt.Printf("Address: %s, %d - %s, %s (%s) - %s\n",
-			address.Street, address.Number, address.City, address.State, address.UF, address.ZIP)
+		log.Fatal(err)
 	}
+	fmt.Printf("Phone: (%s) %s\n", ph.AreaCode, ph.Number)
 
-	certificate, _ := m.NewCertificate()
-	fmt.Println("Brazilian birth certificate:", certificate.Brazil.BirthCertificate.Number)
+	// You can also use the MockGenerator interface for dependency injection:
+	printLanguage(m)
 
 	fmt.Println(cli.Footer)
 }
+
+func printLanguage(m mocai.MockGenerator) {
+	fmt.Printf("\nLanguage: %s\n", m.Language())
+}

pkg/mocai/entities/address/generator.go

@@ -17,12 +17,13 @@ type Address struct {
 	ZIP    string
 }
 
-type SlicesToCheck struct {
+// slicesToCheck is an internal helper for validating required data slices.
+type slicesToCheck struct {
 	data []string
 	err  error
 }
 
-// NewAddress generates a mock address using a custom language and a random source
+// NewAddress generates a mock address using a custom language and a random source.
 func NewAddress(lang string, rnd translations.RandSource) (*Address, error) {
 	addr, err := generateAddress(lang, rnd)
 	if err != nil {
@@ -37,22 +38,22 @@ func generateAddress(lang string, rnd translations.RandSource) (*Address, error)
 		supportedLang = "ptbr"
 	}
 	if rnd == nil {
-		rnd = translations.NewSafeRandSource(translations.DefaultRandSource())
+		rnd = translations.DefaultRandSource()
 	}
 
 	streets := translations.GetList(supportedLang, "address_street")
 	cities := translations.GetList(supportedLang, "address_city")
 	states := translations.GetList(supportedLang, "address_state")
 	zips := translations.GetList(supportedLang, "address_zip")
 
-	slicesToCheck := []SlicesToCheck{
+	checks := []slicesToCheck{
 		{streets, ErrNoStreets},
 		{cities, ErrNoCities},
 		{states, ErrNoStates},
 		{zips, ErrNoZips},
 	}
 
-	for _, s := range slicesToCheck {
+	for _, s := range checks {
 		if len(s.data) == 0 {
 			return nil, s.err
 		}