@eusilvio/cep-lookup 2.4.0 → 2.6.0

package/dist/src/cache/index.js

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

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

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

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

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

package/dist/src/errors.d.ts

@@ -0,0 +1,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

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+    }
+}
+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;
+    }
+}
+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;
+    }
+}
+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;
+    }
+}
+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,7 +1,9 @@
-import { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult, RateLimitOptions, EventName, EventListener, EventMap } from "./types";
-import { Cache, InMemoryCache } from "./cache";
-export type { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult, RateLimitOptions, EventName, EventListener, EventMap, Cache };
+import { 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, 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, ProviderUnavailableError };
 /**
  * @class CepLookup
  * @description A class for looking up Brazilian postal codes (CEPs) using multiple providers.
@@ -13,32 +15,35 @@ export declare class CepLookup {
     private cache?;
     private rateLimit?;
     private staggerDelay;
+    private retries;
+    private retryDelay;
+    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;
     off<T extends EventName>(eventName: T, listener: EventListener<T>): void;
     /**
      * @method warmup
      * @description Pings providers to determine the fastest one and updates the internal priority order.
      * Useful to call on UI events like 'focus' on the CEP input.
+     * @returns {Promise<Provider[]>} The list of providers sorted by latency.
      */
-    warmup(): Promise<void>;
+    warmup(): Promise<Provider[]>;
+    private 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>;
-    lookupCeps(ceps: string[], concurrency?: number): Promise<BulkCepResult[]>;
+    private _lookupFromProviders;
+    lookupCeps<T = Address>(ceps: string[], concurrency?: number, mapper?: (address: Address) => T): Promise<BulkCepResult<T>[]>;
 }
-/**
- * @deprecated Use `new CepLookup(options).lookup(cep)` instead.
- */
-export declare function lookupCep<T = Address>(options: CepLookupOptions & {
-    cep: string;
-    mapper?: (address: Address) => T;
-}): Promise<T>;
-/**
- * @deprecated Use `new CepLookup(options).lookupCeps(ceps)` instead.
- */
-export declare function lookupCeps(options: CepLookupOptions & {
-    ceps: string[];
-    concurrency?: number;
-}): Promise<BulkCepResult[]>;

package/dist/src/index.js

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

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

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

package/dist/src/providers/index.js

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

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

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