Drop-in helper para auto-preencher endereço via ViaCEP (Global e ES Module) com estados/erros, validateOnBlur, AbortController, timeout/retry/backoff, fallback, cache TTL, escopo por form, UF <select> e transformers.
npm install viacep-autofill 
Biblioteca JS “drop-in” para mascarar CEP, consultar provedores públicos e preencher automaticamente endereço (rua, bairro, cidade, UF).
cache: 'memory' | 'localStorage' | false, com cacheTTL configurável.root: '#form-endereco' → auto-map data-viacep apenas dentro do form indicado.addUfIfMissing: true).transform(data, ctx) => data para normalizar/ajustar antes de preencher (ex.: capitalizar logradouro, remover traço do CEP em hidden).00000-000 enquanto digita.data-viacep ou manual por fields.onSuccess, onNotFound, onError, onStateChange.IDLE, TYPING, FETCHING, SUCCESS, NOT_FOUND, ERROR, CANCELED, INVALID_CEP, RATE_LIMITED.---
bash
npm install viacep-autofill
`CDN (global):
html
`ES Module (CDN):
html
`---
✅ Uso rápido (Global)
html
`---
🧩 API
js
init({
root: null, // '#form-endereco' → limita auto-map
cep: '#cep', // seletor obrigatório
autoFormat: true,
fetchOnLength: 8,
debounce: 300,
validateOnBlur: false, // saída
outputsSelector: '[data-viacep]',
fields: {},
fillStrategy: 'replace',
clearOnEmpty: true,
disableDuringFetch: true,
// rede
fetchTimeout: 6000,
retries: 1,
retryBackoffBase: 300,
fallback: true,
// cache
cache: 'memory', // 'memory' | 'localStorage' | false
cacheTTL: 300000, // ms
// helpers
addUfIfMissing: false, // cria option se necessário
transform: null, // (data, ctx) => data
// callbacks
onSuccess: (data, ctx) => {},
onNotFound: (cep, ctx) => {},
onError: (err, ctx) => {},
onStateChange: (state, payload, ctx) => {}
});
`$3
, TYPING, FETCHING, SUCCESS, NOT_FOUND, ERROR, CANCELED, INVALID_CEP, RATE_LIMITED$3
, TIMEOUT, RATE_LIMITED, NETWORK, PROVIDER---
📁 Estrutura
viacep-autofill/
├── dist/
│ ├── viacep-autofill.global.js # versão global (window.ViaCepAutofill)
│ └── viacep-autofill.module.js # versão ES Module (export { init, STATES, ERR })
├── src/
│ └── core.js # código principal
├── sample/
│ └── index.html # amostra de utilização
│ └── index-advanced.html # amostra de utilização
├── package.json
├── CHANGELOG.md
└── README.md