@eusilvio/cep-lookup 1.2.3 → 1.3.0

package/README.md

@@ -99,6 +99,46 @@ cepLookup.lookup("01001-000", myMapper).then((customAddress: CustomAddress) => {
 });
 ```
 
+### Example 3: Bulk CEP Lookup
+
+For scenarios where you need to query multiple CEPs at once, you can use the `lookupCeps` function. It processes the CEPs in parallel with a configurable concurrency limit to avoid overwhelming the providers.
+
+```typescript
+import { lookupCeps, BulkCepResult } from "@eusilvio/cep-lookup";
+import {
+  viaCepProvider,
+  brasilApiProvider,
+} from "@eusilvio/cep-lookup/providers";
+
+const cepsToLookup = ["01001-000", "99999-999", "04538-132"];
+
+lookupCeps({
+  ceps: cepsToLookup,
+  providers: [viaCepProvider, brasilApiProvider],
+  concurrency: 5, // Optional: Number of parallel requests
+}).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'
+  //   }
+  // ]
+});
+```
+
 ## API
 
 ### `new CepLookup(options)`
@@ -117,6 +157,17 @@ Returns a `Promise` that resolves to the address in the default format (`Address
 - `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`.
 
+### `lookupCeps(options): Promise<BulkCepResult[]>`
+
+Looks up multiple CEPs in bulk. Returns a `Promise` that resolves to an array of `BulkCepResult` objects, one for each queried CEP.
+
+- `options`: A configuration object extending the `CepLookup` options.
+  - `ceps` (string[], **required**): An array of CEP strings to be queried.
+  - `providers` (Provider[], **required**): An array of providers.
+  - `concurrency` (number, _optional_): The number of parallel requests to make. Defaults to `5`.
+  - `fetcher` (Fetcher, _optional_): A custom fetch function.
+  - `cache` (Cache, _optional_): A cache instance.
+
 ## Examples
 
 You can find more detailed examples in the `examples/` directory:

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { Address, Fetcher, Provider, CepLookupOptions } from "./types";
+import { Address, Fetcher, Provider, CepLookupOptions, BulkCepResult } from "./types";
 import { Cache, InMemoryCache } from "./cache";
