validart_br 0.1.0

Extensão do validart com validadores brasileiros (CPF, CNPJ, PIX, telefone e mais) e tradução pt-BR completa.

Validart BR

Extensão do validart com validadores brasileiros e locale pt-BR.

Validadores implementados como patterns dos pontos de extensão do core — mesma API que qualquer outro país. Traz também um VLocale pt-BR completo (cobre todas as mensagens do core + as deste pacote) e métodos de atalho para reduzir o verbosismo em código BR-only.

Sumário

• Instalação
• Uso básico
• Validadores
  • CPF
  • CNPJ
  • CEP
  • PIS/PASEP
  • Título de eleitor
  • CNH
  • Renavam
  • Telefone brasileiro
  • Placa
  • Chave PIX
• Duas formas equivalentes
• ValidationMode
• Locale pt-BR
  • Override de mensagens
  • Códigos de erro
• Extensibilidade
  • Escrevendo um pattern novo
• Exemplo completo
• Licença

Instalação

dart pub add validart validart_br

import 'package:validart/validart.dart';
import 'package:validart_br/validart_br.dart';

Uso básico

// Aplica as traduções pt-BR do core + validart_br
V.setLocale(VLocaleBr.ptBr);

final schema = V.string().trim().cpf();

schema.validate('123.456.789-09'); // true
schema.validate('111.111.111-11'); // false

schema.errors('000.000.000-00')?.first.message; // 'CPF inválido'

// parse — lança ao falhar
schema.parse('123.456.789-09'); // '123.456.789-09'

// safeParse — nunca lança
final result = schema.safeParse('000.000.000-00');
if (result case VFailure(:final errors)) {
  print(errors.first.message); // 'CPF inválido'
}

Validadores

Método	Descrição
cpf({mode, message})	CPF (11 dígitos). mode controla se aceita máscara.
cnpj({mode, alphanumeric, message})	CNPJ. Default aceita o novo formato alfanumérico da Receita.
cep({mode, message})	CEP (8 dígitos).
pis({mode, message})	PIS/PASEP/NIS (11 dígitos).
tituloEleitor({message})	Título de eleitor (12 dígitos, UF 01–28).
cnh({message})	CNH (11 dígitos).
renavam({message})	Renavam (11 dígitos).
phoneBr({…})	Telefone BR com flags de DDD, DDI, mobileOnly e mode.
plate({mode, message})	Placa — formato antigo (AAA-9999) ou Mercosul (AAA9A99).
pixKey({allow, message})	Identificador PIX — chaves do DICT e/ou BR Code. allow restringe os tipos aceitos.

CPF

V.string().cpf().validate('123.456.789-09'); // true
V.string().cpf().validate('11111111111');    // false (repetido)

V.string().cpf(mode: ValidationMode.unformatted)
  .validate('12345678909'); // true

CNPJ

A partir de julho/2026 a Receita Federal emite CNPJs alfanuméricos: os 12 primeiros caracteres podem ser [0-9A-Z] e os 2 últimos (DVs) continuam numéricos. validart_br aceita esse formato por padrão e continua validando os CNPJs puramente numéricos existentes — dígitos são subconjunto do alfanumérico.

V.string().cnpj().validate('12.345.678/0001-95'); // true (numérico)
V.string().cnpj().validate('12.ABC.345/01DE-35'); // true (alfanumérico)

V.string().cnpj(alphanumeric: false)
  .validate('12.ABC.345/01DE-35'); // false — só dígitos

Letras devem vir em caixa alta. Se o input pode vir com minúsculas, encadeie .toUpperCase() antes (mesma regra para plate()):

V.string().toUpperCase().cnpj();
V.string().toUpperCase().plate();

CEP

V.string().cep().validate('01001-000'); // true
V.string().cep().validate('01001000');  // true
V.string().cep().validate('0100100');   // false

PIS/PASEP

V.string().pis().validate('120.54789.01-3'); // true
V.string().pis().validate('12054789013');    // true

Título de eleitor

V.string().tituloEleitor().validate('876543210329'); // true
V.string().tituloEleitor().validate('123456780099'); // false (UF 00)

