@eusilvio/cep-lookup 2.5.1 → 2.6.0

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/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,231 +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`
+## Error Handling
 
-```typescript
-import { CepLookup, Address } from "@eusilvio/cep-lookup";
-import { viaCepProvider } from "@eusilvio/cep-lookup/providers";
-
-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
+## Circuit Breaker
 
-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"];
-
-// 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, 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, 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.
-- `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.
-
-### Observability Events API
-
-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.
-
-```typescript
-const cepLookup = new CepLookup({ providers: [...] });
-
-// 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 });
-});
-
-// 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 });
-});
-
-// 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');
-});
-
-// The lookup call remains the same
-cepLookup.lookup("01001-000");
+## 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
+  }
+]
+*/
 ```
 
-## Examples
+## Bulk Lookup
 
-You can find more detailed examples in the `examples/` directory:
+```ts
+const results = await lookup.lookupCeps(["01001-000", "99999-999"], 2);
+```
 
-- **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`
+## API Summary
 
-## Creating a Custom Provider
+### `new CepLookup(options)`
 
-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.
+- `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 }`.
 
-```typescript
-import { Provider, Address } from "@eusilvio/cep-lookup";
+### Methods
 
-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",
-    };
-  },
-};
-```
-
-## Running Tests
-
-```bash
-npm test
-```
+- `lookup(cep, mapper?)`
+- `lookupCeps(ceps, concurrency?)`
+- `warmup()`
+- `getProviderHealth()`
+- `getProviderMetrics()`
+- `on(event, listener)` / `off(event, listener)`
 
 ## 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)
 
+## Production docs
+
+- [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 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)}};
+"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 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};
+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/src/errors.d.ts

@@ -1,23 +1,35 @@
+export type CepErrorCode = "INVALID_CEP" | "RATE_LIMITED" | "TIMEOUT" | "NOT_FOUND" | "PROVIDER_UNAVAILABLE" | "ALL_PROVIDERS_FAILED" | "UNKNOWN";
 export declare class CepValidationError extends Error {
     readonly cep: string;
+    readonly code: CepErrorCode;
     constructor(cep: string);
 }
 export declare class RateLimitError extends Error {
     readonly limit: number;
     readonly window: number;
+    readonly code: CepErrorCode;
     constructor(limit: number, window: number);
 }
 export declare class ProviderTimeoutError extends Error {
     readonly provider: string;
     readonly timeout: number;
+    readonly code: CepErrorCode;
     constructor(provider: string, timeout: number);
 }
 export declare class CepNotFoundError extends Error {
     readonly cep: string;
     readonly provider?: string;
+    readonly code: CepErrorCode;
     constructor(cep: string, provider?: string);
 }
 export declare class AllProvidersFailedError extends Error {
     readonly errors: Error[];
+    readonly code: CepErrorCode;
     constructor(errors: Error[]);
 }
+export declare class ProviderUnavailableError extends Error {
+    readonly provider: string;
+    readonly code: CepErrorCode;
+    constructor(provider: string);
+}
+export declare function normalizeProviderError(error: unknown, cep: string, provider: string): Error;

