@eusilvio/cep-lookup 2.0.0 → 2.0.1

package/README.md

@@ -149,6 +149,7 @@ Creates a new `CepLookup` instance.
   - `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).
 
 ### `cepLookup.lookup<T = Address>(cep, mapper?): Promise<T>`
 
@@ -168,6 +169,35 @@ Looks up multiple CEPs in bulk. Returns a `Promise` that resolves to an array of
   - `fetcher` (Fetcher, _optional_): A custom fetch function.
   - `cache` (Cache, _optional_): A cache instance.
 
+### 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");
+```
+
 ## Examples
 
 You can find more detailed examples in the `examples/` directory:

package/dist/index.d.ts

@@ -1,10 +1,9 @@
-import { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult, RateLimitOptions } from "./types";
+import { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult, RateLimitOptions, EventName, EventListener, EventMap } from "./types";
 import { Cache, InMemoryCache } from "./cache";
-export { Address, Fetcher, Provider, CepLookupOptions, Cache, InMemoryCache, BulkCepResult, RateLimitOptions };
+export { Address, Fetcher, Provider, CepLookupOptions, Cache, InMemoryCache, BulkCepResult, RateLimitOptions, EventName, EventListener, EventMap };
 /**
  * @class CepLookup
  * @description A class for looking up Brazilian postal codes (CEPs) using multiple providers.
- * It queries multiple services simultaneously and returns the response from the fastest one.
  */
 export declare class CepLookup {
     private providers;
@@ -12,46 +11,17 @@ export declare class CepLookup {
     private cache?;
     private rateLimit?;
     private requestTimestamps;
-    /**
-     * @constructor
-     * @param {CepLookupOptions} options - The options for initializing the CepLookup instance.
-     */
+    private emitter;
     constructor(options: CepLookupOptions);
+    on<T extends EventName>(eventName: T, listener: EventListener<T>): void;
+    off<T extends EventName>(eventName: T, listener: EventListener<T>): void;
     private checkRateLimit;
-    /**
-     * @method lookup
-     * @description Looks up an address for a given CEP.
-     * @template T - The expected return type, defaults to `Address`.
-     * @param {string} cep - The CEP to be queried.
-     * @param {(address: Address) => T} [mapper] - An optional function to transform the `Address` object into a custom format `T`.
-     * @returns {Promise<T>} A Promise that resolves to the address in the default `Address` format or a custom format `T` if a mapper is provided.
-     * @throws {Error} If the CEP is invalid or if all providers fail to find the CEP.
-     */
     lookup<T = Address>(cep: string, mapper?: (address: Address) => T): Promise<T>;
 }
-/**
- * @function lookupCep
- * @description Backward-compatible function for looking up a CEP. Internally creates a `CepLookup` instance.
- * @template T - The expected return type, defaults to `Address`.
- * @param {object} options - Options for the lookup.
- * @param {string} options.cep - The CEP to be queried.
- * @param {Provider[]} options.providers - An array of `Provider` instances.
- * @param {Fetcher} [options.fetcher] - The `Fetcher` function. Defaults to global `fetch` if not provided.
- * @param {Cache} [options.cache] - The `Cache` instance.
- * @param {(address: Address) => T} [options.mapper] - An optional function to transform the `Address` object.
- * @returns {Promise<T>} A Promise that resolves to the address.
- * @throws {Error} If the CEP is invalid or if all providers fail.
- */
 export declare function lookupCep<T = Address>(options: CepLookupOptions & {
     cep: string;
     mapper?: (address: Address) => T;
 }): Promise<T>;
-/**
- * @function lookupCeps
- * @description Looks up multiple CEPs in bulk with controlled concurrency.
- * @param {CepLookupOptions & { ceps: string[], concurrency?: number }} options - Options for the bulk lookup.
- * @returns {Promise<BulkCepResult[]>} A Promise that resolves to an array of results for each CEP.
- */
 export declare function lookupCeps(options: CepLookupOptions & {
     ceps: string[];
     concurrency?: number;

package/dist/index.js

@@ -1 +1 @@
-"use strict";var g=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var k=Object.getOwnPropertyNames;var A=Object.prototype.hasOwnProperty;var L=(r,e)=>{for(var t in e)g(r,t,{get:e[t],enumerable:!0})},y=(r,e,t,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let s of k(e))!A.call(r,s)&&s!==t&&g(r,s,{get:()=>e[s],enumerable:!(i=v(e,s))||i.enumerable});return r};var T=r=>y(g({},"__esModule",{value:!0}),r);var x={};L(x,{CepLookup:()=>h,InMemoryCache:()=>m,lookupCep:()=>P,lookupCeps:()=>b});module.exports=T(x);var m=class{constructor(){this.cache=new Map}get(e){return this.cache.get(e)}set(e,t){this.cache.set(e,t)}clear(){this.cache.clear()}};function N(r){if(!/^(\d{8}|\d{5}-\d{3})$/.test(r))throw new Error("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN.");return r.replace("-","")}function C(r){let e={...r};for(let t in e)typeof e[t]=="string"&&(e[t]=e[t].trim());return e}var h=class{constructor(e){this.requestTimestamps=[];this.providers=e.providers,this.fetcher=e.fetcher||(async(t,i)=>{let s=await fetch(t,{signal:i});if(!s.ok)throw new Error(`HTTP error! status: ${s.status}`);return s.json()}),this.cache=e.cache,this.rateLimit=e.rateLimit}checkRateLimit(){if(!this.rateLimit)return;let e=Date.now(),t=e-this.rateLimit.per;if(this.requestTimestamps=this.requestTimestamps.filter(i=>i>t),this.requestTimestamps.length>=this.rateLimit.requests)throw new Error(`Rate limit exceeded: ${this.rateLimit.requests} requests per ${this.rateLimit.per}ms.`);this.requestTimestamps.push(e)}async lookup(e,t){this.checkRateLimit();let i=N(e);if(this.cache){let o=this.cache.get(i);if(o)return Promise.resolve(t?t(o):o)}let s=new AbortController,{signal:a}=s,u=this.providers.map(o=>{let p=o.buildUrl(i),l=new Promise((c,n)=>{let d,w=()=>{clearTimeout(d),n(new DOMException("Aborted","AbortError"))};o.timeout?(d=setTimeout(()=>{a.removeEventListener("abort",w),n(new Error(`Timeout from ${o.name}`))},o.timeout),a.addEventListener("abort",w,{once:!0})):a.addEventListener("abort",w,{once:!0})}),f=this.fetcher(p,a).then(c=>o.transform(c)).then(c=>{let n=C(c);return this.cache&&this.cache.set(i,n),t?t(n):n});return Promise.race([f,l])});try{return await Promise.any(u)}finally{s.abort()}}};function P(r){let{cep:e,providers:t,fetcher:i,mapper:s,cache:a}=r;return new h({providers:t,fetcher:i,cache:a}).lookup(e,s)}async function b(r){let{ceps:e,providers:t,fetcher:i,cache:s,concurrency:a=5}=r;if(!e||e.length===0)return[];let u=new h({providers:t,fetcher:i,cache:s}),o=new Array(e.length),p=0,l=async()=>{for(;p<e.length;){let c=p++;if(c>=e.length)break;let n=e[c];try{let d=await u.lookup(n);if(d)o[c]={cep:n,data:d,provider:d.service};else throw new Error("No address found")}catch(d){o[c]={cep:n,data:null,error:d}}}},f=Array.from({length:Math.min(a,e.length)},()=>l());return await Promise.all(f),o.filter(Boolean)}0&&(module.exports={CepLookup,InMemoryCache,lookupCep,lookupCeps});
+"use strict";var w=Object.defineProperty;var E=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var y=Object.prototype.hasOwnProperty;var N=(r,e)=>{for(var t in e)w(r,t,{get:e[t],enumerable:!0})},x=(r,e,t,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of A(e))!y.call(r,i)&&i!==t&&w(r,i,{get:()=>e[i],enumerable:!(s=E(e,i))||s.enumerable});return r};var C=r=>x(w({},"__esModule",{value:!0}),r);var O={};N(O,{CepLookup:()=>m,InMemoryCache:()=>l,lookupCep:()=>R,lookupCeps:()=>q});module.exports=C(O);var l=class{constructor(){this.cache=new Map}get(e){return this.cache.get(e)}set(e,t){this.cache.set(e,t)}clear(){this.cache.clear()}};var T=class{constructor(){this.listeners={}}on(e,t){this.listeners[e]||(this.listeners[e]=[]),this.listeners[e].push(t)}off(e,t){this.listeners[e]&&(this.listeners[e]=this.listeners[e].filter(s=>s!==t))}emit(e,t){this.listeners[e]&&this.listeners[e].forEach(s=>s(t))}};function b(r){if(!/^(\d{8}|\d{5}-\d{3})$/.test(r))throw new Error("Invalid CEP format. Use either NNNNNNNN or NNNNN-NNN.");return r.replace("-","")}function P(r){let e={...r};for(let t in e)typeof e[t]=="string"&&(e[t]=e[t].trim());return e}var m=class{constructor(e){this.requestTimestamps=[];this.providers=e.providers,this.emitter=new T,this.fetcher=e.fetcher||(async(t,s)=>{let i=await fetch(t,{signal:s});if(!i.ok)throw new Error(`HTTP error! status: ${i.status}`);return i.json()}),this.cache=e.cache,this.rateLimit=e.rateLimit}on(e,t){this.emitter.on(e,t)}off(e,t){this.emitter.off(e,t)}checkRateLimit(){if(!this.rateLimit)return;let e=Date.now(),t=e-this.rateLimit.per;if(this.requestTimestamps=this.requestTimestamps.filter(s=>s>t),this.requestTimestamps.length>=this.rateLimit.requests)throw new Error(`Rate limit exceeded: ${this.rateLimit.requests} requests per ${this.rateLimit.per}ms.`);this.requestTimestamps.push(e)}async lookup(e,t){this.checkRateLimit();let s=b(e);if(this.cache){let n=this.cache.get(s);if(n)return this.emitter.emit("cache:hit",{cep:s}),Promise.resolve(t?t(n):n)}let i=new AbortController,{signal:d}=i,h=this.providers.map(n=>{let u=Date.now(),p=n.buildUrl(s),f=new Promise((o,c)=>{if(!n.timeout)return;let a=setTimeout(()=>{d.removeEventListener("abort",g);let k=Date.now()-u,L=new Error(`Timeout from ${n.name}`);this.emitter.emit("failure",{provider:n.name,cep:s,duration:k,error:L}),c(L)},n.timeout),g=()=>clearTimeout(a);d.addEventListener("abort",g,{once:!0})}),v=this.fetcher(p,d).then(o=>n.transform(o)).then(o=>{let c=Date.now()-u,a=P(o);return this.emitter.emit("success",{provider:n.name,cep:s,duration:c,address:a}),this.cache&&this.cache.set(s,a),t?t(a):a}).catch(o=>{let c=Date.now()-u;throw o.message.includes("Timeout from")||this.emitter.emit("failure",{provider:n.name,cep:s,duration:c,error:o}),o});return Promise.race([v,f])});try{return h.length===1?await h[0]:await Promise.any(h)}finally{i.abort()}}};function R(r){let{cep:e,providers:t,fetcher:s,mapper:i,cache:d,rateLimit:h}=r;return new m({providers:t,fetcher:s,cache:d,rateLimit:h}).lookup(e,i)}async function q(r){let{ceps:e,providers:t,fetcher:s,cache:i,concurrency:d=5,rateLimit:h}=r;if(!e||e.length===0)return[];let n=new m({providers:t,fetcher:s,cache:i,rateLimit:h}),u=new Array(e.length),p=0,f=async()=>{for(;p<e.length;){let o=p++;if(o>=e.length)break;let c=e[o];try{let a=await n.lookup(c);if(a)u[o]={cep:c,data:a,provider:a.service};else throw new Error("No address found")}catch(a){u[o]={cep:c,data:null,error:a}}}},v=Array.from({length:Math.min(d,e.length)},()=>f());return await Promise.all(v),u.filter(Boolean)}0&&(module.exports={CepLookup,InMemoryCache,lookupCep,lookupCeps});

package/dist/types.d.ts

@@ -1,12 +1,7 @@
+import { Cache } from "./cache";
 /**
  * @interface Address
  * @description Represents a standardized address object returned by the CEP lookup.
- * @property {string} cep - The postal code.
- * @property {string} state - The state abbreviation (e.g., 'SP', 'RJ').
- * @property {string} city - The city name.
- * @property {string} neighborhood - The neighborhood name.
- * @property {string} street - The street name.
- * @property {string} service - The name of the service that provided the address (e.g., 'ViaCEP', 'BrasilAPI').
  */
 export interface Address {
     cep: string;
@@ -19,9 +14,6 @@ export interface Address {
 /**
  * @interface Provider
  * @description Defines the contract for a CEP lookup provider.
- * @property {string} name - The name of the provider.
- * @property {(cep: string) => string} buildUrl - A function that constructs the API URL for a given CEP.
- * @property {(response: any) => Address} transform - A function that transforms the raw API response into a standardized `Address` object.
  */
 export interface Provider {
     name: string;
@@ -31,39 +23,30 @@ export interface Provider {
 }
 /**
  * @typedef {function(url: string, signal?: AbortSignal): Promise<any>}
- * @description A function that fetches data from a given URL and returns a Promise resolving to the response data.
+ * @description A function that fetches data from a given URL.
  */
 export type Fetcher = (url: string, signal?: AbortSignal) => Promise<any>;
+/**
+ * @interface RateLimitOptions
+ * @description Options for configuring the internal rate limiter.
+ */
+export interface RateLimitOptions {
+    requests: number;
+    per: number;
+}
 /**
  * @interface CepLookupOptions
  * @description Options for initializing the `CepLookup` class.
- * @property {Provider[]} providers - An array of `Provider` instances to be used for CEP lookup.
- * @property {Fetcher} [fetcher] - The `Fetcher` function to be used for making HTTP requests. Defaults to global `fetch` if not provided.
  */
-import { Cache } from "./cache";
 export interface CepLookupOptions {
     providers: Provider[];
     fetcher?: Fetcher;
     cache?: Cache;
     rateLimit?: RateLimitOptions;
 }
-/**
- * @interface RateLimitOptions
- * @description Options for configuring the internal rate limiter.
- * @property {number} requests - The maximum number of requests allowed within the time window.
- * @property {number} per - The time window in milliseconds.
- */
-export interface RateLimitOptions {
-    requests: number;
-    per: number;
-}
 /**
  * @interface BulkCepResult
  * @description Represents the result for a single CEP in a bulk lookup operation.
- * @property {string} cep - The original CEP string.
- * @property {Address | null} data - The address data if the lookup was successful, otherwise null.
- * @property {string} [provider] - The name of the provider that successfully resolved the address.
- * @property {Error} [error] - An error object if the lookup failed for this specific CEP.
  */
 export interface BulkCepResult {
     cep: string;
@@ -71,3 +54,25 @@ export interface BulkCepResult {
     provider?: string;
     error?: Error;
 }
+export type EventName = 'success' | 'failure' | 'cache:hit';
+export interface SuccessPayload {
+    provider: string;
+    cep: string;
+    duration: number;
+    address: Address;
+}
+export interface FailurePayload {
+    provider: string;
+    cep: string;
+    duration: number;
+    error: Error;
+}
+export interface CacheHitPayload {
+    cep: string;
+}
+export interface EventMap {
+    success: SuccessPayload;
+    failure: FailurePayload;
+    'cache:hit': CacheHitPayload;
+}
+export type EventListener<T extends EventName> = (payload: EventMap[T]) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eusilvio/cep-lookup",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "A modern, flexible, and agnostic CEP lookup library written in TypeScript.",
   "license": "MIT",
   "repository": {