@eusilvio/cep-lookup-react 0.4.1 → 2.6.0

package/README.md

@@ -1,107 +1,106 @@
 # @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.
+React hooks/provider for [`@eusilvio/cep-lookup`](https://www.npmjs.com/package/@eusilvio/cep-lookup).
 
 ## Installation
 
 ```bash
-npm install @eusilvio/cep-lookup @eusilvio/cep-lookup-react react
-# or
-yarn add @eusilvio/cep-lookup @eusilvio/cep-lookup-react react
+npm install @eusilvio/cep-lookup @eusilvio/cep-lookup-react react react-dom
 ```
 
 ## Compatibility
 
 - React: `>= 16.8`
-- Node.js (for tooling/tests): `20.x`, `22.x`, `24.x`
-- Support policy: [SUPPORT.md](../../SUPPORT.md)
+- Node.js (tooling/tests): `20.x`, `22.x`, `24.x`
+- Core peer: `@eusilvio/cep-lookup ^2.6.0`
 
 ## 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';
+```tsx
+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);
+function CepField() {
+  const [cep, setCep] = React.useState("01001000");
+  const { address, loading, error, warmup } = useCepLookup(cep);
 
   return (
     <div>
-      <input value={cep} onChange={(e) => setCep(e.target.value)} />
+      <input
+        value={cep}
+        onFocus={() => warmup()}
+        onChange={(e) => setCep(e.target.value)}
+      />
       {loading && <p>Loading...</p>}
-      {error && <p>Error: {error.message}</p>}
-      {address && (
-        <pre>{JSON.stringify(address, null, 2)}</pre>
-      )}
+      {error && <p>{error.message}</p>}
+      {address && <pre>{JSON.stringify(address, null, 2)}</pre>}
     </div>
   );
-};
+}
 
-const App = () => (
-  <CepProvider>
-    <CepDisplay />
-  </CepProvider>
-);
-
-export default App;
+export default function App() {
+  return (
+    <CepProvider>
+      <CepField />
+    </CepProvider>
+  );
+}
 ```
 
-## Advanced Configuration
+## Resilience Example (Provider Options)
 
-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.
+```tsx
+import { CepProvider } from "@eusilvio/cep-lookup-react";
+import { viaCepProvider, brasilApiProvider } from "@eusilvio/cep-lookup/providers";
 
-### Example: Using only the ViaCEP provider
+<CepProvider
+  providers={[viaCepProvider, brasilApiProvider]}
+  circuitBreaker={{ enabled: true, failureThreshold: 3, cooldownMs: 30000 }}
+  retries={1}
+  rateLimit={{ requests: 60, per: 60_000 }}
+>
+  {/* app */}
+</CepProvider>
+```
 
-```jsx
-import { CepProvider } from '@eusilvio/cep-lookup-react';
-import { viaCepProvider } from '@eusilvio/cep-lookup/providers';
+## Events Example
 
-const App = () => (
-  <CepProvider providers={[viaCepProvider]}>
-    {/* Your components here */}
-  </CepProvider>
-);
+```tsx
+<CepProvider
+  onSuccess={({ provider, duration }) => console.log("success", provider, duration)}
+  onFailure={({ provider, error }) => console.log("failure", provider, error.message)}
+  onCacheHit={({ cep }) => console.log("cache hit", cep)}
+>
+  {/* app */}
+</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.
-- `cache` (optional): `Cache` - A cache instance. Defaults to a persistent `InMemoryCache`.
-- `rateLimit` (optional): `RateLimitOptions` - Options for rate limiting.
-- `mapper` (optional): `(address: Address) => T` - A function to transform the address object globally.
-- `onSuccess` (optional): `(event) => void` - Callback triggered on successful lookups.
-- `onFailure` (optional): `(event) => void` - Callback triggered on lookup failures.
-- `onCacheHit` (optional): `(event) => void` - Callback triggered on cache hits.
-
 ### `useCepLookup<T = Address>(cep: string, delay?: number)`
 
-A React hook that performs the CEP lookup with built-in race condition protection.
+Returns `{ address, error, loading, warmup }`.
 
-**Parameters**
+### `useBulkCepLookup<T = Address>(ceps: string[], options?)`
 
-- `cep`: `string` - The CEP to look up.
-- `delay` (optional): `number` - The debounce delay in milliseconds. Defaults to `500`.
+Returns `{ results, error, loading, refresh }`.
 
-**Returns**
+### `<CepProvider />`
 
-An object with `address` (typed as `T`), `loading`, `error`, and `warmup`.
+Accepts `CepLookupOptions` as props (`providers`, `cache`, `rateLimit`, `retries`, `retryDelay`, `circuitBreaker`, `staggerDelay`, `fetcher`) plus:
 
-- `warmup`: `() => Promise<void>` - Function to trigger provider ranking optimization. Best used on `onFocus` events.
+- `mapper`
+- `onSuccess`
+- `onFailure`
+- `onCacheHit`
 
 ## Community
 
-- Contributing guide: [CONTRIBUTING.md](../../CONTRIBUTING.md)
-- Code of conduct: [CODE_OF_CONDUCT.md](../../CODE_OF_CONDUCT.md)
+- [CONTRIBUTING.md](../../CONTRIBUTING.md)
+- [CODE_OF_CONDUCT.md](../../CODE_OF_CONDUCT.md)
+- [SECURITY.md](../../SECURITY.md)
+
+## Production docs
+
+- [Best Practices](../../docs/BEST_PRACTICES.md)
+- [Cookbook](../../docs/COOKBOOK.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eusilvio/cep-lookup-react",
-  "version": "0.4.1",
+  "version": "2.6.0",
   "description": "React hooks and provider for @eusilvio/cep-lookup",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
     }
   },
   "peerDependencies": {
-    "@eusilvio/cep-lookup": "^2.5.1",
+    "@eusilvio/cep-lookup": "^2.6.0",
     "react": ">=16.8.0",
     "react-dom": ">=16.8.0"
   },