@eusilvio/cep-lookup 1.0.0

package/README.md

@@ -0,0 +1,166 @@
+# @eusilvio/cep-lookup
+
+[![NPM Version](https://img.shields.io/npm/v/@eusilvio/cep-lookup.svg)](https://www.npmjs.com/package/@eusilvio/cep-lookup)
+[![Build Status](https://img.shields.io/github/workflow/status/eusilvio/cep-lookup/CI)](https://github.com/eusilvio/cep-lookup/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A modern, flexible, and agnostic CEP (Brazilian postal code) lookup library written in TypeScript.
+
+## About
+
+`@eusilvio/cep-lookup` was created to solve address lookup from a CEP in a different way. Instead of relying on a single data source, it queries multiple services simultaneously and returns the response from the fastest one.
+
+Its agnostic design allows it to be used in any JavaScript environment with any HTTP client, and its powerful "mapper" system allows you to format the data output exactly as you need.
+
+## Key Features
+
+- **Multiple Providers (Race Strategy)**: Queries multiple CEP APIs at the same time and uses the first valid response.
+- **Class-Based API**: Create a reusable instance with your settings.
+- **Customizable Return Format**: Provide a `mapper` function to transform the address data into any format your application needs.
+- **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.
+
+## Installation
+
+```bash
+npm install @eusilvio/cep-lookup
+```
+
+## How to Use
+
+### Example 1: Basic Usage
+
+```typescript
+import { CepLookup, Address } from "@eusilvio/cep-lookup";
+import {
+  viaCepProvider,
+  brasilApiProvider,
+} from "@eusilvio/cep-lookup/providers";
+
+// 1. Create an instance of CepLookup (fetcher is now optional and defaults to global fetch)
+const cepLookup = new CepLookup({
+  providers: [viaCepProvider, brasilApiProvider],
+});
+
+// 2. Look up a CEP
+cepLookup.lookup("01001-000").then((address: Address) => {
+  console.log("Address found:", address);
+  // Output:
+  // {
+  //   cep: '01001-000',
+  //   state: 'SP',
+  //   city: 'São Paulo',
+  //   neighborhood: 'Sé',
+  //   street: 'Praça da Sé',
+  //   service: 'ViaCEP'
+  // }
+});
+```
+
+### Example 2: Custom Return with `mapper`
+
+```typescript
+import { CepLookup, Address } from "@eusilvio/cep-lookup";
+import { viaCepProvider } from "@eusilvio/cep-lookup/providers";
+
+const cepLookup = new CepLookup({
+  providers: [viaCepProvider],
+});
+
+// 1. Define your "mapper" function
+interface CustomAddress {
+  postalCode: string;
+  fullAddress: string;
+  source: string;
+}
+
+const myMapper = (address: Address): CustomAddress => {
+  return {
+    postalCode: address.cep,
+    fullAddress: `${address.street}, ${address.neighborhood} - ${address.city}/${address.state}`,
+    source: address.service,
+  };
+};
+
+// 2. Look up a CEP with the mapper
+cepLookup.lookup("01001-000", myMapper).then((customAddress: CustomAddress) => {
+  console.log("Address found (custom format):", customAddress);
+  // Output:
+  // {
+  //   postalCode: '01001-000',
+  //   fullAddress: 'Praça da Sé, Sé - São Paulo/SP',
+  //   source: 'ViaCEP'
+  // }
+});
+```
+
+## API
+
+### `new CepLookup(options)`
+
+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.
+
+### `cepLookup.lookup<T = Address>(cep, mapper?): Promise<T>`
+
+Returns a `Promise` that resolves to the address in the default format (`Address`) or in the custom format `T` if a `mapper` is provided.
+
+- `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`.
+
+## Examples
+
+You can find more detailed examples in the `examples/` directory:
+
+- **Basic Usage**: `examples/example.ts`
+- **Custom Provider**: `examples/custom-provider-example.ts`
+- **Node.js Usage**: `examples/node-example.ts`
+- **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
+```
+
+## Creating a Custom Provider
+
+Your custom provider must always transform the API response to the library's default `Address` interface. The user's `mapper` will handle the final customization.
+
+```typescript
+import { Provider, Address } from "@eusilvio/cep-lookup";
+
+const myCustomProvider: Provider = {
+  name: "MyCustomAPI",
+  buildUrl: (cep: string) => `https://myapi.com/cep/${cep}`,
+  transform: (response: any): Address => {
+    // Transforms the response from "MyCustomAPI" to the "Address" format
+    return {
+      cep: response.postal_code,
+      state: response.data.state_short,
+      city: response.data.city_name,
+      neighborhood: response.data.neighborhood,
+      street: response.data.street_name,
+      service: "MyCustomAPI",
+    };
+  },
+};
+```
+
+## Running Tests
+
+```bash
+npm test
+```
+
+## License
+
+Distributed under the MIT License.

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { Address, Fetcher, Provider, CepLookupOptions } from "./types";
+export { Address, Fetcher, Provider, CepLookupOptions };
+/**
+ * @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;
+    private fetcher;
+    /**
+     * @constructor
+     * @param {CepLookupOptions} options - The options for initializing the CepLookup instance.
+     */
+    constructor(options: CepLookupOptions);
+    /**
+     * @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 {(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>;

package/dist/index.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CepLookup = void 0;
+exports.lookupCep = lookupCep;
+/**
+ * @function validateCep
+ * @description Validates and cleans a CEP string. Removes non-digit characters and checks for an 8-digit length.
+ * @param {string} cep - The CEP string to validate.
+ * @returns {string} The cleaned, 8-digit CEP string.
+ * @throws {Error} If the CEP is invalid (not 8 digits after cleaning).
+ */
+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;
+}
+/**
+ * @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.
+ */
+class CepLookup {
+    /**
+     * @constructor
+     * @param {CepLookupOptions} options - The options for initializing the CepLookup instance.
+     */
+    constructor(options) {
+        this.providers = options.providers;
+        this.fetcher = options.fetcher || (async (url) => {
+            const response = await fetch(url);
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            return response.json();
+        });
+    }
+    /**
+     * @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);
+        const promises = this.providers.map((provider) => {
+            const url = provider.buildUrl(cleanedCep);
+            return this.fetcher(url)
+                .then((response) => provider.transform(response))
+                .then((address) => (mapper ? mapper(address) : address));
+        });
+        return Promise.any(promises);
+    }
+}
+exports.CepLookup = CepLookup;
+/**
+ * @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 {(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.
+ */
+function lookupCep(options) {
+    const { cep, providers, fetcher, mapper } = options;
+    const cepLookup = new CepLookup({ providers, fetcher });
+    return cepLookup.lookup(cep, mapper);
+}

package/dist/providers/apicep.d.ts

@@ -0,0 +1,9 @@
+import { Provider } from "../types";
+/**
+ * @const {Provider} apicepProvider
+ * @description Provider for the ApiCEP service.
+ * @property {string} name - "ApiCEP".
+ * @property {(cep: string) => string} buildUrl - Constructs the URL for ApiCEP.
+ * @property {(response: any) => Address} transform - Transforms ApiCEP's response into a standardized `Address` object.
+ */
+export declare const apicepProvider: Provider;

package/dist/providers/apicep.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apicepProvider = void 0;
+/**
+ * @const {Provider} apicepProvider
+ * @description Provider for the ApiCEP service.
+ * @property {string} name - "ApiCEP".
+ * @property {(cep: string) => string} buildUrl - Constructs the URL for ApiCEP.
+ * @property {(response: any) => Address} transform - Transforms ApiCEP's response into a standardized `Address` object.
+ */
+exports.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",
+        };
+    },
+};

package/dist/providers/brasil-api.d.ts

@@ -0,0 +1,9 @@
+import { Provider } from "../types";
+/**
+ * @const {Provider} brasilApiProvider
+ * @description Provider for the BrasilAPI service.
+ * @property {string} name - "BrasilAPI".
+ * @property {(cep: string) => string} buildUrl - Constructs the URL for BrasilAPI.
+ * @property {(response: any) => Address} transform - Transforms BrasilAPI's response into a standardized `Address` object.
+ */
+export declare const brasilApiProvider: Provider;

package/dist/providers/brasil-api.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.brasilApiProvider = void 0;
+/**
+ * @const {Provider} brasilApiProvider
+ * @description Provider for the BrasilAPI service.
+ * @property {string} name - "BrasilAPI".
+ * @property {(cep: string) => string} buildUrl - Constructs the URL for BrasilAPI.
+ * @property {(response: any) => Address} transform - Transforms BrasilAPI's response into a standardized `Address` object.
+ */
+exports.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",
+        };
+    },
+};

package/dist/providers/index.d.ts

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

package/dist/providers/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./viacep"), exports);
+__exportStar(require("./brasil-api"), exports);
+__exportStar(require("./apicep"), exports);

package/dist/providers/viacep.d.ts

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

package/dist/providers/viacep.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.viaCepProvider = void 0;
+/**
+ * @const {Provider} viaCepProvider
+ * @description Provider for the ViaCEP service.
+ * @property {string} name - "ViaCEP".
+ * @property {(cep: string) => string} buildUrl - Constructs the URL for ViaCEP API.
+ * @property {(response: any) => Address} transform - Transforms ViaCEP's response into a standardized `Address` object.
+ * @throws {Error} If ViaCEP response indicates an error (e.g., CEP not found).
+ */
+exports.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",
+        };
+    },
+};

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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;
+    state: string;
+    city: string;
+    neighborhood: string;
+    street: string;
+    service: string;
+}
+/**
+ * @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;
+    buildUrl: (cep: string) => string;
+    transform: (response: any) => Address;
+}
+/**
+ * @typedef {function(url: string): 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>;
+/**
+ * @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.
+ */
+export interface CepLookupOptions {
+    providers: Provider[];
+    fetcher?: Fetcher;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@eusilvio/cep-lookup",
+  "version": "1.0.0",
+  "description": "A modern, flexible, and agnostic CEP lookup library written in TypeScript.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./providers": "./dist/providers/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "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"
+  },
+  "keywords": [
+    "cep",
+    "lookup",
+    "typescript",
+    "address",
+    "correios"
+  ],
+  "author": "",
+  "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",
+    "jest": "^30.1.3",
+    "ts-jest": "^29.4.4",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.9.2"
+  }
+}