cpf

Biblioteca JavaScript e TypeScript para validar, inspecionar, formatar, normalizar, gerar e reparar CPF e CNPJ. Suporta CNPJ numérico e alfanumérico.

A biblioteca confirma estrutura e dígitos verificadores. Ela não confirma identidade, titularidade, emissão ou situação cadastral.

• CPF e CNPJ com ou sem máscara;
• CNPJ numérico e alfanumérico;
• validação booleana ou diagnóstico detalhado;
• formatação de valores completos e parciais;
• normalização e parsing sem perda de zeros à esquerda;
• cálculo de dígitos verificadores;
• geração unitária ou em lote;
• busca de candidatos para documentos incompletos;
• ESM, CommonJS, TypeScript e bundle para navegador;
• zero dependências de runtime.

npm install cpf

import cpf, { cnpj } from 'cpf'

cpf.isValid('529.982.247-25') // true
cpf.format('5299822') // '529.982.2'

cnpj.isValid('12.ABC.345/01DE-35') // true
cnpj.getKind('12.ABC.345/01DE-35') // 'alphanumeric'

O export padrão e o export nomeado cpf contêm as operações de CPF. O export nomeado cnpj contém as operações de CNPJ.

Confirma o comprimento, os caracteres, as regras de repetição e os dígitos verificadores. Entradas inválidas retornam false; a função não lança erro para tipos inesperados.

cpf.isValid('529.982.247-25') // true
cpf.isValid('529.982.247-26') // false

cnpj.isValid('11.222.333/0001-81') // true
cnpj.isValid('12.ABC.345/01DE-35') // true

As operações estritas de CNPJ esperam letras maiúsculas. Use normalize para preparar uma entrada que possa conter letras minúsculas.

Executa as mesmas verificações de isValid, mas retorna o valor normalizado e, em caso de falha, um código que identifica a primeira regra violada.

cpf.inspect('529.982.247-26')
// {
//   valid: false,
//   normalized: '52998224726',
//   issue: 'INVALID_CHECK_DIGITS'
// }

cnpj.inspect('12.ABC.345/01DE-35')
// { valid: true, normalized: '12ABC34501DE35' }

Os possíveis valores de issue são:

• INVALID_TYPE;
• INVALID_CHARACTERS;
• INVALID_LENGTH;
• INVALID_VERIFIER_CHARACTERS — somente CNPJ;
• REPEATED_CHARACTERS;
• INVALID_CHECK_DIGITS.

normalized é null quando não é possível normalizar a entrada com segurança.

Verifica somente a máscara. Não calcula nem confirma os dígitos verificadores.

cpf.matchesFormat('529.982.247-25') // true
cpf.matchesFormat('529.982', { completeness: 'partial' }) // true

cnpj.matchesFormat('12.ABC.345/01DE-35') // true

Aplica a máscara canônica e aceita strings parciais, o que permite seu uso durante a digitação em formulários.

cpf.format('5299822') // '529.982.2'
cpf.format('52998224725') // '529.982.247-25'

cnpj.format('12ABC34501DE35') // '12.ABC.345/01DE-35'

Entradas numéricas são aceitas somente com strict: false e devem ser inteiros seguros não negativos. Prefira strings para preservar zeros à esquerda.

Remove a máscara sem remover zeros à esquerda. Em CNPJ, letras são convertidas para maiúsculas.

cpf.normalize('529.982.247-25') // '52998224725'
cnpj.normalize('12.abc.345/01de-35') // '12ABC34501DE35'

Exige uma representação completa depois de remover os separadores admitidos e separa suas partes semânticas. Em CNPJ, converte letras para maiúsculas. parse não confirma a posição da máscara nem os dígitos verificadores; use matchesFormat e isValid para essas verificações.

cpf.parse('529.982.247-25')
// {
//   value: '52998224725',
//   body: '529982247',
//   checkDigits: '25',
//   regionDigit: '7'
// }

cnpj.parse('12.ABC.345/01DE-35')
// {
//   value: '12ABC34501DE35',
//   root: '12ABC345',
//   branch: '01DE',
//   checkDigits: '35'
// }

Calcula os dois dígitos verificadores. CPF recebe um array com nove dígitos; CNPJ recebe uma string ou um array com os doze caracteres do corpo.

