@eusilvio/cep-lookup-react 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# @eusilvio/cep-lookup-react
+
+React hook for [`@eusilvio/cep-lookup`](https://www.npmjs.com/package/@eusilvio/cep-lookup).
+
+Provides a flexible and easy-to-use React hook (`useCepLookup`) to look up Brazilian postal codes (CEPs), with built-in debounce, caching, and full configuration via a React Context Provider.
+
+## Installation
+
+```bash
+npm install @eusilvio/cep-lookup @eusilvio/cep-lookup-react react
+# or
+yarn add @eusilvio/cep-lookup @eusilvio/cep-lookup-react react
+```
+
+## Basic Usage
+
+Wrap your application or component tree with the `CepProvider` and use the `useCepLookup` hook anywhere inside it.
+
+```jsx
+import React from 'react';
+import { CepProvider, useCepLookup } from '@eusilvio/cep-lookup-react';
+
+const CepDisplay = () => {
+  const [cep, setCep] = React.useState('01001000');
+  const { address, loading, error } = useCepLookup(cep);
+
+  return (
+    <div>
+      <input value={cep} onChange={(e) => setCep(e.target.value)} />
+      {loading && <p>Loading...</p>}
+      {error && <p>Error: {error.message}</p>}
+      {address && (
+        <pre>{JSON.stringify(address, null, 2)}</pre>
+      )}
+    </div>
+  );
+};
+
+const App = () => (
+  <CepProvider>
+    <CepDisplay />
+  </CepProvider>
+);
+
+export default App;
+```
+
+## Advanced Configuration
+
+You can pass any `CepLookupOptions` to the `CepProvider` to customize its behavior, such as changing providers, adding a custom cache, or setting a rate limit.
+
+### Example: Using only the ViaCEP provider
+
+```jsx
+import { CepProvider } from '@eusilvio/cep-lookup-react';
+import { viaCepProvider } from '@eusilvio/cep-lookup/providers';
+
+const App = () => (
+  <CepProvider providers={[viaCepProvider]}>
+    {/* Your components here */}
+  </CepProvider>
+);
+```
+
+## API
+
+### `<CepProvider />`
+
+A React component that provides the `CepLookup` instance to its children.
+
+**Props**
+
+It accepts all options from `CepLookupOptions` as props:
+
+- `providers` (optional): `Provider[]` - An array of CEP providers. Defaults to `[viaCepProvider, brasilApiProvider, apicepProvider]`.
+- `cache` (optional): `Cache` - A cache instance (e.g., `new InMemoryCache()`). Defaults to a new `InMemoryCache` instance.
+- `rateLimit` (optional): `RateLimitOptions` - Options for rate limiting.
+- `fetcher` (optional): `Fetcher` - A custom fetch implementation.
+
+### `useCepLookup(cep: string, debounceTime?: number)`
+
+A React hook that performs the CEP lookup.
+
+**Parameters**
+
+- `cep`: `string` - The CEP to look up.
+- `debounceTime` (optional): `number` - The debounce time in milliseconds before the lookup is triggered. Defaults to `500`.
+
+**Returns**
+
+An object with the following properties:
+
+- `address`: `Address | null` - The found address object, or `null` if not found or not yet loaded.
+- `loading`: `boolean` - `true` when a lookup is in progress.
+- `error`: `Error | null` - An `Error` object if the lookup fails, otherwise `null`.

package/dist/CepProvider.d.ts

@@ -0,0 +1,18 @@
+import React, { ReactNode } from "react";
+import { Address, CepLookup, CepLookupOptions, EventMap } from "@eusilvio/cep-lookup";
+export interface CepContextValue {
+    instance: CepLookup;
+    mapper?: (address: Address) => any;
+    options: CepLookupOptions;
+}
+interface CepProviderProps extends Partial<CepLookupOptions> {
+    children: ReactNode;
+    mapper?: (address: Address) => any;
+    onSuccess?: (event: EventMap['success']) => void;
+    onFailure?: (event: EventMap['failure']) => void;
+    onCacheHit?: (event: EventMap['cache:hit']) => void;
+}
+export declare const CepProvider: React.FC<CepProviderProps>;
+export declare const useCepLookupInstance: () => CepContextValue;
+export {};
+//# sourceMappingURL=CepProvider.d.ts.map

package/dist/CepProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CepProvider.d.ts","sourceRoot":"","sources":["../src/CepProvider.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,EAEZ,SAAS,EAIV,MAAM,OAAO,CAAC;AACf,OAAO,EACL,OAAO,EACP,SAAS,EACT,gBAAgB,EAEhB,QAAQ,EACT,MAAM,sBAAsB,CAAC;AAS9B,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,GAAG,CAAC;IAEnC,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAQD,UAAU,gBAAiB,SAAQ,OAAO,CAAC,gBAAgB,CAAC;IAC1D,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,GAAG,CAAC;IAEnC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;IACjD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;IACjD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACrD;AAED,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC,gBAAgB,CA2DlD,CAAC;AAEF,eAAO,MAAM,oBAAoB,uBAOhC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './useCepLookup';
+export * from './CepProvider';
+export * from './useBulkCepLookup';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+var x=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var I=Object.getOwnPropertyNames;var A=Object.prototype.hasOwnProperty;var M=(e,t)=>{for(var o in t)x(e,o,{get:t[o],enumerable:!0})},O=(e,t,o,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of I(t))!A.call(e,n)&&n!==o&&x(e,n,{get:()=>t[n],enumerable:!(r=b(t,n))||r.enumerable});return e};var B=e=>O(x({},"__esModule",{value:!0}),e);var F={};M(F,{CepProvider:()=>N,useBulkCepLookup:()=>D,useCepLookup:()=>V,useCepLookupInstance:()=>L});module.exports=B(F);var f=require("react");var v=require("@eusilvio/cep-lookup/providers"),p=require("react"),d=require("@eusilvio/cep-lookup"),w=require("react/jsx-runtime"),y=[v.viaCepProvider,v.brasilApiProvider,v.apicepProvider],P=new d.CepLookup({providers:y,cache:new d.InMemoryCache}),g=(0,p.createContext)({instance:P,options:{providers:y,cache:new d.InMemoryCache}}),N=({children:e,mapper:t,onSuccess:o,onFailure:r,onCacheHit:n,...s})=>{let a=(0,p.useMemo)(()=>Object.keys(s).length?new d.CepLookup({providers:y,cache:new d.InMemoryCache,...s}):P,[s]);(0,p.useEffect)(()=>(o&&a.on("success",o),r&&a.on("failure",r),n&&a.on("cache:hit",n),()=>{o&&a.off("success",o),r&&a.off("failure",r),n&&a.off("cache:hit",n)}),[a,o,r,n]);let c=(0,p.useMemo)(()=>({instance:a,mapper:t,options:{providers:y,cache:new d.InMemoryCache,...s}}),[a,t,s]);return(0,w.jsx)(g.Provider,{value:c,children:e})},L=()=>{let e=(0,p.useContext)(g);if(!e)throw new Error("useCepLookupInstance must be used within a CepProvider");return e};function T(e,t){let o;return(...r)=>new Promise(n=>{o&&clearTimeout(o),o=setTimeout(()=>n(e(...r)),t)})}var V=(e,t=500)=>{let[o,r]=(0,f.useState)(null),[n,s]=(0,f.useState)(null),[a,c]=(0,f.useState)(!1),{instance:h,mapper:C}=L(),u=(0,f.useCallback)(T(async i=>{c(!0),s(null);try{let l=await h.lookup(i);r(C?C(l):l)}catch(l){s(l),r(null)}finally{c(!1)}},t),[t,h,C]);return(0,f.useEffect)(()=>{let i=e.replace(/\D/g,"");i.length===8?u(i):(r(null),s(null))},[e,u]),{address:o,error:n,loading:a}};var m=require("react"),E=require("@eusilvio/cep-lookup");var D=(e,t)=>{let[o,r]=(0,m.useState)([]),[n,s]=(0,m.useState)(!1),[a,c]=(0,m.useState)(null),{instance:h,mapper:C,options:u}=L(),i=(0,m.useCallback)(async()=>{if(!e||e.length===0){r([]),s(!1),c(null);return}s(!0),c(null);try{let l=e.map(k=>k.replace(/\D/g,"")),R=(await(0,E.lookupCeps)({ceps:l,providers:u.providers,cache:u.cache,fetcher:u.fetcher,rateLimit:u.rateLimit,concurrency:t?.concurrency})).map(k=>({...k,data:k.data&&C?C(k.data):k.data}));r(R)}catch(l){c(l),r([])}finally{s(!1)}},[e,t,h,C,u]);return(0,m.useEffect)(()=>{i()},[i]),{results:o,loading:n,error:a,performBulkLookup:i}};

