npm package: @kodatec/brasil-utils
Description: Utilitários para dados brasileiros: formatação, validação e máscaras de CPF, CNPJ, CEP, telefone, moeda e mais.
Author: Neemias Renan
Latest version: 1.0.0

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

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

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

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

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

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

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

### Mascaras (IMask)

Configuracoes prontas para uso com [IMask](https://imask.js.org/):

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

### Constantes

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

## Licenca

MIT