cpf.calculateCheckDigits([5, 2, 9, 9, 8, 2, 2, 4, 7]) // [2, 5]
cnpj.calculateCheckDigits('12ABC34501DE') // [3, 5]

Retorna candidatos matematicamente válidos para uma posição desconhecida. CPF usa X como marcador; CNPJ usa ? por padrão.

cpf.findValidRepairs('5299822472X') // ['52998224725']
cnpj.findValidRepairs('12.ABC.345/01DE-3?') // ['12ABC34501DE35']

CNPJ permite configurar placeholder e restringir os candidatos com kind: 'numeric' | 'alphanumeric'. Dois marcadores são aceitos somente nas posições dos verificadores.

Gera um CPF ou CNPJ e sempre retorna uma string.

cpf.generate()
cpf.generate({ validity: 'invalid', output: 'plain' })

cnpj.generate({ kind: 'alphanumeric' })

randomSource deve retornar um número no intervalo [0, 1). A geração não é criptograficamente segura e não garante unicidade.

Gera uma lista usando as mesmas opções de generate. count deve ser um inteiro entre 1 e 10.000. Divida volumes maiores em lotes menores para evitar reter todos os resultados em memória ao mesmo tempo.

cpf.generateMany(3, { output: 'plain' })
cnpj.generateMany(3, { kind: 'alphanumeric' })

Retorna as UFs associadas ao nono dígito do corpo do CPF. A classificação não valida os dígitos verificadores.

cpf.getFiscalRegions('529.982.247-25') // ['ES', 'RJ']

Classifica uma estrutura completa como numeric ou alphanumeric. Retorna null para uma estrutura incompatível e não confirma os dígitos verificadores.

cnpj.getKind('11.222.333/0001-81') // 'numeric'
cnpj.getKind('12.ABC.345/01DE-35') // 'alphanumeric'

As operações de consulta evitam exceções para entradas inválidas. Operações que transformam dados ou recebem opções explícitas rejeitam contratos incorretos.

import cpf, { cnpj } from 'cpf'
import { cpf as namedCpf } from 'cpf'

import cpfOnly, { isValid as isValidCpf } from 'cpf/cpf'
import cnpjOnly, { isValid as isValidCnpj } from 'cpf/cnpj'

Os subpaths oferecem o namespace como export padrão e cada operação como export nomeado.

const { default: cpf, cpf: namedCpf, cnpj } = require('cpf')
const cpfOnly = require('cpf/cpf').default
const cnpjOnly = require('cpf/cnpj').default

O bundle IIFE expõe globalThis.cpf; o namespace CNPJ fica disponível em globalThis.cpf.cnpj.

O pacote inclui declarações para ESM e CommonJS. Os principais tipos públicos são:

• DocumentIssueCode;
• CpfIssueCode, CpfInspectionResult e CnpjInspectionResult;
• CpfGenerationOptions e CnpjGenerationOptions;
• CpfGenerationValidity, CnpjGenerationValidity, CpfGenerationOutput e CnpjGenerationOutput;
• CpfFormatOptions e CnpjFormatOptions;
• CpfFormatMatchOptions e CnpjFormatMatchOptions;
• CpfParseResult e CnpjParseResult;
• CnpjKind, CnpjCharacter e CnpjAsciiCharacter.

O subpath cpf/cnpj também exporta CnpjBody e RepairOptions. Nos subpaths, os tipos compartilhados são exportados sem os prefixos Cpf e Cnpj, como FormatOptions, GenerationOptions, GenerationValidity, GenerationOutput, InspectionResult e ParseResult.

A versão 3 remove os aliases e as opções legadas da série 2.x. Entre as mudanças estão validate → isValid, unformat → normalize, calc → calculateCheckDigits e generate({ count }) → generateMany(count).

Consulte o guia de migração para a tabela completa de equivalências e as mudanças de parsing, geração e CNPJ alfanumérico.

• Node.js 16 ou mais recente;
• ESM e CommonJS;
• navegadores por meio do bundle IIFE;
• zero dependências de runtime.

• Contrato da API;
• regras de domínio;
• migração da versão 2.x;
• compatibilidade e evolução;
• política de suporte;
• arquitetura e decisões arquiteturais;
• changelog;
• segurança.

npm run verify

Consulte o guia de contribuição antes de abrir um pull request.

Distribuído sob a licença MIT.