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

Instalação

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.

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('[email protected]') // boolean
await Validate.isValidMobile('(11) 91234-5678') // boolean
await Validate.isValidPix(TypePix.EMAIL, '[email protected]') // lança Error se inválida

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

Util — Formatação numérica e textual

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

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.

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

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

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

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

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

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

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

Licença

Veja o arquivo LICENSE para mais detalhes.