@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

``bash
npm install @kodatec/brasil-utils
`

Uso

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

API

$3

| 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 |

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

$3

#### 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 |

`ts
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 |

`ts
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 |

`ts
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" |

$3

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

`ts
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)
`

$3

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 |

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

IMask(element, maskCpf)
`

$3

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

Licenca

MIT