Brazilian.PrimitivesTypes 1.2.0

Brazilian.PrimitivesTypes

Idioma: Português do Brasil | English

Brazilian.PrimitivesTypes é uma biblioteca .NET para modelar identificadores brasileiros como value objects imutáveis.

Ela valida e normaliza valores como CPF, CNPJ, CEP, chaves Pix, telefones brasileiros, placas, RENAVAM, CNH, CNS, título eleitoral, inscrição estadual e identificadores bancários sem fazer chamadas externas.

Instalação

dotnet add package Brazilian.PrimitivesTypes

O repositório atual usa .NET 10.

Exemplo Rápido

using Brazilian.PrimitivesTypes;

Cpf cpf = Cpf.Parse("529.982.247-25");
Cnpj cnpj = Cnpj.Parse("00.000.000/e08g-12");
Cep cep = Cep.Parse("01311-000");
ChavePix pix = ChavePix.Parse("(11) 98765-4321");

Console.WriteLine(cpf.Value);       // 52998224725
Console.WriteLine(cnpj.Value);      // 00000000E08G12
Console.WriteLine(cep.Formatted);   // 01311-000
Console.WriteLine(pix.Value);       // +5511987654321

Dapper + SQL Server

A integração com Dapper também é opcional e vive em um pacote separado:

dotnet add package Brazilian.PrimitivesTypes.Dapper.SqlServer

Registre os handlers uma vez no bootstrap da aplicação:

using Brazilian.PrimitivesTypes.Dapper.SqlServer;

BrazilianPrimitivesDapperSqlServer.Register();

Os handlers permitem usar os primitives diretamente em parâmetros escalares de INSERT, UPDATE e WHERE, além de materializá-los em SELECT. Eles enviam o Value canônico como AnsiString com o tamanho recomendado para varchar(n).

Dapper não cria schema nem migrations: a aplicação continua responsável pelas colunas SQL Server. Rg e InscricaoEstadual são Value-only nesta integração; a UF não é persistida nem recuperada. List expansion (IN @Values) de coleções de primitives não usa os handlers por item no Dapper 2.1.x e, por isso, não é declarada como cenário suportado.

Consulte o guia completo de Dapper com SQL Server para instalação, SqlConnection, registro, INSERT, SELECT, UPDATE, filtros parametrizados, nullable, DynamicParameters, tabela completa de varchar(n) e diferenças em relação ao EF Core.

Entity Framework Core + SQL Server

A integração com EF Core é opcional e vive em um pacote separado:

dotnet add package Brazilian.PrimitivesTypes.EntityFrameworkCore.SqlServer

Ela persiste os Value canônicos em colunas SQL Server, respeita T? como SQL NULL e permite consultas LINQ usando os tipos fortes do domínio. RG e Inscrição Estadual suportam modos explícitos context-free e state-aware; nenhuma UF é inferida automaticamente.

Consulte o guia completo de Entity Framework Core com SQL Server para o exemplo Customer, convenções globais, Fluent API, schema esperado, nullabilidade e persistência de Rg/InscricaoEstadual com e sem UF.

O Que a Biblioteca Faz

• Representa identificadores brasileiros com tipos explícitos.
• Preserva zeros à esquerda.
• Aceita somente formatos documentados.
• Normaliza valores canônicos de forma determinística.
• Implementa dígitos verificadores locais quando o tipo realmente contém esse algoritmo.
• Separa validade estrutural ou matemática de existência real.

Limites de Validação

IsValid, TryParse e Parse são operações locais. Elas não consultam Receita Federal, Correios, Banco Central, DICT, Anatel, SENATRAN, DETRAN, TSE, CADSUS, SINTEGRA, SEFAZ, Caixa, Banco do Brasil, CNIS ou sistemas bancários.

Um valor aceito pela biblioteca pode ter estrutura ou dígitos verificadores válidos e ainda assim não existir, não estar ativo, não pertencer a determinada pessoa ou empresa, não estar regular, não ser alcançável ou não estar vigente em uma base oficial.

Primitivos Suportados

Consulte o inventário de primitivos para formatos canônicos, formatos aceitos, normalizações e modo de validação.

Design

A biblioteca segue um contrato conservador de value objects:

• entrada inválida falha na criação;
• valores canônicos são armazenados como string, não como número;
• igualdade usa o valor normalizado e, quando necessário, contexto explícito como BrazilianState;
• instâncias default de structs não expõem valor válido;
• nenhum tipo remove texto arbitrário para tentar encontrar um identificador dentro dele.

Leia mais em Princípios de design.

Desenvolvimento

dotnet tool restore
dotnet restore --locked-mode
dotnet format Brazilian.PrimitivesTypes.slnx --verify-no-changes --no-restore
dotnet build Brazilian.PrimitivesTypes.slnx --configuration Release --no-restore
dotnet test Brazilian.PrimitivesTypes.slnx --configuration Release --no-build

Validação dos pacotes:

dotnet pack src/Brazilian.PrimitivesTypes/Brazilian.PrimitivesTypes.csproj --configuration Release --no-build --output artifacts/packages
dotnet pack src/Brazilian.PrimitivesTypes.EntityFrameworkCore.SqlServer/Brazilian.PrimitivesTypes.EntityFrameworkCore.SqlServer.csproj --configuration Release --no-build --output artifacts/packages
dotnet pack src/Brazilian.PrimitivesTypes.Dapper.SqlServer/Brazilian.PrimitivesTypes.Dapper.SqlServer.csproj --configuration Release --no-build --output artifacts/packages
dotnet run --file scripts/verify-package.cs -- artifacts/packages --package-id Brazilian.PrimitivesTypes
dotnet run --file scripts/verify-package.cs -- artifacts/packages --package-id Brazilian.PrimitivesTypes.EntityFrameworkCore.SqlServer --expected-dependency Brazilian.PrimitivesTypes
dotnet run --file scripts/verify-package.cs -- artifacts/packages --package-id Brazilian.PrimitivesTypes.Dapper.SqlServer --expected-dependency Brazilian.PrimitivesTypes
dotnet run --file scripts/verify-package.cs -- artifacts/packages --package-id Brazilian.PrimitivesTypes.Dapper.SqlServer --expected-dependency Dapper

Contribuição

Veja CONTRIBUTING.md, CHANGELOG.md e SECURITY.md.