@kodatec/brasil-utils

Utilitarios para dados brasileiros: formatacao, validacao e mascaras de CPF, CNPJ, CEP, telefone, moeda e mais.

• TypeScript com tipos inclusos
• ESM e CommonJS
• Zero dependencias em runtime
• Configuracoes de mascara compativeis com IMask

Instalacao

npm install @kodatec/brasil-utils

Uso

import {
  validarCPF,
  formataCpf,
  maskCpf,
  getUfs,
} from '@kodatec/brasil-utils'

API

Validacao

| Funcao | Descricao | |---|---| | validarCPF(cpf) | Valida CPF (aceita com ou sem mascara) | | validarCNPJ(cnpj) | Valida CNPJ (aceita com ou sem mascara) | | isValidDate(dateString) | Valida data no formato DD/MM/YYYY | | isValidDateMesAno(dateString) | Valida mes/ano no formato MM/YYYY |

validarCPF('123.456.789-09') // true | false
validarCNPJ('11.222.333/0001-81') // true | false
isValidDate('31/12/2025') // true
isValidDateMesAno('13/2025') // false

Formatacao

Documentos

| Funcao | Descricao | |---|---| | formataCpf(cpf, mascarar?) | Formata CPF. mascarar=true (padrao) oculta digitos: ***.456.789-** | | formataCnpj(cnpj, mascarar?) | Formata CNPJ. mascarar=false (padrao) exibe completo | | formataNis(nis) | Formata NIS/PIS/PASEP: 123.45678.90-1 | | formataCep(cep) | Formata CEP: 12345-678 | | formataTelefone(telefone) | Formata telefone fixo ou celular: (11) 99999-9999 |

formataCpf('12345678909')        // '***.$2.$3-**'
formataCpf('12345678909', false) // '123.456.789-09'
formataCnpj('11222333000181')    // '11.222.333/0001-81'
formataTelefone('11999998888')   // '(11) 99999-8888'

Moeda

| Funcao | Descricao | |---|---| | formataMoedaReais(valor) | Formata numero para moeda BRL: R$ 1.234,56 |

formataMoedaReais(1234.5) // 'R$ 1.234,50'

Nomes

| Funcao | Descricao | |---|---| | formataNome(nome) | Primeiro + ultimo nome: Alex Furtunato | | formataNomePessoal(nome) | Nome completo com preposicoes em minusculo: Alex Fabiano de Araujo Furtunato |

formataNome('ALEX FABIANO DE ARAÚJO FURTUNATO')
// 'Alex Furtunato'

formataNomePessoal('ALEX FABIANO DE ARAÚJO FURTUNATO')
// 'Alex Fabiano de Araújo Furtunato'

Datas

| Funcao | Descricao | |---|---| | formataDataRetirandoHora(datastr) | "2025-05-21T17:57:10" → "21/05/2025" | | formataDataFromDb(datastr) | "2025-05-21" → "21/05/2025" | | formataDataHoraFromDb(datastr) | Data e hora do banco para pt-BR | | formataDiaMesFromDb(datastr) | "21/05" | | formataDataInt(datastr) | 7022025 → "07/02/2025" | | mudaFormatoDataSep(datastr) | Alterna entre DD/MM/YYYY e YYYY-MM-DD | | converterParaDataIso(dataString) | DD/MM/YYYY → YYYY/MM/DD | | mudaFormatoMesAno(datastr) | Alterna entre MM/YYYY e YYYY-MM | | formataDataMesReferencia(data) | "2025-05" → "05/2025" | | formatarDataExtrato(data) | Inteiro para data formatada |

Arquivo

| Funcao | Descricao | |---|---| | formataTamanhoArquivo(bytes) | 1024 → "1 KB" |

Normalizacao

| Funcao | Descricao | |---|---| | removeAcentos(texto) | Remove acentos: "Sao Paulo" → "Sao Paulo" | | removeMascara(valor) | Remove tudo exceto digitos | | removerPontuacao(valor) | Remove pontuacao de documentos, preserva nomes |

removeAcentos('São Paulo') // 'Sao Paulo'
removeMascara('123.456.789-09') // '12345678909'
removerPontuacao('123.456.789-09') // '12345678909'
removerPontuacao('João da Silva') // 'João da Silva' (mantém)

Mascaras (IMask)

Configuracoes prontas para uso com IMask:

| Constante | Mascara | |---|---| | maskCpf | 000.000.000-00 | | maskCnpj | 00.000.000/0000-00 | | maskCpfCnpj | Dinamica: CPF ou CNPJ conforme digitacao | | maskCep | 00000-000 | | maskTelefone | Dinamica: fixo (00) 0000-0000 ou celular (00) 00000-0000 | | maskNis | 000.00000.00-0 | | maskMoeda | Numero com separador de milhar . e decimal , | | maskData | 00/00/0000 | | maskMesAno | 00/0000 |

import IMask from 'imask'
import { maskCpf } from '@kodatec/brasil-utils'

IMask(element, maskCpf)

Constantes

| Funcao | Descricao | |---|---| | getUfs() | Lista das 27 UFs brasileiras { sigla, nome } | | localePtBr() | Traducao pt-BR para PrimeVue/PrimeReact |

Licenca

MIT