feat: standardize error handling and add throwOnError options to async utils

.changeset/small-apes-repair.md

@@ -0,0 +1,9 @@
+---
+'@tanstack/react-pacer': minor
+'@tanstack/solid-pacer': minor
+'@tanstack/pacer': minor
+---
+
+breaking: remove `onError`, `onSuccess`, `onSettled` options from `AsyncQueuer` in favor of options of the same name on the `AsyncQueuer`
+feat: standardize error handling callbacks on `AsyncQueuer`, `AsyncDebouncer`, `AsyncRateLimiter`, and `AsyncThrottler`
+feat: add `throwOnError` option to `AsyncQueuer`, `AsyncDebouncer`, `AsyncRateLimiter`, and `AsyncThrottler`

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

@@ -11,16 +11,30 @@ title: useAsyncDebouncer
 function useAsyncDebouncer<TFn>(fn, options): AsyncDebouncer<TFn>
 ```
 
-Defined in: [react-pacer/src/async-debouncer/useAsyncDebouncer.ts:42](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-debouncer/useAsyncDebouncer.ts#L42)
+Defined in: [react-pacer/src/async-debouncer/useAsyncDebouncer.ts:60](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-debouncer/useAsyncDebouncer.ts#L60)
 
 A low-level React hook that creates an `AsyncDebouncer` instance to delay execution of an async function.
 
 This hook is designed to be flexible and state-management agnostic - it simply returns a debouncer instance that
 you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc).
 
 Async debouncing ensures that an async function only executes after a specified delay has passed since its last invocation.
-This is useful for handling fast-changing inputs like search fields, form validation, or any scenario where you want to
-wait for user input to settle before making expensive async calls.
+Each new invocation resets the delay timer. This is useful for handling frequent events like window resizing
+or input changes where you only want to execute the handler after the events have stopped occurring.
+
+Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until
+the function stops being called for the specified delay period.
+
+Unlike the non-async Debouncer, this async version supports returning values from the debounced function,
+making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
+instead of setting the result on a state variable from within the debounced function.
+
+Error Handling:
+- If an `onError` handler is provided, it will be called with the error and debouncer instance
+- If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+- If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+- Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+- The error state can be checked using the underlying AsyncDebouncer instance
 
 ## Type Parameters
 
@@ -61,6 +75,11 @@ const { maybeExecute } = useAsyncDebouncer(
   },
   {
     wait: 300,
+    leading: true,   // Execute immediately on first call
+    trailing: false, // Skip trailing edge updates
+    onError: (error) => {
+      console.error('API call failed:', error);
+    }
   }
 );
 ```

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

@@ -8,10 +8,10 @@ title: useAsyncQueuedState
 # Function: useAsyncQueuedState()
 
 ```ts
-function useAsyncQueuedState<TValue>(options): [() => Promise<TValue>[], AsyncQueuer<TValue>]
+function useAsyncQueuedState<TFn>(options): [TFn[], AsyncQueuer<TFn>]
 ```
 