package/dist/src/errors.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AllProvidersFailedError = exports.CepNotFoundError = exports.ProviderTimeoutError = exports.RateLimitError = exports.CepValidationError = void 0;
+exports.ProviderUnavailableError = exports.AllProvidersFailedError = exports.CepNotFoundError = exports.ProviderTimeoutError = exports.RateLimitError = exports.CepValidationError = void 0;
+exports.normalizeProviderError = normalizeProviderError;
 class CepValidationError extends Error {
     constructor(cep) {
         super("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN.");
+        this.code = "INVALID_CEP";
         this.name = "CepValidationError";
         this.cep = cep;
     }
@@ -12,6 +14,7 @@ exports.CepValidationError = CepValidationError;
 class RateLimitError extends Error {
     constructor(limit, window) {
         super(`Rate limit exceeded: ${limit} requests per ${window}ms.`);
+        this.code = "RATE_LIMITED";
         this.name = "RateLimitError";
         this.limit = limit;
         this.window = window;
@@ -21,6 +24,7 @@ exports.RateLimitError = RateLimitError;
 class ProviderTimeoutError extends Error {
     constructor(provider, timeout) {
         super(`Timeout from ${provider}`);
+        this.code = "TIMEOUT";
         this.name = "ProviderTimeoutError";
         this.provider = provider;
         this.timeout = timeout;
@@ -30,6 +34,7 @@ exports.ProviderTimeoutError = ProviderTimeoutError;
 class CepNotFoundError extends Error {
     constructor(cep, provider) {
         super("CEP not found");
+        this.code = "NOT_FOUND";
         this.name = "CepNotFoundError";
         this.cep = cep;
         this.provider = provider;
@@ -39,8 +44,39 @@ exports.CepNotFoundError = CepNotFoundError;
 class AllProvidersFailedError extends Error {
     constructor(errors) {
         super("All providers failed to resolve the CEP.");
+        this.code = "ALL_PROVIDERS_FAILED";
         this.name = "AllProvidersFailedError";
         this.errors = errors;
     }
 }
 exports.AllProvidersFailedError = AllProvidersFailedError;
+class ProviderUnavailableError extends Error {
+    constructor(provider) {
+        super(`Provider ${provider} is temporarily unavailable (circuit open).`);
+        this.code = "PROVIDER_UNAVAILABLE";
+        this.name = "ProviderUnavailableError";
+        this.provider = provider;
+    }
+}
+exports.ProviderUnavailableError = ProviderUnavailableError;
+function normalizeProviderError(error, cep, provider) {
+    if (error instanceof Error) {
+        if (error instanceof CepValidationError ||
+            error instanceof RateLimitError ||
+            error instanceof ProviderTimeoutError ||
+            error instanceof CepNotFoundError ||
+            error instanceof ProviderUnavailableError ||
+            error instanceof AllProvidersFailedError) {
+            return error;
+        }
+        const message = error.message?.toLowerCase?.() || "";
+        if (message.includes("cep not found") || message.includes("not found") || message.includes("status: 404")) {
+            return new CepNotFoundError(cep, provider);
+        }
+        if (error.name === "AbortError") {
+            return error;
+        }
+        return error;
+    }
+    return new Error(String(error));
+}

package/dist/src/index.d.ts

@@ -1,9 +1,9 @@
-import { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult, RateLimitOptions, EventName, EventListener, EventMap } from "./types";
+import { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult, RateLimitOptions, EventName, EventListener, EventMap, ProviderHealth, ProviderMetrics, CircuitBreakerOptions } from "./types";
 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 };
+import { CepValidationError, RateLimitError, ProviderTimeoutError, CepNotFoundError, AllProvidersFailedError, ProviderUnavailableError } from "./errors";
+export type { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult, RateLimitOptions, EventName, EventListener, EventMap, Cache, InMemoryCacheOptions, ProviderHealth, ProviderMetrics, CircuitBreakerOptions };
 export { InMemoryCache };
-export { CepValidationError, RateLimitError, ProviderTimeoutError, CepNotFoundError, AllProvidersFailedError };
+export { CepValidationError, RateLimitError, ProviderTimeoutError, CepNotFoundError, AllProvidersFailedError, ProviderUnavailableError };
 /**
  * @class CepLookup
  * @description A class for looking up Brazilian postal codes (CEPs) using multiple providers.
@@ -20,6 +20,10 @@ export declare class CepLookup {
     private logger?;
     private requestTimestamps;
     private emitter;
+    private circuitBreakerEnabled;
+    private circuitFailureThreshold;
+    private circuitCooldownMs;
+    private providerState;
     constructor(options: CepLookupOptions);
     private log;
     on<T extends EventName>(eventName: T, listener: EventListener<T>): void;
@@ -31,6 +35,13 @@ export declare class CepLookup {
      * @returns {Promise<Provider[]>} The list of providers sorted by latency.
      */
     warmup(): Promise<Provider[]>;
+    private getOrCreateProviderState;
+    private recordProviderSuccess;
+    private recordProviderFailure;
+    private isProviderOpen;
+    private scoreProvider;
+    getProviderHealth(): ProviderHealth[];
+    getProviderMetrics(): ProviderMetrics[];
     private checkRateLimit;
     lookup<T = Address>(cep: string, mapper?: (address: Address) => T): Promise<T>;
     private _lookupFromProviders;

package/dist/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CepLookup = exports.AllProvidersFailedError = exports.CepNotFoundError = exports.ProviderTimeoutError = exports.RateLimitError = exports.CepValidationError = exports.InMemoryCache = void 0;
+exports.CepLookup = exports.ProviderUnavailableError = 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");
@@ -9,6 +9,7 @@ Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: functi
 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; } });
+Object.defineProperty(exports, "ProviderUnavailableError", { enumerable: true, get: function () { return errors_1.ProviderUnavailableError; } });
 const ddd_by_state_1 = require("./data/ddd-by-state");
 // Minimal EventEmitter for internal use
 class EventEmitter {
@@ -86,6 +87,7 @@ function enrichAddress(address) {
 class CepLookup {
     constructor(options) {
         this.requestTimestamps = [];
+        this.providerState = new Map();
         this.providers = options.providers;
         this.sortedProviders = [...options.providers];
         this.emitter = new EventEmitter();
@@ -102,6 +104,20 @@ class CepLookup {
         this.retries = options.retries ?? 0;
         this.retryDelay = options.retryDelay ?? 1000;
         this.logger = options.logger;
+        this.circuitBreakerEnabled = options.circuitBreaker?.enabled ?? true;
+        this.circuitFailureThreshold = options.circuitBreaker?.failureThreshold ?? 3;
+        this.circuitCooldownMs = options.circuitBreaker?.cooldownMs ?? 30000;
+        this.providers.forEach((provider) => {
+            this.providerState.set(provider.name, {
+                consecutiveFailures: 0,
+                successCount: 0,
+                failureCount: 0,
+                avgLatencyMs: 0,
+                requests: 0,
+                timeoutErrors: 0,
+                notFoundErrors: 0,
+            });
+        });
     }
     log(msg, data) {
         this.logger?.debug(msg, data);
@@ -144,6 +160,100 @@ class CepLookup {
         controller.abort();
         return this.sortedProviders;
     }
+    getOrCreateProviderState(providerName) {
+        const existing = this.providerState.get(providerName);
+        if (existing)
+            return existing;
+        const created = {
+            consecutiveFailures: 0,
+            successCount: 0,
+            failureCount: 0,
+            avgLatencyMs: 0,
+            requests: 0,
+            timeoutErrors: 0,
+            notFoundErrors: 0,
+        };
+        this.providerState.set(providerName, created);
+        return created;
+    }
+    recordProviderSuccess(providerName, durationMs) {
+        const state = this.getOrCreateProviderState(providerName);
+        state.requests += 1;
+        state.successCount += 1;
+        state.consecutiveFailures = 0;
+        const n = state.successCount + state.failureCount;
+        state.avgLatencyMs = n === 1 ? durationMs : ((state.avgLatencyMs * (n - 1)) + durationMs) / n;
+        state.openUntil = undefined;
+    }
+    recordProviderFailure(providerName, durationMs, error) {
+        const state = this.getOrCreateProviderState(providerName);
+        state.requests += 1;
+        state.failureCount += 1;
+        state.consecutiveFailures += 1;
+        const n = state.successCount + state.failureCount;
+        state.avgLatencyMs = n === 1 ? durationMs : ((state.avgLatencyMs * (n - 1)) + durationMs) / n;
+        if (error instanceof errors_1.ProviderTimeoutError) {
+            state.timeoutErrors += 1;
+        }
+        if (error instanceof errors_1.CepNotFoundError) {
+            state.notFoundErrors += 1;
+        }
+        if (this.circuitBreakerEnabled && state.consecutiveFailures >= this.circuitFailureThreshold) {
+            state.openUntil = Date.now() + this.circuitCooldownMs;
+        }
+    }
+    isProviderOpen(providerName) {
+        if (!this.circuitBreakerEnabled)
+            return false;
+        const state = this.getOrCreateProviderState(providerName);
+        if (!state.openUntil)
+            return false;
+        if (Date.now() >= state.openUntil) {
+            state.openUntil = undefined;
+            state.consecutiveFailures = 0;
+            return false;
+        }
+        return true;
+    }
+    scoreProvider(provider) {
+        const state = this.getOrCreateProviderState(provider.name);
+        const total = state.successCount + state.failureCount;
+        const successRate = total === 0 ? 1 : state.successCount / total;
+        const latencyPenalty = state.avgLatencyMs > 0 ? Math.min(state.avgLatencyMs / 1000, 1) : 0;
+        const openPenalty = this.isProviderOpen(provider.name) ? 1 : 0;
+        return (successRate * 0.8) + ((1 - latencyPenalty) * 0.2) - openPenalty;
+    }
+    getProviderHealth() {
+        return this.providers
+            .map((provider) => {
+            const state = this.getOrCreateProviderState(provider.name);
+            return {
+                provider: provider.name,
+                score: Number(this.scoreProvider(provider).toFixed(4)),
+                isOpen: this.isProviderOpen(provider.name),
+                openUntil: state.openUntil,
+                consecutiveFailures: state.consecutiveFailures,
+                successCount: state.successCount,
+                failureCount: state.failureCount,
+                avgLatencyMs: Number(state.avgLatencyMs.toFixed(2)),
+            };
+        })
+            .sort((a, b) => b.score - a.score);
+    }
+    getProviderMetrics() {
+        return this.providers.map((provider) => {
+            const state = this.getOrCreateProviderState(provider.name);
+            return {
+                provider: provider.name,
+                requests: state.requests,
+                successes: state.successCount,
+                failures: state.failureCount,
+                timeoutErrors: state.timeoutErrors,
+                notFoundErrors: state.notFoundErrors,
+                avgLatencyMs: Number(state.avgLatencyMs.toFixed(2)),
+            };
+        });
+    }
     checkRateLimit() {
         if (!this.rateLimit)
             return;
@@ -190,6 +300,15 @@ class CepLookup {
     async _lookupFromProviders(cleanedCep, mapper) {
         const controller = new AbortController();
         const { signal } = controller;
+        const availableProviders = this.sortedProviders.filter((provider) => !this.isProviderOpen(provider.name));
+        const providersByHealth = [...availableProviders].sort((a, b) => this.scoreProvider(b) - this.scoreProvider(a));
+        const selectedProviders = providersByHealth.length > 0 ? providersByHealth : [...this.sortedProviders].sort((a, b) => this.scoreProvider(b) - this.scoreProvider(a));
+        if (selectedProviders.length === 0) {
+            throw new errors_1.AllProvidersFailedError([new errors_1.ProviderUnavailableError("all")]);
+        }
+        if (availableProviders.length === 0 && this.circuitBreakerEnabled) {
+            throw new errors_1.AllProvidersFailedError(selectedProviders.map((p) => new errors_1.ProviderUnavailableError(p.name)));
+        }
         const createProviderPromise = (provider) => {
             const startTime = Date.now();
             const url = provider.buildUrl(cleanedCep);
@@ -201,6 +320,7 @@ class CepLookup {
                     signal.removeEventListener('abort', onAbort);
                     const duration = Date.now() - startTime;
                     const error = new errors_1.ProviderTimeoutError(provider.name, provider.timeout);
+                    this.recordProviderFailure(provider.name, duration, error);
                     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);
@@ -213,6 +333,7 @@ class CepLookup {
                 .then((address) => {
                 const duration = Date.now() - startTime;
                 const sanitizedAddress = enrichAddress(sanitizeAddress(address));
+                this.recordProviderSuccess(provider.name, duration);
                 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) {
@@ -222,16 +343,18 @@ class CepLookup {
             })
                 .catch((error) => {
                 const duration = Date.now() - startTime;
-                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 });
+                const normalizedError = (0, errors_1.normalizeProviderError)(error, cleanedCep, provider.name);
+                if (normalizedError.name !== 'AbortError' && !(normalizedError instanceof errors_1.ProviderTimeoutError)) {
+                    this.recordProviderFailure(provider.name, duration, normalizedError);
+                    this.log('provider:failure', { provider: provider.name, cep: cleanedCep, error: normalizedError.message });
+                    this.emitter.emit('failure', { provider: provider.name, cep: cleanedCep, duration, error: normalizedError });
                 }
-                throw error;
+                throw normalizedError;
             });
             return Promise.race([fetchPromise, timeoutPromise]);
         };
-        const bestProvider = this.sortedProviders[0];
-        const otherProviders = this.sortedProviders.slice(1);
+        const bestProvider = selectedProviders[0];
+        const otherProviders = selectedProviders.slice(1);
         if (otherProviders.length === 0) {
             try {
                 return await createProviderPromise(bestProvider);

package/dist/src/types.d.ts

@@ -54,6 +54,8 @@ export interface CepLookupOptions {
     logger?: {
         debug: (msg: string, data?: Record<string, unknown>) => void;
     };
+    /** Circuit breaker options for provider resilience */
+    circuitBreaker?: CircuitBreakerOptions;
 }
 /**
  * @interface BulkCepResult
@@ -87,3 +89,30 @@ export interface EventMap {
     'cache:hit': CacheHitPayload;
 }
 export type EventListener<T extends EventName> = (payload: EventMap[T]) => void;
+export interface CircuitBreakerOptions {
+    /** Consecutive failures required to open the circuit. Default: 3 */
+    failureThreshold?: number;
+    /** Cooldown in ms before trying a provider again. Default: 30000 */
+    cooldownMs?: number;
+    /** Enable/disable circuit breaker. Default: true */
+    enabled?: boolean;
+}
+export interface ProviderHealth {
+    provider: string;
+    score: number;
+    isOpen: boolean;
+    openUntil?: number;
+    consecutiveFailures: number;
+    successCount: number;
+    failureCount: number;
+    avgLatencyMs: number;
+}
+export interface ProviderMetrics {
+    provider: string;
+    requests: number;
+    successes: number;
+    failures: number;
+    timeoutErrors: number;
+    notFoundErrors: number;
+    avgLatencyMs: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eusilvio/cep-lookup",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "A agnostic, performant and flexible CEP lookup library with race strategy and caching.",
   "license": "MIT",
   "author": "Silvio Souza",