feat: more queuer hooks and first react query examples

.changeset/tricky-pants-hear-react.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/react-pacer': minor
+---
+
+- breaking: renamed `useQueuerState` hook to `useQueuedState`
+- breaking: changed return signature of `useQueuedState` to include the `addItem` function
+- feat: add `useQueuedValue` hook

.changeset/tricky-pants-hear-solid.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/solid-pacer': minor
+---
+
+- breaking: renamed `createQueuerState` hook to `createQueuedState`
+- breaking: changed return signature of `createQueuedState` to include the `addItem` function
+- feat: add `createQueuedValue` hook

.changeset/tricky-pants-hear.md

@@ -0,0 +1,15 @@
+---
+'@tanstack/pacer': minor
+---
+
+- feat: add queuer expiration feature to `AsyncQueuer` and `Queuer`
+- feat: add return values and types to `AsyncDebouncer`, `AsyncThrottler`, and `AsyncRateLimiter`
+- feat: standardize `onSuccess`, `onSettled`, and `onError` in `AsyncDebouncer`, `AsyncThrottler`, and `AsyncRateLimiter`
+- feat: replace `getExecutionCount` with `getSuccessCount`, `getErrorCount`, and `getSettleCount` in `AsyncDebouncer`, `AsyncThrottler`, and `AsyncRateLimiter`
+- feat: add `getIsPending`, `getIsExecuting`, and `getLastResult` to `AsyncThrottler`
+- feat: add `leading` and `trailing` options to `AsyncThrottler`
+- breaking: rename `onExecute` to `onSettled` in `AsyncDebouncer`, `AsyncThrottler`, and `AsyncRateLimiter`
+- breaking: Set `started` to `true` by default in `AsyncQueuer` and `Queuer`
+- breaking: Simplified generics to just use `TFn` instead of `TFn, TArgs` in debouncers, throttlers, and rate limiters
+- fix: fixed leading and trailing edge behavior of `Debouncer` and `AsyncDebouncer`
+- fix: fixed `getIsPending` to return correct value in `AsyncDebouncer`

README.md

@@ -74,7 +74,7 @@ Take control of your application's timing with TanStack Pacer's rate limiting, t
   - Perform deep equality checks between values
   - Create custom comparison logic for specific needs
 - **Convenient Hooks**
-  - Reduce boilerplate code with pre-built hooks like `useDebouncedCallback`, `useThrottledValue`, and `useQueuerState`, and more.
+  - Reduce boilerplate code with pre-built hooks like `useDebouncedCallback`, `useThrottledValue`, and `useQueuedState`, and more.
 - **Type Safety**
   - Full type safety with TypeScript that makes sure that your functions will always be called with the correct arguments
   - Generics for flexible and reusable utilities

docs/config.json

@@ -365,7 +365,7 @@
               "to": "framework/react/reference/functions/usequeuer"
             },
             {
-              "label": "useQueuerState",
+              "label": "useQueuedState",
               "to": "framework/react/reference/functions/usequeuerstate"
             },
             {
@@ -613,16 +613,20 @@
               "to": "framework/react/examples/useQueuer"
             },
             {
-              "label": "useQueuerState",
-              "to": "framework/react/examples/useQueuerState"
+              "label": "useQueuedState",
+              "to": "framework/react/examples/useQueuedState"
+            },
+            {
+              "label": "useQueuedValue",
+              "to": "framework/react/examples/useQueuedValue"
             },
             {
               "label": "useAsyncQueuer",
               "to": "framework/react/examples/useAsyncQueuer"
             },
             {
-              "label": "useAsyncQueuerState",
-              "to": "framework/react/examples/useAsyncQueuerState"
+              "label": "useAsyncQueuedState",
+              "to": "framework/react/examples/useAsyncQueuedState"
             }
           ]
         },
@@ -644,6 +648,29 @@
           ]
         }
       ]