package/dist/useBulkCepLookup.d.ts

@@ -0,0 +1,10 @@
+import { BulkCepResult } from '@eusilvio/cep-lookup';
+export declare const useBulkCepLookup: (ceps: string[], options?: {
+    concurrency?: number;
+}) => {
+    results: BulkCepResult[];
+    loading: boolean;
+    error: Error;
+    performBulkLookup: () => Promise<void>;
+};
+//# sourceMappingURL=useBulkCepLookup.d.ts.map

package/dist/useBulkCepLookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBulkCepLookup.d.ts","sourceRoot":"","sources":["../src/useBulkCepLookup.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,aAAa,EAAoB,MAAM,sBAAsB,CAAC;AAGnF,eAAO,MAAM,gBAAgB,GAC3B,MAAM,MAAM,EAAE,EACd,UAAU;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;CAgDnC,CAAC"}

package/dist/useCepLookup.d.ts

@@ -0,0 +1,6 @@
+export declare const useCepLookup: (cep: string, debounceTime?: number) => {
+    address: any;
+    error: Error;
+    loading: boolean;
+};
+//# sourceMappingURL=useCepLookup.d.ts.map

package/dist/useCepLookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCepLookup.d.ts","sourceRoot":"","sources":["../src/useCepLookup.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,EAAE,qBAAkB;;;;CAmC3D,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@eusilvio/cep-lookup-react",
+  "version": "0.1.0",
+  "description": "React hook for cep-lookup.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "clean": "rm -rf dist && rm tsconfig.tsbuildinfo",
+    "build": "npm run clean && tsc --build && esbuild src/index.ts --bundle --platform=neutral --format=cjs --outdir=dist --minify --external:react --external:@eusilvio/cep-lookup",
+    "test": "jest"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "@eusilvio/cep-lookup": "^2.0.1",
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "jest": "^30.1.3",
+    "ts-jest": "^29.4.4",
+    "@types/jest": "^30.0.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "@testing-library/react": "^15.0.7",
+    "@testing-library/jest-dom": "^6.9.1",
+    "esbuild": "^0.20.2"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eusilvio/cep-lookup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eusilvio/cep-lookup/issues"
+  },
+  "homepage": "https://github.com/eusilvio/cep-lookup#readme",
+  "keywords": [
+    "cep",
+    "lookup",
+    "react",
+    "hook"
+  ],
+  "author": "Silvio Souza",
+  "sideEffects": false
+}