feat: Add built-in retry util into into async utils

docs/framework/react/reference/functions/pacerprovider.md

@@ -0,0 +1,24 @@
+---
+id: PacerProvider
+title: PacerProvider
+---
+
+<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
+
+# Function: PacerProvider()
+
+```ts
+function PacerProvider(__namedParameters): Element
+```
+
+Defined in: [react-pacer/src/provider/PacerProvider.tsx:43](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/provider/PacerProvider.tsx#L43)
+
+## Parameters
+
+### \_\_namedParameters
+
+[`PacerProviderProps`](../../interfaces/pacerproviderprops.md)
+
+## Returns
+
+`Element`

docs/framework/react/reference/functions/useasyncbatcher.md

@@ -14,7 +14,7 @@ function useAsyncBatcher<TValue, TSelected>(
 selector): ReactAsyncBatcher<TValue, TSelected>
 ```
 
-Defined in: [react-pacer/src/async-batcher/useAsyncBatcher.ts:167](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-batcher/useAsyncBatcher.ts#L167)
+Defined in: [react-pacer/src/async-batcher/useAsyncBatcher.ts:168](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-batcher/useAsyncBatcher.ts#L168)
 
 A React hook that creates an `AsyncBatcher` instance for managing asynchronous batches of items.
 

docs/framework/react/reference/functions/useasyncdebouncer.md

@@ -14,7 +14,7 @@ function useAsyncDebouncer<TFn, TSelected>(
 selector): ReactAsyncDebouncer<TFn, TSelected>
 ```
 
-Defined in: [react-pacer/src/async-debouncer/useAsyncDebouncer.ts:149](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-debouncer/useAsyncDebouncer.ts#L149)
+Defined in: [react-pacer/src/async-debouncer/useAsyncDebouncer.ts:150](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-debouncer/useAsyncDebouncer.ts#L150)
 
 A low-level React hook that creates an `AsyncDebouncer` instance to delay execution of an async function.
 

docs/framework/react/reference/functions/useasyncqueuer.md

@@ -14,7 +14,7 @@ function useAsyncQueuer<TValue, TSelected>(
 selector): ReactAsyncQueuer<TValue, TSelected>
 ```
 
-Defined in: [react-pacer/src/async-queuer/useAsyncQueuer.ts:167](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-queuer/useAsyncQueuer.ts#L167)
+Defined in: [react-pacer/src/async-queuer/useAsyncQueuer.ts:168](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-queuer/useAsyncQueuer.ts#L168)
 
 A lower-level React hook that creates an `AsyncQueuer` instance for managing an async queue of items.
 

docs/framework/react/reference/functions/useasyncratelimiter.md

@@ -14,7 +14,7 @@ function useAsyncRateLimiter<TFn, TSelected>(
 selector): ReactAsyncRateLimiter<TFn, TSelected>
 ```
 
-Defined in: [react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts:178](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts#L178)
+Defined in: [react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts:179](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts#L179)
 
 A low-level React hook that creates an `AsyncRateLimiter` instance to limit how many times an async function can execute within a time window.
 

docs/framework/react/reference/functions/useasyncretryer.md

@@ -0,0 +1,165 @@
+---
+id: useAsyncRetryer
+title: useAsyncRetryer
+---
+
+<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
+
+# Function: useAsyncRetryer()
+
+```ts
+function useAsyncRetryer<TFn, TSelected>(
+   fn, 
+   options, 
+selector): ReactAsyncRetryer<TFn, TSelected>
+```
+
+Defined in: [react-pacer/src/async-retryer/useAsyncRetryer.ts:152](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-retryer/useAsyncRetryer.ts#L152)
+
+A low-level React hook that creates an `AsyncRetryer` instance to retry execution of an async function.
+
+This hook is designed to be flexible and state-management agnostic - it simply returns a retryer instance that
+you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc).
+
+Async retrying automatically re-executes a failed async function up to a specified number of attempts with
+configurable backoff strategies. This is useful for handling transient errors like network failures, temporary
+server issues, or rate limiting where you want to automatically retry the operation.
+
+Error Handling:
+- If an `onError` handler is provided, it will be called for every error during execution
+- If an `onLastError` handler is provided, it will be called only for the final error after all retries fail
+- If `throwOnError` is 'last' (default), only the final error after all retries will be thrown
+- If `throwOnError` is true, every error will be thrown immediately (disables retrying)
+- If `throwOnError` is false, errors are never thrown and undefined is returned instead
+
+## State Management and Selector
+
+The hook uses TanStack Store for reactive state management. The `selector` parameter allows you
+to specify which state changes will trigger a re-render, optimizing performance by preventing
+unnecessary re-renders when irrelevant state changes occur.
+
+**By default, there will be no reactive state subscriptions** and you must opt-in to state
+tracking by providing a selector function. This prevents unnecessary re-renders and gives you
+full control over when your component updates. Only when you provide a selector will the
+component re-render when the selected state values change.
+
+Available state properties:
+- `currentAttempt`: The current retry attempt number (0 when not executing)
+- `executionCount`: Total number of completed executions (successful or failed)
+- `isExecuting`: Whether the retryer is currently executing the function
+- `lastError`: The most recent error encountered during execution
+- `lastExecutionTime`: Timestamp of the last execution completion in milliseconds
+- `lastResult`: The result from the most recent successful execution
+- `status`: Current execution status ('disabled' | 'idle' | 'executing' | 'retrying')
+- `totalExecutionTime`: Total time spent executing (including retries) in milliseconds
+
+## Type Parameters
+
+• **TFn** *extends* `AnyAsyncFunction`
+
+• **TSelected** = \{\}
+
+## Parameters
+
+### fn
+
+`TFn`
+
+### options
+
+`AsyncRetryerOptions`\<`TFn`\>
+
+### selector
+
+(`state`) => `TSelected`
+
+## Returns
+
+[`ReactAsyncRetryer`](../../interfaces/reactasyncretryer.md)\<`TFn`, `TSelected`\>
+
+## Example
+
+```tsx
+// Default behavior - no reactive state subscriptions
+const apiRetryer = useAsyncRetryer(
+  async (userId: string) => {
+    const response = await fetch(`/api/users/${userId}`);
+    if (!response.ok) throw new Error('Failed to fetch user');
+    return response.json();
+  },
+  { maxAttempts: 3, backoff: 'exponential' }
+);
+
+// Opt-in to re-render when execution state changes (optimized for loading indicators)
+const apiRetryer = useAsyncRetryer(
+  async (userId: string) => {
+    const response = await fetch(`/api/users/${userId}`);
+    if (!response.ok) throw new Error('Failed to fetch user');
+    return response.json();
+  },
+  { maxAttempts: 3, backoff: 'exponential' },
+  (state) => ({
+    isExecuting: state.isExecuting,
+    currentAttempt: state.currentAttempt
+  })
+);
+
+// Opt-in to re-render when results are available (optimized for data display)
+const apiRetryer = useAsyncRetryer(
+  async (userId: string) => {
+    const response = await fetch(`/api/users/${userId}`);
+    if (!response.ok) throw new Error('Failed to fetch user');
+    return response.json();
+  },
+  { maxAttempts: 3, backoff: 'exponential' },
+  (state) => ({
+    lastResult: state.lastResult,
+    executionCount: state.executionCount
+  })
+);
+
+// Opt-in to re-render when error state changes (optimized for error handling)
+const apiRetryer = useAsyncRetryer(
+  async (userId: string) => {
+    const response = await fetch(`/api/users/${userId}`);
+    if (!response.ok) throw new Error('Failed to fetch user');
+    return response.json();
+  },
+  {
+    maxAttempts: 3,
+    backoff: 'exponential',
+    onError: (error) => console.error('API call failed:', error),
+    onLastError: (error) => console.error('All retries failed:', error)
+  },
+  (state) => ({
+    lastError: state.lastError,
+    status: state.status
+  })
+);
+
+// With state management
+const [userData, setUserData] = useState(null);
+const { execute, state } = useAsyncRetryer(
+  async (userId) => {
+    const response = await fetch(`/api/users/${userId}`);
+    if (!response.ok) throw new Error('Failed to fetch user');
+    const data = await response.json();
+    setUserData(data);
+    return data;
+  },
+  {
+    maxAttempts: 5,
+    backoff: 'exponential',
+    baseWait: 1000,
+    onRetry: (attempt, error) => {
+      console.log(`Retry attempt ${attempt} after error:`, error);
+    },
+    onError: (error) => {
+      console.error('Request failed:', error);
+    }
+  }
+);
+
+// Access the selected state (will be empty object {} unless selector provided)
+const { isExecuting, currentAttempt } = state;
+```

docs/framework/react/reference/functions/useasyncthrottler.md

@@ -14,7 +14,7 @@ function useAsyncThrottler<TFn, TSelected>(
 selector): ReactAsyncThrottler<TFn, TSelected>
 ```
 
-Defined in: [react-pacer/src/async-throttler/useAsyncThrottler.ts:160](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-throttler/useAsyncThrottler.ts#L160)
+Defined in: [react-pacer/src/async-throttler/useAsyncThrottler.ts:161](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-throttler/useAsyncThrottler.ts#L161)
 
 A low-level React hook that creates an `AsyncThrottler` instance to limit how often an async function can execute.
 

docs/framework/react/reference/functions/usebatcher.md

@@ -14,7 +14,7 @@ function useBatcher<TValue, TSelected>(
 selector): ReactBatcher<TValue, TSelected>
 ```
 
-Defined in: [react-pacer/src/batcher/useBatcher.ts:121](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/batcher/useBatcher.ts#L121)
+Defined in: [react-pacer/src/batcher/useBatcher.ts:122](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/batcher/useBatcher.ts#L122)
 
 A React hook that creates and manages a Batcher instance.
 

docs/framework/react/reference/functions/usedebouncer.md

@@ -14,7 +14,7 @@ function useDebouncer<TFn, TSelected>(
 selector): ReactDebouncer<TFn, TSelected>
 ```
 
-Defined in: [react-pacer/src/debouncer/useDebouncer.ts:102](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncer.ts#L102)
+Defined in: [react-pacer/src/debouncer/useDebouncer.ts:103](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncer.ts#L103)
 
 A React hook that creates and manages a Debouncer instance.
 

docs/framework/react/reference/functions/usedefaultpaceroptions.md

@@ -0,0 +1,18 @@
+---
+id: useDefaultPacerOptions
+title: useDefaultPacerOptions
+---
+
+<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
+
+# Function: useDefaultPacerOptions()
+
+```ts
+function useDefaultPacerOptions(): PacerProviderOptions
+```
+
+Defined in: [react-pacer/src/provider/PacerProvider.tsx:62](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/provider/PacerProvider.tsx#L62)
+
+## Returns
+
+[`PacerProviderOptions`](../../interfaces/pacerprovideroptions.md)

docs/framework/react/reference/functions/usepacercontext.md

@@ -0,0 +1,18 @@
+---
+id: usePacerContext
+title: usePacerContext
+---
+
+<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
+
+# Function: usePacerContext()
+
+```ts
+function usePacerContext(): null | PacerContextValue
+```
+
+Defined in: [react-pacer/src/provider/PacerProvider.tsx:58](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/provider/PacerProvider.tsx#L58)
+
+## Returns
+
+`null` \| `PacerContextValue`

docs/framework/react/reference/functions/usequeuer.md

@@ -14,7 +14,7 @@ function useQueuer<TValue, TSelected>(
 selector): ReactQueuer<TValue, TSelected>
 ```
 
-Defined in: [react-pacer/src/queuer/useQueuer.ts:132](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/queuer/useQueuer.ts#L132)
+Defined in: [react-pacer/src/queuer/useQueuer.ts:133](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/queuer/useQueuer.ts#L133)
 
 A React hook that creates and manages a Queuer instance.
 

docs/framework/react/reference/functions/useratelimiter.md

@@ -14,7 +14,7 @@ function useRateLimiter<TFn, TSelected>(
 selector): ReactRateLimiter<TFn, TSelected>
 ```
 
-Defined in: [react-pacer/src/rate-limiter/useRateLimiter.ts:141](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/rate-limiter/useRateLimiter.ts#L141)
+Defined in: [react-pacer/src/rate-limiter/useRateLimiter.ts:142](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/rate-limiter/useRateLimiter.ts#L142)
 
 A low-level React hook that creates a `RateLimiter` instance to enforce rate limits on function execution.
 

docs/framework/react/reference/functions/usethrottler.md

@@ -14,7 +14,7 @@ function useThrottler<TFn, TSelected>(
 selector): ReactThrottler<TFn, TSelected>
 ```
 
-Defined in: [react-pacer/src/throttler/useThrottler.ts:107](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/throttler/useThrottler.ts#L107)
+Defined in: [react-pacer/src/throttler/useThrottler.ts:108](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/throttler/useThrottler.ts#L108)
 
 A low-level React hook that creates a `Throttler` instance that limits how often the provided function can execute.
 

docs/framework/react/reference/index.md

@@ -9,10 +9,13 @@ title: "@tanstack/react-pacer"
 
 ## Interfaces
 
+- [PacerProviderOptions](../interfaces/pacerprovideroptions.md)
+- [PacerProviderProps](../interfaces/pacerproviderprops.md)
 - [ReactAsyncBatcher](../interfaces/reactasyncbatcher.md)
 - [ReactAsyncDebouncer](../interfaces/reactasyncdebouncer.md)
 - [ReactAsyncQueuer](../interfaces/reactasyncqueuer.md)
 - [ReactAsyncRateLimiter](../interfaces/reactasyncratelimiter.md)
+- [ReactAsyncRetryer](../interfaces/reactasyncretryer.md)
 - [ReactAsyncThrottler](../interfaces/reactasyncthrottler.md)
 - [ReactBatcher](../interfaces/reactbatcher.md)
 - [ReactDebouncer](../interfaces/reactdebouncer.md)
@@ -22,6 +25,7 @@ title: "@tanstack/react-pacer"
 
 ## Functions
 
+- [PacerProvider](../functions/pacerprovider.md)
 - [useAsyncBatchedCallback](../functions/useasyncbatchedcallback.md)
 - [useAsyncBatcher](../functions/useasyncbatcher.md)
 - [useAsyncDebouncedCallback](../functions/useasyncdebouncedcallback.md)
@@ -30,6 +34,7 @@ title: "@tanstack/react-pacer"
 - [useAsyncQueuer](../functions/useasyncqueuer.md)
 - [useAsyncRateLimitedCallback](../functions/useasyncratelimitedcallback.md)
 - [useAsyncRateLimiter](../functions/useasyncratelimiter.md)
+- [useAsyncRetryer](../functions/useasyncretryer.md)
 - [useAsyncThrottledCallback](../functions/useasyncthrottledcallback.md)
 - [useAsyncThrottler](../functions/useasyncthrottler.md)
 - [useBatchedCallback](../functions/usebatchedcallback.md)
@@ -38,6 +43,8 @@ title: "@tanstack/react-pacer"
 - [useDebouncedState](../functions/usedebouncedstate.md)
 - [useDebouncedValue](../functions/usedebouncedvalue.md)
 - [useDebouncer](../functions/usedebouncer.md)
+- [useDefaultPacerOptions](../functions/usedefaultpaceroptions.md)
+- [usePacerContext](../functions/usepacercontext.md)
 - [useQueuedState](../functions/usequeuedstate.md)
 - [useQueuedValue](../functions/usequeuedvalue.md)
 - [useQueuer](../functions/usequeuer.md)