CNH

V.string().cnh().validate('12345678900'); // true
V.string().cnh().validate('00000000000'); // false

Renavam

V.string().renavam().validate('12345678900'); // true

Telefone brasileiro

Aceita celular (9 dígitos iniciando com 9) e fixo (8 dígitos), com ou sem DDD e DDI. Use os parâmetros para restringir a forma.

V.string().phoneBr().validate('(11) 98765-4321'); // true
V.string().phoneBr().validate('11987654321');     // true
V.string().phoneBr().validate('[phone]'); // true

V.string().phoneBr(
  countryCode: CountryCodeFormat.required, // exige +55
  areaCode: AreaCodeFormat.required,       // exige DDD
  mobileOnly: true,                        // só celular
  mode: ValidationMode.formatted,          // exige separadores
).validate('[phone]'); // true

Placa

Aceita formato antigo (AAA-9999 / AAA9999) e Mercosul (AAA9A99). Letras devem estar em caixa alta — encadeie .toUpperCase() quando o input pode vir minúsculo.

V.string().plate().validate('ABC-1234'); // true (antiga)
V.string().plate().validate('ABC1D23');  // true (Mercosul)

V.string().toUpperCase().plate().validate('abc-1234'); // true

Chave PIX

pixKey() aceita por padrão as cinco chaves do DICT:

• CPF (11 dígitos, sem máscara)
• CNPJ (14 dígitos, só numérico, sem máscara)
• E-mail
• Telefone em E.164 com +55 e celular (+55DDDNNNNNNNNN)
• UUID v4 (chave aleatória)

Cada formato é checado no modo estrito exigido pelo PIX.

V.string().pixKey().validate('12345678909');                        // true (CPF)
V.string().pixKey().validate('[e-mail]');                   // true (e-mail)
V.string().pixKey().validate('[phone]');                     // true (telefone)
V.string().pixKey().validate('123e4567-e89b-12d3-a456-426614174000'); // true (UUID)

Restrinja os tipos aceitos com allow:

V.string().pixKey(allow: const [PixKeyType.email, PixKeyType.phone]);
// rejeita CPF, CNPJ e UUID

Inclua PixKeyType.brCode para também aceitar o BR Code — payload EMVCo do QR Code PIX ("copia e cola"). A validação segue o padrão de mercado (estrito): estrutura TLV, CRC16-CCITT-FALSE batendo e campos obrigatórios do Bacen (moeda 986, país BR, GUID br.gov.bcb.pix).

// Aceita os 5 tipos de chave + BR Code:
V.string().pixKey(allow: PixKeyType.values);

// Só BR Code:
V.string().pixKey(allow: const [PixKeyType.brCode]);

Duas formas equivalentes

Cada validador BR tem duas formas de uso, ambas sempre equivalentes:

Atalho	Forma explícita via pattern do core
V.string().cpf()	V.string().taxId(patterns: [const CpfPattern()])
V.string().cnpj()	V.string().taxId(patterns: [const CnpjPattern()])
V.string().pis()	V.string().taxId(patterns: [const PisPattern()])
V.string().tituloEleitor()	V.string().taxId(patterns: [const TituloEleitorPattern()])
V.string().cnh()	V.string().taxId(patterns: [const CnhPattern()])
V.string().renavam()	V.string().taxId(patterns: [const RenavamPattern()])
V.string().cep()	V.string().postalCode(patterns: [const CepPattern()])
V.string().plate()	V.string().licensePlate(patterns: [const BrPlatePattern()])
V.string().phoneBr()	V.string().phone(patterns: [const BrPhonePattern()])

Use os atalhos em código BR-only (mais legível). Use os patterns explícitos quando precisar compor múltiplos países na mesma validação:

V.string().taxId(patterns: [const CpfPattern(), const UsSsnPattern()]);
// aceita CPF brasileiro OU Social Security Number americano

ValidationMode

Validadores com máscara aceitam ValidationMode para controlar a forma:

V.string().cpf(mode: ValidationMode.any);         // default: com ou sem máscara
V.string().cpf(mode: ValidationMode.formatted);   // só com máscara
V.string().cpf(mode: ValidationMode.unformatted); // só dígitos

