docsbr

A documentação em inglês está disponível clicando aqui.

📚 Índice

• Sobre o Projeto
• Funcionalidades
• Instalação
• Importação
• Referência da API
  • CPF
  • CNPJ
• Exemplos de Uso
• Testes
• Tecnologias
• Autor
• Licença

📝 Sobre o Projeto

Lidar com documentos brasileiros como CPF e CNPJ exige implementar manualmente algoritmos de validação (Mod-11), máscaras de formatação e lógicas de geração. A docsbr centraliza todas essas operações em uma API clara, previsível e sem dependências externas.

A biblioteca foi desenvolvida com foco em:

• Correção: algoritmos fiéis às especificações oficiais da Receita Federal.
• Simplicidade: API mínima e consistente entre todos os módulos.
• Compatibilidade: funciona em Node.js ≥ 18, projetos ESM e bundlers modernos (Vite, esbuild, Webpack, etc.).

✨ Funcionalidades

Implementadas

• [x] CPF: validação, formatação, desformatação e geração
• [x] CNPJ: validação, formatação, desformatação e geração

Roadmap

• [ ] CEP: consulta e validação
• [ ] PIX: validação de chaves Pix
• [ ] PIS/PASEP: validação
• [ ] CNH: validação
• [ ] Título de Eleitor: validação
• [ ] RENAVAM: validação

📦 Instalação

Instale o docsbr usando o gerenciador de pacotes de sua preferência.

npm install docsbr

yarn add docsbr

pnpm add docsbr

🔌 Importação

A docsbr exporta os módulos cpf e cnpj como namespaces. Você pode importar pelo ponto de entrada principal ou diretamente via subpath imports.

Ponto de entrada principal (recomendado)

import { cpf, cnpj } from 'docsbr';

Subpath imports (tree-shaking)

import { format, unformat, isValid, generate } from 'docsbr/cpf';
import { format, unformat, isValid, generate } from 'docsbr/cnpj';

📖 Referência da API

CPF

cpf.format(value: string): string

Aplica a máscara ###.###.###-## a um CPF. Aceita o valor com ou sem formatação.

import { cpf } from 'docsbr';

cpf.format('52998224725'); // '529.982.247-25'
cpf.format('529.982.247-25'); // '529.982.247-25'

cpf.unformat(value: string): string

Remove a formatação e retorna apenas os dígitos.

cpf.unformat('529.982.247-25'); // '52998224725'
cpf.unformat('52998224725'); // '52998224725'

cpf.isValid(value: string): boolean

Valida um CPF pelo algoritmo Mod-11. Aceita o valor com ou sem formatação.

cpf.isValid('529.982.247-25'); // true
cpf.isValid('52998224725'); // true
cpf.isValid('111.111.111-11'); // false (sequência repetida)
cpf.isValid('000.000.000-00'); // false

cpf.generate(formatted?: boolean): string

Gera um CPF válido aleatório. Por padrão retorna apenas os dígitos; passe true para retornar formatado.

cpf.generate(); // ex: '52998224725'
cpf.generate(true); // ex: '529.982.247-25'

CNPJ

cnpj.format(value: string): string

Aplica a máscara ##.###.###/####-## a um CNPJ. Aceita o valor com ou sem formatação.

import { cnpj } from 'docsbr';

cnpj.format('11444777000161'); // '11.444.777/0001-61'
cnpj.format('11.444.777/0001-61'); // '11.444.777/0001-61'

cnpj.unformat(value: string): string

Remove a formatação e retorna apenas os dígitos.

cnpj.unformat('11.444.777/0001-61'); // '11444777000161'
cnpj.unformat('11444777000161'); // '11444777000161'

cnpj.isValid(value: string): boolean

Valida um CNPJ pelo algoritmo Mod-11. Aceita o valor com ou sem formatação.

cnpj.isValid('11.444.777/0001-61'); // true
cnpj.isValid('11444777000161'); // true
cnpj.isValid('11.111.111/1111-11'); // false (sequência repetida)
cnpj.isValid('00.000.000/0000-00'); // false

cnpj.generate(formatted?: boolean): string

Gera um CNPJ válido aleatório. Por padrão retorna apenas os dígitos; passe true para retornar formatado.

cnpj.generate(); // ex: '11444777000161'
cnpj.generate(true); // ex: '11.444.777/0001-61'

💻 Exemplos de Uso

O código de exemplo completo pode ser visualizado em src/test.ts.

Usando importação por namespace

import { cpf, cnpj } from 'docsbr';

// CPF
console.log(cpf.format('52998224725')); // '529.982.247-25'
console.log(cpf.unformat('529.982.247-25')); // '52998224725'
console.log(cpf.isValid('529.982.247-25')); // true
console.log(cpf.isValid('111.111.111-11')); // false
console.log(cpf.generate()); // ex: '52998224725'
console.log(cpf.generate(true)); // ex: '529.982.247-25'

// CNPJ
console.log(cnpj.format('11444777000161')); // '11.444.777/0001-61'
console.log(cnpj.unformat('11.444.777/0001-61')); // '11444777000161'
console.log(cnpj.isValid('11.444.777/0001-61')); // true
console.log(cnpj.isValid('11.111.111/1111-11')); // false
console.log(cnpj.generate()); // ex: '11444777000161'
console.log(cnpj.generate(true)); // ex: '11.444.777/0001-61'

Usando importação por sub-caminho

import { format, unformat, isValid, generate } from 'docsbr/cpf';

console.log(format('52998224725')); // '529.982.247-25'
console.log(unformat('529.982.247-25')); // '52998224725'
console.log(isValid('529.982.247-25')); // true
console.log(generate(true)); // ex: '529.982.247-25'

🧪 Testes

Os testes são escritos com Vitest e cobrem todos os módulos da biblioteca.

# Rodar todos os testes
npm run test

# Rodar com relatório de cobertura
npm run coverage

# Modo watch (re-executa ao salvar)
npm run test:watch

🛠 Tecnologias

• TypeScript: linguagem principal
• Vitest: framework de testes
• ESLint + Prettier: linting e formatação de código

👨🏻‍💻 Autor

| Artur Bomtempo | | :--------------------------------------------------------------------------------------------------------------------------------------------------: |

Desenvolvido por Artur Bomtempo 👋🏻. Entre em contato:

📄 Licença

Distribuído sob a licença MIT. Consulte o arquivo LICENSE para mais detalhes.

Copyright (c) 2025 Artur Bomtempo Colen