jsegd/README.md

Utilitário de ferramentas para desenvolvimento

# jsEGD

Biblioteca JavaScript/TypeScript para desenvolvimento front-end em ambientes EGD.  
Fornece utilitários de validação, formatação, provedores de dados brasileiros e integração com processos EGD BPM.

> **Documentação completa (TypeDoc):** [https://jsegd.netlify.app](https://jsegd.netlify.app)

---


## Instalação

```bash
npm install jsegd
```

---


## Entradas do pacote

O pacote expõe três entradas independentes:

| Entrada    | Importação        | Conteúdo                                                         |
| ---------- | ----------------- | ---------------------------------------------------------------- |
| Principal  | `jsegd`           | Utilitários core: validação, formatação, cache, eventos          |
| Provedores | `jsegd/providers` | Consultas a APIs brasileiras: CEP, bancos, municípios, DOCX      |
| HTML       | `jsegd/html`      | Utilitários para manipulação de elementos HTML                   |

---


## Módulo principal — `jsegd`

### `Validate` — Validação de dados brasileiros

Valida CPF, CNPJ, CEP, e-mail, celular e chaves Pix.

```typescript
import { Validate, TypePix } from 'jsegd'

await Validate.isValidCPF('123.456.789-09') // boolean
await Validate.isValidCNPJ('11.222.333/0001-81') // boolean (numérico e alfanumérico)
await Validate.isValidCEP('01310-100') // boolean
await Validate.isValidEmail('usuario@dominio.com.br') // boolean
await Validate.isValidMobile('(11) 91234-5678') // boolean
await Validate.isValidPix(TypePix.EMAIL, 'pix@banco.com') // lança Error se inválida
```

**`TypePix`** — enum para tipo de chave Pix: `DOCUMENT`, `EMAIL`, `MOBILE`, `EVP`.

---


### `Util` — Formatação numérica e textual

```typescript
import { Util } from 'jsegd'
import { Currency } from 'jsegd' // enum compartilhado com WrittenOut

await Util.parseNumber('R$ 1.250,99') // 1250.99
Util.convertToMonetaryValue(1250.99) // "R$ 1.250,99"
Util.convertToMonetaryValue(1250.99, Currency.USD) // "$1,250.99"
await Util.removeAccents('São Paulo') // "Sao Paulo"
await Util.abbreviate('Avenida Paulista') // "AV Paulista"
```

---


### `WrittenOut` — Valores por extenso

```typescript
import { WrittenOut, DeadlineUnit, Currency } from 'jsegd'

WrittenOut.formatNumber(1234.56)
// "um mil e duzentos e trinta e quatro reais e cinquenta e seis centavos"

WrittenOut.formatCurrency(1.01, Currency.GBP)
// "uma libra e um penny"

WrittenOut.formatDeadline(2, DeadlineUnit.Hour)
// "duas horas"

WrittenOut.formatDate(new Date('2025-01-25'))
// "sábado, vinte e cinco de janeiro de dois mil e vinte e cinco"
```

**`DeadlineUnit`** — enum: `Second`, `Minute`, `Hour`, `Day`, `Week`, `Month`, `Bimonth`, `Quarter`, `Semester`, `Year`.  
**`Currency`** — enum: `BRL`, `USD`, `EUR`, `JPY`, `GBP`, `CNY`.

---


### `EventBus` — Barramento de eventos tipado

Implementa o padrão publish/subscribe com singleton e tipagem estrita.

```typescript
import { EventBus } from 'jsegd'

type MyEvents = {
    'dados:carregados': [data: string[]]
    erro: [message: string]
}

const bus = EventBus.getInstance<MyEvents>()

const unsubscribe = bus.on('dados:carregados', (data) => {
    console.log(data)
})

bus.emit('dados:carregados', ['item1', 'item2'])

unsubscribe() // cancela inscrição
```

| Método                  | Descrição                                          |
| ----------------------- | -------------------------------------------------- |
| `on(event, callback)`   | Inscreve handler; retorna função para desinscrever |
| `once(event, callback)` | Inscreve handler de disparo único                  |
| `off(event, callback)`  | Remove callback específico                         |
| `emit(event, ...args)`  | Emite evento com argumentos                        |
| `clear(event?)`         | Remove todos os callbacks de um evento ou todos    |

---


### `LocalCache` — Cache com TTL e IndexedDB

```typescript
import { LocalCache } from 'jsegd'

const cache = LocalCache.getInstance('meu-cache', 5 * 60 * 1000) // storeName + TTL em ms

await cache.set('chave', { id: 1, nome: 'Dado' })
const valor = await cache.get<{ id: number; nome: string }>('chave') // ou null se expirado
await cache.remove('chave')
await cache.purgeExpired() // retorna quantidade de entradas removidas
await cache.clear()
```

---


## Módulo de provedores — `jsegd/providers`

### `AddressController` — Consulta de endereços via ViaCEP

```typescript
import { AddressController } from 'jsegd/providers'

const address = await AddressController.findByCep('01310-100')

console.log(address.logradouro) // "Avenida Paulista"
console.log(address.localidade) // "São Paulo"
console.log(address.uf) // "SP"
```

---


### `BankController` — Consulta de bancos brasileiros

```typescript
import { BankController } from 'jsegd/providers'

const todos = await BankController.list()
const resultados = await BankController.filterByCodeOrFullName('341')
const itau = await BankController.findByFullName('Itaú')

console.log(itau[0].fullName) // "Itaú Unibanco S.A."
console.log(itau[0].code) // 341
console.log(itau[0].ispb) // "60701190"
```

---


### `MunicipalityController` — Consulta de municípios via IBGE

```typescript
import { MunicipalityController } from 'jsegd/providers'

const municipios = await MunicipalityController.findByName('São Paulo')

const sp = municipios[0]
console.log(sp.cityName) // "São Paulo"
console.log(sp.stateAbbreviation) // "SP"
console.log(sp.cityId) // código IBGE
```

---


### `DocxRenderer` — Renderização de templates DOCX

```typescript
import { DocxRenderer } from 'jsegd/providers'

// `template` é um ArrayBuffer com o arquivo .docx
const blob = DocxRenderer.render(template, {
    nome: 'João Silva',
    cpf: '123.456.789-09',
    data: '25/01/2025',
})

// Fazer download
const url = URL.createObjectURL(blob)
```

---


## Documentação de referência

A documentação completa da API, gerada automaticamente com **TypeDoc** a partir dos comentários JSDoc do projeto, está disponível em:

**[https://jsegd.netlify.app](https://jsegd.netlify.app)**

Inclui todos os módulos, classes, interfaces, tipos e enumerações com descrições detalhadas.

---


## Licença

Veja o arquivo [LICENSE](https://jsegd.netlify.app/documents/license) para mais detalhes.