+    },
+    {
+      "label": "Advanced Examples",
+      "children": [],
+      "frameworks": [
+        {
+          "label": "react",
+          "children": [
+            {
+              "label": "React Query Debounced Prefetch",
+              "to": "framework/react/examples/react-query-debounced-prefetch"
+            },
+            {
+              "label": "React Query Throttled Prefetch",
+              "to": "framework/react/examples/react-query-throttled-prefetch"
+            },
+            {
+              "label": "React Query Queued Prefetch",
+              "to": "framework/react/examples/react-query-queued-prefetch"
+            }
+          ]
+        }
+      ]
     }
   ]
 }

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

@@ -8,10 +8,10 @@ title: useAsyncDebouncer
 # Function: useAsyncDebouncer()
 
 ```ts
-function useAsyncDebouncer<TFn, TArgs>(fn, options): AsyncDebouncer<TFn, TArgs>
+function useAsyncDebouncer<TFn>(fn, options): AsyncDebouncer<TFn>
 ```
 
-Defined in: [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:42](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-debouncer/useAsyncDebouncer.ts#L42)
 
 A low-level React hook that creates an `AsyncDebouncer` instance to delay execution of an async function.
 
@@ -26,8 +26,6 @@ wait for user input to settle before making expensive async calls.
 
 • **TFn** *extends* `AnyAsyncFunction`
 
-• **TArgs** *extends* `any`[]
-
 ## Parameters
 
 ### fn
@@ -36,11 +34,11 @@ wait for user input to settle before making expensive async calls.
 
 ### options
 
-`AsyncDebouncerOptions`\<`TFn`, `TArgs`\>
+`AsyncDebouncerOptions`\<`TFn`\>
 
 ## Returns
 
-`AsyncDebouncer`\<`TFn`, `TArgs`\>
+`AsyncDebouncer`\<`TFn`\>
 
 ## Example
 

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

@@ -1,17 +1,17 @@
 ---
-id: useAsyncQueuerState
-title: useAsyncQueuerState
+id: useAsyncQueuedState
+title: useAsyncQueuedState
 ---
 
 <!-- DO NOT EDIT: this page is autogenerated from the type comments -->
 
-# Function: useAsyncQueuerState()
+# Function: useAsyncQueuedState()
 
 ```ts
-function useAsyncQueuerState<TValue>(options): [() => Promise<TValue>[], AsyncQueuer<TValue>]
+function useAsyncQueuedState<TValue>(options): [() => Promise<TValue>[], AsyncQueuer<TValue>]
 ```
 
-Defined in: [async-queuer/useAsyncQueuerState.ts:53](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-queuer/useAsyncQueuerState.ts#L53)
+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)
 
 A higher-level React hook that creates an `AsyncQueuer` instance with built-in state management.
 
@@ -50,7 +50,7 @@ The state will automatically update whenever items are:
 
 ```tsx
 // Create a queue with state management
-const [queueItems, asyncQueuer] = useAsyncQueuerState({
+const [queueItems, asyncQueuer] = useAsyncQueuedState({
   concurrency: 2,
   maxSize: 100,
   started: true

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

@@ -11,7 +11,7 @@ title: useAsyncQueuer
 function useAsyncQueuer<TValue>(options): AsyncQueuer<TValue>
 ```
 
-Defined in: [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:55](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-queuer/useAsyncQueuer.ts#L55)
 
 A lower-level React hook that creates an `AsyncQueuer` instance for managing an async queue of items.
 

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

@@ -8,10 +8,10 @@ title: useAsyncRateLimiter
 # Function: useAsyncRateLimiter()
 
 ```ts
-function useAsyncRateLimiter<TFn, TArgs>(fn, options): AsyncRateLimiter<TFn, TArgs>
+function useAsyncRateLimiter<TFn>(fn, options): AsyncRateLimiter<TFn>
 ```
 
-Defined in: [async-rate-limiter/useAsyncRateLimiter.ts:43](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts#L43)
+Defined in: [react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts:43](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-rate-limiter/useAsyncRateLimiter.ts#L43)
 
 A low-level React hook that creates an `AsyncRateLimiter` instance to limit how many times an async function can execute within a time window.
 
@@ -26,8 +26,6 @@ managing resource constraints, or controlling bursts of async operations.
 
 • **TFn** *extends* `AnyAsyncFunction`
 
-• **TArgs** *extends* `any`[]
-
 ## Parameters
 
 ### fn
@@ -36,11 +34,11 @@ managing resource constraints, or controlling bursts of async operations.
 
 ### options
 
-`AsyncRateLimiterOptions`\<`TFn`, `TArgs`\>
+`AsyncRateLimiterOptions`\<`TFn`\>
 
 ## Returns
 
-`AsyncRateLimiter`\<`TFn`, `TArgs`\>
+`AsyncRateLimiter`\<`TFn`\>
 
 ## Example
 

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

@@ -8,10 +8,10 @@ title: useAsyncThrottler
 # Function: useAsyncThrottler()
 
 ```ts
-function useAsyncThrottler<TFn, TArgs>(fn, options): AsyncThrottler<TFn, TArgs>
+function useAsyncThrottler<TFn>(fn, options): AsyncThrottler<TFn>
 ```
 
-Defined in: [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:44](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-throttler/useAsyncThrottler.ts#L44)
 
 A low-level React hook that creates an `AsyncThrottler` instance to limit how often an async function can execute.
 
@@ -26,8 +26,6 @@ database operations, or other async tasks.
 
 • **TFn** *extends* `AnyAsyncFunction`
 
-• **TArgs** *extends* `any`[]
-
 ## Parameters
 
 ### fn
@@ -36,11 +34,11 @@ database operations, or other async tasks.
 
 ### options
 
-`AsyncThrottlerOptions`\<`TFn`, `TArgs`\>
+`AsyncThrottlerOptions`\<`TFn`\>
 
 ## Returns
 
-`AsyncThrottler`\<`TFn`, `TArgs`\>
+`AsyncThrottler`\<`TFn`\>
 
 ## Example
 

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

@@ -8,10 +8,10 @@ title: useDebouncedCallback
 # Function: useDebouncedCallback()
 
 ```ts
-function useDebouncedCallback<TFn, TArgs>(fn, options): (...args) => void
+function useDebouncedCallback<TFn>(fn, options): (...args) => void
 ```
 
-Defined in: [debouncer/useDebouncedCallback.ts:42](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncedCallback.ts#L42)
+Defined in: [react-pacer/src/debouncer/useDebouncedCallback.ts:42](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncedCallback.ts#L42)
 
 A React hook that creates a debounced version of a callback function.
 This hook is essentially a wrapper around the basic `debounce` function
@@ -36,8 +36,6 @@ Consider using the `useDebouncer` hook instead.
 
 • **TFn** *extends* `AnyFunction`
 
-• **TArgs** *extends* `any`[]
-
 ## Parameters
 
 ### fn
@@ -46,7 +44,7 @@ Consider using the `useDebouncer` hook instead.
 
 ### options
 
-`DebouncerOptions`\<`TFn`, `TArgs`\>
+`DebouncerOptions`\<`TFn`\>
 
 ## Returns
 
@@ -56,7 +54,7 @@ Consider using the `useDebouncer` hook instead.
 
 #### args
 
-...`TArgs`
+...`Parameters`\<`TFn`\>
 
 ### Returns
 

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

@@ -8,10 +8,10 @@ title: useDebouncedState
 # Function: useDebouncedState()
 
 ```ts
-function useDebouncedState<TValue>(value, options): [TValue, Dispatch<SetStateAction<TValue>>, Debouncer<Dispatch<SetStateAction<TValue>>, [TValue]>]
+function useDebouncedState<TValue>(value, options): [TValue, Dispatch<SetStateAction<TValue>>, Debouncer<Dispatch<SetStateAction<TValue>>>]
 ```
 
-Defined in: [debouncer/useDebouncedState.ts:38](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncedState.ts#L38)
+Defined in: [react-pacer/src/debouncer/useDebouncedState.ts:38](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncedState.ts#L38)
 
 A React hook that creates a debounced state value, combining React's useState with debouncing functionality.
 This hook provides both the current debounced value and methods to update it.
@@ -38,11 +38,11 @@ The hook returns a tuple containing:
 
 ### options
 
-`DebouncerOptions`\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>, \[`SetStateAction`\<`TValue`\>\]\>
+`DebouncerOptions`\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>\>
 
 ## Returns
 
-\[`TValue`, `Dispatch`\<`SetStateAction`\<`TValue`\>\>, `Debouncer`\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>, \[`TValue`\]\>\]
+\[`TValue`, `Dispatch`\<`SetStateAction`\<`TValue`\>\>, `Debouncer`\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>\>\]
 
 ## Example
 

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

@@ -8,10 +8,10 @@ title: useDebouncedValue
 # Function: useDebouncedValue()
 
 ```ts
-function useDebouncedValue<TValue>(value, options): [TValue, Debouncer<Dispatch<SetStateAction<TValue>>, [TValue]>]
+function useDebouncedValue<TValue>(value, options): [TValue, Debouncer<Dispatch<SetStateAction<TValue>>>]
 ```
 
-Defined in: [debouncer/useDebouncedValue.ts:41](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncedValue.ts#L41)
+Defined in: [react-pacer/src/debouncer/useDebouncedValue.ts:41](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncedValue.ts#L41)
 
 A React hook that creates a debounced value that updates only after a specified delay.
 Unlike useDebouncedState, this hook automatically tracks changes to the input value
@@ -25,9 +25,9 @@ This is useful for deriving debounced values from props or state that change fre
 like search queries or form inputs, where you want to limit how often downstream effects
 or calculations occur.
 
-The hook returns a tuple containing:
-- The current debounced value
-- The debouncer instance with control methods
+The hook returns the current debounced value and the underlying debouncer instance.
+The debouncer instance can be used to access additional functionality like cancellation
+and execution counts.
 
 ## Type Parameters
 
@@ -41,11 +41,11 @@ The hook returns a tuple containing:
 
 ### options
 
-`DebouncerOptions`\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>, \[`SetStateAction`\<`TValue`\>\]\>
+`DebouncerOptions`\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>\>
 
 ## Returns
 
-\[`TValue`, `Debouncer`\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>, \[`TValue`\]\>\]
+\[`TValue`, `Debouncer`\<`Dispatch`\<`SetStateAction`\<`TValue`\>\>\>\]
 
 ## Example
 

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

@@ -8,10 +8,10 @@ title: useDebouncer
 # Function: useDebouncer()
 
 ```ts
-function useDebouncer<TFn, TArgs>(fn, options): Debouncer<TFn, TArgs>
+function useDebouncer<TFn>(fn, options): Debouncer<TFn>
 ```
 
-Defined in: [debouncer/useDebouncer.ts:42](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncer.ts#L42)
+Defined in: [react-pacer/src/debouncer/useDebouncer.ts:42](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/debouncer/useDebouncer.ts#L42)
 
 A React hook that creates and manages a Debouncer instance.
 
@@ -31,8 +31,6 @@ timer resets and starts waiting again.
 
 • **TFn** *extends* `AnyFunction`
 
-• **TArgs** *extends* `any`[]
-
 ## Parameters
 
 ### fn
@@ -41,11 +39,11 @@ timer resets and starts waiting again.
 
 ### options
 
-`DebouncerOptions`\<`TFn`, `TArgs`\>
+`DebouncerOptions`\<`TFn`\>
 
 ## Returns
 
-`Debouncer`\<`TFn`, `TArgs`\>
+`Debouncer`\<`TFn`\>
 
 ## Example