Aplica-se a cpf, cnpj, cep, pis, plate e phoneBr.

Locale pt-BR

VLocaleBr.ptBr traduz todas as mensagens do core do validart mais os códigos específicos do validart_br:

V.setLocale(VLocaleBr.ptBr);

V.string().email().errors('x')?.first.message;
// 'E-mail inválido'

V.string().cpf().errors('000.000.000-00')?.first.message;
// 'CPF inválido'

V.string().min(3).errors('a')?.first.message;
// 'Deve ter no mínimo 3 caracteres'

Duas formas de aplicar:

// 1. Pronto para uso (core + BR):
V.setLocale(VLocaleBr.ptBr);

// 2. Override pontual:
V.setLocale(VLocaleBr.ptBrWith({
  VCode.required: 'Obrigatório',
  VStringCode.taxId: '{name} fora do padrão',
}));

Se precisar de acesso aos mapas brutos (ex.: compor com mensagens de outro pacote), use VLocaleBr.coreMessages, VLocaleBr.brMessages e VLocaleBr.messages (união das duas).

Override de mensagens

Override global (via locale) afeta todos os validadores que emitem o código:

V.setLocale(VLocaleBr.ptBrWith({
  VStringCode.taxId: '{name} fora do padrão', // CPF/CNPJ/PIS/CNH/…
}));

Override por chamada (via parâmetro message) sobrescreve só aquela instância — útil quando o gênero gramatical da mensagem importa:

V.string().cnh(message: 'CNH inválida');   // força feminino só aqui
V.string().plate(message: 'Placa não reconhecida');

Códigos de erro

Os patterns plugáveis do core usam códigos genéricos com interpolação de {name}:

Código do core	Template pt-BR	Exemplos renderizados
VStringCode.taxId	{name} inválido	"CPF inválido", "CNPJ inválido", "CNH inválido"
VStringCode.postalCode	{name} inválido	"CEP inválido"
VStringCode.licensePlate	{name} inválida	"Placa inválida"
VStringCode.phone	Telefone inválido (sem interpolação)	"Telefone inválido"

O {name} vem da propriedade name de cada pattern — CpfPattern declara 'CPF', CnpjPattern declara 'CNPJ', e assim por diante.

Único código específico do validart_br:

Constante	Código	Mensagem pt-BR
VStringCodeBr.invalidPixKey	invalid_pix_key	Chave PIX inválida

Extensibilidade

Este pacote é construído inteiramente sobre os pontos de extensão públicos do core. Cada validador BR é uma classe que estende um abstract do validart:

Pattern BR	Abstract do core
CpfPattern	TaxIdPattern
CnpjPattern	TaxIdPattern
PisPattern	TaxIdPattern
TituloEleitorPattern	TaxIdPattern
CnhPattern	TaxIdPattern
RenavamPattern	TaxIdPattern
CepPattern	PostalCodePattern
BrPlatePattern	LicensePlatePattern
BrPhonePattern	PhonePattern

O único validador standalone é PixKeyValidator — é uma união de formatos heterogêneos (chaves do DICT + BR Code), então não cabe num único pattern.

Escrevendo um pattern novo

Se precisar de um validador que não está aqui, escreva um pattern próprio — mesma API que os patterns deste pacote:

class MeuDocumentoPattern extends TaxIdPattern {
  const MeuDocumentoPattern();

  @override
  String get name => 'Meu Documento';

  @override
  bool matches(String value) {
    // sua regra de validação aqui
    return value.length == 10;
  }
}

V.string().taxId(patterns: [const MeuDocumentoPattern()]);
// Mensagem com VLocaleBr.ptBr: "Meu Documento inválido"

Se quiser combinar vários países/documentos na mesma validação, passe todos em patterns::

V.string().taxId(patterns: [
  const CpfPattern(),
  const CnpjPattern(),
  const MeuDocumentoPattern(),
]);

Exemplo completo

Veja example/example.dart. Para rodar:

dart run example/example.dart

Licença

Veja LICENSE para detalhes.