@eusilvio/cep-lookup 2.4.0 → 2.5.1

package/LICENSE

@@ -1,24 +1,4 @@
-# Project License
-
-This project was developed with the philosophy that knowledge and tools should be accessible to all. I believe that by sharing our work freely, we can empower other creators to build incredible things.
-
-That's why I chose the MIT License for this project. In simple terms, this means you have complete freedom to use, modify, and distribute this code, even for commercial purposes, with a single condition: you must keep the original copyright and license notice included.
-
-Thank you for your interest and contributions!
-
----
-
-# Licença do Projeto
-
-Este projeto foi desenvolvido com a filosofia de que o conhecimento e as ferramentas devem ser acessíveis a todos. Acredito que, ao compartilhar nosso trabalho livremente, podemos capacitar outros criadores a construir coisas incríveis.
-
-Por isso, escolhi a Licença MIT para este projeto. Em termos simples, isso significa que você tem total liberdade para usar, modificar e distribuir este código, até mesmo para fins comerciais, com uma única condição: mantenha o aviso de licença e copyright originais.
-
-Agradecemos o seu interesse e contribuição!
-
----
-
-### MIT License
+MIT License
 
 Copyright (c) 2025 Silvio Campos
 
@@ -39,29 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----
-
-### Tradução para Português (Apenas para referência)
-
-_Aviso: Esta é uma tradução não oficial e serve apenas para facilitar o entendimento. A versão em inglês é a que possui validade legal._
-
-Copyright (c) 2025 Silvio Campos
-
-É concedida permissão, gratuitamente, a qualquer pessoa que obtenha uma cópia
-deste software e dos arquivos de documentação associados (o "Software"), para negociar
-o Software sem restrições, incluindo, sem limitação, os direitos
-de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender
-cópias do Software, e permitir que as pessoas a quem o Software é
-fornecido o façam, sujeito às seguintes condições:
-
-O aviso de copyright acima e este aviso de permissão devem ser incluídos em todas as
-cópias ou partes substanciais do Software.
-
-O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU
-IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO,
-ADEQUAÇÃO A UM FIM ESPECÍFICO E NÃO VIOLAÇÃO. EM NENHUMA CIRCUNSTÂNCIA OS
-AUTORES OU TITULARES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER REIVINDICAÇÃO, DANOS OU OUTRA
-RESPONSABILIDADE, SEJA EM UMA AÇÃO DE CONTRATO, ILÍCITO CIVIL OU DE OUTRA FORMA, DECORRENTE DE,
-FORA DE OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO
-SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 [![NPM Version](https://img.shields.io/npm/v/@eusilvio/cep-lookup.svg)](https://www.npmjs.com/package/@eusilvio/cep-lookup)
 [![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/@eusilvio/cep-lookup)](https://www.npmjs.com/package/@eusilvio/cep-lookup)
-[![Build Status](https://img.shields.io/github/workflow/status/eusilvio/cep-lookup/CI)](https://github.com/eusilvio/cep-lookup/actions)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/eusilvio/cep-lookup/ci.yml)](https://github.com/eusilvio/cep-lookup/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 A modern, flexible, and agnostic CEP (Brazilian postal code) lookup library written in TypeScript.
@@ -119,7 +119,7 @@ const cepLookup = new CepLookup({
 });
 
 // 2. Look up multiple CEPs
-cepLookup.lookupCeps(cepsToLookup, { concurrency: 2 }).then((results: BulkCepResult[]) => {
+cepLookup.lookupCeps(cepsToLookup, 2).then((results: BulkCepResult[]) => {
   console.log("Bulk lookup results:", results);
   // Output:
   // [
@@ -166,13 +166,12 @@ Returns a `Promise` that resolves to the address in the default format (`Address
 - `cep` (string, **required**): The CEP to be queried.
 - `mapper` ((address: Address) => T, _optional_): A function that receives the default `Address` object and transforms it into a new format `T`.
 
-### `cepLookup.lookupCeps(ceps, options?): Promise<BulkCepResult[]>`
+### `cepLookup.lookupCeps(ceps, concurrency?): Promise<BulkCepResult[]>`
 
 Looks up multiple CEPs in bulk. Returns a `Promise` that resolves to an array of `BulkCepResult` objects, one for each queried CEP.
 
 - `ceps` (string[], **required**): An array of CEP strings to be queried.
-- `options` (object, _optional_): An options object.
-  - `concurrency` (number): The number of parallel requests to make. Defaults to `5`.
+- `concurrency` (number, _optional_): The number of parallel requests to make. Defaults to `5`.
 
 > **Note on Deprecated Functions:**
 > Standalone `lookupCep` and `lookupCeps` functions are deprecated and will be removed in a future version. Please use the methods on a `CepLookup` instance instead.
@@ -249,6 +248,13 @@ const myCustomProvider: Provider = {
 npm test
 ```
 
+## Compatibility and support
+
+- Node.js: `20.x`, `22.x`, `24.x`
+- React package: `react >= 16.8`
+- Vue package: `vue ^3`
+- Maintenance policy: [SUPPORT.md](../../SUPPORT.md)
+
 ## License
 
-Distributed under the MIT License.
+Distributed under the MIT License.

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";var g=Object.defineProperty;var N=Object.getOwnPropertyDescriptor;var x=Object.getOwnPropertyNames;var R=Object.prototype.hasOwnProperty;var D=(i,e)=>{for(var t in e)g(i,t,{get:e[t],enumerable:!0})},O=(i,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let s of x(e))!R.call(i,s)&&s!==t&&g(i,s,{get:()=>e[s],enumerable:!(r=N(e,s))||r.enumerable});return i};var q=i=>O(g({},"__esModule",{value:!0}),i);var z={};D(z,{CepLookup:()=>f,InMemoryCache:()=>w,lookupCep:()=>M,lookupCeps:()=>$});module.exports=q(z);var w=class{constructor(){this.cache=new Map}get(e){return this.cache.get(e)}set(e,t){this.cache.set(e,t)}clear(){this.cache.clear()}};var k=class{constructor(){this.listeners={}}on(e,t){this.listeners[e]||(this.listeners[e]=[]),this.listeners[e].push(t)}off(e,t){let r=this.listeners[e];r&&(this.listeners[e]=r.filter(s=>s!==t))}emit(e,t){let r=this.listeners[e];r&&r.forEach(s=>s(t))}};function B(i){if(!/^(\d{8}|\d{5}-\d{3})$/.test(i))throw new Error("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN.");return i.replace("-","")}function I(i){let e={...i};return Object.keys(e).forEach(t=>{let r=e[t];typeof r=="string"&&(e[t]=r.trim())}),e}var f=class{constructor(e){this.requestTimestamps=[];this.providers=e.providers,this.sortedProviders=[...e.providers],this.emitter=new k,this.fetcher=e.fetcher||(async(t,r)=>{let s=await fetch(t,{signal:r});if(!s.ok)throw new Error(`HTTP error! status: ${s.status}`);return s.json()}),this.cache=e.cache,this.rateLimit=e.rateLimit,this.staggerDelay=e.staggerDelay??100}on(e,t){this.emitter.on(e,t)}off(e,t){this.emitter.off(e,t)}async warmup(){let e="01001000",t=new AbortController,r=this.providers.map(async o=>{let a=Date.now();try{let u=o.buildUrl(e);return await this.fetcher(u,t.signal),{provider:o,duration:Date.now()-a,error:!1}}catch{return{provider:o,duration:1/0,error:!0}}}),c=(await Promise.all(r)).sort((o,a)=>o.duration-a.duration);this.sortedProviders=c.map(o=>o.provider).filter(o=>!!o),t.abort()}checkRateLimit(){if(!this.rateLimit)return;let e=Date.now(),t=e-this.rateLimit.per;if(this.requestTimestamps=this.requestTimestamps.filter(r=>r>t),this.requestTimestamps.length>=this.rateLimit.requests)throw new Error(`Rate limit exceeded: ${this.rateLimit.requests} requests per ${this.rateLimit.per}ms.`);this.requestTimestamps.push(e)}async lookup(e,t){this.checkRateLimit();let r=B(e);if(this.cache){let n=this.cache.get(r);if(n)return this.emitter.emit("cache:hit",{cep:r}),t?t(n):n}let s=new AbortController,{signal:c}=s,o=n=>{let h=Date.now(),T=n.buildUrl(r),b=new Promise((l,m)=>{if(!n.timeout)return;let p=setTimeout(()=>{c.removeEventListener("abort",L);let A=Date.now()-h,P=new Error(`Timeout from ${n.name}`);this.emitter.emit("failure",{provider:n.name,cep:r,duration:A,error:P}),m(P)},n.timeout),L=()=>clearTimeout(p);c.addEventListener("abort",L,{once:!0})}),C=this.fetcher(T,c).then(l=>n.transform(l)).then(l=>{let m=Date.now()-h,p=I(l);return this.emitter.emit("success",{provider:n.name,cep:r,duration:m,address:p}),this.cache&&this.cache.set(r,p),t?t(p):p}).catch(l=>{let m=Date.now()-h;throw!l.message.includes("Timeout from")&&l.name!=="AbortError"&&this.emitter.emit("failure",{provider:n.name,cep:r,duration:m,error:l}),l});return Promise.race([C,b])},a=this.sortedProviders[0],u=this.sortedProviders.slice(1);if(u.length===0)try{return await o(a)}finally{s.abort()}let d=null,v=null,y=new Promise((n,h)=>{v=()=>{if(d&&clearTimeout(d),c.aborted)return;let T=u.map(o);Promise.any(T).then(n).catch(h)},d=setTimeout(v,this.staggerDelay)}),E=o(a).catch(n=>{throw v&&v(),n});try{return await Promise.any([E,y])}finally{d&&clearTimeout(d),s.abort()}}async lookupCeps(e,t=5){if(!e||e.length===0)return[];let r=new Array(e.length),s=0,c=async()=>{for(;s<e.length;){let a=s++;if(a>=e.length)break;let u=e[a];try{let d=await this.lookup(u);if(d)r[a]={cep:u,data:d,provider:d.service};else throw new Error("No address found")}catch(d){r[a]={cep:u,data:null,error:d}}}},o=Array.from({length:Math.min(t,e.length)},()=>c());return await Promise.all(o),r.filter(Boolean)}};function M(i){console.warn("[cep-lookup] The standalone `lookupCep` function is deprecated and will be removed in a future version. Please use `new CepLookup(options).lookup(cep)` instead.");let{cep:e,providers:t,fetcher:r,mapper:s,cache:c,rateLimit:o}=i;return new f({providers:t,fetcher:r,cache:c,rateLimit:o}).lookup(e,s)}async function $(i){console.warn("[cep-lookup] The standalone `lookupCeps` function is deprecated and will be removed in a future version. Please use `new CepLookup(options).lookupCeps(ceps)` instead.");let{ceps:e,providers:t,fetcher:r,cache:s,concurrency:c=5,rateLimit:o}=i;return new f({providers:t,fetcher:r,cache:s,rateLimit:o}).lookupCeps(e,c)}
+"use strict";var A=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var S=Object.getOwnPropertyNames;var I=Object.prototype.hasOwnProperty;var z=(s,e)=>{for(var t in e)A(s,t,{get:e[t],enumerable:!0})},B=(s,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of S(e))!I.call(s,i)&&i!==t&&A(s,i,{get:()=>e[i],enumerable:!(r=O(e,i))||r.enumerable});return s};var q=s=>B(A({},"__esModule",{value:!0}),s);var U={};z(U,{AllProvidersFailedError:()=>w,CepLookup:()=>L,CepNotFoundError:()=>T,CepValidationError:()=>v,InMemoryCache:()=>E,ProviderTimeoutError:()=>y,RateLimitError:()=>g});module.exports=q(U);var E=class{constructor(e){this.cache=new Map;this.ttl=e?.ttl??1/0,this.maxSize=e?.maxSize??1/0}get(e){let t=this.cache.get(e);if(t){if(this.ttl!==1/0&&Date.now()-t.timestamp>this.ttl){this.cache.delete(e);return}return t.value}}set(e,t){if(this.cache.has(e)&&this.cache.delete(e),this.cache.size>=this.maxSize){let r=this.cache.keys().next().value;r!==void 0&&this.cache.delete(r)}this.cache.set(e,{value:t,timestamp:Date.now()})}delete(e){this.cache.delete(e)}has(e){if(!this.cache.has(e))return!1;let t=this.cache.get(e);return this.ttl!==1/0&&Date.now()-t.timestamp>this.ttl?(this.cache.delete(e),!1):!0}clear(){this.cache.clear()}};var v=class extends Error{constructor(e){super("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN."),this.name="CepValidationError",this.cep=e}},g=class extends Error{constructor(e,t){super(`Rate limit exceeded: ${e} requests per ${t}ms.`),this.name="RateLimitError",this.limit=e,this.window=t}},y=class extends Error{constructor(e,t){super(`Timeout from ${e}`),this.name="ProviderTimeoutError",this.provider=e,this.timeout=t}},T=class extends Error{constructor(e,t){super("CEP not found"),this.name="CepNotFoundError",this.cep=e,this.provider=t}},w=class extends Error{constructor(e){super("All providers failed to resolve the CEP."),this.name="AllProvidersFailedError",this.errors=e}};var N={AC:"68",AL:"82",AM:"92",AP:"96",BA:"71",CE:"85",DF:"61",ES:"27",GO:"62",MA:"98",MG:"31",MS:"67",MT:"65",PA:"91",PB:"83",PE:"81",PI:"86",PR:"41",RJ:"21",RN:"84",RO:"69",RR:"95",RS:"51",SC:"48",SE:"79",SP:"11",TO:"63"};var x=class{constructor(){this.listeners={}}on(e,t){this.listeners[e]||(this.listeners[e]=[]),this.listeners[e].push(t)}off(e,t){let r=this.listeners[e];r&&(this.listeners[e]=r.filter(i=>i!==t))}emit(e,t){let r=this.listeners[e];r&&r.forEach(i=>i(t))}};function F(s){if(!/^(\d{8}|\d{5}-\d{3})$/.test(s))throw new v(s);return s.replace("-","")}function $(s){let e={...s};return Object.keys(e).forEach(t=>{let r=e[t];typeof r=="string"&&(e[t]=r.trim())}),e}function K(s){if(!s.ddd&&s.state){let e=N[s.state];if(e)return{...s,ddd:e}}return s}var L=class{constructor(e){this.requestTimestamps=[];this.providers=e.providers,this.sortedProviders=[...e.providers],this.emitter=new x,this.fetcher=e.fetcher||(async(t,r)=>{let i=await fetch(t,{signal:r});if(!i.ok)throw new Error(`HTTP error! status: ${i.status}`);return i.json()}),this.cache=e.cache,this.rateLimit=e.rateLimit,this.staggerDelay=e.staggerDelay??100,this.retries=e.retries??0,this.retryDelay=e.retryDelay??1e3,this.logger=e.logger}log(e,t){this.logger?.debug(e,t)}on(e,t){this.emitter.on(e,t)}off(e,t){this.emitter.off(e,t)}async warmup(){let e="01001000",t=new AbortController,r=this.providers.map(async n=>{let a=Date.now();try{let c=n.buildUrl(e);return await this.fetcher(c,t.signal),{provider:n,duration:Date.now()-a,error:!1}}catch{return{provider:n,duration:1/0,error:!0}}}),d=(await Promise.all(r)).sort((n,a)=>n.duration-a.duration);return this.sortedProviders=d.map(n=>n.provider).filter(n=>!!n),t.abort(),this.sortedProviders}checkRateLimit(){if(!this.rateLimit)return;let e=Date.now(),t=e-this.rateLimit.per;if(this.requestTimestamps=this.requestTimestamps.filter(r=>r>t),this.requestTimestamps.length>=this.rateLimit.requests)throw new g(this.rateLimit.requests,this.rateLimit.per);this.requestTimestamps.push(e)}async lookup(e,t){this.checkRateLimit();let r=F(e);if(this.log("lookup:start",{cep:r}),this.cache){let n=this.cache.get(r);if(n)return this.log("cache:hit",{cep:r}),this.emitter.emit("cache:hit",{cep:r}),t?t(n):n}let i,d=1+this.retries;for(let n=0;n<d;n++){if(n>0){let a=this.retryDelay*Math.pow(2,n-1);this.log("retry:attempt",{attempt:n,cep:r,delay:a}),await new Promise(c=>setTimeout(c,a))}try{return await this._lookupFromProviders(r,t)}catch(a){if(a instanceof v||a instanceof g)throw a;i=a}}throw i}async _lookupFromProviders(e,t){let r=new AbortController,{signal:i}=r,d=o=>{let m=Date.now(),b=o.buildUrl(e);this.log("provider:start",{provider:o.name,cep:e});let C=new Promise((l,p)=>{if(!o.timeout)return;let f=setTimeout(()=>{i.removeEventListener("abort",R);let M=Date.now()-m,P=new y(o.name,o.timeout);this.log("provider:failure",{provider:o.name,cep:e,error:P.message}),this.emitter.emit("failure",{provider:o.name,cep:e,duration:M,error:P}),p(P)},o.timeout),R=()=>clearTimeout(f);i.addEventListener("abort",R,{once:!0})}),D=this.fetcher(b,i).then(l=>o.transform(l)).then(l=>{let p=Date.now()-m,f=K($(l));return this.log("provider:success",{provider:o.name,cep:e,duration:p}),this.emitter.emit("success",{provider:o.name,cep:e,duration:p,address:f}),this.cache&&this.cache.set(e,f),t?t(f):f}).catch(l=>{let p=Date.now()-m;throw!l.message.includes("Timeout from")&&l.name!=="AbortError"&&(this.log("provider:failure",{provider:o.name,cep:e,error:l.message}),this.emitter.emit("failure",{provider:o.name,cep:e,duration:p,error:l})),l});return Promise.race([D,C])},n=this.sortedProviders[0],a=this.sortedProviders.slice(1);if(a.length===0)try{return await d(n)}finally{r.abort()}let c=null,h=null,u=new Promise((o,m)=>{h=()=>{if(c&&clearTimeout(c),i.aborted)return;let b=a.map(d);Promise.any(b).then(o).catch(m)},c=setTimeout(h,this.staggerDelay)}),k=d(n).catch(o=>{throw h&&h(),o});try{return await Promise.any([k,u])}catch(o){let m=o.errors||[o];throw new w(m)}finally{c&&clearTimeout(c),r.abort()}}async lookupCeps(e,t=5,r){if(!e||e.length===0)return[];let i=new Array(e.length),d=0,n=async()=>{for(;d<e.length;){let c=d++;if(c>=e.length)break;let h=e[c];try{let u=await this.lookup(h);if(u)i[c]={cep:h,data:r?r(u):u,provider:u.service};else throw new Error("No address found")}catch(u){i[c]={cep:h,data:null,error:u}}}},a=Array.from({length:Math.min(t,e.length)},()=>n());return await Promise.all(a),i.filter(Boolean)}};

package/dist/index.mjs

@@ -1 +1 @@
-var T=class{constructor(){this.cache=new Map}get(e){return this.cache.get(e)}set(e,t){this.cache.set(e,t)}clear(){this.cache.clear()}};var g=class{constructor(){this.listeners={}}on(e,t){this.listeners[e]||(this.listeners[e]=[]),this.listeners[e].push(t)}off(e,t){let r=this.listeners[e];r&&(this.listeners[e]=r.filter(s=>s!==t))}emit(e,t){let r=this.listeners[e];r&&r.forEach(s=>s(t))}};function A(c){if(!/^(\d{8}|\d{5}-\d{3})$/.test(c))throw new Error("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN.");return c.replace("-","")}function N(c){let e={...c};return Object.keys(e).forEach(t=>{let r=e[t];typeof r=="string"&&(e[t]=r.trim())}),e}var v=class{constructor(e){this.requestTimestamps=[];this.providers=e.providers,this.sortedProviders=[...e.providers],this.emitter=new g,this.fetcher=e.fetcher||(async(t,r)=>{let s=await fetch(t,{signal:r});if(!s.ok)throw new Error(`HTTP error! status: ${s.status}`);return s.json()}),this.cache=e.cache,this.rateLimit=e.rateLimit,this.staggerDelay=e.staggerDelay??100}on(e,t){this.emitter.on(e,t)}off(e,t){this.emitter.off(e,t)}async warmup(){let e="01001000",t=new AbortController,r=this.providers.map(async i=>{let n=Date.now();try{let u=i.buildUrl(e);return await this.fetcher(u,t.signal),{provider:i,duration:Date.now()-n,error:!1}}catch{return{provider:i,duration:1/0,error:!0}}}),a=(await Promise.all(r)).sort((i,n)=>i.duration-n.duration);this.sortedProviders=a.map(i=>i.provider).filter(i=>!!i),t.abort()}checkRateLimit(){if(!this.rateLimit)return;let e=Date.now(),t=e-this.rateLimit.per;if(this.requestTimestamps=this.requestTimestamps.filter(r=>r>t),this.requestTimestamps.length>=this.rateLimit.requests)throw new Error(`Rate limit exceeded: ${this.rateLimit.requests} requests per ${this.rateLimit.per}ms.`);this.requestTimestamps.push(e)}async lookup(e,t){this.checkRateLimit();let r=A(e);if(this.cache){let o=this.cache.get(r);if(o)return this.emitter.emit("cache:hit",{cep:r}),t?t(o):o}let s=new AbortController,{signal:a}=s,i=o=>{let h=Date.now(),w=o.buildUrl(r),E=new Promise((l,m)=>{if(!o.timeout)return;let p=setTimeout(()=>{a.removeEventListener("abort",k);let C=Date.now()-h,L=new Error(`Timeout from ${o.name}`);this.emitter.emit("failure",{provider:o.name,cep:r,duration:C,error:L}),m(L)},o.timeout),k=()=>clearTimeout(p);a.addEventListener("abort",k,{once:!0})}),b=this.fetcher(w,a).then(l=>o.transform(l)).then(l=>{let m=Date.now()-h,p=N(l);return this.emitter.emit("success",{provider:o.name,cep:r,duration:m,address:p}),this.cache&&this.cache.set(r,p),t?t(p):p}).catch(l=>{let m=Date.now()-h;throw!l.message.includes("Timeout from")&&l.name!=="AbortError"&&this.emitter.emit("failure",{provider:o.name,cep:r,duration:m,error:l}),l});return Promise.race([b,E])},n=this.sortedProviders[0],u=this.sortedProviders.slice(1);if(u.length===0)try{return await i(n)}finally{s.abort()}let d=null,f=null,P=new Promise((o,h)=>{f=()=>{if(d&&clearTimeout(d),a.aborted)return;let w=u.map(i);Promise.any(w).then(o).catch(h)},d=setTimeout(f,this.staggerDelay)}),y=i(n).catch(o=>{throw f&&f(),o});try{return await Promise.any([y,P])}finally{d&&clearTimeout(d),s.abort()}}async lookupCeps(e,t=5){if(!e||e.length===0)return[];let r=new Array(e.length),s=0,a=async()=>{for(;s<e.length;){let n=s++;if(n>=e.length)break;let u=e[n];try{let d=await this.lookup(u);if(d)r[n]={cep:u,data:d,provider:d.service};else throw new Error("No address found")}catch(d){r[n]={cep:u,data:null,error:d}}}},i=Array.from({length:Math.min(t,e.length)},()=>a());return await Promise.all(i),r.filter(Boolean)}};function O(c){console.warn("[cep-lookup] The standalone `lookupCep` function is deprecated and will be removed in a future version. Please use `new CepLookup(options).lookup(cep)` instead.");let{cep:e,providers:t,fetcher:r,mapper:s,cache:a,rateLimit:i}=c;return new v({providers:t,fetcher:r,cache:a,rateLimit:i}).lookup(e,s)}async function q(c){console.warn("[cep-lookup] The standalone `lookupCeps` function is deprecated and will be removed in a future version. Please use `new CepLookup(options).lookupCeps(ceps)` instead.");let{ceps:e,providers:t,fetcher:r,cache:s,concurrency:a=5,rateLimit:i}=c;return new v({providers:t,fetcher:r,cache:s,rateLimit:i}).lookupCeps(e,a)}export{v as CepLookup,T as InMemoryCache,O as lookupCep,q as lookupCeps};
+var b=class{constructor(e){this.cache=new Map;this.ttl=e?.ttl??1/0,this.maxSize=e?.maxSize??1/0}get(e){let t=this.cache.get(e);if(t){if(this.ttl!==1/0&&Date.now()-t.timestamp>this.ttl){this.cache.delete(e);return}return t.value}}set(e,t){if(this.cache.has(e)&&this.cache.delete(e),this.cache.size>=this.maxSize){let r=this.cache.keys().next().value;r!==void 0&&this.cache.delete(r)}this.cache.set(e,{value:t,timestamp:Date.now()})}delete(e){this.cache.delete(e)}has(e){if(!this.cache.has(e))return!1;let t=this.cache.get(e);return this.ttl!==1/0&&Date.now()-t.timestamp>this.ttl?(this.cache.delete(e),!1):!0}clear(){this.cache.clear()}};var v=class extends Error{constructor(e){super("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN."),this.name="CepValidationError",this.cep=e}},g=class extends Error{constructor(e,t){super(`Rate limit exceeded: ${e} requests per ${t}ms.`),this.name="RateLimitError",this.limit=e,this.window=t}},y=class extends Error{constructor(e,t){super(`Timeout from ${e}`),this.name="ProviderTimeoutError",this.provider=e,this.timeout=t}},P=class extends Error{constructor(e,t){super("CEP not found"),this.name="CepNotFoundError",this.cep=e,this.provider=t}},w=class extends Error{constructor(e){super("All providers failed to resolve the CEP."),this.name="AllProvidersFailedError",this.errors=e}};var L={AC:"68",AL:"82",AM:"92",AP:"96",BA:"71",CE:"85",DF:"61",ES:"27",GO:"62",MA:"98",MG:"31",MS:"67",MT:"65",PA:"91",PB:"83",PE:"81",PI:"86",PR:"41",RJ:"21",RN:"84",RO:"69",RR:"95",RS:"51",SC:"48",SE:"79",SP:"11",TO:"63"};var A=class{constructor(){this.listeners={}}on(e,t){this.listeners[e]||(this.listeners[e]=[]),this.listeners[e].push(t)}off(e,t){let r=this.listeners[e];r&&(this.listeners[e]=r.filter(i=>i!==t))}emit(e,t){let r=this.listeners[e];r&&r.forEach(i=>i(t))}};function M(o){if(!/^(\d{8}|\d{5}-\d{3})$/.test(o))throw new v(o);return o.replace("-","")}function O(o){let e={...o};return Object.keys(e).forEach(t=>{let r=e[t];typeof r=="string"&&(e[t]=r.trim())}),e}function S(o){if(!o.ddd&&o.state){let e=L[o.state];if(e)return{...o,ddd:e}}return o}var R=class{constructor(e){this.requestTimestamps=[];this.providers=e.providers,this.sortedProviders=[...e.providers],this.emitter=new A,this.fetcher=e.fetcher||(async(t,r)=>{let i=await fetch(t,{signal:r});if(!i.ok)throw new Error(`HTTP error! status: ${i.status}`);return i.json()}),this.cache=e.cache,this.rateLimit=e.rateLimit,this.staggerDelay=e.staggerDelay??100,this.retries=e.retries??0,this.retryDelay=e.retryDelay??1e3,this.logger=e.logger}log(e,t){this.logger?.debug(e,t)}on(e,t){this.emitter.on(e,t)}off(e,t){this.emitter.off(e,t)}async warmup(){let e="01001000",t=new AbortController,r=this.providers.map(async s=>{let a=Date.now();try{let c=s.buildUrl(e);return await this.fetcher(c,t.signal),{provider:s,duration:Date.now()-a,error:!1}}catch{return{provider:s,duration:1/0,error:!0}}}),d=(await Promise.all(r)).sort((s,a)=>s.duration-a.duration);return this.sortedProviders=d.map(s=>s.provider).filter(s=>!!s),t.abort(),this.sortedProviders}checkRateLimit(){if(!this.rateLimit)return;let e=Date.now(),t=e-this.rateLimit.per;if(this.requestTimestamps=this.requestTimestamps.filter(r=>r>t),this.requestTimestamps.length>=this.rateLimit.requests)throw new g(this.rateLimit.requests,this.rateLimit.per);this.requestTimestamps.push(e)}async lookup(e,t){this.checkRateLimit();let r=M(e);if(this.log("lookup:start",{cep:r}),this.cache){let s=this.cache.get(r);if(s)return this.log("cache:hit",{cep:r}),this.emitter.emit("cache:hit",{cep:r}),t?t(s):s}let i,d=1+this.retries;for(let s=0;s<d;s++){if(s>0){let a=this.retryDelay*Math.pow(2,s-1);this.log("retry:attempt",{attempt:s,cep:r,delay:a}),await new Promise(c=>setTimeout(c,a))}try{return await this._lookupFromProviders(r,t)}catch(a){if(a instanceof v||a instanceof g)throw a;i=a}}throw i}async _lookupFromProviders(e,t){let r=new AbortController,{signal:i}=r,d=n=>{let m=Date.now(),E=n.buildUrl(e);this.log("provider:start",{provider:n.name,cep:e});let k=new Promise((l,p)=>{if(!n.timeout)return;let f=setTimeout(()=>{i.removeEventListener("abort",x);let D=Date.now()-m,T=new y(n.name,n.timeout);this.log("provider:failure",{provider:n.name,cep:e,error:T.message}),this.emitter.emit("failure",{provider:n.name,cep:e,duration:D,error:T}),p(T)},n.timeout),x=()=>clearTimeout(f);i.addEventListener("abort",x,{once:!0})}),C=this.fetcher(E,i).then(l=>n.transform(l)).then(l=>{let p=Date.now()-m,f=S(O(l));return this.log("provider:success",{provider:n.name,cep:e,duration:p}),this.emitter.emit("success",{provider:n.name,cep:e,duration:p,address:f}),this.cache&&this.cache.set(e,f),t?t(f):f}).catch(l=>{let p=Date.now()-m;throw!l.message.includes("Timeout from")&&l.name!=="AbortError"&&(this.log("provider:failure",{provider:n.name,cep:e,error:l.message}),this.emitter.emit("failure",{provider:n.name,cep:e,duration:p,error:l})),l});return Promise.race([C,k])},s=this.sortedProviders[0],a=this.sortedProviders.slice(1);if(a.length===0)try{return await d(s)}finally{r.abort()}let c=null,h=null,u=new Promise((n,m)=>{h=()=>{if(c&&clearTimeout(c),i.aborted)return;let E=a.map(d);Promise.any(E).then(n).catch(m)},c=setTimeout(h,this.staggerDelay)}),N=d(s).catch(n=>{throw h&&h(),n});try{return await Promise.any([N,u])}catch(n){let m=n.errors||[n];throw new w(m)}finally{c&&clearTimeout(c),r.abort()}}async lookupCeps(e,t=5,r){if(!e||e.length===0)return[];let i=new Array(e.length),d=0,s=async()=>{for(;d<e.length;){let c=d++;if(c>=e.length)break;let h=e[c];try{let u=await this.lookup(h);if(u)i[c]={cep:h,data:r?r(u):u,provider:u.service};else throw new Error("No address found")}catch(u){i[c]={cep:h,data:null,error:u}}}},a=Array.from({length:Math.min(t,e.length)},()=>s());return await Promise.all(a),i.filter(Boolean)}};export{w as AllProvidersFailedError,R as CepLookup,P as CepNotFoundError,v as CepValidationError,b as InMemoryCache,y as ProviderTimeoutError,g as RateLimitError};

package/dist/providers/index.cjs

@@ -1 +1 @@
-"use strict";var e=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var c=Object.getOwnPropertyNames;var m=Object.prototype.hasOwnProperty;var P=(r,t)=>{for(var o in t)e(r,o,{get:t[o],enumerable:!0})},f=(r,t,o,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of c(t))!m.call(r,i)&&i!==o&&e(r,i,{get:()=>t[i],enumerable:!(a=d(t,i))||a.enumerable});return r};var l=r=>f(e({},"__esModule",{value:!0}),r);var b={};P(b,{apicepProvider:()=>u,brasilApiProvider:()=>h,viaCepProvider:()=>v});module.exports=l(b);var v={name:"ViaCEP",buildUrl:r=>`https://viacep.com.br/ws/${r}/json/`,transform:r=>{if(!r||r.erro===!0||r.erro==="true")throw new Error("CEP not found");return{cep:(r.cep||"").replace("-",""),state:r.uf||"",city:r.localidade||"",neighborhood:r.bairro||"",street:r.logradouro||"",service:"ViaCEP"}}};var h={name:"BrasilAPI",buildUrl:r=>`https://brasilapi.com.br/api/cep/v1/${r}`,transform:r=>{if(!r||r.errors||r.message)throw new Error(r.message||"CEP not found");return{cep:(r.cep||"").replace("-",""),state:r.state||"",city:r.city||"",neighborhood:r.neighborhood||"",street:r.street||"",service:"BrasilAPI"}}};var u={name:"ApiCEP",buildUrl:r=>`https://cdn.apicep.com/file/apicep/${r}.json`,transform:r=>{if(!r||r.status!==200)throw new Error(r?.message||"CEP not found");return{cep:(r.code||"").replace("-",""),state:r.state||"",city:r.city||"",neighborhood:r.district||"",street:r.address||"",service:"ApiCEP"}}};
+"use strict";var o=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var c=Object.getOwnPropertyNames;var m=Object.prototype.hasOwnProperty;var f=(r,t)=>{for(var d in t)o(r,d,{get:t[d],enumerable:!0})},P=(r,t,d,e)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of c(t))!m.call(r,i)&&i!==d&&o(r,i,{get:()=>t[i],enumerable:!(e=a(t,i))||e.enumerable});return r};var l=r=>P(o({},"__esModule",{value:!0}),r);var g={};f(g,{apicepProvider:()=>v,brasilApiProvider:()=>u,openCepProvider:()=>b,viaCepProvider:()=>n});module.exports=l(g);var n={name:"ViaCEP",buildUrl:r=>`https://viacep.com.br/ws/${r}/json/`,transform:r=>{if(!r||r.erro===!0||r.erro==="true")throw new Error("CEP not found");return{cep:(r.cep||"").replace("-",""),state:r.uf||"",city:r.localidade||"",neighborhood:r.bairro||"",street:r.logradouro||"",service:"ViaCEP",ibge:r.ibge||void 0,ddd:r.ddd||void 0}}};var u={name:"BrasilAPI",buildUrl:r=>`https://brasilapi.com.br/api/cep/v1/${r}`,transform:r=>{if(!r||r.errors||r.message)throw new Error(r.message||"CEP not found");return{cep:(r.cep||"").replace("-",""),state:r.state||"",city:r.city||"",neighborhood:r.neighborhood||"",street:r.street||"",service:"BrasilAPI"}}};var v={name:"ApiCEP",buildUrl:r=>`https://cdn.apicep.com/file/apicep/${r}.json`,transform:r=>{if(!r||r.status!==200)throw new Error(r?.message||"CEP not found");return{cep:(r.code||"").replace("-",""),state:r.state||"",city:r.city||"",neighborhood:r.district||"",street:r.address||"",service:"ApiCEP"}}};var b={name:"OpenCEP",buildUrl:r=>`https://opencep.com/v1/${r}`,transform:r=>{if(!r||r.error)throw new Error("CEP not found");return{cep:(r.cep||"").replace("-",""),state:r.uf||"",city:r.localidade||"",neighborhood:r.bairro||"",street:r.logradouro||"",service:"OpenCEP",ibge:r.ibge||void 0}}};

package/dist/providers/index.mjs

@@ -1 +1 @@
-var t={name:"ViaCEP",buildUrl:r=>`https://viacep.com.br/ws/${r}/json/`,transform:r=>{if(!r||r.erro===!0||r.erro==="true")throw new Error("CEP not found");return{cep:(r.cep||"").replace("-",""),state:r.uf||"",city:r.localidade||"",neighborhood:r.bairro||"",street:r.logradouro||"",service:"ViaCEP"}}};var o={name:"BrasilAPI",buildUrl:r=>`https://brasilapi.com.br/api/cep/v1/${r}`,transform:r=>{if(!r||r.errors||r.message)throw new Error(r.message||"CEP not found");return{cep:(r.cep||"").replace("-",""),state:r.state||"",city:r.city||"",neighborhood:r.neighborhood||"",street:r.street||"",service:"BrasilAPI"}}};var a={name:"ApiCEP",buildUrl:r=>`https://cdn.apicep.com/file/apicep/${r}.json`,transform:r=>{if(!r||r.status!==200)throw new Error(r?.message||"CEP not found");return{cep:(r.code||"").replace("-",""),state:r.state||"",city:r.city||"",neighborhood:r.district||"",street:r.address||"",service:"ApiCEP"}}};export{a as apicepProvider,o as brasilApiProvider,t as viaCepProvider};
+var t={name:"ViaCEP",buildUrl:r=>`https://viacep.com.br/ws/${r}/json/`,transform:r=>{if(!r||r.erro===!0||r.erro==="true")throw new Error("CEP not found");return{cep:(r.cep||"").replace("-",""),state:r.uf||"",city:r.localidade||"",neighborhood:r.bairro||"",street:r.logradouro||"",service:"ViaCEP",ibge:r.ibge||void 0,ddd:r.ddd||void 0}}};var d={name:"BrasilAPI",buildUrl:r=>`https://brasilapi.com.br/api/cep/v1/${r}`,transform:r=>{if(!r||r.errors||r.message)throw new Error(r.message||"CEP not found");return{cep:(r.cep||"").replace("-",""),state:r.state||"",city:r.city||"",neighborhood:r.neighborhood||"",street:r.street||"",service:"BrasilAPI"}}};var e={name:"ApiCEP",buildUrl:r=>`https://cdn.apicep.com/file/apicep/${r}.json`,transform:r=>{if(!r||r.status!==200)throw new Error(r?.message||"CEP not found");return{cep:(r.code||"").replace("-",""),state:r.state||"",city:r.city||"",neighborhood:r.district||"",street:r.address||"",service:"ApiCEP"}}};var c={name:"OpenCEP",buildUrl:r=>`https://opencep.com/v1/${r}`,transform:r=>{if(!r||r.error)throw new Error("CEP not found");return{cep:(r.cep||"").replace("-",""),state:r.uf||"",city:r.localidade||"",neighborhood:r.bairro||"",street:r.logradouro||"",service:"OpenCEP",ibge:r.ibge||void 0}}};export{e as apicepProvider,d as brasilApiProvider,c as openCepProvider,t as viaCepProvider};

package/dist/src/cache/index.d.ts

@@ -7,30 +7,27 @@ export interface Cache {
     get(key: string): Address | undefined;
     set(key: string, value: Address): void;
     clear(): void;
+    delete?(key: string): void;
+    has?(key: string): boolean;
+}
+export interface InMemoryCacheOptions {
+    /** Time-to-live in milliseconds. Default: Infinity (no expiry) */
+    ttl?: number;
+    /** Maximum number of entries. Default: Infinity (no limit) */
+    maxSize?: number;
 }
 /**
  * @class InMemoryCache
- * @description A simple in-memory cache implementation for storing CEP lookups.
+ * @description In-memory cache with optional TTL and size limit.
  */
 export declare class InMemoryCache implements Cache {
     private cache;
-    /**
-     * @method get
-     * @description Retrieves an address from the cache.
-     * @param {string} key - The CEP to look up.
-     * @returns {Address | undefined} The cached address or undefined if not found.
-     */
+    private ttl;
+    private maxSize;
+    constructor(options?: InMemoryCacheOptions);
     get(key: string): Address | undefined;
-    /**
-     * @method set
-     * @description Stores an address in the cache.
-     * @param {string} key - The CEP to use as the cache key.
-     * @param {Address} value - The address to store.
-     */
     set(key: string, value: Address): void;
-    /**
-     * @method clear
-     * @description Clears the entire cache.
-     */
+    delete(key: string): void;
+    has(key: string): boolean;
     clear(): void;
 }

package/dist/src/cache/index.js

@@ -3,34 +3,49 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryCache = void 0;
 /**
  * @class InMemoryCache
- * @description A simple in-memory cache implementation for storing CEP lookups.
+ * @description In-memory cache with optional TTL and size limit.
  */
 class InMemoryCache {
-    constructor() {
+    constructor(options) {
         this.cache = new Map();
+        this.ttl = options?.ttl ?? Infinity;
+        this.maxSize = options?.maxSize ?? Infinity;
     }
-    /**
-     * @method get
-     * @description Retrieves an address from the cache.
-     * @param {string} key - The CEP to look up.
-     * @returns {Address | undefined} The cached address or undefined if not found.
-     */
     get(key) {
-        return this.cache.get(key);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        if (this.ttl !== Infinity && Date.now() - entry.timestamp > this.ttl) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
     }
-    /**
-     * @method set
-     * @description Stores an address in the cache.
-     * @param {string} key - The CEP to use as the cache key.
-     * @param {Address} value - The address to store.
-     */
     set(key, value) {
-        this.cache.set(key, value);
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        if (this.cache.size >= this.maxSize) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        this.cache.set(key, { value, timestamp: Date.now() });
+    }
+    delete(key) {
+        this.cache.delete(key);
+    }
+    has(key) {
+        if (!this.cache.has(key))
+            return false;
+        const entry = this.cache.get(key);
+        if (this.ttl !== Infinity && Date.now() - entry.timestamp > this.ttl) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
     }
-    /**
-     * @method clear
-     * @description Clears the entire cache.
-     */
     clear() {
         this.cache.clear();
     }

package/dist/src/data/ddd-by-state.d.ts

@@ -0,0 +1,2 @@
+/** DDD da capital de cada estado (fallback para providers que nao retornam DDD) */
+export declare const dddByState: Record<string, string>;

package/dist/src/data/ddd-by-state.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dddByState = void 0;
+/** DDD da capital de cada estado (fallback para providers que nao retornam DDD) */
+exports.dddByState = {
+    AC: "68", AL: "82", AM: "92", AP: "96", BA: "71",
+    CE: "85", DF: "61", ES: "27", GO: "62", MA: "98",
+    MG: "31", MS: "67", MT: "65", PA: "91", PB: "83",
+    PE: "81", PI: "86", PR: "41", RJ: "21", RN: "84",
+    RO: "69", RR: "95", RS: "51", SC: "48", SE: "79",
+    SP: "11", TO: "63",
+};

package/dist/src/errors.d.ts

@@ -0,0 +1,23 @@
+export declare class CepValidationError extends Error {
+    readonly cep: string;
+    constructor(cep: string);
+}
+export declare class RateLimitError extends Error {
+    readonly limit: number;
+    readonly window: number;
+    constructor(limit: number, window: number);
+}
+export declare class ProviderTimeoutError extends Error {
+    readonly provider: string;
+    readonly timeout: number;
+    constructor(provider: string, timeout: number);
+}
+export declare class CepNotFoundError extends Error {
+    readonly cep: string;
+    readonly provider?: string;
+    constructor(cep: string, provider?: string);
+}
+export declare class AllProvidersFailedError extends Error {
+    readonly errors: Error[];
+    constructor(errors: Error[]);
+}

package/dist/src/errors.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AllProvidersFailedError = exports.CepNotFoundError = exports.ProviderTimeoutError = exports.RateLimitError = exports.CepValidationError = void 0;
+class CepValidationError extends Error {
+    constructor(cep) {
+        super("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN.");
+        this.name = "CepValidationError";
+        this.cep = cep;
+    }
+}
+exports.CepValidationError = CepValidationError;
+class RateLimitError extends Error {
+    constructor(limit, window) {
+        super(`Rate limit exceeded: ${limit} requests per ${window}ms.`);
+        this.name = "RateLimitError";
+        this.limit = limit;
+        this.window = window;
+    }
+}
+exports.RateLimitError = RateLimitError;
+class ProviderTimeoutError extends Error {
+    constructor(provider, timeout) {
+        super(`Timeout from ${provider}`);
+        this.name = "ProviderTimeoutError";
+        this.provider = provider;
+        this.timeout = timeout;
+    }
+}
+exports.ProviderTimeoutError = ProviderTimeoutError;
+class CepNotFoundError extends Error {
+    constructor(cep, provider) {
+        super("CEP not found");
+        this.name = "CepNotFoundError";
+        this.cep = cep;
+        this.provider = provider;
+    }
+}
+exports.CepNotFoundError = CepNotFoundError;
+class AllProvidersFailedError extends Error {
+    constructor(errors) {
+        super("All providers failed to resolve the CEP.");
+        this.name = "AllProvidersFailedError";
+        this.errors = errors;
+    }
+}
+exports.AllProvidersFailedError = AllProvidersFailedError;

package/dist/src/index.d.ts

@@ -1,7 +1,9 @@
 import { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult, RateLimitOptions, EventName, EventListener, EventMap } from "./types";
-import { Cache, InMemoryCache } from "./cache";
-export type { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult, RateLimitOptions, EventName, EventListener, EventMap, Cache };
+import { Cache, InMemoryCache, InMemoryCacheOptions } from "./cache";
+import { CepValidationError, RateLimitError, ProviderTimeoutError, CepNotFoundError, AllProvidersFailedError } from "./errors";
+export type { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult, RateLimitOptions, EventName, EventListener, EventMap, Cache, InMemoryCacheOptions };
 export { InMemoryCache };
+export { CepValidationError, RateLimitError, ProviderTimeoutError, CepNotFoundError, AllProvidersFailedError };
 /**
  * @class CepLookup
  * @description A class for looking up Brazilian postal codes (CEPs) using multiple providers.
@@ -13,32 +15,24 @@ export declare class CepLookup {
     private cache?;
     private rateLimit?;
     private staggerDelay;
+    private retries;
+    private retryDelay;
+    private logger?;
     private requestTimestamps;
     private emitter;
     constructor(options: CepLookupOptions);
+    private log;
     on<T extends EventName>(eventName: T, listener: EventListener<T>): void;
     off<T extends EventName>(eventName: T, listener: EventListener<T>): void;
     /**
      * @method warmup
      * @description Pings providers to determine the fastest one and updates the internal priority order.
      * Useful to call on UI events like 'focus' on the CEP input.
+     * @returns {Promise<Provider[]>} The list of providers sorted by latency.
      */
-    warmup(): Promise<void>;
+    warmup(): Promise<Provider[]>;
     private checkRateLimit;
     lookup<T = Address>(cep: string, mapper?: (address: Address) => T): Promise<T>;
-    lookupCeps(ceps: string[], concurrency?: number): Promise<BulkCepResult[]>;
+    private _lookupFromProviders;
+    lookupCeps<T = Address>(ceps: string[], concurrency?: number, mapper?: (address: Address) => T): Promise<BulkCepResult<T>[]>;
 }
-/**
- * @deprecated Use `new CepLookup(options).lookup(cep)` instead.
- */
-export declare function lookupCep<T = Address>(options: CepLookupOptions & {
-    cep: string;
-    mapper?: (address: Address) => T;
-}): Promise<T>;
-/**
- * @deprecated Use `new CepLookup(options).lookupCeps(ceps)` instead.
- */
-export declare function lookupCeps(options: CepLookupOptions & {
-    ceps: string[];
-    concurrency?: number;
-}): Promise<BulkCepResult[]>;

package/dist/src/index.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CepLookup = exports.InMemoryCache = void 0;
-exports.lookupCep = lookupCep;
-exports.lookupCeps = lookupCeps;
+exports.CepLookup = exports.AllProvidersFailedError = exports.CepNotFoundError = exports.ProviderTimeoutError = exports.RateLimitError = exports.CepValidationError = exports.InMemoryCache = void 0;
 const cache_1 = require("./cache");
 Object.defineProperty(exports, "InMemoryCache", { enumerable: true, get: function () { return cache_1.InMemoryCache; } });
+const errors_1 = require("./errors");
+Object.defineProperty(exports, "CepValidationError", { enumerable: true, get: function () { return errors_1.CepValidationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+Object.defineProperty(exports, "ProviderTimeoutError", { enumerable: true, get: function () { return errors_1.ProviderTimeoutError; } });
+Object.defineProperty(exports, "CepNotFoundError", { enumerable: true, get: function () { return errors_1.CepNotFoundError; } });
+Object.defineProperty(exports, "AllProvidersFailedError", { enumerable: true, get: function () { return errors_1.AllProvidersFailedError; } });
+const ddd_by_state_1 = require("./data/ddd-by-state");
 // Minimal EventEmitter for internal use
 class EventEmitter {
     constructor() {
@@ -41,7 +46,7 @@ class EventEmitter {
 function validateCep(cep) {
     const cepRegex = /^(\d{8}|\d{5}-\d{3})$/;
     if (!cepRegex.test(cep)) {
-        throw new Error("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN.");
+        throw new errors_1.CepValidationError(cep);
     }
     return cep.replace("-", "");
 }
@@ -61,6 +66,19 @@ function sanitizeAddress(address) {
     });
     return sanitized;
 }
+/**
+ * @function enrichAddress
+ * @description Enriches an address with DDD fallback when the provider doesn't return it.
+ */
+function enrichAddress(address) {
+    if (!address.ddd && address.state) {
+        const fallbackDdd = ddd_by_state_1.dddByState[address.state];
+        if (fallbackDdd) {
+            return { ...address, ddd: fallbackDdd };
+        }
+    }
+    return address;
+}
 /**
  * @class CepLookup
  * @description A class for looking up Brazilian postal codes (CEPs) using multiple providers.
@@ -81,6 +99,12 @@ class CepLookup {
         this.cache = options.cache;
         this.rateLimit = options.rateLimit;
         this.staggerDelay = options.staggerDelay ?? 100;
+        this.retries = options.retries ?? 0;
+        this.retryDelay = options.retryDelay ?? 1000;
+        this.logger = options.logger;
+    }
+    log(msg, data) {
+        this.logger?.debug(msg, data);
     }
     on(eventName, listener) {
         this.emitter.on(eventName, listener);
@@ -92,6 +116,7 @@ class CepLookup {
      * @method warmup
      * @description Pings providers to determine the fastest one and updates the internal priority order.
      * Useful to call on UI events like 'focus' on the CEP input.
+     * @returns {Promise<Provider[]>} The list of providers sorted by latency.
      */
     async warmup() {
         const controlCep = "01001000"; // Praça da Sé (Fixed Valid CEP)
@@ -117,6 +142,7 @@ class CepLookup {
             .filter(p => !!p);
         // Abort any lingering requests (though we awaited all)
         controller.abort();
+        return this.sortedProviders;
     }
     checkRateLimit() {
         if (!this.rateLimit)
@@ -125,33 +151,57 @@ class CepLookup {
         const windowStart = now - this.rateLimit.per;
         this.requestTimestamps = this.requestTimestamps.filter((ts) => ts > windowStart);
         if (this.requestTimestamps.length >= this.rateLimit.requests) {
-            throw new Error(`Rate limit exceeded: ${this.rateLimit.requests} requests per ${this.rateLimit.per}ms.`);
+            throw new errors_1.RateLimitError(this.rateLimit.requests, this.rateLimit.per);
         }
         this.requestTimestamps.push(now);
     }
     async lookup(cep, mapper) {
         this.checkRateLimit();
         const cleanedCep = validateCep(cep);
+        this.log('lookup:start', { cep: cleanedCep });
         if (this.cache) {
             const cachedAddress = this.cache.get(cleanedCep);
             if (cachedAddress) {
+                this.log('cache:hit', { cep: cleanedCep });
                 this.emitter.emit('cache:hit', { cep: cleanedCep });
                 return mapper ? mapper(cachedAddress) : cachedAddress;
             }
         }
+        let lastError;
+        const maxAttempts = 1 + this.retries;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            if (attempt > 0) {
+                const delay = this.retryDelay * Math.pow(2, attempt - 1);
+                this.log('retry:attempt', { attempt, cep: cleanedCep, delay });
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+            try {
+                return await this._lookupFromProviders(cleanedCep, mapper);
+            }
+            catch (error) {
+                if (error instanceof errors_1.CepValidationError || error instanceof errors_1.RateLimitError) {
+                    throw error;
+                }
+                lastError = error;
+            }
+        }
+        throw lastError;
+    }
+    async _lookupFromProviders(cleanedCep, mapper) {
         const controller = new AbortController();
         const { signal } = controller;
-        // Helper to create the promise for a specific provider
         const createProviderPromise = (provider) => {
             const startTime = Date.now();
             const url = provider.buildUrl(cleanedCep);
+            this.log('provider:start', { provider: provider.name, cep: cleanedCep });
             const timeoutPromise = new Promise((_, reject) => {
                 if (!provider.timeout)
                     return;
                 const timeoutId = setTimeout(() => {
                     signal.removeEventListener('abort', onAbort);
                     const duration = Date.now() - startTime;
-                    const error = new Error(`Timeout from ${provider.name}`);
+                    const error = new errors_1.ProviderTimeoutError(provider.name, provider.timeout);
+                    this.log('provider:failure', { provider: provider.name, cep: cleanedCep, error: error.message });
                     this.emitter.emit('failure', { provider: provider.name, cep: cleanedCep, duration, error });
                     reject(error);
                 }, provider.timeout);
@@ -162,7 +212,8 @@ class CepLookup {
                 .then((response) => provider.transform(response))
                 .then((address) => {
                 const duration = Date.now() - startTime;
-                const sanitizedAddress = sanitizeAddress(address);
+                const sanitizedAddress = enrichAddress(sanitizeAddress(address));
+                this.log('provider:success', { provider: provider.name, cep: cleanedCep, duration });
                 this.emitter.emit('success', { provider: provider.name, cep: cleanedCep, duration, address: sanitizedAddress });
                 if (this.cache) {
                     this.cache.set(cleanedCep, sanitizedAddress);
@@ -171,18 +222,16 @@ class CepLookup {
             })
                 .catch((error) => {
                 const duration = Date.now() - startTime;
-                // Only emit failure if it's not a self-induced abortion or timeout handled elsewhere
                 if (!error.message.includes('Timeout from') && error.name !== 'AbortError') {
+                    this.log('provider:failure', { provider: provider.name, cep: cleanedCep, error: error.message });
                     this.emitter.emit('failure', { provider: provider.name, cep: cleanedCep, duration, error });
                 }
                 throw error;
             });
             return Promise.race([fetchPromise, timeoutPromise]);
         };
-        // Staggered Strategy using sortedProviders
         const bestProvider = this.sortedProviders[0];
         const otherProviders = this.sortedProviders.slice(1);
-        // If we only have one provider, just execute it
         if (otherProviders.length === 0) {
             try {
                 return await createProviderPromise(bestProvider);
@@ -191,7 +240,6 @@ class CepLookup {
                 controller.abort();
             }
         }
-        // Execute primary and manage staggering
         let staggerTimeout = null;
         let triggerOthers = null;
         const secondaryPromise = new Promise((resolve, reject) => {
@@ -206,7 +254,6 @@ class CepLookup {
             staggerTimeout = setTimeout(triggerOthers, this.staggerDelay);
         });
         const primaryPromise = createProviderPromise(bestProvider).catch((err) => {
-            // If primary fails, trigger others immediately
             if (triggerOthers)
                 triggerOthers();
             throw err;
@@ -214,13 +261,17 @@ class CepLookup {
         try {
             return await Promise.any([primaryPromise, secondaryPromise]);
         }
+        catch (aggregateError) {
+            const errors = aggregateError.errors || [aggregateError];
+            throw new errors_1.AllProvidersFailedError(errors);
+        }
         finally {
             if (staggerTimeout)
                 clearTimeout(staggerTimeout);
             controller.abort();
         }
     }
-    async lookupCeps(ceps, concurrency = 5) {
+    async lookupCeps(ceps, concurrency = 5, mapper) {
         if (!ceps || ceps.length === 0) {
             return [];
         }
@@ -235,7 +286,11 @@ class CepLookup {
                 try {
                     const address = await this.lookup(cep);
                     if (address) {
-                        results[currentIndex] = { cep, data: address, provider: address.service };
+                        results[currentIndex] = {
+                            cep,
+                            data: mapper ? mapper(address) : address,
+                            provider: address.service,
+                        };
                     }
                     else {
                         throw new Error('No address found');
@@ -252,21 +307,3 @@ class CepLookup {
     }
 }
 exports.CepLookup = CepLookup;
-/**
- * @deprecated Use `new CepLookup(options).lookup(cep)` instead.
- */
-function lookupCep(options) {
-    console.warn("[cep-lookup] The standalone `lookupCep` function is deprecated and will be removed in a future version. Please use `new CepLookup(options).lookup(cep)` instead.");
-    const { cep, providers, fetcher, mapper, cache, rateLimit } = options;
-    const cepLookup = new CepLookup({ providers, fetcher, cache, rateLimit });
-    return cepLookup.lookup(cep, mapper);
-}
-/**
- * @deprecated Use `new CepLookup(options).lookupCeps(ceps)` instead.
- */
-async function lookupCeps(options) {
-    console.warn("[cep-lookup] The standalone `lookupCeps` function is deprecated and will be removed in a future version. Please use `new CepLookup(options).lookupCeps(ceps)` instead.");
-    const { ceps, providers, fetcher, cache, concurrency = 5, rateLimit } = options;
-    const cepLookup = new CepLookup({ providers, fetcher, cache, rateLimit });
-    return cepLookup.lookupCeps(ceps, concurrency);
-}

package/dist/src/providers/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./viacep";
 export * from "./brasil-api";
 export * from "./apicep";
+export * from "./opencep";

package/dist/src/providers/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./viacep"), exports);
 __exportStar(require("./brasil-api"), exports);
 __exportStar(require("./apicep"), exports);
+__exportStar(require("./opencep"), exports);

package/dist/src/providers/opencep.d.ts

@@ -0,0 +1,10 @@
+import { Provider } from "../types";
+/**
+ * @const {Provider} openCepProvider
+ * @description Provider for the OpenCEP service.
+ * @property {string} name - "OpenCEP".
+ * @property {(cep: string) => string} buildUrl - Constructs the URL for OpenCEP API.
+ * @property {(response: any) => Address} transform - Transforms OpenCEP's response into a standardized `Address` object.
+ * @throws {Error} If OpenCEP response indicates an error.
+ */
+export declare const openCepProvider: Provider;

package/dist/src/providers/opencep.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openCepProvider = void 0;
+/**
+ * @const {Provider} openCepProvider
+ * @description Provider for the OpenCEP service.
+ * @property {string} name - "OpenCEP".
+ * @property {(cep: string) => string} buildUrl - Constructs the URL for OpenCEP API.
+ * @property {(response: any) => Address} transform - Transforms OpenCEP's response into a standardized `Address` object.
+ * @throws {Error} If OpenCEP response indicates an error.
+ */
+exports.openCepProvider = {
+    name: "OpenCEP",
+    buildUrl: (cep) => `https://opencep.com/v1/${cep}`,
+    transform: (response) => {
+        if (!response || response.error) {
+            throw new Error("CEP not found");
+        }
+        // OpenCEP returns status code 404 for not found, which fetcher catches.
+        // But sometimes APIs return 200 with error data.
+        // Assuming standard JSON return based on description.
+        return {
+            cep: (response.cep || "").replace("-", ""),
+            state: response.uf || "",
+            city: response.localidade || "",
+            neighborhood: response.bairro || "",
+            street: response.logradouro || "",
+            service: "OpenCEP",
+            ibge: response.ibge || undefined,
+        };
+    },
+};

package/dist/src/providers/viacep.js

@@ -23,6 +23,8 @@ exports.viaCepProvider = {
             neighborhood: response.bairro || "",
             street: response.logradouro || "",
             service: "ViaCEP",
+            ibge: response.ibge || undefined,
+            ddd: response.ddd || undefined,
         };
     },
 };

package/dist/src/types.d.ts

@@ -10,6 +10,8 @@ export interface Address {
     neighborhood: string;
     street: string;
     service: string;
+    ibge?: string;
+    ddd?: string;
 }
 /**
  * @interface Provider
@@ -44,14 +46,22 @@ export interface CepLookupOptions {
     cache?: Cache;
     rateLimit?: RateLimitOptions;
     staggerDelay?: number;
+    /** Number of retries after all providers fail. Default: 0 */
+    retries?: number;
+    /** Base delay in ms between retries (exponential backoff). Default: 1000 */
+    retryDelay?: number;
+    /** Optional logger for debug output */
+    logger?: {
+        debug: (msg: string, data?: Record<string, unknown>) => void;
+    };
 }
 /**
  * @interface BulkCepResult
  * @description Represents the result for a single CEP in a bulk lookup operation.
  */
-export interface BulkCepResult {
+export interface BulkCepResult<T = Address> {
     cep: string;
-    data: Address | null;
+    data: T | null;
     provider?: string;
     error?: Error;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eusilvio/cep-lookup",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "description": "A agnostic, performant and flexible CEP lookup library with race strategy and caching.",
   "license": "MIT",
   "author": "Silvio Souza",
@@ -34,7 +34,8 @@
   "scripts": {
     "clean": "rm -rf dist tsconfig.tsbuildinfo",
     "build": "npm run clean && tsc --emitDeclarationOnly --outDir dist && esbuild src/index.ts src/providers/index.ts --bundle --platform=neutral --format=cjs --outdir=dist --out-extension:.js=.cjs --minify && esbuild src/index.ts src/providers/index.ts --bundle --platform=neutral --format=esm --outdir=dist --out-extension:.js=.mjs --minify",
-    "test": "jest"
+    "test": "jest",
+    "test:html": "npx http-server . -o examples/index.html -c-1"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",