brazilian-core

Camada de integração de utilitários brasileiros para o stack TypeScript moderno (Zod · class-validator · NestJS), com mensagens em pt-BR.

Brazilian utilities integration layer for the modern TypeScript stack (Zod · class-validator · NestJS), with pt-BR messages.

Por que existe? / Why?

🇧🇷 Já existem bibliotecas maduras de validação crua de documentos brasileiros (validation-br, @brazilian-utils/brazilian-utils, brazilian-values). O brazilian-core não reimplementa dígitos verificadores — ele delega a validação para a validation-br (que já cobre CPF, CNPJ alfanumérico, etc.) e entrega o que falta: adapters de framework e DX em português.

🇺🇸 Mature libraries already cover raw Brazilian document validation. brazilian-core does not reimplement check digits — it delegates validation to validation-br and adds the missing layer: framework adapters (Zod, class-validator, NestJS) and a pt-BR developer experience.

Instalação / Install

npm i brazilian-core

Os adapters dependem de peer dependencies opcionais — instale apenas o que usar:

npm i zod                                   # para  brazilian-core/zod
npm i class-validator                       # para  brazilian-core/class-validator
npm i @nestjs/common class-validator        # para  brazilian-core/nestjs

npm i brazilian-core não arrasta zod, class-validator nem @nestjs/common. O core depende apenas de validation-br. Build dual ESM + CJS, tree-shakeable.

brazilian-core — core (zero peer deps)

Validação, formatação e geradores. Sem dependências de framework.

import {
  isCPF,
  isCNPJ,
  isCPFOrCNPJ,
  isCEP,
  isPhone,
  formatCPF,
  formatCNPJ,
  formatCEP,
  formatPhone,
  formatBRL,
  parseBRL,
  fakeCPF,
  fakeCNPJ,
} from 'brazilian-core'

isCPF('529.982.247-25') // true
isCNPJ('12ABC34501DE35') // true  → CNPJ alfanumérico (obrigatório a partir de 2026)
isCPFOrCNPJ('11.222.333/0001-81') // true

formatCPF('52998224725') // '529.982.247-25'
formatCNPJ('12ABC34501DE35') // '12.ABC.345/01DE-35'
formatCEP('01001000') // '01001-000'
formatPhone('11987654321') // '(11) 98765-4321'
formatBRL(1234.56) // 'R$ 1.234,56'
parseBRL('R$ 1.234,56') // 1234.56

fakeCPF() // CPF válido aleatório, ex.: '00318756536'
fakeCNPJ({ alphanumeric: true }) // CNPJ alfanumérico válido aleatório

| Função | Descrição | | --------------------------------- | --------------------------------------------------------- | | isCPF(v) | Valida CPF (com/sem máscara). | | isCNPJ(v) | Valida CNPJ numérico ou alfanumérico. | | isCPFOrCNPJ(v) | Valida CPF (11) ou CNPJ (14) pelo tamanho. | | isCEP(v) / isPhone(v) | Valida CEP (8 dígitos) e telefone BR (fixo/celular, +55). | | formatCPF/CNPJ/CEP/Phone | Aplica a máscara correspondente. | | formatBRL(n, opts?) | Formata número como moeda BRL via Intl. | | parseBRL(s) | Converte "R$ 1.234,56" → 1234.56 (NaN se inválido). | | fakeCPF(opts?) | Gera CPF válido ({ masked }). | | fakeCNPJ(opts?) | Gera CNPJ válido ({ alphanumeric, masked }). | | onlyDigits / onlyAlphanumeric | Helpers de normalização de máscara. |

brazilian-core/zod

Helpers para compor com z.string(), com mensagens pt-BR (customizáveis).

import { z } from 'zod'
import { cpf, cnpj, cep, phone, cpfOrCnpj } from 'brazilian-core/zod'

const ClienteSchema = z.object({
  cpf: cpf(), // mensagem default: "CPF inválido"
  cnpj: cnpj('CNPJ da empresa inválido'), // mensagem customizada
  cep: cep(),
  telefone: phone(),
})

ClienteSchema.parse({
  cpf: '529.982.247-25',
  cnpj: '12.ABC.345/01DE-35',
  cep: '01001-000',
  telefone: '(11) 98765-4321',
})

Compatível com Zod 3 e 4.

brazilian-core/class-validator

Decorators prontos com mensagens default em pt-BR.

import { IsCPF, IsCNPJ, IsCEP, IsPhone, IsCPFOrCNPJ } from 'brazilian-core/class-validator'

class CriarClienteDto {
  @IsCPF()
  cpf!: string

  @IsCNPJ({ message: 'CNPJ inválido, confira o cadastro' })
  cnpj!: string

  @IsCEP()
  cep!: string

  @IsPhone()
  telefone!: string
}

Requer experimentalDecorators no seu tsconfig.json.

brazilian-core/nestjs

Pipes que limpam a máscara na entrada e validam (lançam BadRequestException quando inválido), retornando o valor normalizado.

import { Controller, Get, Param } from '@nestjs/common'
import { CpfPipe, CnpjPipe } from 'brazilian-core/nestjs'

@Controller('clientes')
export class ClientesController {
  // '529.982.247-25' chega no handler já como '52998224725'
  @Get(':cpf')
  buscar(@Param('cpf', CpfPipe) cpf: string) {
    return { cpf }
  }
}

Pipes disponíveis: CpfPipe, CnpjPipe, CpfCnpjPipe, CepPipe, PhonePipe.

CNPJ alfanumérico

A partir de 2026 o CNPJ pode conter letras nas 12 primeiras posições (Nota Técnica COCAD/SUARA/RFB nº 49/2024). O brazilian-core valida e formata os dois formatos de forma transparente:

isCNPJ('12ABC34501DE35') // true
formatCNPJ('12ABC34501DE35') // '12.ABC.345/01DE-35'

Desenvolvimento / Development

npm install
npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm test            # vitest
npm run build       # tsup (ESM + CJS + types)

Veja o CONTRIBUTING.md para o fluxo de changesets.

Licença / License

MIT © Jackson Marcondes