-export { Address, Fetcher, Provider, CepLookupOptions, Cache, InMemoryCache };
+export { Address, Fetcher, Provider, CepLookupOptions, Cache, InMemoryCache, BulkCepResult };
 /**
  * @class CepLookup
  * @description A class for looking up Brazilian postal codes (CEPs) using multiple providers.
@@ -43,3 +43,13 @@ 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;
+}): Promise<BulkCepResult[]>;

package/dist/index.js

@@ -1 +1 @@
-"use strict";var u=Object.defineProperty;var A=Object.getOwnPropertyDescriptor;var w=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var k=(s,e)=>{for(var t in e)u(s,t,{get:e[t],enumerable:!0})},C=(s,e,t,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of w(e))!T.call(s,r)&&r!==t&&u(s,r,{get:()=>e[r],enumerable:!(o=A(e,r))||o.enumerable});return s};var P=s=>C(u({},"__esModule",{value:!0}),s);var y={};k(y,{CepLookup:()=>d,InMemoryCache:()=>a,lookupCep:()=>E});module.exports=P(y);var a=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 b(s){let e=s.replace(/\D/g,"");if(e.length!==8)throw new Error("Invalid CEP. It must have 8 digits.");return e}var d=class{constructor(e){this.providers=e.providers,this.fetcher=e.fetcher||(async(t,o)=>{let r=await fetch(t,{signal:o});if(!r.ok)throw new Error(`HTTP error! status: ${r.status}`);return r.json()}),this.cache=e.cache}async lookup(e,t){let o=b(e);if(this.cache){let n=this.cache.get(o);if(n)return Promise.resolve(t?t(n):n)}let r=new AbortController,{signal:i}=r,p=this.providers.map(n=>{let f=n.buildUrl(o),v=new Promise((c,l)=>{let m,h=()=>{clearTimeout(m),l(new DOMException("Aborted","AbortError"))};n.timeout?(m=setTimeout(()=>{i.removeEventListener("abort",h),l(new Error(`Timeout from ${n.name}`))},n.timeout),i.addEventListener("abort",h,{once:!0})):i.addEventListener("abort",h,{once:!0})}),g=this.fetcher(f,i).then(c=>n.transform(c)).then(c=>(this.cache&&this.cache.set(o,c),t?t(c):c));return Promise.race([g,v])});try{return await Promise.any(p)}finally{r.abort()}}};function E(s){let{cep:e,providers:t,fetcher:o,mapper:r,cache:i}=s;return new d({providers:t,fetcher:o,cache:i}).lookup(e,r)}0&&(module.exports={CepLookup,InMemoryCache,lookupCep});
+"use strict";var v=Object.defineProperty;var w=Object.getOwnPropertyDescriptor;var k=Object.getOwnPropertyNames;var A=Object.prototype.hasOwnProperty;var C=(s,e)=>{for(var r in e)v(s,r,{get:e[r],enumerable:!0})},y=(s,e,r,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of k(e))!A.call(s,t)&&t!==r&&v(s,t,{get:()=>e[t],enumerable:!(n=w(e,t))||n.enumerable});return s};var P=s=>y(v({},"__esModule",{value:!0}),s);var x={};C(x,{CepLookup:()=>u,InMemoryCache:()=>p,lookupCep:()=>b,lookupCeps:()=>E});module.exports=P(x);var p=class{constructor(){this.cache=new Map}get(e){return this.cache.get(e)}set(e,r){this.cache.set(e,r)}clear(){this.cache.clear()}};function T(s){let e=s.replace(/\D/g,"");if(e.length!==8)throw new Error("Invalid CEP. It must have 8 digits.");return e}var u=class{constructor(e){this.providers=e.providers,this.fetcher=e.fetcher||(async(r,n)=>{let t=await fetch(r,{signal:n});if(!t.ok)throw new Error(`HTTP error! status: ${t.status}`);return t.json()}),this.cache=e.cache}async lookup(e,r){let n=T(e);if(this.cache){let o=this.cache.get(n);if(o)return Promise.resolve(r?r(o):o)}let t=new AbortController,{signal:i}=t,h=this.providers.map(o=>{let l=o.buildUrl(n),m=new Promise((c,d)=>{let a,g=()=>{clearTimeout(a),d(new DOMException("Aborted","AbortError"))};o.timeout?(a=setTimeout(()=>{i.removeEventListener("abort",g),d(new Error(`Timeout from ${o.name}`))},o.timeout),i.addEventListener("abort",g,{once:!0})):i.addEventListener("abort",g,{once:!0})}),f=this.fetcher(l,i).then(c=>o.transform(c)).then(c=>(this.cache&&this.cache.set(n,c),r?r(c):c));return Promise.race([f,m])});try{return await Promise.any(h)}finally{t.abort()}}};function b(s){let{cep:e,providers:r,fetcher:n,mapper:t,cache:i}=s;return new u({providers:r,fetcher:n,cache:i}).lookup(e,t)}async function E(s){let{ceps:e,providers:r,fetcher:n,cache:t,concurrency:i=5}=s;if(!e||e.length===0)return[];let h=new u({providers:r,fetcher:n,cache:t}),o=new Array(e.length),l=0,m=async()=>{for(;l<e.length;){let c=l++;if(c>=e.length)break;let d=e[c];try{let a=await h.lookup(d);if(a)o[c]={cep:d,data:a,provider:a.service};else throw new Error("No address found")}catch(a){o[c]={cep:d,data:null,error:a}}}},f=Array.from({length:Math.min(i,e.length)},()=>m());return await Promise.all(f),o.filter(Boolean)}0&&(module.exports={CepLookup,InMemoryCache,lookupCep,lookupCeps});

package/dist/meta.json

@@ -0,0 +1,132 @@
+{
+  "inputs": {
+    "src/types.ts": {
+      "bytes": 2529,
+      "imports": [
+        {
+          "path": "./cache",
+          "kind": "import-statement",
+          "external": true
+        }
+      ],
+      "format": "esm"
+    },
+    "src/cache/index.ts": {
+      "bytes": 1150,
+      "imports": [
+        {
+          "path": "../types",
+          "kind": "import-statement",
+          "external": true
+        }
+      ],
+      "format": "esm"
+    },
+    "src/index.ts": {
+      "bytes": 6549,
+      "imports": [
+        {
+          "path": "src/types.ts",
+          "kind": "import-statement",
+          "original": "./types"
+        },
+        {
+          "path": "src/cache/index.ts",
+          "kind": "import-statement",
+          "original": "./cache"
+        }
+      ],
+      "format": "esm"
+    },
+    "src/providers/viacep.ts": {
+      "bytes": 917,
+      "imports": [
+        {
+          "path": "../types",
+          "kind": "import-statement",
+          "external": true
+        }
+      ],
+      "format": "esm"
+    },
+    "src/providers/brasil-api.ts": {
+      "bytes": 790,
+      "imports": [
+        {
+          "path": "../types",
+          "kind": "import-statement",
+          "external": true
+        }
+      ],
+      "format": "esm"
+    },
+    "src/providers/apicep.ts": {
+      "bytes": 768,
+      "imports": [
+        {
+          "path": "../types",
+          "kind": "import-statement",
+          "external": true
+        }
+      ],
+      "format": "esm"
+    },
+    "src/providers/index.ts": {
+      "bytes": 83,
+      "imports": [
+        {
+          "path": "src/providers/viacep.ts",
+          "kind": "import-statement",
+          "original": "./viacep"
+        },
+        {
+          "path": "src/providers/brasil-api.ts",
+          "kind": "import-statement",
+          "original": "./brasil-api"
+        },
+        {
+          "path": "src/providers/apicep.ts",
+          "kind": "import-statement",
+          "original": "./apicep"
+        }
+      ],
+      "format": "esm"
+    }
+  },
+  "outputs": {
+    "dist/index.js": {
+      "imports": [],
+      "exports": [],
+      "entryPoint": "src/index.ts",
+      "inputs": {
+        "src/index.ts": {
+          "bytesInOutput": 1736
+        },
+        "src/cache/index.ts": {
+          "bytesInOutput": 135
+        }
+      },
+      "bytes": 2364
+    },
+    "dist/providers/index.js": {
+      "imports": [],
+      "exports": [],
+      "entryPoint": "src/providers/index.ts",
+      "inputs": {
+        "src/providers/index.ts": {
+          "bytesInOutput": 102
+        },
+        "src/providers/viacep.ts": {
+          "bytesInOutput": 236
+        },
+        "src/providers/brasil-api.ts": {
+          "bytesInOutput": 197
+        },
+        "src/providers/apicep.ts": {
+          "bytesInOutput": 193
+        }
+      },
+      "bytes": 1224
+    }
+  }
+}

package/dist/types.d.ts

@@ -46,3 +46,17 @@ export interface CepLookupOptions {
     fetcher?: Fetcher;
     cache?: Cache;
 }
+/**
+ * @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;
+    data: Address | null;
+    provider?: string;
+    error?: Error;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eusilvio/cep-lookup",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "A modern, flexible, and agnostic CEP lookup library written in TypeScript.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",