@eusilvio/cep-lookup 1.1.0 → 1.2.0

package/README.md

@@ -21,6 +21,7 @@ Its agnostic design allows it to be used in any JavaScript environment with any
 - **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.
 
 ## Installation
 
@@ -30,6 +31,8 @@ npm install @eusilvio/cep-lookup
 
 ## How to Use
 
+`@eusilvio/cep-lookup` is designed to be straightforward. You can create a reusable instance of the `CepLookup` class with your desired settings or use the `lookupCep` function for a quick, one-off lookup. The library also includes a simple in-memory cache to avoid repeated requests, which you can use or replace with your own implementation.
+
 ### Example 1: Basic Usage
 
 ```typescript
@@ -105,6 +108,7 @@ 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.
 
 ### `cepLookup.lookup<T = Address>(cep, mapper?): Promise<T>`
 
@@ -123,14 +127,7 @@ You can find more detailed examples in the `examples/` directory:
 - **React Component**: `examples/react-example.tsx`
 - **React Hook**: `examples/react-hook-example.ts`
 - **Angular Component/Service**: `examples/angular-example.ts`
-
-To run the examples, use the following commands:
-
-```bash
-npm run example
-npm run custom-example
-npm run node-example
-```
+- **Cache Usage**: `examples/cache-example.ts`
 
 ## Creating a Custom Provider
 

package/dist/cache/index.d.ts

@@ -0,0 +1,36 @@
+import { Address } from '../types';
+/**
+ * @interface Cache
+ * @description Defines the contract for a cache implementation.
+ */
+export interface Cache {
+    get(key: string): Address | undefined;
+    set(key: string, value: Address): void;
+    clear(): void;
+}
+/**
+ * @class InMemoryCache
+ * @description A simple in-memory cache implementation for storing CEP lookups.
+ */
+export declare class InMemoryCache implements Cache {
+    private cache;
+    /**
+     * @method get
+     * @description Retrieves an address from the cache.
+     * @param {string} key - The CEP to look up.
+     * @returns {Address | undefined} The cached address or undefined if not found.
+     */
+    get(key: string): Address | undefined;
+    /**
+     * @method set
+     * @description Stores an address in the cache.
+     * @param {string} key - The CEP to use as the cache key.
+     * @param {Address} value - The address to store.
+     */
+    set(key: string, value: Address): void;
+    /**
+     * @method clear
+     * @description Clears the entire cache.
+     */
+    clear(): void;
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Address, Fetcher, Provider, CepLookupOptions } from "./types";
-export { Address, Fetcher, Provider, CepLookupOptions };
+import { Cache, InMemoryCache } from "./cache";
+export { Address, Fetcher, Provider, CepLookupOptions, Cache, InMemoryCache };
 /**
  * @class CepLookup
  * @description A class for looking up Brazilian postal codes (CEPs) using multiple providers.
@@ -8,6 +9,7 @@ export { Address, Fetcher, Provider, CepLookupOptions };
 export declare class CepLookup {
     private providers;
     private fetcher;
+    private cache?;
     /**
      * @constructor
      * @param {CepLookupOptions} options - The options for initializing the CepLookup instance.
@@ -32,6 +34,7 @@ export declare class CepLookup {
  * @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.

package/dist/index.js

@@ -1 +1 @@
-"use strict";var c=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var u=Object.getOwnPropertyNames;var h=Object.prototype.hasOwnProperty;var l=(e,r)=>{for(var s in r)c(e,s,{get:r[s],enumerable:!0})},f=(e,r,s,t)=>{if(r&&typeof r=="object"||typeof r=="function")for(let o of u(r))!h.call(e,o)&&o!==s&&c(e,o,{get:()=>r[o],enumerable:!(t=a(r,o))||t.enumerable});return e};var v=e=>f(c({},"__esModule",{value:!0}),e);var T={};l(T,{CepLookup:()=>p,lookupCep:()=>k});module.exports=v(T);function m(e){let r=e.replace(/\D/g,"");if(r.length!==8)throw new Error("Invalid CEP. It must have 8 digits.");return r}var p=class{constructor(r){this.providers=r.providers,this.fetcher=r.fetcher||(async s=>{let t=await fetch(s);if(!t.ok)throw new Error(`HTTP error! status: ${t.status}`);return t.json()})}async lookup(r,s){let t=m(r),o=this.providers.map(i=>{let d=i.buildUrl(t);return this.fetcher(d).then(n=>i.transform(n)).then(n=>s?s(n):n)});return Promise.any(o)}};function k(e){let{cep:r,providers:s,fetcher:t,mapper:o}=e;return new p({providers:s,fetcher:t}).lookup(r,o)}0&&(module.exports={CepLookup,lookupCep});
+import{Address as f,Fetcher as v,Provider as T,CepLookupOptions as w}from"./types";import{Cache as C,InMemoryCache as k}from"./cache";function P(i){const e=i.replace(/\D/g,"");if(e.length!==8)throw new Error("Invalid CEP. It must have 8 digits.");return e}class g{constructor(e){this.providers=e.providers,this.fetcher=e.fetcher||(async(r,s)=>{const o=await fetch(r,{signal:s});if(!o.ok)throw new Error(`HTTP error! status: ${o.status}`);return o.json()}),this.cache=e.cache}async lookup(e,r){const s=P(e);if(this.cache){const t=this.cache.get(s);if(t)return Promise.resolve(r?r(t):t)}const o=new AbortController,{signal:n}=o,h=this.providers.map(t=>{const d=t.buildUrl(s),m=new Promise((c,u)=>{let p;const a=()=>{clearTimeout(p),u(new DOMException("Aborted","AbortError"))};t.timeout?(p=setTimeout(()=>{n.removeEventListener("abort",a),u(new Error(`Timeout from ${t.name}`))},t.timeout),n.addEventListener("abort",a,{once:!0})):n.addEventListener("abort",a,{once:!0})}),l=this.fetcher(d,n).then(c=>t.transform(c)).then(c=>(this.cache&&this.cache.set(s,c),r?r(c):c));return Promise.race([l,m])});try{return await Promise.any(h)}finally{o.abort()}}}function E(i){const{cep:e,providers:r,fetcher:s,mapper:o,cache:n}=i;return new g({providers:r,fetcher:s,cache:n}).lookup(e,o)}export{f as Address,C as Cache,g as CepLookup,w as CepLookupOptions,v as Fetcher,k as InMemoryCache,T as Provider,E as lookupCep};

package/dist/providers/index.js

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

package/dist/types.d.ts

@@ -25,21 +25,24 @@ export interface Address {
  */
 export interface Provider {
     name: string;
+    timeout?: number;
     buildUrl: (cep: string) => string;
     transform: (response: any) => Address;
 }
 /**
- * @typedef {function(url: string): Promise<any>}
+ * @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.
  */
-export type Fetcher = (url: string) => Promise<any>;
+export type Fetcher = (url: string, signal?: AbortSignal) => Promise<any>;
 /**
  * @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;
 }

package/package.json

@@ -1,27 +1,34 @@
 {
   "name": "@eusilvio/cep-lookup",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A modern, flexible, and agnostic CEP lookup library written in TypeScript.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./providers": {
+      "import": "./dist/providers/index.js",
+      "types": "./dist/providers/index.d.ts"
+    }
+  },
+  "sideEffects": false,
   "files": [
     "dist"
   ],
   "publishConfig": {
     "access": "public"
   },
-  "exports": {
-    ".": "./dist/index.js",
-    "./providers": "./dist/providers/index.js"
-  },
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "npm run clean && tsc --emitDeclarationOnly --outDir dist && esbuild src/index.ts src/providers/index.ts --outdir=dist --bundle --platform=node --format=cjs",
-    "build:prod": "npm run clean && tsc --emitDeclarationOnly --outDir dist && esbuild src/index.ts src/providers/index.ts --outdir=dist --bundle --platform=node --format=cjs --minify",
+    "type:check": "tsc --noEmit",
+    "build": "npm run clean && npm run type:check && npm run build:types && npm run build:js",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist --rootDir src",
+    "build:js": "esbuild src/index.ts src/providers/index.ts --outdir=dist --outbase=src --format=esm --platform=neutral --target=esnext --minify",
     "test": "jest",
-    "example": "ts-node -r tsconfig-paths/register examples/example.ts",
-    "custom-example": "ts-node -r tsconfig-paths/register examples/custom-provider-example.ts",
-    "node-example": "ts-node -r tsconfig-paths/register examples/node-example.ts"
+    "cache-example": "ts-node -r tsconfig-paths/register examples/cache-example.ts"
   },
   "keywords": [
     "cep",
@@ -44,6 +51,7 @@
     "@types/jest": "^30.0.0",
     "esbuild": "^0.20.2",
     "jest": "^30.1.3",
+    "p-limit": "^2.3.0",
     "ts-jest": "^29.4.4",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",