brazilian-docs-validator
v0.1.2
Published
Utilities to validate, parse and format Brazilian documents and identifiers.
Downloads
450
Maintainers
Readme
brazilian-docs-validator
brazilian-docs-validator é uma biblioteca para validar, interpretar, normalizar
e formatar documentos e identificadores brasileiros. A API é pequena, combinável,
tipada e segura, com suporte a ESM, CommonJS e declarações TypeScript.
Módulos disponíveis: CPF, CNPJ, Título de Eleitor, PIS/PASEP/NIT/NIS e Cartão SUS / CNS.
Instalação
npm install brazilian-docs-validatorSumário
- Visão Geral
- Entrypoints
- CPF
- CNPJ
- Título de Eleitor
- PIS / PASEP / NIT / NIS
- Cartão SUS / CNS
- Desenvolvimento
Visão Geral
A biblioteca expõe funções pequenas e combináveis para três fluxos principais:
- Validação booleana, quando você só precisa de
trueoufalse. - Validação detalhada, quando precisa de códigos de erro estáveis.
- Formatação e normalização, quando precisa preparar valores para tela, API ou banco.
import { formatCpf, isValidCpf, validateCpf } from 'brazilian-docs-validator';
isValidCpf('529.982.247-25'); // true
formatCpf('52998224725'); // '529.982.247-25'
const result = validateCpf('529.982.247-24');
if (!result.valid) {
result.issues[0]?.code; // 'CPF_INVALID_CHECKSUM'
}Cada módulo segue o mesmo conjunto de funções: normalize*, isValid*,
validate*, parse*, assertValid*, format*, format*Partial,
isFormatted* e uma classe *ValidationError. Por padrão, caracteres não
numéricos são removidos antes da validação; use a opção { strict: true } para
aceitar apenas o formato oficial.
Entrypoints
O pacote publica ESM, CommonJS e declarações TypeScript. Importe pelo pacote principal ou pelos entrypoints específicos:
import { isValidCpf } from 'brazilian-docs-validator';
import { isValidCpf } from 'brazilian-docs-validator/cpf';
import { isValidCnpj } from 'brazilian-docs-validator/cnpj';
import { isValidTituloEleitor } from 'brazilian-docs-validator/titulo-eleitor';
import { isValidNis } from 'brazilian-docs-validator/nis';
import { isValidPis as isValidPisFromAlias } from 'brazilian-docs-validator/pis';
import { isValidCns } from 'brazilian-docs-validator/cns';
import { isValidCartaoSus } from 'brazilian-docs-validator/cartao-sus';CPF
O módulo CPF valida, interpreta, normaliza e formata CPFs brasileiros.
import { isValidCpf } from 'brazilian-docs-validator';
import { isValidCpf } from 'brazilian-docs-validator/cpf';API
normalizeCpf(value)isValidCpf(value, options?)validateCpf(value, options?)parseCpf(value, options?)assertValidCpf(value, options?)formatCpf(value, options?)formatCpfPartial(value)isFormattedCpf(value)CpfValidationError
Normalização
normalizeCpf retorna apenas os dígitos numéricos do valor recebido.
normalizeCpf('cpf: 529.982.247-25'); // '52998224725'
normalizeCpf(null); // ''Validação Booleana
isValidCpf retorna apenas true ou false. Use quando o fluxo não precisa
explicar o motivo da falha.
isValidCpf('529.982.247-25'); // true
isValidCpf('529.982.247-24'); // false
isValidCpf('cpf: 529.982.247-25'); // true (não numéricos são removidos)
isValidCpf('cpf: 529.982.247-25', { strict: true }); // falseValidação Detalhada
validateCpf retorna um resultado estruturado. Use quando a aplicação precisa
exibir mensagens, mapear erros ou tomar decisões com base no tipo de falha.
validateCpf('529.982.247-25');
// { valid: true, value: '52998224725', formatted: '529.982.247-25', issues: [] }
validateCpf('111.111.111-11');
// {
// valid: false,
// value: null,
// formatted: null,
// issues: [{ code: 'CPF_REPEATED_DIGITS', message: 'CPF cannot contain the same digit repeated 11 times.' }]
// }Códigos de Erro
CPF_EMPTY: valor vazio,nullouundefined.CPF_INVALID_FORMAT: formato inválido quandostrict: true.CPF_INVALID_LENGTH: valor não contém exatamente 11 dígitos.CPF_REPEATED_DIGITS: CPF com o mesmo dígito repetido 11 vezes.CPF_INVALID_CHECKSUM: dígitos verificadores inválidos.
Parsing
parseCpf retorna o CPF normalizado e formatado. Se o valor for inválido,
lança CpfValidationError. assertValidCpf usa a mesma validação, mas não
retorna valor.
parseCpf('52998224725');
// { value: '52998224725', formatted: '529.982.247-25' }
try {
parseCpf('529.982.247-24');
} catch (error) {
if (error instanceof CpfValidationError) {
error.issues[0]?.code; // 'CPF_INVALID_CHECKSUM'
}
}
assertValidCpf('529.982.247-25'); // não lança erroFormatação
formatCpf formata um valor com exatamente 11 dígitos. Por padrão valida apenas
o tamanho; use validate: true para validar os dígitos verificadores antes.
formatCpf('52998224725'); // '529.982.247-25'
formatCpf('12345678901', { validate: true }); // lança CpfValidationErrorformatCpfPartial formata entradas incompletas, útil para máscaras de input.
Valores com mais de 11 dígitos são cortados.
formatCpfPartial('1234'); // '123.4'
formatCpfPartial('1234567'); // '123.456.7'
formatCpfPartial('1234567890'); // '123.456.789-0'isFormattedCpf verifica apenas se o valor está no formato 000.000.000-00.
Não valida os dígitos verificadores.
isFormattedCpf('529.982.247-25'); // true
isFormattedCpf('52998224725'); // falseCNPJ
O módulo CNPJ valida, interpreta, normaliza e formata CNPJs nos dois modelos:
- Modelo numérico antigo:
00.000.000/0000-00. - Modelo alfanumérico novo:
AA.AAA.AAA/AAAA-00, com letras permitidas nas 12 primeiras posições e dígitos numéricos nas 2 últimas.
O cálculo dos dígitos verificadores usa módulo 11. Para o modelo alfanumérico, cada caractere das 12 primeiras posições é convertido pelo valor ASCII menos 48, mantendo os pesos tradicionais do CNPJ.
Referências oficiais: Receita Federal — CNPJ · Receita Federal — CNPJ alfanumérico.
import { isValidCnpj } from 'brazilian-docs-validator';
import { isValidCnpj } from 'brazilian-docs-validator/cnpj';API
normalizeCnpj(value)isValidCnpj(value, options?)validateCnpj(value, options?)parseCnpj(value, options?)assertValidCnpj(value, options?)formatCnpj(value, options?)formatCnpjPartial(value)isFormattedCnpj(value)CnpjValidationError
Normalização
normalizeCnpj remove pontuação, converte letras para maiúsculas e mantém
apenas caracteres alfanuméricos.
normalizeCnpj('04.252.011/0001-10'); // '04252011000110'
normalizeCnpj('12.abc.345/01de-35'); // '12ABC34501DE35'
normalizeCnpj(null); // ''Validação Booleana
isValidCnpj('04.252.011/0001-10'); // true
isValidCnpj('12.ABC.345/01DE-35'); // true
isValidCnpj('04.252.011/0001-11'); // false
isValidCnpj('12.abc.345/01de-35'); // true (minúsculas são normalizadas)
isValidCnpj('12.abc.345/01de-35', { strict: true }); // false
isValidCnpj('12.ABC.345/01DE-35', { strict: true }); // trueValidação Detalhada
validateCnpj retorna um resultado estruturado, incluindo o modelo detectado.
validateCnpj('12.ABC.345/01DE-35');
// { valid: true, value: '12ABC34501DE35', formatted: '12.ABC.345/01DE-35', model: 'alphanumeric', issues: [] }
validateCnpj('04.252.011/0001-10');
// { valid: true, value: '04252011000110', formatted: '04.252.011/0001-10', model: 'numeric', issues: [] }
validateCnpj('12.ABC.345/01DE-AA');
// {
// valid: false,
// value: null,
// formatted: null,
// model: null,
// issues: [{ code: 'CNPJ_INVALID_CHARACTERS', message: 'CNPJ must contain 12 alphanumeric characters followed by 2 numeric check digits.' }]
// }Códigos de Erro
CNPJ_EMPTY: valor vazio,nullouundefined.CNPJ_INVALID_FORMAT: formato inválido quandostrict: true.CNPJ_INVALID_LENGTH: valor não contém exatamente 14 caracteres.CNPJ_INVALID_CHARACTERS: as 12 primeiras posições não são alfanuméricas ou os 2 dígitos verificadores não são numéricos.CNPJ_REPEATED_DIGITS: CNPJ numérico com o mesmo dígito repetido 14 vezes.CNPJ_INVALID_CHECKSUM: dígitos verificadores inválidos.
Parsing
parseCnpj retorna o valor normalizado, o valor formatado e o modelo detectado.
Se o valor for inválido, lança CnpjValidationError. assertValidCnpj usa a
mesma validação, mas não retorna valor.
parseCnpj('12ABC34501DE35');
// { value: '12ABC34501DE35', formatted: '12.ABC.345/01DE-35', model: 'alphanumeric' }
try {
parseCnpj('04.252.011/0001-11');
} catch (error) {
if (error instanceof CnpjValidationError) {
error.issues[0]?.code; // 'CNPJ_INVALID_CHECKSUM'
}
}
assertValidCnpj('12.ABC.345/01DE-35'); // não lança erroFormatação
formatCnpj formata um valor com exatamente 14 caracteres válidos. Por padrão
valida apenas tamanho e posições; use validate: true para validar os dígitos
verificadores antes.
formatCnpj('04252011000110'); // '04.252.011/0001-10'
formatCnpj('12abc34501de35'); // '12.ABC.345/01DE-35'
formatCnpj('12ABC34501DE00', { validate: true }); // lança CnpjValidationErrorformatCnpjPartial formata entradas incompletas. Valores com mais de 14
caracteres são cortados.
formatCnpjPartial('123456'); // '12.345.6'
formatCnpjPartial('123456789'); // '12.345.678/9'
formatCnpjPartial('12abc34501de3'); // '12.ABC.345/01DE-3'isFormattedCnpj verifica apenas se o valor está no formato 00.000.000/0000-00,
com letras maiúsculas permitidas nas 12 primeiras posições. Não valida os dígitos
verificadores.
isFormattedCnpj('04.252.011/0001-10'); // true
isFormattedCnpj('12.ABC.345/01DE-35'); // true
isFormattedCnpj('12.abc.345/01de-35'); // falseTítulo de Eleitor
O módulo valida, interpreta, normaliza e formata inscrições eleitorais brasileiras. Valida apenas estrutura, código da UF eleitoral e dígitos verificadores — não consulta a base do TSE e não informa situação eleitoral.
Referências: TSE — Resolução nº 21.538/2003 · TSE — sobre o título.
import { isValidTituloEleitor } from 'brazilian-docs-validator';
import { isValidTituloEleitor } from 'brazilian-docs-validator/titulo-eleitor';Estrutura
O número tem 12 dígitos:
- 8 primeiros dígitos: sequência da inscrição.
- 2 dígitos seguintes: código da UF eleitoral, de
01a28. - 2 últimos dígitos: dígitos verificadores.
O código 28 representa eleitorado no exterior, identificado como ZZ. O
cálculo dos DVs usa módulo 11: o primeiro DV sobre os 8 primeiros dígitos (pesos
2,3,4,5,6,7,8,9) e o segundo sobre o código da UF e o primeiro DV (pesos
7,8,9); quando o resto é 10, o dígito usado é 0.
API
normalizeTituloEleitor(value)isValidTituloEleitor(value, options?)validateTituloEleitor(value, options?)parseTituloEleitor(value, options?)assertValidTituloEleitor(value, options?)formatTituloEleitor(value, options?)formatTituloEleitorPartial(value)isFormattedTituloEleitor(value)getTituloEleitorState(stateCode)TituloEleitorValidationError
Normalização
normalizeTituloEleitor('0798 1719 0302'); // '079817190302'
normalizeTituloEleitor('titulo: 0798 1719 0302'); // '079817190302'
normalizeTituloEleitor(null); // ''Validação Booleana
isValidTituloEleitor('0798 1719 0302'); // true
isValidTituloEleitor('0798 1719 0303'); // false
isValidTituloEleitor('titulo: 0798 1719 0302'); // true
isValidTituloEleitor('titulo: 0798 1719 0302', { strict: true }); // false
isValidTituloEleitor('0798 1719 0302', { strict: true }); // trueValidação Detalhada
validateTituloEleitor retorna um resultado estruturado, incluindo UF eleitoral.
validateTituloEleitor('0798 1719 0302');
// { valid: true, value: '079817190302', formatted: '0798 1719 0302', stateCode: '03', state: 'RJ', issues: [] }
validateTituloEleitor('0798 1719 0303');
// {
// valid: false,
// value: null,
// formatted: null,
// stateCode: null,
// state: null,
// issues: [{ code: 'TITULO_ELEITOR_INVALID_CHECKSUM', message: 'Titulo de eleitor check digits are invalid.' }]
// }Códigos de Erro
TITULO_ELEITOR_EMPTY: valor vazio,nullouundefined.TITULO_ELEITOR_INVALID_FORMAT: formato inválido quandostrict: true.TITULO_ELEITOR_INVALID_LENGTH: valor não contém exatamente 12 dígitos.TITULO_ELEITOR_INVALID_STATE_CODE: código da UF eleitoral fora de01a28.TITULO_ELEITOR_REPEATED_DIGITS: valor com o mesmo dígito repetido 12 vezes.TITULO_ELEITOR_INVALID_CHECKSUM: dígitos verificadores inválidos.
Parsing
parseTituloEleitor retorna o valor normalizado, o formatado e a UF eleitoral.
Se o valor for inválido, lança TituloEleitorValidationError.
assertValidTituloEleitor usa a mesma validação, mas não retorna valor.
parseTituloEleitor('079817190302');
// { value: '079817190302', formatted: '0798 1719 0302', stateCode: '03', state: 'RJ' }
try {
parseTituloEleitor('0798 1719 0303');
} catch (error) {
if (error instanceof TituloEleitorValidationError) {
error.issues[0]?.code; // 'TITULO_ELEITOR_INVALID_CHECKSUM'
}
}
assertValidTituloEleitor('0798 1719 0302'); // não lança erroFormatação
formatTituloEleitor formata um valor com exatamente 12 dígitos. Por padrão
valida apenas tamanho e código da UF; use validate: true para validar os
dígitos verificadores antes.
formatTituloEleitor('079817190302'); // '0798 1719 0302'
formatTituloEleitor('079817190303', { validate: true }); // lança TituloEleitorValidationErrorformatTituloEleitorPartial formata entradas incompletas. Valores com mais de 12
dígitos são cortados.
formatTituloEleitorPartial('12345'); // '1234 5'
formatTituloEleitorPartial('123456789'); // '1234 5678 9'isFormattedTituloEleitor verifica apenas se o valor está no formato
0000 0000 0000. Não valida os dígitos verificadores.
isFormattedTituloEleitor('0798 1719 0302'); // true
isFormattedTituloEleitor('079817190302'); // falsegetTituloEleitorState retorna a sigla da UF eleitoral para um código válido.
getTituloEleitorState('01'); // 'SP'
getTituloEleitorState('28'); // 'ZZ'
getTituloEleitorState('00'); // nullPIS / PASEP / NIT / NIS
O módulo valida, interpreta, normaliza e formata o número de identificação social usado em cadastros trabalhistas, previdenciários e sociais.
A API canônica usa o nome NIS. As funções de PIS, PASEP e NIT são
aliases da mesma implementação, porque a sequência numérica não identifica
sozinha o contexto de emissão. O módulo valida apenas estrutura e dígito
verificador; não consulta bases da Caixa, Banco do Brasil, INSS, CNIS, CadÚnico
ou eSocial.
import { isValidNis, isValidPis } from 'brazilian-docs-validator';
import { isValidNis, isValidPis } from 'brazilian-docs-validator/nis';
import { isValidPis } from 'brazilian-docs-validator/pis';
import { isValidPasep } from 'brazilian-docs-validator/pasep';
import { isValidNit } from 'brazilian-docs-validator/nit';Estrutura
O número tem 11 dígitos: 10 primeiros de base e o último de verificação. O
formato usado pela lib é 000.00000.00-0. O DV usa módulo 11: multiplique os 10
primeiros dígitos pelos pesos 3,2,9,8,7,6,5,4,3,2, some os produtos, calcule
11 - (soma % 11) e, quando o resultado for 10 ou 11, use 0.
API Canônica
normalizeNis(value)isValidNis(value, options?)validateNis(value, options?)parseNis(value, options?)assertValidNis(value, options?)formatNis(value, options?)formatNisPartial(value)isFormattedNis(value)NisValidationError
Aliases
Para cada nome existem as mesmas funções da API canônica, trocando o sufixo:
- PIS:
normalizePis,isValidPis,validatePis,parsePis,assertValidPis,formatPis,formatPisPartial,isFormattedPis,PisValidationError. - PASEP:
normalizePasep,isValidPasep,validatePasep,parsePasep,assertValidPasep,formatPasep,formatPasepPartial,isFormattedPasep,PasepValidationError. - NIT:
normalizeNit,isValidNit,validateNit,parseNit,assertValidNit,formatNit,formatNitPartial,isFormattedNit,NitValidationError.
Normalização
normalizeNis('120.64476.89-1'); // '12064476891'
normalizeNis('nis: 120.64476.89-1'); // '12064476891'
normalizeNis(null); // ''Validação Booleana
isValidNis('120.64476.89-1'); // true
isValidPis('120.64476.89-1'); // true
isValidNis('120.64476.89-2'); // false
isValidNis('nis: 120.64476.89-1'); // true
isValidNis('nis: 120.64476.89-1', { strict: true }); // false
isValidNis('120.64476.89-1', { strict: true }); // trueValidação Detalhada
validateNis('120.64476.89-1');
// { valid: true, value: '12064476891', formatted: '120.64476.89-1', issues: [] }
validateNis('120.64476.89-2');
// {
// valid: false,
// value: null,
// formatted: null,
// issues: [{ code: 'NIS_INVALID_CHECKSUM', message: 'NIS check digit is invalid.' }]
// }Códigos de Erro
NIS_EMPTY: valor vazio,nullouundefined.NIS_INVALID_FORMAT: formato inválido quandostrict: true.NIS_INVALID_LENGTH: valor não contém exatamente 11 dígitos.NIS_REPEATED_DIGITS: valor com o mesmo dígito repetido 11 vezes.NIS_INVALID_CHECKSUM: dígito verificador inválido.
Parsing
parseNis retorna o valor normalizado e o formatado. Se o valor for inválido,
lança NisValidationError. Os aliases retornam o mesmo resultado.
parseNis('12064476891');
// { value: '12064476891', formatted: '120.64476.89-1' }
parsePis('12064476891');
parsePasep('12064476891');
parseNit('12064476891');Formatação
formatNis formata um valor com exatamente 11 dígitos. Por padrão valida apenas
o tamanho; use validate: true para validar o dígito verificador antes.
formatNis('12064476891'); // '120.64476.89-1'
formatPis('12064476891'); // '120.64476.89-1'
formatNis('12345678901', { validate: true }); // lança NisValidationErrorformatNisPartial formata entradas incompletas. Valores com mais de 11 dígitos
são cortados.
formatNisPartial('1234'); // '123.4'
formatNisPartial('123456789'); // '123.45678.9'isFormattedNis verifica apenas se o valor está no formato 000.00000.00-0.
Não valida o dígito verificador.
isFormattedNis('120.64476.89-1'); // true
isFormattedNis('12064476891'); // falseCartão SUS / CNS
O módulo valida, interpreta, normaliza e formata números do Cartão Nacional de
Saúde. A API canônica usa o nome CNS; as funções CartaoSus são aliases da
mesma implementação. Valida apenas estrutura e dígito verificador — não consulta
CADSUS, DataSUS, RNDS, Conecte SUS ou qualquer base oficial.
Referências: DataSUS — Cartão Nacional de Saúde · ANS — algoritmos do SIB-XML (CNS).
import { isValidCns, isValidCartaoSus } from 'brazilian-docs-validator';
import { isValidCns, isValidCartaoSus } from 'brazilian-docs-validator/cns';
import { isValidCartaoSus } from 'brazilian-docs-validator/cartao-sus';Estrutura
O CNS tem 15 dígitos. Modelos aceitos:
- Definitivo: começa com
1ou2. - Provisório: começa com
7,8ou9.
O formato usado pela lib é 000 0000 0000 0000. As regras do dígito verificador
variam pelo primeiro dígito: o definitivo usa pesos 15..5 sobre os 11 primeiros
dígitos com sufixos 000/001; o provisório é válido quando a soma dos 15
dígitos pelos pesos 15..1 é divisível por 11.
API Canônica
normalizeCns(value)isValidCns(value, options?)validateCns(value, options?)parseCns(value, options?)assertValidCns(value, options?)formatCns(value, options?)formatCnsPartial(value)isFormattedCns(value)getCnsModel(value)CnsValidationError
Aliases Cartão SUS
As mesmas funções existem com o sufixo CartaoSus: normalizeCartaoSus,
isValidCartaoSus, validateCartaoSus, parseCartaoSus, assertValidCartaoSus,
formatCartaoSus, formatCartaoSusPartial, isFormattedCartaoSus,
getCartaoSusModel e CartaoSusValidationError.
Normalização
normalizeCns('120 6447 6891 0004'); // '120644768910004'
normalizeCns('cns: 120 6447 6891 0004'); // '120644768910004'
normalizeCns(null); // ''Validação Booleana
isValidCns('120 6447 6891 0004'); // true
isValidCartaoSus('700 0000 0000 0005'); // true
isValidCns('120 6447 6891 0005'); // false
isValidCns('cns: 120 6447 6891 0004'); // true
isValidCns('cns: 120 6447 6891 0004', { strict: true }); // false
isValidCns('120 6447 6891 0004', { strict: true }); // trueValidação Detalhada
validateCns retorna um resultado estruturado, incluindo o modelo detectado.
validateCns('120 6447 6891 0004');
// { valid: true, value: '120644768910004', formatted: '120 6447 6891 0004', model: 'definitive', issues: [] }
validateCns('700 0000 0000 0005');
// { valid: true, value: '700000000000005', formatted: '700 0000 0000 0005', model: 'provisional', issues: [] }
validateCns('120 6447 6891 0005');
// {
// valid: false,
// value: null,
// formatted: null,
// model: null,
// issues: [{ code: 'CNS_INVALID_CHECKSUM', message: 'CNS check digit is invalid.' }]
// }Códigos de Erro
CNS_EMPTY: valor vazio,nullouundefined.CNS_INVALID_FORMAT: formato inválido quandostrict: true.CNS_INVALID_LENGTH: valor não contém exatamente 15 dígitos.CNS_INVALID_START_DIGIT: valor não começa com1,2,7,8ou9.CNS_REPEATED_DIGITS: valor com o mesmo dígito repetido 15 vezes.CNS_INVALID_CHECKSUM: dígito verificador inválido.
Parsing
parseCns retorna o valor normalizado, o formatado e o modelo detectado. Se o
valor for inválido, lança CnsValidationError.
parseCns('120644768910004');
// { value: '120644768910004', formatted: '120 6447 6891 0004', model: 'definitive' }
try {
parseCns('120644768910005');
} catch (error) {
if (error instanceof CnsValidationError) {
error.issues[0]?.code; // 'CNS_INVALID_CHECKSUM'
}
}Formatação
formatCns formata um valor com exatamente 15 dígitos e primeiro dígito aceito.
Por padrão valida apenas tamanho e primeiro dígito; use validate: true para
validar o algoritmo antes.
formatCns('120644768910004'); // '120 6447 6891 0004'
formatCartaoSus('700000000000005'); // '700 0000 0000 0005'
formatCns('120644768910005', { validate: true }); // lança CnsValidationErrorformatCnsPartial formata entradas incompletas. Valores com mais de 15 dígitos
são cortados.
formatCnsPartial('12345678'); // '123 4567 8'
formatCnsPartial('123456789012'); // '123 4567 8901 2'isFormattedCns verifica apenas se o valor está no formato 000 0000 0000 0000.
Não valida o dígito verificador.
isFormattedCns('120 6447 6891 0004'); // true
isFormattedCns('120644768910004'); // falsegetCnsModel identifica o modelo pelo primeiro dígito.
getCnsModel('120644768910004'); // 'definitive'
getCnsModel('700000000000005'); // 'provisional'
getCnsModel('300000000000006'); // nullDesenvolvimento
npm install
npm run check
npm run pack:checknpm run check executa lint, typecheck, testes, build e validação do pacote.
