br-helpers

Biblioteca para validar, formatar, analisar e normalizar identificadores brasileiros em projetos JavaScript e TypeScript.

Desempenho

Na execução pública de benchmark de 22/03/2026 no repositório br-helpers-benchmark, o br-helpers ficou em 1º lugar nos cenários mistos de CPF e CNPJ entre as bibliotecas populares comparadas do npm.

Nas tabelas abaixo, cada célula mostra ops/s (% do throughput do br-helpers naquele cenário). Assim fica mais fácil comparar o valor absoluto e a distância relativa para a baseline.

CPF

| Biblioteca | Validos sem mascara | DV incorreto | Misto | | ----------------------- | ------------------: | ---------------: | ----------------: | | br-helpers | 14,071,031 (100%) | 9,983,228 (100%) | 12,534,156 (100%) | | br-validations | 10,723,861 (76%) | 8,589,885 (86%) | 10,423,544 (83%) | | gerador-validador-cpf | 7,447,902 (53%) | 5,786,769 (58%) | 7,163,119 (57%) | | validar-cpf | 5,974,215 (42%) | 4,875,385 (49%) | 6,696,503 (53%) | | brazilian-values | 4,173,274 (30%) | 3,697,350 (37%) | 4,865,178 (39%) | | validations-br | 4,065,900 (29%) | 3,507,960 (35%) | 4,655,205 (37%) | | validation-br | 6,180,852 (44%) | 3,212,046 (32%) | 4,209,947 (34%) | | js-brasil | 3,960,898 (28%) | 3,440,446 (34%) | 4,037,402 (32%) | | @fnando/cpf | 1,960,492 (14%) | 1,813,368 (18%) | 2,717,810 (22%) | | cpf-cnpj-validator | 1,918,325 (14%) | 1,768,985 (18%) | 2,622,318 (21%) | | cpf | 1,311,813 (9%) | 1,208,693 (12%) | 1,742,383 (14%) |

xychart-beta horizontal
    title "CPF misto (% do throughput do br-helpers)"
    x-axis ["br-helpers", "br-validations", "gerador-validador-cpf", "validar-cpf", "brazilian-values", "validations-br", "validation-br", "js-brasil", "@fnando/cpf", "cpf-cnpj-validator", "cpf"]
    y-axis "Percentual" 0 --> 100
    bar [100, 83, 57, 53, 39, 37, 34, 32, 22, 21, 14]

CNPJ

| Biblioteca | Validos sem mascara | DV incorreto | Misto | | -------------------- | ------------------: | ---------------: | ---------------: | | br-helpers | 10,847,399 (100%) | 5,521,262 (100%) | 7,041,163 (100%) | | br-validations | 6,732,193 (62%) | 4,318,535 (78%) | 5,694,458 (81%) | | js-brasil | 5,102,666 (47%) | 3,048,297 (55%) | 3,960,542 (56%) | | validations-br | 4,140,787 (38%) | 2,775,958 (50%) | 3,560,248 (51%) | | brazilian-values | 3,745,655 (35%) | 2,600,348 (47%) | 3,325,153 (47%) | | validation-br | 1,034,955 (10%) | 771,381 (14%) | 1,026,318 (15%) | | @fnando/cnpj | 498,416 (5%) | 449,309 (8%) | 660,309 (9%) | | cpf-cnpj-validator | 449,454 (4%) | 418,080 (8%) | 607,077 (9%) |

xychart-beta horizontal
    title "CNPJ misto (% do throughput do br-helpers)"
    x-axis ["br-helpers", "br-validations", "js-brasil", "validations-br", "brazilian-values", "validation-br", "@fnando/cnpj", "cpf-cnpj-validator"]
    y-axis "Percentual" 0 --> 100
    bar [100, 81, 56, 51, 47, 15, 9, 9]

O benchmark também mede cenários com documentos válidos sem máscara, com máscara, dígitos verificadores incorretos, dígitos repetidos e valores incompletos. Nem todas as bibliotecas comparadas suportam CNPJ alfanumérico, mas o br-helpers cobre CPF, CNPJ numérico e CNPJ alfanumérico no mesmo pacote.

Os números absolutos variam por máquina, versão do Node.js e dataset, então o ideal é consultar o repositório de benchmark para ver a metodologia, as tabelas completas e as bibliotecas incluídas na comparação.

Como o desempenho é alcançado

• A normalização percorre a entrada em uma única passada por charCode, sem regex no caminho quente. Entrada já normalizada (só dígitos, ou só maiúsculas e dígitos no CNPJ) é devolvida como está, sem alocação.
• isValid valida a string normalizada diretamente, sem criar instâncias de Identifier nem objetos intermediários.
• As checagens rodam da mais barata para a mais cara: tamanho, depois caracteres repetidos, depois dígitos verificadores.
• Nenhum teste de padrão por regex é necessário: como os dígitos verificadores calculados estão sempre entre 0 e 9, uma letra nas duas últimas posições nunca confere.
• parse retorna objetos com chaves literais, mantendo formas monomórficas para o motor JavaScript.
• Entrada com caracteres não ASCII cai em um caminho de compatibilidade que preserva a semântica Unicode de toUpperCase.

