@eusilvio/cep-lookup 2.4.0 → 2.6.0

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

@@ -1,28 +1,10 @@
 # @eusilvio/cep-lookup
 
 [![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.
-
-## About
-
-`@eusilvio/cep-lookup` was created to solve address lookup from a CEP in a different way. Instead of relying on a single data source, it queries multiple services simultaneously and returns the response from the fastest one.
-
-Its agnostic design allows it to be used in any JavaScript environment with any HTTP client, and its powerful "mapper" system allows you to format the data output exactly as you need.
-
-## Key Features
-
-- **Multiple Providers (Race Strategy)**: Queries multiple CEP APIs at the same time and uses the first valid response.
-- **Class-Based API**: Create a reusable instance with your settings.
-- **Bulk Lookups**: Efficiently look up multiple CEPs with a single method call.
-- **Customizable Return Format**: Provide a `mapper` function to transform the address data into any format your application needs.
-- **HTTP Client Agnostic**: You provide the fetch function, giving you full control over the requests. Defaults to global `fetch` if not provided.
-- **Modular and Extensible Architecture**: Adding a new CEP data source is trivial.
-- **Fully Typed**: Developed with TypeScript to ensure type safety and a great developer experience.
-- **Caching**: Built-in support for caching to avoid repeated requests for the same CEP.
+Core CEP lookup engine with multi-provider race, resilience controls, and metrics.
 
 ## Installation
 
@@ -30,225 +12,142 @@ Its agnostic design allows it to be used in any JavaScript environment with any
 npm install @eusilvio/cep-lookup
 ```
 
-## How to Use
+## Features
 
-`@eusilvio/cep-lookup` is designed to be straightforward. You create a reusable instance of the `CepLookup` class with your desired settings and use its methods to look up single or multiple CEPs. The library also includes a simple in-memory cache to avoid repeated requests, which you can use or replace with your own implementation.
+- Multi-provider race strategy.
+- Cache and rate limiting.
+- Retry with exponential backoff.
+- Standardized errors with error codes.
+- Circuit breaker per provider.
+- Provider health score and runtime metrics.
+- Event-based observability.
 
-### Example 1: Basic Usage
+## Basic Usage
 
-```typescript
-import { CepLookup, Address } from "@eusilvio/cep-lookup";
-import {
-  viaCepProvider,
-  brasilApiProvider,
-} from "@eusilvio/cep-lookup/providers";
+```ts
+import { CepLookup } from "@eusilvio/cep-lookup";
+import { viaCepProvider, brasilApiProvider } from "@eusilvio/cep-lookup/providers";
 
-// 1. Create an instance of CepLookup
-const cepLookup = new CepLookup({
+const lookup = new CepLookup({
   providers: [viaCepProvider, brasilApiProvider],
 });
 
-// 2. Look up a CEP
-cepLookup.lookup("01001-000").then((address: Address) => {
-  console.log("Address found:", address);
-  // Output:
-  // {
-  //   cep: '01001-000',
-  //   state: 'SP',
-  //   city: 'São Paulo',
-  //   neighborhood: 'Sé',
-  //   street: 'Praça da Sé',
-  //   service: 'ViaCEP'
-  // }
-});
+const address = await lookup.lookup("01001-000");
+console.log(address);
 ```
 
-### Example 2: Custom Return with `mapper`
-
-```typescript
-import { CepLookup, Address } from "@eusilvio/cep-lookup";
-import { viaCepProvider } from "@eusilvio/cep-lookup/providers";
+## Error Handling
 
-const cepLookup = new CepLookup({
-  providers: [viaCepProvider],
-});
-
-// 1. Define your "mapper" function
-interface CustomAddress {
-  postalCode: string;
-  fullAddress: string;
-  source: string;
+```ts
+import {
+  CepLookup,
+  CepNotFoundError,
+  ProviderTimeoutError,
+  RateLimitError,
+  AllProvidersFailedError,
+} from "@eusilvio/cep-lookup";
+
+try {
+  await lookup.lookup("01001000");
+} catch (error) {
+  if (error instanceof CepNotFoundError) {
+    console.log(error.code); // NOT_FOUND
+  } else if (error instanceof ProviderTimeoutError) {
+    console.log(error.code); // TIMEOUT
+  } else if (error instanceof RateLimitError) {
+    console.log(error.code); // RATE_LIMITED
+  } else if (error instanceof AllProvidersFailedError) {
+    console.log(error.code); // ALL_PROVIDERS_FAILED
+  }
 }
-
-const myMapper = (address: Address): CustomAddress => {
-  return {
-    postalCode: address.cep,
-    fullAddress: `${address.street}, ${address.neighborhood} - ${address.city}/${address.state}`,
-    source: address.service,
-  };
-};
-
-// 2. Look up a CEP with the mapper
-cepLookup.lookup("01001-000", myMapper).then((customAddress: CustomAddress) => {
-  console.log("Address found (custom format):", customAddress);
-  // Output:
-  // {
-  //   postalCode: '01001-000',
-  //   fullAddress: 'Praça da Sé, Sé - São Paulo/SP',
-  //   source: 'ViaCEP'
-  // }
-});
 ```
 
-### Example 3: Bulk CEP Lookup
-
-For scenarios where you need to query multiple CEPs at once, you can use the `lookupCeps` method. It processes the CEPs in parallel with a configurable concurrency limit to avoid overwhelming the providers.
-
-```typescript
-import { CepLookup, BulkCepResult } from "@eusilvio/cep-lookup";
-import {
-  viaCepProvider,
-  brasilApiProvider,
-} from "@eusilvio/cep-lookup/providers";
-
-const cepsToLookup = ["01001-000", "99999-999", "04538-132"];
+## Circuit Breaker
 
-// 1. Create an instance with your settings
-const cepLookup = new CepLookup({
+```ts
+const lookup = new CepLookup({
   providers: [viaCepProvider, brasilApiProvider],
-});
-
-// 2. Look up multiple CEPs
-cepLookup.lookupCeps(cepsToLookup, { concurrency: 2 }).then((results: BulkCepResult[]) => {
-  console.log("Bulk lookup results:", results);
-  // Output:
-  // [
-  //   {
-  //     cep: '01001-000',
-  //     data: { cep: '01001-000', state: 'SP', city: 'São Paulo', ... },
-  //     provider: 'ViaCEP'
-  //   },
-  //   {
-  //     cep: '99999-999',
-  //     data: null,
-  //     error: [Error: All providers failed to find the CEP]
-  //   },
-  //   {
-  //     cep: '04538-132',
-  //     data: { cep: '04538-132', state: 'SP', city: 'São Paulo', ... },
-  //     provider: 'BrasilAPI'
-  //   }
-  // ]
+  circuitBreaker: {
+    enabled: true,
+    failureThreshold: 3,
+    cooldownMs: 30_000,
+  },
 });
 ```
 
-## API
-
-### `new CepLookup(options)`
-
-Creates a new `CepLookup` instance.
-
-- `options`: A configuration object.
-  - `providers` (Provider[], **required**): An array of providers that will be queried.
-  - `fetcher` (Fetcher, _optional_): Your asynchronous function that fetches data from a URL. Defaults to global `fetch` if not provided.
-  - `cache` (Cache, _optional_): An instance of a cache that implements the `Cache` interface. Use `InMemoryCache` for a simple in-memory cache.
-  - `rateLimit` ({ requests: number, per: number }, _optional_): Configures an in-memory rate limiter (e.g., `{ requests: 10, per: 1000 }` for 10 requests per second).
-  - `staggerDelay` (number, _optional_): Time in milliseconds to wait for the fastest provider before triggering backups (default: `100`).
-
-### `cepLookup.warmup()`
-
-Pings all providers to determine the fastest one for the current environment. Call this during idle UI time (like when a user focuses a CEP input field) to optimize the subsequent `lookup` call.
-
-### `cepLookup.lookup<T = Address>(cep, mapper?): Promise<T>`
-
-Returns a `Promise` that resolves to the address in the default format (`Address`) or in the custom format `T` if a `mapper` is provided.
-
-- `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[]>`
-
-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`.
+## Health and SLA Metrics
+
+```ts
+const health = lookup.getProviderHealth();
+/*
+[
+  {
+    provider: 'ViaCEP',
+    score: 0.94,
+    isOpen: false,
+    successCount: 12,
+    failureCount: 1,
+    avgLatencyMs: 52.11,
+    ...
+  }
+]
+*/
+
+const metrics = lookup.getProviderMetrics();
+/*
+[
+  {
+    provider: 'ViaCEP',
+    requests: 13,
+    successes: 12,
+    failures: 1,
+    timeoutErrors: 0,
+    notFoundErrors: 1,
+    avgLatencyMs: 52.11
+  }
+]
+*/
+```
 
-> **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.
+## Bulk Lookup
 
-### Observability Events API
+```ts
+const results = await lookup.lookupCeps(["01001-000", "99999-999"], 2);
+```
 
-Version 2.0.0 introduced an event-based API to monitor the library's behavior. You can listen to events to gather metrics on provider performance, latency, and errors.
+## API Summary
 
-```typescript
-const cepLookup = new CepLookup({ providers: [...] });
+### `new CepLookup(options)`
 
-// Fired for each successful provider response
-cepLookup.on('success', ({ provider, cep, duration }) => {
-  console.log(`[${provider}] Success for CEP ${cep} in ${duration}ms`);
-  // myMetrics.timing('cep.latency', duration, { provider });
-});
+- `providers`: required provider list.
+- `fetcher`: optional custom HTTP fetch function.
+- `cache`: optional cache implementation.
+- `rateLimit`: `{ requests, per }`.
+- `staggerDelay`: delay before backup providers.
+- `retries`: retry count after failure.
+- `retryDelay`: base retry delay in ms.
+- `circuitBreaker`: `{ enabled, failureThreshold, cooldownMs }`.
 
-// Fired for each failed provider response
-cepLookup.on('failure', ({ provider, cep, error }) => {
-  console.error(`[${provider}] Failure for CEP ${cep}: ${error.message}`);
-  // myMetrics.increment('cep.failure', { provider });
-});
+### Methods
 
-// Fired when a CEP is resolved from the cache
-cepLookup.on('cache:hit', ({ cep }) => {
-  console.log(`[Cache] CEP ${cep} found in cache.`);
-  // myMetrics.increment('cep.cache_hit');
-});
+- `lookup(cep, mapper?)`
+- `lookupCeps(ceps, concurrency?)`
+- `warmup()`
+- `getProviderHealth()`
+- `getProviderMetrics()`
+- `on(event, listener)` / `off(event, listener)`
 
-// The lookup call remains the same
-cepLookup.lookup("01001-000");
-```
+## Compatibility and support
 
-## Examples
-
-You can find more detailed examples in the `examples/` directory:
-
-- **Basic Usage**: `examples/example.ts`
-- **Bulk Lookup**: `examples/bulk-example.ts`
-- **Custom Provider**: `examples/custom-provider-example.ts`
-- **Node.js Usage**: `examples/node-example.ts`
-- **React Component**: `examples/react-example.tsx`
-- **React Hook**: `examples/react-hook-example.ts`
-- **Angular Component/Service**: `examples/angular-example.ts`
-- **Cache Usage**: `examples/cache-example.ts`
-
-## Creating a Custom Provider
-
-Your custom provider must always transform the API response to the library's default `Address` interface. The user's `mapper` will handle the final customization.
-
-```typescript
-import { Provider, Address } from "@eusilvio/cep-lookup";
-
-const myCustomProvider: Provider = {
-  name: "MyCustomAPI",
-  buildUrl: (cep: string) => `https://myapi.com/cep/${cep}`,
-  transform: (response: any): Address => {
-    // Transforms the response from "MyCustomAPI" to the "Address" format
-    return {
-      cep: response.postal_code,
-      state: response.data.state_short,
-      city: response.data.city_name,
-      neighborhood: response.data.neighborhood,
-      street: response.data.street_name,
-      service: "MyCustomAPI",
-    };
-  },
-};
-```
+- Node.js: `20.x`, `22.x`, `24.x`
+- Maintenance policy: [SUPPORT.md](../../SUPPORT.md)
 
-## Running Tests
+## Production docs
 
-```bash
-npm test
-```
+- [Best Practices](../../docs/BEST_PRACTICES.md)
+- [Migration Guide](../../docs/MIGRATION.md)
+- [Cookbook](../../docs/COOKBOOK.md)
 
 ## License
 
-Distributed under the MIT License.
+MIT

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 x=Object.defineProperty;var U=Object.getOwnPropertyDescriptor;var q=Object.getOwnPropertyNames;var _=Object.prototype.hasOwnProperty;var z=(i,e)=>{for(var t in e)x(i,t,{get:e[t],enumerable:!0})},V=(i,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let s of q(e))!_.call(i,s)&&s!==t&&x(i,s,{get:()=>e[s],enumerable:!(r=U(e,s))||r.enumerable});return i};var H=i=>V(x({},"__esModule",{value:!0}),i);var G={};z(G,{AllProvidersFailedError:()=>p,CepLookup:()=>O,CepNotFoundError:()=>E,CepValidationError:()=>f,InMemoryCache:()=>A,ProviderTimeoutError:()=>v,ProviderUnavailableError:()=>P,RateLimitError:()=>g});module.exports=H(G);var A=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 f=class extends Error{constructor(t){super("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN.");this.code="INVALID_CEP";this.name="CepValidationError",this.cep=t}},g=class extends Error{constructor(t,r){super(`Rate limit exceeded: ${t} requests per ${r}ms.`);this.code="RATE_LIMITED";this.name="RateLimitError",this.limit=t,this.window=r}},v=class extends Error{constructor(t,r){super(`Timeout from ${t}`);this.code="TIMEOUT";this.name="ProviderTimeoutError",this.provider=t,this.timeout=r}},E=class extends Error{constructor(t,r){super("CEP not found");this.code="NOT_FOUND";this.name="CepNotFoundError",this.cep=t,this.provider=r}},p=class extends Error{constructor(t){super("All providers failed to resolve the CEP.");this.code="ALL_PROVIDERS_FAILED";this.name="AllProvidersFailedError",this.errors=t}},P=class extends Error{constructor(t){super(`Provider ${t} is temporarily unavailable (circuit open).`);this.code="PROVIDER_UNAVAILABLE";this.name="ProviderUnavailableError",this.provider=t}};function F(i,e,t){if(i instanceof Error){if(i instanceof f||i instanceof g||i instanceof v||i instanceof E||i instanceof P||i instanceof p)return i;let r=i.message?.toLowerCase?.()||"";return r.includes("cep not found")||r.includes("not found")||r.includes("status: 404")?new E(e,t):(i.name==="AbortError",i)}return new Error(String(i))}var S={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 M=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 $(i){if(!/^(\d{8}|\d{5}-\d{3})$/.test(i))throw new f(i);return i.replace("-","")}function K(i){let e={...i};return Object.keys(e).forEach(t=>{let r=e[t];typeof r=="string"&&(e[t]=r.trim())}),e}function j(i){if(!i.ddd&&i.state){let e=S[i.state];if(e)return{...i,ddd:e}}return i}var O=class{constructor(e){this.requestTimestamps=[];this.providerState=new Map;this.providers=e.providers,this.sortedProviders=[...e.providers],this.emitter=new M,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,this.retries=e.retries??0,this.retryDelay=e.retryDelay??1e3,this.logger=e.logger,this.circuitBreakerEnabled=e.circuitBreaker?.enabled??!0,this.circuitFailureThreshold=e.circuitBreaker?.failureThreshold??3,this.circuitCooldownMs=e.circuitBreaker?.cooldownMs??3e4,this.providers.forEach(t=>{this.providerState.set(t.name,{consecutiveFailures:0,successCount:0,failureCount:0,avgLatencyMs:0,requests:0,timeoutErrors:0,notFoundErrors:0})})}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 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);return this.sortedProviders=c.map(o=>o.provider).filter(o=>!!o),t.abort(),this.sortedProviders}getOrCreateProviderState(e){let t=this.providerState.get(e);if(t)return t;let r={consecutiveFailures:0,successCount:0,failureCount:0,avgLatencyMs:0,requests:0,timeoutErrors:0,notFoundErrors:0};return this.providerState.set(e,r),r}recordProviderSuccess(e,t){let r=this.getOrCreateProviderState(e);r.requests+=1,r.successCount+=1,r.consecutiveFailures=0;let s=r.successCount+r.failureCount;r.avgLatencyMs=s===1?t:(r.avgLatencyMs*(s-1)+t)/s,r.openUntil=void 0}recordProviderFailure(e,t,r){let s=this.getOrCreateProviderState(e);s.requests+=1,s.failureCount+=1,s.consecutiveFailures+=1;let c=s.successCount+s.failureCount;s.avgLatencyMs=c===1?t:(s.avgLatencyMs*(c-1)+t)/c,r instanceof v&&(s.timeoutErrors+=1),r instanceof E&&(s.notFoundErrors+=1),this.circuitBreakerEnabled&&s.consecutiveFailures>=this.circuitFailureThreshold&&(s.openUntil=Date.now()+this.circuitCooldownMs)}isProviderOpen(e){if(!this.circuitBreakerEnabled)return!1;let t=this.getOrCreateProviderState(e);return t.openUntil?Date.now()>=t.openUntil?(t.openUntil=void 0,t.consecutiveFailures=0,!1):!0:!1}scoreProvider(e){let t=this.getOrCreateProviderState(e.name),r=t.successCount+t.failureCount,s=r===0?1:t.successCount/r,c=t.avgLatencyMs>0?Math.min(t.avgLatencyMs/1e3,1):0,o=this.isProviderOpen(e.name)?1:0;return s*.8+(1-c)*.2-o}getProviderHealth(){return this.providers.map(e=>{let t=this.getOrCreateProviderState(e.name);return{provider:e.name,score:Number(this.scoreProvider(e).toFixed(4)),isOpen:this.isProviderOpen(e.name),openUntil:t.openUntil,consecutiveFailures:t.consecutiveFailures,successCount:t.successCount,failureCount:t.failureCount,avgLatencyMs:Number(t.avgLatencyMs.toFixed(2))}}).sort((e,t)=>t.score-e.score)}getProviderMetrics(){return this.providers.map(e=>{let t=this.getOrCreateProviderState(e.name);return{provider:e.name,requests:t.requests,successes:t.successCount,failures:t.failureCount,timeoutErrors:t.timeoutErrors,notFoundErrors:t.notFoundErrors,avgLatencyMs:Number(t.avgLatencyMs.toFixed(2))}})}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=$(e);if(this.log("lookup:start",{cep:r}),this.cache){let o=this.cache.get(r);if(o)return this.log("cache:hit",{cep:r}),this.emitter.emit("cache:hit",{cep:r}),t?t(o):o}let s,c=1+this.retries;for(let o=0;o<c;o++){if(o>0){let a=this.retryDelay*Math.pow(2,o-1);this.log("retry:attempt",{attempt:o,cep:r,delay:a}),await new Promise(u=>setTimeout(u,a))}try{return await this._lookupFromProviders(r,t)}catch(a){if(a instanceof f||a instanceof g)throw a;s=a}}throw s}async _lookupFromProviders(e,t){let r=new AbortController,{signal:s}=r,c=this.sortedProviders.filter(n=>!this.isProviderOpen(n.name)),o=[...c].sort((n,l)=>this.scoreProvider(l)-this.scoreProvider(n)),a=o.length>0?o:[...this.sortedProviders].sort((n,l)=>this.scoreProvider(l)-this.scoreProvider(n));if(a.length===0)throw new p([new P("all")]);if(c.length===0&&this.circuitBreakerEnabled)throw new p(a.map(n=>new P(n.name)));let u=n=>{let l=Date.now(),L=n.buildUrl(e);this.log("provider:start",{provider:n.name,cep:e});let I=new Promise((b,m)=>{if(!n.timeout)return;let d=setTimeout(()=>{s.removeEventListener("abort",R);let N=Date.now()-l,T=new v(n.name,n.timeout);this.recordProviderFailure(n.name,N,T),this.log("provider:failure",{provider:n.name,cep:e,error:T.message}),this.emitter.emit("failure",{provider:n.name,cep:e,duration:N,error:T}),m(T)},n.timeout),R=()=>clearTimeout(d);s.addEventListener("abort",R,{once:!0})}),B=this.fetcher(L,s).then(b=>n.transform(b)).then(b=>{let m=Date.now()-l,d=j(K(b));return this.recordProviderSuccess(n.name,m),this.log("provider:success",{provider:n.name,cep:e,duration:m}),this.emitter.emit("success",{provider:n.name,cep:e,duration:m,address:d}),this.cache&&this.cache.set(e,d),t?t(d):d}).catch(b=>{let m=Date.now()-l,d=F(b,e,n.name);throw d.name!=="AbortError"&&!(d instanceof v)&&(this.recordProviderFailure(n.name,m,d),this.log("provider:failure",{provider:n.name,cep:e,error:d.message}),this.emitter.emit("failure",{provider:n.name,cep:e,duration:m,error:d})),d});return Promise.race([B,I])},y=a[0],h=a.slice(1);if(h.length===0)try{return await u(y)}finally{r.abort()}let w=null,C=null,k=new Promise((n,l)=>{C=()=>{if(w&&clearTimeout(w),s.aborted)return;let L=h.map(u);Promise.any(L).then(n).catch(l)},w=setTimeout(C,this.staggerDelay)}),D=u(y).catch(n=>{throw C&&C(),n});try{return await Promise.any([D,k])}catch(n){let l=n.errors||[n];throw new p(l)}finally{w&&clearTimeout(w),r.abort()}}async lookupCeps(e,t=5,r){if(!e||e.length===0)return[];let s=new Array(e.length),c=0,o=async()=>{for(;c<e.length;){let u=c++;if(u>=e.length)break;let y=e[u];try{let h=await this.lookup(y);if(h)s[u]={cep:y,data:r?r(h):h,provider:h.service};else throw new Error("No address found")}catch(h){s[u]={cep:y,data:null,error:h}}}},a=Array.from({length:Math.min(t,e.length)},()=>o());return await Promise.all(a),s.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 L=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 E=class extends Error{constructor(t){super("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN.");this.code="INVALID_CEP";this.name="CepValidationError",this.cep=t}},P=class extends Error{constructor(t,r){super(`Rate limit exceeded: ${t} requests per ${r}ms.`);this.code="RATE_LIMITED";this.name="RateLimitError",this.limit=t,this.window=r}},v=class extends Error{constructor(t,r){super(`Timeout from ${t}`);this.code="TIMEOUT";this.name="ProviderTimeoutError",this.provider=t,this.timeout=r}},y=class extends Error{constructor(t,r){super("CEP not found");this.code="NOT_FOUND";this.name="CepNotFoundError",this.cep=t,this.provider=r}},p=class extends Error{constructor(t){super("All providers failed to resolve the CEP.");this.code="ALL_PROVIDERS_FAILED";this.name="AllProvidersFailedError",this.errors=t}},b=class extends Error{constructor(t){super(`Provider ${t} is temporarily unavailable (circuit open).`);this.code="PROVIDER_UNAVAILABLE";this.name="ProviderUnavailableError",this.provider=t}};function R(i,e,t){if(i instanceof Error){if(i instanceof E||i instanceof P||i instanceof v||i instanceof y||i instanceof b||i instanceof p)return i;let r=i.message?.toLowerCase?.()||"";return r.includes("cep not found")||r.includes("not found")||r.includes("status: 404")?new y(e,t):(i.name==="AbortError",i)}return new Error(String(i))}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(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 E(i);return i.replace("-","")}function U(i){let e={...i};return Object.keys(e).forEach(t=>{let r=e[t];typeof r=="string"&&(e[t]=r.trim())}),e}function q(i){if(!i.ddd&&i.state){let e=N[i.state];if(e)return{...i,ddd:e}}return i}var F=class{constructor(e){this.requestTimestamps=[];this.providerState=new Map;this.providers=e.providers,this.sortedProviders=[...e.providers],this.emitter=new x,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,this.retries=e.retries??0,this.retryDelay=e.retryDelay??1e3,this.logger=e.logger,this.circuitBreakerEnabled=e.circuitBreaker?.enabled??!0,this.circuitFailureThreshold=e.circuitBreaker?.failureThreshold??3,this.circuitCooldownMs=e.circuitBreaker?.cooldownMs??3e4,this.providers.forEach(t=>{this.providerState.set(t.name,{consecutiveFailures:0,successCount:0,failureCount:0,avgLatencyMs:0,requests:0,timeoutErrors:0,notFoundErrors:0})})}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 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);return this.sortedProviders=c.map(o=>o.provider).filter(o=>!!o),t.abort(),this.sortedProviders}getOrCreateProviderState(e){let t=this.providerState.get(e);if(t)return t;let r={consecutiveFailures:0,successCount:0,failureCount:0,avgLatencyMs:0,requests:0,timeoutErrors:0,notFoundErrors:0};return this.providerState.set(e,r),r}recordProviderSuccess(e,t){let r=this.getOrCreateProviderState(e);r.requests+=1,r.successCount+=1,r.consecutiveFailures=0;let s=r.successCount+r.failureCount;r.avgLatencyMs=s===1?t:(r.avgLatencyMs*(s-1)+t)/s,r.openUntil=void 0}recordProviderFailure(e,t,r){let s=this.getOrCreateProviderState(e);s.requests+=1,s.failureCount+=1,s.consecutiveFailures+=1;let c=s.successCount+s.failureCount;s.avgLatencyMs=c===1?t:(s.avgLatencyMs*(c-1)+t)/c,r instanceof v&&(s.timeoutErrors+=1),r instanceof y&&(s.notFoundErrors+=1),this.circuitBreakerEnabled&&s.consecutiveFailures>=this.circuitFailureThreshold&&(s.openUntil=Date.now()+this.circuitCooldownMs)}isProviderOpen(e){if(!this.circuitBreakerEnabled)return!1;let t=this.getOrCreateProviderState(e);return t.openUntil?Date.now()>=t.openUntil?(t.openUntil=void 0,t.consecutiveFailures=0,!1):!0:!1}scoreProvider(e){let t=this.getOrCreateProviderState(e.name),r=t.successCount+t.failureCount,s=r===0?1:t.successCount/r,c=t.avgLatencyMs>0?Math.min(t.avgLatencyMs/1e3,1):0,o=this.isProviderOpen(e.name)?1:0;return s*.8+(1-c)*.2-o}getProviderHealth(){return this.providers.map(e=>{let t=this.getOrCreateProviderState(e.name);return{provider:e.name,score:Number(this.scoreProvider(e).toFixed(4)),isOpen:this.isProviderOpen(e.name),openUntil:t.openUntil,consecutiveFailures:t.consecutiveFailures,successCount:t.successCount,failureCount:t.failureCount,avgLatencyMs:Number(t.avgLatencyMs.toFixed(2))}}).sort((e,t)=>t.score-e.score)}getProviderMetrics(){return this.providers.map(e=>{let t=this.getOrCreateProviderState(e.name);return{provider:e.name,requests:t.requests,successes:t.successCount,failures:t.failureCount,timeoutErrors:t.timeoutErrors,notFoundErrors:t.notFoundErrors,avgLatencyMs:Number(t.avgLatencyMs.toFixed(2))}})}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 P(this.rateLimit.requests,this.rateLimit.per);this.requestTimestamps.push(e)}async lookup(e,t){this.checkRateLimit();let r=B(e);if(this.log("lookup:start",{cep:r}),this.cache){let o=this.cache.get(r);if(o)return this.log("cache:hit",{cep:r}),this.emitter.emit("cache:hit",{cep:r}),t?t(o):o}let s,c=1+this.retries;for(let o=0;o<c;o++){if(o>0){let a=this.retryDelay*Math.pow(2,o-1);this.log("retry:attempt",{attempt:o,cep:r,delay:a}),await new Promise(u=>setTimeout(u,a))}try{return await this._lookupFromProviders(r,t)}catch(a){if(a instanceof E||a instanceof P)throw a;s=a}}throw s}async _lookupFromProviders(e,t){let r=new AbortController,{signal:s}=r,c=this.sortedProviders.filter(n=>!this.isProviderOpen(n.name)),o=[...c].sort((n,l)=>this.scoreProvider(l)-this.scoreProvider(n)),a=o.length>0?o:[...this.sortedProviders].sort((n,l)=>this.scoreProvider(l)-this.scoreProvider(n));if(a.length===0)throw new p([new b("all")]);if(c.length===0&&this.circuitBreakerEnabled)throw new p(a.map(n=>new b(n.name)));let u=n=>{let l=Date.now(),A=n.buildUrl(e);this.log("provider:start",{provider:n.name,cep:e});let D=new Promise((g,m)=>{if(!n.timeout)return;let d=setTimeout(()=>{s.removeEventListener("abort",M);let O=Date.now()-l,T=new v(n.name,n.timeout);this.recordProviderFailure(n.name,O,T),this.log("provider:failure",{provider:n.name,cep:e,error:T.message}),this.emitter.emit("failure",{provider:n.name,cep:e,duration:O,error:T}),m(T)},n.timeout),M=()=>clearTimeout(d);s.addEventListener("abort",M,{once:!0})}),I=this.fetcher(A,s).then(g=>n.transform(g)).then(g=>{let m=Date.now()-l,d=q(U(g));return this.recordProviderSuccess(n.name,m),this.log("provider:success",{provider:n.name,cep:e,duration:m}),this.emitter.emit("success",{provider:n.name,cep:e,duration:m,address:d}),this.cache&&this.cache.set(e,d),t?t(d):d}).catch(g=>{let m=Date.now()-l,d=R(g,e,n.name);throw d.name!=="AbortError"&&!(d instanceof v)&&(this.recordProviderFailure(n.name,m,d),this.log("provider:failure",{provider:n.name,cep:e,error:d.message}),this.emitter.emit("failure",{provider:n.name,cep:e,duration:m,error:d})),d});return Promise.race([I,D])},f=a[0],h=a.slice(1);if(h.length===0)try{return await u(f)}finally{r.abort()}let w=null,C=null,S=new Promise((n,l)=>{C=()=>{if(w&&clearTimeout(w),s.aborted)return;let A=h.map(u);Promise.any(A).then(n).catch(l)},w=setTimeout(C,this.staggerDelay)}),k=u(f).catch(n=>{throw C&&C(),n});try{return await Promise.any([k,S])}catch(n){let l=n.errors||[n];throw new p(l)}finally{w&&clearTimeout(w),r.abort()}}async lookupCeps(e,t=5,r){if(!e||e.length===0)return[];let s=new Array(e.length),c=0,o=async()=>{for(;c<e.length;){let u=c++;if(u>=e.length)break;let f=e[u];try{let h=await this.lookup(f);if(h)s[u]={cep:f,data:r?r(h):h,provider:h.service};else throw new Error("No address found")}catch(h){s[u]={cep:f,data:null,error:h}}}},a=Array.from({length:Math.min(t,e.length)},()=>o());return await Promise.all(a),s.filter(Boolean)}};export{p as AllProvidersFailedError,F as CepLookup,y as CepNotFoundError,E as CepValidationError,L as InMemoryCache,v as ProviderTimeoutError,b as ProviderUnavailableError,P 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;
 }