npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

brazilian-docs-validator

v0.1.2

Published

Utilities to validate, parse and format Brazilian documents and identifiers.

Downloads

450

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-validator

Sumário

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 true ou false.
  • 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 }); // false

Validaçã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, null ou undefined.
  • CPF_INVALID_FORMAT: formato inválido quando strict: 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 erro

Formataçã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 CpfValidationError

formatCpfPartial 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'); // false

CNPJ

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 }); // true

Validaçã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, null ou undefined.
  • CNPJ_INVALID_FORMAT: formato inválido quando strict: 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 erro

Formataçã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 CnpjValidationError

formatCnpjPartial 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'); // false

Tí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 01 a 28.
  • 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 }); // true

Validaçã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, null ou undefined.
  • TITULO_ELEITOR_INVALID_FORMAT: formato inválido quando strict: 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 de 01 a 28.
  • 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 erro

Formataçã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 TituloEleitorValidationError

formatTituloEleitorPartial 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'); // false

getTituloEleitorState retorna a sigla da UF eleitoral para um código válido.

getTituloEleitorState('01'); // 'SP'
getTituloEleitorState('28'); // 'ZZ'
getTituloEleitorState('00'); // null

PIS / 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 }); // true

Validaçã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, null ou undefined.
  • NIS_INVALID_FORMAT: formato inválido quando strict: 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 NisValidationError

formatNisPartial 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'); // false

Cartã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 1 ou 2.
  • Provisório: começa com 7, 8 ou 9.

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 }); // true

Validaçã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, null ou undefined.
  • CNS_INVALID_FORMAT: formato inválido quando strict: true.
  • CNS_INVALID_LENGTH: valor não contém exatamente 15 dígitos.
  • CNS_INVALID_START_DIGIT: valor não começa com 1, 2, 7, 8 ou 9.
  • 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 CnsValidationError

formatCnsPartial 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'); // false

getCnsModel identifica o modelo pelo primeiro dígito.

getCnsModel('120644768910004'); // 'definitive'
getCnsModel('700000000000005'); // 'provisional'
getCnsModel('300000000000006'); // null

Desenvolvimento

npm install
npm run check
npm run pack:check

npm run check executa lint, typecheck, testes, build e validação do pacote.