Como as mudanças de desempenho são verificadas

Toda mudança no caminho quente é comparada contra a branch main usando os mesmos datasets e a mesma configuração do repositório de benchmark, executando nas duas ordens de variante para descartar viés de ordem. Antes de medir, um passo de equivalência confirma que isValid, format e parse retornam resultados idênticos nas duas versões para todos os valores dos cenários.

O que o pacote oferece

• Cpf: validação, formatação progressiva e análise completa.
• Cnpj: validação, formatação e análise de CNPJ numérico e alfanumérico.
• Cep: validação estrutural e formatação.
• Phone: validação de DDD, detecção de linha fixa ou celular e parse.
• NumericIdentifier e AlphanumericIdentifier: normalização reutilizável para regras customizadas, incluindo normalizeValue estático sem criação de instância.
• Identifier e MaskSlot: primitives para construir máscaras e abstrair novos helpers.
• CLI br-helpers: comandos para terminal com saída em texto ou JSON.
• Exportações raiz e por subpath para consumo pontual.

Instalação

npm install br-helpers

Para instalar a CLI globalmente:

npm install -g br-helpers

Também funciona com yarn add br-helpers ou pnpm add br-helpers.

Compatibilidade

• Node.js: suporte oficial a >= 20.
• Módulos: build CommonJS e ESM publicadas no mesmo pacote.
• Subpaths: br-helpers/cpf, br-helpers/cnpj, br-helpers/cep, br-helpers/phone e br-helpers/identifiers.
• CI: cobertura validada em Node.js 20, 22 e 24.
• Polyfills: o pacote não injeta polyfills automaticamente.

Início rápido

import { Cep, Cnpj, Cpf, Phone } from 'br-helpers';
import { NumericIdentifier } from 'br-helpers/identifiers';

Cpf.isValid('137.686.636-63'); // true
Cnpj.format('12abc34501de35'); // '12.ABC.345/01DE-35'
Cep.format('01311200'); // '01311-200'
Phone.parse('(11) 97983-7935').kind; // 'mobile'
NumericIdentifier.from('CPF: 137.686.636-63').value; // '13768663663'

Se você preferir importar apenas um helper:

import { Cnpj } from 'br-helpers/cnpj';
import { AlphanumericIdentifier } from 'br-helpers/identifiers';

Em CommonJS:

const { Cep, Cnpj, Cpf, Phone } = require('br-helpers');
const { NumericIdentifier } = require('br-helpers/identifiers');

API resumida

| Export | API principal | Quando usar | | ----------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------- | | Cpf | parse, isValid, format | CPF com ou sem máscara. | | Cnpj | parse, isValid, format | CNPJ numérico legado e alfanumérico. | | Cep | isValid, format | CEP com validação estrutural de 8 dígitos. | | Phone | parse, isValid, format | Telefone com DDD e detecção de tipo da linha. | | NumericIdentifier | from, normalizeValue, value, digits, length, isEmpty, format | Regras estritamente numéricas. | | AlphanumericIdentifier | from, normalizeValue, value, digits, length, isEmpty, format | Regras alfanuméricas em maiúsculo. | | Identifier | value, digits, length, isEmpty, format | Classe base abstrata para extensões. | | MaskSlot | [position, symbol] | Tipo para descrever máscaras customizadas. | | CpfAnalysis, CnpjAnalysis, PhoneAnalysis, PhoneKind | Tipos exportados | Tipagem de retorno e composição em TypeScript. |

Exemplos

CPF

import { Cpf } from 'br-helpers';

Cpf.isValid('137.686.636-63'); // true
Cpf.isValid('000.000.000-00'); // false

Cpf.format('13768663663'); // '137.686.636-63'
Cpf.format('1376866366'); // '137.686.636-6'

const cpf = Cpf.parse('137.686.636-63');

cpf.raw; // '137.686.636-63'
cpf.digits; // '13768663663'
cpf.valid; // true
cpf.formatted; // '137.686.636-63'

CNPJ

import { Cnpj } from 'br-helpers';

Cnpj.isValid('26.149.878/0001-87'); // true
Cnpj.isValid('12ABC34501DE35'); // true
Cnpj.isValid('12abc34501de35'); // true
Cnpj.isValid('26.149.878/0001-88'); // false

Cnpj.format('26149878000187'); // '26.149.878/0001-87'
Cnpj.format('12abc34501de35'); // '12.ABC.345/01DE-35'
Cnpj.format('12ABC34501DE'); // '12.ABC.345/01DE'

const cnpj = Cnpj.parse('12abc34501de35');

cnpj.raw; // '12abc34501de35'
cnpj.value; // '12ABC34501DE35'
cnpj.valid; // true
cnpj.formatted; // '12.ABC.345/01DE-35'

Cnpj aceita o formato numérico legado e o novo formato alfanumérico. Letras minúsculas são normalizadas para maiúsculas, e os dois últimos caracteres continuam sendo dígitos verificadores.

