Idiomas: Português (Brasil) | English | Español | Français

Status

• repositório público e ativo;
• pacote em fase inicial 0.x;
• publicado no npm como @ascnpj/core;
• Trusted Publishing configurado via GitHub Actions;
• algoritmo validado por testes automatizados e vetores compartilhados do ecossistema.

Instalação

npm install @ascnpj/core

Exemplo rápido

import {
  assertValid,
  calculateCNPJCheckDigits,
  format,
  isValid,
  normalize
} from "@ascnpj/core";

isValid("12.ABC.345/01DE-35");
normalize("12.abc.345/01de-35");
format("12ABC34501DE35");
assertValid("12.ABC.345/01DE-35", { strict: true });
calculateCNPJCheckDigits("12ABC34501DE");

Casos de uso

• formulários web e cadastros B2B que precisam aceitar o legado e o novo padrão;
• APIs Node.js que validam e normalizam CNPJ antes de persistir;
• integrações com ERP, faturamento, compliance e onboarding;
• suites de teste e homologação que precisam gerar e validar exemplos consistentes.

O que esta biblioteca entrega

• validação de CNPJ numérico legado;
• validação de CNPJ alfanumérico previsto pela Receita Federal para julho de 2026;
• suporte a entradas com máscara e sem máscara;
• modo permissivo e modo estrito;
• zero dependências de runtime no pacote;
• consistência com vetores compartilhados do hub.

API pública

Funções principais:

• normalize(value)
• isValid(value, options?)
• format(value, options?)
• assertValid(value, options?)
• calculateCheckDigits(base12)
• validateMany(values, options?)

Aliases explícitos:

• normalizeCNPJ(value)
• isValidCNPJ(value, options?)
• formatCNPJ(value, options?)
• assertValidCNPJ(value, options?)
• calculateCNPJCheckDigits(base12)
• validateManyCNPJ(values, options?)

Validação em lote

Além da API unitária, a biblioteca expõe:

• validateMany(values, options?)
• validateManyCNPJ(values, options?)

O retorno preserva a ordem de entrada e entrega:

• items: resultado item a item com index, input, normalized, formatted, valid, strictValid e reason;
• summary: total, válidos, inválidos e contagem agregada por motivo.

import { validateMany } from "@ascnpj/core";

const result = validateMany([
  "12.ABC.345/01DE-35",
  "12.ABC.345/01DE-36",
  null
]);

result.items[0].valid;
result.items[1].reason;
result.summary.reasons;

Garantias centrais

• aceita A-Z0-9 nos 12 primeiros caracteres;
• mantém os 2 dígitos verificadores como numéricos;
• usa módulo 11 com conversão ASCII - 48;
• normaliza entrada para caixa alta;
• rejeita repetições triviais inválidas;
• trata segurança de publicação e supply chain como parte do projeto.

Documentação e referências

• API da biblioteca
• Estratégia de testes
• Checklist de release
• Política de segurança
• Hub do ecossistema AS-CNPJ

Vetores compartilhados

O as-cnpj-js não define a verdade sozinho.

O contrato do ecossistema depende também de:

• vetores compartilhados no hub;
• regras documentadas a partir das fontes oficiais;
• convergência entre implementações futuras em outras linguagens.

Manutenção

Maintainer: @0moura
Contato institucional: [email protected]