-Defined in: [react-pacer/src/async-queuer/useAsyncQueuedState.ts:53](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-queuer/useAsyncQueuedState.ts#L53)
+Defined in: [react-pacer/src/async-queuer/useAsyncQueuedState.ts:54](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-queuer/useAsyncQueuedState.ts#L54)
 
 A higher-level React hook that creates an `AsyncQueuer` instance with built-in state management.
 
@@ -34,17 +34,17 @@ The state will automatically update whenever items are:
 
 ## Type Parameters
 
-• **TValue**
+• **TFn** *extends* `AsyncQueuerFn`
 
 ## Parameters
 
 ### options
 
-`AsyncQueuerOptions`\<`TValue`\> = `{}`
+`AsyncQueuerOptions`\<`TFn`\> = `{}`
 
 ## Returns
 
-\[() => `Promise`\<`TValue`\>[], `AsyncQueuer`\<`TValue`\>\]
+\[`TFn`[], `AsyncQueuer`\<`TFn`\>\]
 
 ## Example
 

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

@@ -8,42 +8,45 @@ title: useAsyncQueuer
 # Function: useAsyncQueuer()
 
 ```ts
-function useAsyncQueuer<TValue>(options): AsyncQueuer<TValue>
+function useAsyncQueuer<TFn>(options): AsyncQueuer<TFn>
 ```
 
-Defined in: [react-pacer/src/async-queuer/useAsyncQueuer.ts:55](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-queuer/useAsyncQueuer.ts#L55)
+Defined in: [react-pacer/src/async-queuer/useAsyncQueuer.ts:54](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-queuer/useAsyncQueuer.ts#L54)
 
 A lower-level React hook that creates an `AsyncQueuer` instance for managing an async queue of items.
 
-This hook provides a flexible, state-management agnostic way to handle queued async operations.
-It returns a queuer instance with methods to add items, control queue execution, and monitor queue state.
-
-The queue can be configured with:
-- Maximum concurrent operations
-- Maximum queue size
-- Processing function for queue items
-- Various lifecycle callbacks
-
-The hook returns an object containing methods to:
-- Add/remove items from the queue
-- Start/stop queue processing
-- Get queue status and items
-- Register event handlers
-- Control execution throttling
+Features:
+- Priority queue support via getPriority option
+- Configurable concurrency limit
+- Task success/error/completion callbacks
+- FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
+- Pause/resume task processing
+- Task cancellation
+- Item expiration to clear stale items from the queue
+
+Tasks are processed concurrently up to the configured concurrency limit. When a task completes,
+the next pending task is processed if below the concurrency limit.
+
+Error Handling:
+- If an `onError` handler is provided, it will be called with the error and queuer instance
+- If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+- If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+- Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+- The error state can be checked using the underlying AsyncQueuer instance
 
 ## Type Parameters
 
-• **TValue**
+• **TFn** *extends* `AsyncQueuerFn`
 
 ## Parameters
 
 ### options
 
-`AsyncQueuerOptions`\<`TValue`\> = `{}`
+`AsyncQueuerOptions`\<`TFn`\> = `{}`
 
 ## Returns
 
-`AsyncQueuer`\<`TValue`\>
+`AsyncQueuer`\<`TFn`\>
 
 ## Example
 
@@ -54,24 +57,17 @@ const asyncQueuer = useAsyncQueuer({
   concurrency: 2,
   maxSize: 100,
   started: false,
+  onSuccess: (result) => {
+    console.log('Item processed:', result);
+  },
+  onError: (error) => {
+    console.error('Processing failed:', error);
+  }
 });
 
 // Add items to queue
 asyncQueuer.addItem(newItem);
 
 // Start processing
 asyncQueuer.start();
-
-// Monitor queue state
-const isPending = !asyncQueuer.isIdle();
-const itemCount = asyncQueuer.size();
-
-// Handle results
-asyncQueuer.onSuccess((result) => {
-  console.log('Item processed:', result);
-});
-
-asyncQueuer.onError((error) => {
-  console.error('Processing failed:', error);
-});
 ```

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

@@ -11,7 +11,7 @@ title: useAsyncRateLimiter
 function useAsyncRateLimiter<TFn>(fn, options): AsyncRateLimiter<TFn>
 ```
 
-Defined in: [react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts:54](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts#L54)
+Defined in: [react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts:67](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts#L67)
 
 A low-level React hook that creates an `AsyncRateLimiter` instance to limit how many times an async function can execute within a time window.
 
@@ -32,6 +32,14 @@ The rate limiter supports two types of windows:
 - 'sliding': A rolling window that allows executions as old ones expire. This provides a more
   consistent rate of execution over time.
 
+Error Handling:
+- If an `onError` handler is provided, it will be called with the error and rate limiter instance
+- If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+- If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+- Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+- The error state can be checked using the underlying AsyncRateLimiter instance
+- Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler
+
 ## Type Parameters
 
 • **TFn** *extends* `AnyAsyncFunction`
@@ -73,7 +81,12 @@ const { maybeExecute } = useAsyncRateLimiter(
   {
     limit: 10,
     window: 60000, // 10 calls per minute
-    onReject: (info) => console.log(`Rate limit exceeded: ${info.nextValidTime - Date.now()}ms until next window`)
+    onReject: (rateLimiter) => {
+      console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
+    },
+    onError: (error) => {
+      console.error('API call failed:', error);
+    }
   }
 );
 ```

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

@@ -11,7 +11,7 @@ title: useAsyncThrottler
 function useAsyncThrottler<TFn>(fn, options): AsyncThrottler<TFn>
 ```
 
-Defined in: [react-pacer/src/async-throttler/useAsyncThrottler.ts:44](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-throttler/useAsyncThrottler.ts#L44)
+Defined in: [react-pacer/src/async-throttler/useAsyncThrottler.ts:55](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-throttler/useAsyncThrottler.ts#L55)
 
 A low-level React hook that creates an `AsyncThrottler` instance to limit how often an async function can execute.
 
@@ -22,6 +22,17 @@ Async throttling ensures an async function executes at most once within a specif
 regardless of how many times it is called. This is useful for rate-limiting expensive API calls,
 database operations, or other async tasks.
 
+Unlike the non-async Throttler, this async version supports returning values from the throttled function,
+making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
+instead of setting the result on a state variable from within the throttled function.
+
+Error Handling:
+- If an `onError` handler is provided, it will be called with the error and throttler instance
+- If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+- If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+- Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+- The error state can be checked using the underlying AsyncThrottler instance
+
 ## Type Parameters
 
 • **TFn** *extends* `AnyAsyncFunction`
@@ -43,21 +54,22 @@ database operations, or other async tasks.
 ## Example
 
 ```tsx
-// Basic API call throttling
+// Basic API call throttling with return value
 const { maybeExecute } = useAsyncThrottler(
   async (id: string) => {
     const data = await api.fetchData(id);
-    return data;
+    return data; // Return value is preserved
   },
   { wait: 1000 }
 );
 
-// With state management
+// With state management and return value
 const [data, setData] = useState(null);
 const { maybeExecute } = useAsyncThrottler(
   async (query) => {
     const result = await searchAPI(query);
     setData(result);
+    return result; // Return value can be used by the caller
   },
   {
     wait: 2000,

docs/framework/solid/reference/functions/createasyncdebouncer.md

@@ -11,16 +11,30 @@ title: createAsyncDebouncer
 function createAsyncDebouncer<TFn>(fn, initialOptions): SolidAsyncDebouncer<TFn>
 ```
 
-Defined in: [async-debouncer/createAsyncDebouncer.ts:59](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-debouncer/createAsyncDebouncer.ts#L59)
+Defined in: [async-debouncer/createAsyncDebouncer.ts:77](https://github.com/TanStack/pacer/blob/main/packages/solid-pacer/src/async-debouncer/createAsyncDebouncer.ts#L77)
 
 A low-level Solid hook that creates an `AsyncDebouncer` instance to delay execution of an async function.
 
 This hook is designed to be flexible and state-management agnostic - it simply returns a debouncer instance that
 you can integrate with any state management solution (createSignal, etc).
 
 Async debouncing ensures that an async function only executes after a specified delay has passed since its last invocation.
-This is useful for handling fast-changing inputs like search fields, form validation, or any scenario where you want to
-wait for user input to settle before making expensive async calls.
+Each new invocation resets the delay timer. This is useful for handling frequent events like window resizing
+or input changes where you only want to execute the handler after the events have stopped occurring.
+
+Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until
+the function stops being called for the specified delay period.
+
+Unlike the non-async Debouncer, this async version supports returning values from the debounced function,
+making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
+instead of setting the result on a state variable from within the debounced function.
+
+Error Handling:
+- If an `onError` handler is provided, it will be called with the error and debouncer instance
+- If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+- If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+- Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+- The error state can be checked using the underlying AsyncDebouncer instance
 
 ## Type Parameters
 
@@ -61,6 +75,11 @@ const { maybeExecute } = createAsyncDebouncer(
   },
   {
     wait: 300,
+    leading: true,   // Execute immediately on first call
+    trailing: false, // Skip trailing edge updates
+    onError: (error) => {
+      console.error('API call failed:', error);
+    }
   }
 );
 ```