CEP

import { Cep } from 'br-helpers';

Cep.isValid('01311-200'); // true
Cep.isValid('123'); // false

Cep.format('01311200'); // '01311-200'
Cep.format('0131120'); // '01311-20'

Cep.isValid valida apenas a estrutura do valor normalizado. Ele não consulta existência real do CEP.

Telefone

import { Phone } from 'br-helpers';

Phone.isValid('(11) 97983-7935'); // true
Phone.isValid('(11) 4983-7935'); // true
Phone.isValid('00979837935'); // false

Phone.format('11979837935'); // '(11) 97983-7935'
Phone.format('1149837935'); // '(11) 4983-7935'
Phone.format('11979837'); // '(11) 97983-7'

const phone = Phone.parse('(11) 97983-7935');

phone.raw; // '(11) 97983-7935'
phone.digits; // '11979837935'
phone.ddd; // '11'
phone.kind; // 'mobile'
phone.valid; // true
phone.formatted; // '(11) 97983-7935'

phone.kind pode retornar 'mobile', 'landline' ou null enquanto o número ainda não permite identificação.

NumericIdentifier

import { NumericIdentifier, type MaskSlot } from 'br-helpers/identifiers';

const cpfMask: MaskSlot[] = [
  [3, '.'],
  [6, '.'],
  [9, '-'],
];

const numeric = NumericIdentifier.from('CPF: 137.686.636-63');

numeric.value; // '13768663663'
numeric.length; // 11
numeric.isEmpty(); // false
numeric.digits; // '13768663663'
numeric.format(cpfMask); // '137.686.636-63'

// Normalização sem criar instância:
NumericIdentifier.normalizeValue('CPF: 137.686.636-63'); // '13768663663'

AlphanumericIdentifier

import { AlphanumericIdentifier, type MaskSlot } from 'br-helpers/identifiers';

const cnpjMask: MaskSlot[] = [
  [2, '.'],
  [5, '.'],
  [8, '/'],
  [12, '-'],
];

const identifier = AlphanumericIdentifier.from('12abc345/01de-35');

identifier.value; // '12ABC34501DE35'
identifier.length; // 14
identifier.isEmpty(); // false
identifier.digits; // '123450135'
identifier.format(cnpjMask); // '12.ABC.345/01DE-35'

// Normalização sem criar instância:
AlphanumericIdentifier.normalizeValue('12abc345/01de-35'); // '12ABC34501DE35'

Formatação progressiva

Os métodos format podem ser usados durante a digitação.

import { Cep, Cnpj, Cpf, Phone } from 'br-helpers';

Cpf.format('137686'); // '137.686'
Cnpj.format('12ABC34501'); // '12.ABC.345/01'
Cep.format('0131120'); // '01311-20'
Phone.format('119798'); // '(11) 9798'

CLI

O pacote publica o binário br-helpers com os comandos cpf, cnpj, cep, phone e identifier.

npx br-helpers cpf 13768663663
npx br-helpers cnpj 12abc34501de35 --output json
npx br-helpers phone "(11) 97983-7935" --field digits
npx br-helpers cep 01311200 --field formatted
npx br-helpers identifier "CPF: 137.686.636-63"

Opções da CLI

• --field ou -f: retorna apenas um campo específico.
• --output ou -o: alterna entre text e json.
• cpf, cnpj, cep e phone encerram com código 0 quando o valor é válido e 2 quando é inválido.
• identifier sempre encerra com código 0.

Exemplo de saída JSON

npx br-helpers cnpj 12abc34501de35 --output json

{
  "raw": "12abc34501de35",
  "value": "12ABC34501DE35",
  "valid": true,
  "formatted": "12.ABC.345/01DE-35"
}

Tipos de retorno

type CpfAnalysis = {
  raw: unknown;
  digits: string;
  valid: boolean;
  formatted: string;
};

type CnpjAnalysis = {
  raw: unknown;
  value: string;
  valid: boolean;
  formatted: string;
};

type PhoneAnalysis = {
  raw: unknown;
  digits: string;
  ddd: string | null;
  kind: 'mobile' | 'landline' | null;
  valid: boolean;
  formatted: string;
};

type MaskSlot = [position: number, symbol: string];

Migrando do v2 para o v3

• Digits foi substituído por NumericIdentifier e AlphanumericIdentifier.
• Digits.from(value).mask(mask) agora vira NumericIdentifier.from(value).format(mask).
• import { Digits } from 'br-helpers/digits' agora vira import { NumericIdentifier, AlphanumericIdentifier } from 'br-helpers/identifiers'.
• Cnpj.parse(...).digits agora vira Cnpj.parse(...).value.
• O Cnpj passa a aceitar e normalizar letras no corpo do documento.

Os detalhes completos da mudança estão em CHANGELOG.md.

TypeScript

O pacote publica declarações de tipo junto com a build em dist, então autocomplete e inferência funcionam sem configuração extra.

Licença

MIT