feat: Enhance async utilities with breaking changes and new features (#40)

- Removed `isRunning` state from `Batcher` and `AsyncBatcher` utilities.
- Updated `flush()` method in `AsyncDebouncer`, `AsyncThrottler`, and `AsyncQueuer` to return Promises.
- Introduced `flushAsBatch` methods in `Queuer` and `AsyncQueuer` for batch processing.
- Added `isExceeded` and `status` properties to `RateLimiter` and `AsyncRateLimiter` for improved tracking.
- Enhanced error handling in `AsyncDebouncer` and `AsyncThrottler` with promise rejection support.
- Improved timeout management in rate limiters with automatic cleanup of expired execution times.

Author: KevinVandy

.changeset/tame-spies-wish.md

@@ -0,0 +1,12 @@
+---
+'@tanstack/pacer': minor
+'@tanstack/react-pacer': minor
+'@tanstack/solid-pacer': minor
+---
+
+breaking: Removed `isRunning` state from `Batcher` and `AsyncBatcher` utils, and also removed `start` and `stop` methods
+breaking: Changed `flush()` method in `AsyncDebouncer`, `AsyncThrottler`, and `AsyncQueuer` to return Promises instead of void
+feat: Added `flushAsBatch` methods to the `Queuer` and `AsyncQueuer` utils
+feat: Added `isExceeded` and `status` state properties to `RateLimiter` and `AsyncRateLimiter` for better rate limit tracking
+feat: Enhanced error handling in `AsyncDebouncer` and `AsyncThrottler` with proper promise rejection support
+feat: Improved timeout management in rate limiters with automatic cleanup of expired execution times

docs/reference/classes/asyncbatcher.md

@@ -7,7 +7,7 @@ title: AsyncBatcher
 
 # Class: AsyncBatcher\<TValue\>
 
-Defined in: [async-batcher.ts:229](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L229)
+Defined in: [async-batcher.ts:224](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L224)
 
 A class that collects items and processes them in batches asynchronously.
 
@@ -82,7 +82,7 @@ batcher.addItem(2);
 new AsyncBatcher<TValue>(fn, initialOptions): AsyncBatcher<TValue>
 ```
 
-Defined in: [async-batcher.ts:236](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L236)
+Defined in: [async-batcher.ts:231](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L231)
 
 #### Parameters
 
@@ -106,7 +106,7 @@ Defined in: [async-batcher.ts:236](https://github.com/TanStack/pacer/blob/main/p
 options: AsyncBatcherOptionsWithOptionalCallbacks<TValue>;
 ```
 
-Defined in: [async-batcher.ts:233](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L233)
+Defined in: [async-batcher.ts:228](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L228)
 
 ***
 
@@ -116,7 +116,7 @@ Defined in: [async-batcher.ts:233](https://github.com/TanStack/pacer/blob/main/p
 readonly store: Store<Readonly<AsyncBatcherState<TValue>>>;
 ```
 
-Defined in: [async-batcher.ts:230](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L230)
+Defined in: [async-batcher.ts:225](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L225)
 
 ## Methods
 
@@ -126,7 +126,7 @@ Defined in: [async-batcher.ts:230](https://github.com/TanStack/pacer/blob/main/p
 addItem(item): void
 ```
 
-Defined in: [async-batcher.ts:287](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L287)
+Defined in: [async-batcher.ts:282](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L282)
 
 Adds an item to the async batcher
 If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed
@@ -149,7 +149,7 @@ If the batch size is reached, timeout occurs, or shouldProcess returns true, the
 clear(): void
 ```
 
-Defined in: [async-batcher.ts:407](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L407)
+Defined in: [async-batcher.ts:384](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L384)
 
 Removes all items from the async batcher
 
@@ -165,7 +165,7 @@ Removes all items from the async batcher
 flush(): Promise<any>
 ```
 
-Defined in: [async-batcher.ts:363](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L363)
+Defined in: [async-batcher.ts:358](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L358)
 
 Processes the current batch of items immediately
 
@@ -181,7 +181,7 @@ Processes the current batch of items immediately
 peekAllItems(): TValue[]
 ```
 
-Defined in: [async-batcher.ts:389](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L389)
+Defined in: [async-batcher.ts:366](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L366)
 
 Returns a copy of all items in the async batcher
 
@@ -197,7 +197,7 @@ Returns a copy of all items in the async batcher
 peekFailedItems(): TValue[]
 ```
 
-Defined in: [async-batcher.ts:393](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L393)
+Defined in: [async-batcher.ts:370](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L370)
 
 #### Returns
 
@@ -211,7 +211,7 @@ Defined in: [async-batcher.ts:393](https://github.com/TanStack/pacer/blob/main/p
 reset(): void
 ```
 
-Defined in: [async-batcher.ts:414](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L414)
+Defined in: [async-batcher.ts:391](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L391)
 
 Resets the async batcher state to its default values
 
@@ -227,7 +227,7 @@ Resets the async batcher state to its default values
 setOptions(newOptions): void
 ```
 
-Defined in: [async-batcher.ts:251](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L251)
+Defined in: [async-batcher.ts:246](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L246)
 
 Updates the async batcher options
 
@@ -240,35 +240,3 @@ Updates the async batcher options
 #### Returns
 
 `void`
-
-***
-
-### start()
-
-```ts
-start(): void
-```
-
-Defined in: [async-batcher.ts:379](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L379)
-
-Starts the async batcher and processes any pending items
-
-#### Returns
-
-`void`
-
-***
-
-### stop()
-
-```ts
-stop(): void
-```
-
-Defined in: [async-batcher.ts:371](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-batcher.ts#L371)
-
-Stops the async batcher from processing batches
-
-#### Returns
-
-`void`

docs/reference/classes/asyncdebouncer.md

@@ -66,7 +66,7 @@ const results = await asyncDebouncer.maybeExecute(inputElement.value);
 new AsyncDebouncer<TFn>(fn, initialOptions): AsyncDebouncer<TFn>
 ```
 
-Defined in: [async-debouncer.ts:180](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L180)
+Defined in: [async-debouncer.ts:181](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L181)
 
 #### Parameters
 
@@ -110,7 +110,7 @@ Defined in: [async-debouncer.ts:170](https://github.com/TanStack/pacer/blob/main
 cancel(): void
 ```
 
-Defined in: [async-debouncer.ts:363](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L363)
+Defined in: [async-debouncer.ts:382](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L382)
 
 Cancels any pending execution or aborts any execution in progress
 
@@ -123,16 +123,16 @@ Cancels any pending execution or aborts any execution in progress
 ### flush()
 
 ```ts
-flush(): void
+flush(): Promise<undefined | ReturnType<TFn>>
 ```
 
-Defined in: [async-debouncer.ts:325](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L325)
+Defined in: [async-debouncer.ts:327](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L327)
 
 Processes the current pending execution immediately
 
 #### Returns
 
-`void`
+`Promise`\<`undefined` \| `ReturnType`\<`TFn`\>\>
 
 ***
 
@@ -142,7 +142,7 @@ Processes the current pending execution immediately
 maybeExecute(...args): Promise<undefined | ReturnType<TFn>>
 ```
 
-Defined in: [async-debouncer.ts:254](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L254)
+Defined in: [async-debouncer.ts:255](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L255)
 
 Attempts to execute the debounced function.
 If a call is already in progress, it will be queued.
@@ -178,7 +178,7 @@ The error from the debounced function if no onError handler is configured
 reset(): void
 ```
 
-Defined in: [async-debouncer.ts:372](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L372)
+Defined in: [async-debouncer.ts:391](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L391)
 
 Resets the debouncer state to its default values
 
@@ -194,7 +194,7 @@ Resets the debouncer state to its default values
 setOptions(newOptions): void
 ```
 
-Defined in: [async-debouncer.ts:195](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L195)
+Defined in: [async-debouncer.ts:196](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-debouncer.ts#L196)
 
 Updates the async debouncer options
 

docs/reference/classes/asyncqueuer.md

@@ -156,7 +156,7 @@ queuer.addItem('task2', 'front');
 clear(): void
 ```
 
-Defined in: [async-queuer.ts:686](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L686)
+Defined in: [async-queuer.ts:704](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L704)
 
 Removes all pending items from the queue. Does not affect active tasks.
 
@@ -172,7 +172,7 @@ Removes all pending items from the queue. Does not affect active tasks.
 execute(position?): Promise<any>
 ```
 
-Defined in: [async-queuer.ts:520](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L520)
+Defined in: [async-queuer.ts:526](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L526)
 
 Removes and returns the next item from the queue and executes the task function with it.
 
@@ -199,10 +199,10 @@ queuer.execute('back');
 ### flush()
 
 ```ts
-flush(numberOfItems, position?): void
+flush(numberOfItems, position?): Promise<void>
 ```
 
-Defined in: [async-queuer.ts:555](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L555)
+Defined in: [async-queuer.ts:561](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L561)
 
 Processes a specified number of items to execute immediately with no wait time
 If no numberOfItems is provided, all items will be processed
@@ -219,7 +219,30 @@ If no numberOfItems is provided, all items will be processed
 
 #### Returns
 
-`void`
+`Promise`\<`void`\>
+
+***
+
+### flushAsBatch()
+
+```ts
+flushAsBatch(batchFunction): Promise<void>
+```
+
+Defined in: [async-queuer.ts:575](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L575)
+
+Processes all items in the queue as a batch using the provided function
+The queue is cleared after processing
+
+#### Parameters
+
+##### batchFunction
+
+(`items`) => `Promise`\<`any`\>
+
+#### Returns
+
+`Promise`\<`void`\>
 
 ***
 
@@ -261,7 +284,7 @@ queuer.getNextItem('back');
 peekActiveItems(): TValue[]
 ```
 
-Defined in: [async-queuer.ts:649](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L649)
+Defined in: [async-queuer.ts:667](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L667)
 
 Returns the items currently being processed (active tasks).
 
@@ -277,7 +300,7 @@ Returns the items currently being processed (active tasks).
 peekAllItems(): TValue[]
 ```
 
-Defined in: [async-queuer.ts:642](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L642)
+Defined in: [async-queuer.ts:660](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L660)
 
 Returns a copy of all items in the queue, including active and pending items.
 
@@ -293,7 +316,7 @@ Returns a copy of all items in the queue, including active and pending items.
 peekNextItem(position): undefined | TValue
 ```
 
-Defined in: [async-queuer.ts:632](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L632)
+Defined in: [async-queuer.ts:650](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L650)
 
 Returns the next item in the queue without removing it.
 
@@ -322,7 +345,7 @@ queuer.peekNextItem('back'); // back
 peekPendingItems(): TValue[]
 ```
 
-Defined in: [async-queuer.ts:656](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L656)
+Defined in: [async-queuer.ts:674](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L674)
 
 Returns the items waiting to be processed (pending tasks).
 
@@ -338,7 +361,7 @@ Returns the items waiting to be processed (pending tasks).
 reset(): void
 ```
 
-Defined in: [async-queuer.ts:694](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L694)
+Defined in: [async-queuer.ts:712](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L712)
 
 Resets the queuer state to its default values
 
@@ -376,7 +399,7 @@ Updates the queuer options. New options are merged with existing options.
 start(): void
 ```
 
-Defined in: [async-queuer.ts:663](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L663)
+Defined in: [async-queuer.ts:681](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L681)
 
 Starts processing items in the queue. If already running, does nothing.
 
@@ -392,7 +415,7 @@ Starts processing items in the queue. If already running, does nothing.
 stop(): void
 ```
 
-Defined in: [async-queuer.ts:673](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L673)
+Defined in: [async-queuer.ts:691](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-queuer.ts#L691)
 
 Stops processing items in the queue. Does not clear the queue.