@eusilvio/cep-lookup 1.2.2 → 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,147 +1 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  CepLookup: () => CepLookup,
-  InMemoryCache: () => InMemoryCache,
-  lookupCep: () => lookupCep
-});
-module.exports = __toCommonJS(src_exports);
-
-// src/cache/index.ts
-var InMemoryCache = class {
-  constructor() {
-    this.cache = /* @__PURE__ */ new Map();
-  }
-  /**
-   * @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);
-  }
-  /**
-   * @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);
-  }
-  /**
-   * @method clear
-   * @description Clears the entire cache.
-   */
-  clear() {
-    this.cache.clear();
-  }
-};
-
-// src/index.ts
-function validateCep(cep) {
-  const cleanedCep = cep.replace(/\D/g, "");
-  if (cleanedCep.length !== 8) {
-    throw new Error("Invalid CEP. It must have 8 digits.");
-  }
-  return cleanedCep;
-}
-var CepLookup = class {
-  /**
-   * @constructor
-   * @param {CepLookupOptions} options - The options for initializing the CepLookup instance.
-   */
-  constructor(options) {
-    this.providers = options.providers;
-    this.fetcher = options.fetcher || (async (url, signal) => {
-      const response = await fetch(url, { signal });
-      if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`);
-      }
-      return response.json();
-    });
-    this.cache = options.cache;
-  }
-  /**
-   * @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.
-   */
-  async lookup(cep, mapper) {
-    const cleanedCep = validateCep(cep);
-    if (this.cache) {
-      const cachedAddress = this.cache.get(cleanedCep);
-      if (cachedAddress) {
-        return Promise.resolve(mapper ? mapper(cachedAddress) : cachedAddress);
-      }
-    }
-    const controller = new AbortController();
-    const { signal } = controller;
-    const promises = this.providers.map((provider) => {
-      const url = provider.buildUrl(cleanedCep);
-      const timeoutPromise = new Promise((resolve, reject) => {
-        let timeoutId;
-        const onAbort = () => {
-          clearTimeout(timeoutId);
-          reject(new DOMException("Aborted", "AbortError"));
-        };
-        if (provider.timeout) {
-          timeoutId = setTimeout(() => {
-            signal.removeEventListener("abort", onAbort);
-            reject(new Error(`Timeout from ${provider.name}`));
-          }, provider.timeout);
-          signal.addEventListener("abort", onAbort, { once: true });
-        } else {
-          signal.addEventListener("abort", onAbort, { once: true });
-        }
-      });
-      const fetchPromise = this.fetcher(url, signal).then((response) => provider.transform(response)).then((address) => {
-        if (this.cache) {
-          this.cache.set(cleanedCep, address);
-        }
-        return mapper ? mapper(address) : address;
-      });
-      return Promise.race([fetchPromise, timeoutPromise]);
-    });
-    try {
-      return await Promise.any(promises);
-    } finally {
-      controller.abort();
-    }
-  }
-};
-function lookupCep(options) {
-  const { cep, providers, fetcher, mapper, cache } = options;
-  const cepLookup = new CepLookup({ providers, fetcher, cache });
-  return cepLookup.lookup(cep, mapper);
-}
-// Annotate the CommonJS export names for ESM import in node:
-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/providers/index.js

@@ -1,84 +1 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/providers/index.ts
-var providers_exports = {};
-__export(providers_exports, {
-  apicepProvider: () => apicepProvider,
-  brasilApiProvider: () => brasilApiProvider,
-  viaCepProvider: () => viaCepProvider
-});
-module.exports = __toCommonJS(providers_exports);
-
-// src/providers/viacep.ts
-var viaCepProvider = {
-  name: "ViaCEP",
-  buildUrl: (cep) => `https://viacep.com.br/ws/${cep}/json/`,
-  transform: (response) => {
-    if (response.erro) {
-      throw new Error("CEP not found");
-    }
-    return {
-      cep: response.cep,
-      state: response.uf,
-      city: response.localidade,
-      neighborhood: response.bairro,
-      street: response.logradouro,
-      service: "ViaCEP"
-    };
-  }
-};
-
-// src/providers/brasil-api.ts
-var brasilApiProvider = {
-  name: "BrasilAPI",
-  buildUrl: (cep) => `https://brasilapi.com.br/api/cep/v1/${cep}`,
-  transform: (response) => {
-    return {
-      cep: response.cep,
-      state: response.state,
-      city: response.city,
-      neighborhood: response.neighborhood,
-      street: response.street,
-      service: "BrasilAPI"
-    };
-  }
-};
-
-// src/providers/apicep.ts
-var apicepProvider = {
-  name: "ApiCEP",
-  buildUrl: (cep) => `https://cdn.apicep.com/file/apicep/${cep}.json`,
-  transform: (response) => {
-    return {
-      cep: response.code,
-      state: response.state,
-      city: response.city,
-      neighborhood: response.district,
-      street: response.address,
-      service: "ApiCEP"
-    };
-  }
-};
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  apicepProvider,
-  brasilApiProvider,
-  viaCepProvider
-});
+"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});

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.2",
+  "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",
@@ -12,40 +12,18 @@
   "files": [
     "dist"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
   "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",
+    "build": "npm run clean && tsc --emitDeclarationOnly --outDir dist && esbuild src/index.ts src/providers/index.ts --bundle --platform=node --format=cjs --outdir=dist --minify --external:node:*",
     "test": "jest"
   },
-  "keywords": [
-    "cep",
-    "lookup",
-    "typescript",
-    "address",
-    "correios"
-  ],
-  "author": "Silvio Campos",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/eusilvio/cep-lookup.git"
-  },
-  "bugs": {
-    "url": "https://github.com/eusilvio/cep-lookup/issues"
-  },
-  "homepage": "https://github.com/eusilvio/cep-lookup#readme",
   "devDependencies": {
-    "@types/jest": "^30.0.0",
     "esbuild": "^0.20.2",
+    "typescript": "^5.9.2",
+    "@types/jest": "^30.0.0",
     "jest": "^30.1.3",
-    "p-limit": "^2.3.0",
     "ts-jest": "^29.4.4",
     "ts-node": "^10.9.2",
-    "tsconfig-paths": "^4.2.0",
-    "typescript": "^5.9.2"
+    "tsconfig-paths": "^4.2.0"
   }
 }