@tanstack/pacer 0.21.0 → 0.22.0

package/src/async-queuer.ts

@@ -431,25 +431,36 @@ export class AsyncQueuer<TValue> {
     this.#checkExpiredItems()
 
     // Process items concurrently up to the concurrency limit
-    const activeItems = this.store.state.activeItems
+    let scheduledAsyncWork = false
+    const activeItems = [...this.store.state.activeItems]
     while (
       activeItems.length < this.#getConcurrency() &&
       this.store.state.items.length > 0
     ) {
       const nextItem = this.peekNextItem()
-      if (!nextItem) {
+      if (nextItem === undefined) {
         break
       }
       activeItems.push(nextItem)
       this.#setState({
-        activeItems,
+        activeItems: [...activeItems],
       })
+      scheduledAsyncWork = true
       ;(async () => {
-        await this.execute()
+        try {
+          await this.execute()
+        } catch {
+          // errors are already surfaced via onError/errorCount (and rethrown to
+          // direct execute/flush callers); swallowing here prevents unhandled
+          // rejections and keeps the processing chain alive
+        }
 
         const wait = this.#getWait()
         if (wait > 0) {
-          const timeoutId = setTimeout(() => this.#tick(), wait)
+          const timeoutId = setTimeout(() => {
+            this.#timeoutIds.delete(timeoutId)
+            this.#tick()
+          }, wait)
           this.#timeoutIds.add(timeoutId)
           return
         }
@@ -458,12 +469,17 @@ export class AsyncQueuer<TValue> {
       })()
     }
 
-    this.#setState({ pendingTick: false })
+    // pendingTick must stay true while executions or wait timers are pending so
+    // that addItem does not trigger an extra tick that bypasses the wait period
+    if (!scheduledAsyncWork) {
+      this.#setState({ pendingTick: false })
+    }
   }
 
   /**
    * Adds an item to the queue. If the queue is full, the item is rejected and onReject is called.
    * Items can be inserted based on priority or at the front/back depending on configuration.
+   * `undefined` cannot be queued (it is the internal "no item" sentinel) and is always rejected.
    *
    * @example
    * ```ts
@@ -480,6 +496,16 @@ export class AsyncQueuer<TValue> {
       addItemCount: this.store.state.addItemCount + 1,
     })
 
+    // undefined is the internal "no item" sentinel (peekNextItem/getNextItem);
+    // queuing it would wedge the processing loop and block items behind it
+    if (item === undefined) {
+      this.#setState({
+        rejectionCount: this.store.state.rejectionCount + 1,
+      })
+      this.options.onReject?.(item, this)
+      return false
+    }
+
     if (this.store.state.items.length >= (this.options.maxSize ?? Infinity)) {
       this.#setState({
         rejectionCount: this.store.state.rejectionCount + 1,
@@ -492,7 +518,7 @@ export class AsyncQueuer<TValue> {
     const priority =
       this.options.getPriority !== defaultOptions.getPriority
         ? this.options.getPriority!(item)
-        : (item as any).priority
+        : (item as any)?.priority
 
     const items = this.store.state.items
     const itemTimestamps = this.store.state.itemTimestamps
@@ -503,7 +529,7 @@ export class AsyncQueuer<TValue> {
         const existingPriority =
           this.options.getPriority !== defaultOptions.getPriority
             ? this.options.getPriority!(existing)
-            : (existing as any).priority
+            : (existing as any)?.priority
         return existingPriority < priority
       })
 
@@ -616,10 +642,10 @@ export class AsyncQueuer<TValue> {
         isExecuting: true,
       })
       try {
-        const currentAsyncRetryer = new AsyncRetryer(this.fn, {
-          ...this.options.asyncRetryerOptions,
-          key: `${this.key}-retryer-${currentExecuteCount}`,
-        })
+        const currentAsyncRetryer = new AsyncRetryer(
+          this.fn,
+          this.options.asyncRetryerOptions,
+        )
         this.asyncRetryers.set(currentExecuteCount, currentAsyncRetryer)
         const lastResult = await currentAsyncRetryer.execute(item) // EXECUTE!
         this.#setState({
@@ -637,11 +663,17 @@ export class AsyncQueuer<TValue> {
         }
       } finally {
         this.asyncRetryers.delete(currentExecuteCount) // dispose retryer
+        // remove only one occurrence so duplicate item values keep accurate
+        // concurrency accounting
+        const remainingActiveItems = [...this.store.state.activeItems]
+        const activeItemIndex = remainingActiveItems.indexOf(item)
+        if (activeItemIndex !== -1) {
+          remainingActiveItems.splice(activeItemIndex, 1)
+        }
         this.#setState({
-          activeItems: this.store.state.activeItems.filter(
-            (activeItem) => activeItem !== item,
-          ),
-          isExecuting: false,
+          activeItems: remainingActiveItems,
+          // other executions may still be in flight (concurrency > 1 or flush)
+          isExecuting: this.asyncRetryers.size > 0,
           settledCount: this.store.state.settledCount + 1,
         })
         this.options.onSettled?.(item, this)
@@ -658,10 +690,33 @@ export class AsyncQueuer<TValue> {
     numberOfItems: number = this.store.state.items.length,
     position?: QueuePosition,
   ): Promise<void> => {
-    this.#clearTimeouts() // clear any pending timeouts
-    await Promise.all(
+    this.#clearTimeouts() // clear any pending timeouts (kills the tick chain)
+    const results = await Promise.allSettled(
       Array.from({ length: numberOfItems }, () => this.execute(position)),
     )
+    // the tick chain was killed above; restart it so remaining and future items
+    // process even when a flushed task rejected. Remaining items resume with the
+    // normal wait spacing after the flushed executions.
+    this.#setState({ pendingTick: false })
+    if (this.store.state.isRunning && this.store.state.items.length > 0) {
+      const wait = this.#getWait()
+      if (wait > 0) {
+        this.#setState({ pendingTick: true })
+        const timeoutId = setTimeout(() => {
+          this.#timeoutIds.delete(timeoutId)
+          this.#tick()
+        }, wait)
+        this.#timeoutIds.add(timeoutId)
+      } else {
+        this.#tick()
+      }
+    }
+    const failure = results.find(
+      (result): result is PromiseRejectedResult => result.status === 'rejected',
+    )
+    if (failure) {
+      throw failure.reason
+    }
   }
 
   /**
@@ -671,9 +726,17 @@ export class AsyncQueuer<TValue> {
   flushAsBatch = async (
     batchFunction: (items: Array<TValue>) => Promise<any>,
   ): Promise<void> => {
-    this.#clearTimeouts() // clear any pending timeouts
+    this.#clearTimeouts() // clear any pending timeouts (kills the tick chain)
     const items = this.#getAllItems()
-    await batchFunction(items)
+    try {
+      await batchFunction(items)
+    } finally {
+      // restore the tick chain even when the batch function rejects
+      this.#setState({ pendingTick: false })
+      if (this.store.state.isRunning && this.store.state.items.length > 0) {
+        this.#tick()
+      }
+    }
   }
 
   /**

package/src/async-rate-limiter.ts

@@ -25,7 +25,7 @@ export interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {
   /**
    * The result from the most recent successful function execution
    */
-  lastResult: ReturnType<TFn> | undefined
+  lastResult: Awaited<ReturnType<TFn>> | undefined
   /**
    * Number of function executions that have been rejected due to rate limiting
    */
@@ -118,7 +118,7 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
    * Optional function to call when the rate-limited function is executed
    */
   onSuccess?: (
-    result: ReturnType<TFn>,
+    result: Awaited<ReturnType<TFn>>,
     args: Parameters<TFn>,
     rateLimiter: AsyncRateLimiter<TFn>,
   ) => void
@@ -357,7 +357,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
    */
   maybeExecute = async (
     ...args: Parameters<TFn>
-  ): Promise<ReturnType<TFn> | undefined> => {
+  ): Promise<Awaited<ReturnType<TFn>> | undefined> => {
     this.#setState({
       maybeExecuteCount: this.store.state.maybeExecuteCount + 1,
     })
@@ -380,7 +380,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
 
   #execute = async (
     ...args: Parameters<TFn>
-  ): Promise<ReturnType<TFn> | undefined> => {
+  ): Promise<Awaited<ReturnType<TFn>> | undefined> => {
     if (!this.#getEnabled()) return
 
     const currentMaybeExecute = this.store.state.maybeExecuteCount
@@ -393,10 +393,10 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
 
     try {
       // Create a new AsyncRetryer for this execution to avoid cancelling concurrent executions
-      const currentAsyncRetryer = new AsyncRetryer(this.fn, {
-        ...this.options.asyncRetryerOptions,
-        key: `${this.key}-retryer-${currentMaybeExecute}`,
-      })
+      const currentAsyncRetryer = new AsyncRetryer(
+        this.fn,
+        this.options.asyncRetryerOptions,
+      )
       this.asyncRetryers.set(currentMaybeExecute, currentAsyncRetryer)
       const result = await currentAsyncRetryer.execute(...args) // EXECUTE!
       this.#setCleanupTimeout(now)
@@ -404,7 +404,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
         successCount: this.store.state.successCount + 1,
         lastResult: result,
       })
-      this.options.onSuccess?.(result as ReturnType<TFn>, args, this)
+      this.options.onSuccess?.(result as Awaited<ReturnType<TFn>>, args, this)
     } catch (error) {
       this.#setState({
         errorCount: this.store.state.errorCount + 1,
@@ -416,7 +416,8 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     } finally {
       this.asyncRetryers.delete(currentMaybeExecute) // dispose retryer
       this.#setState({
-        isExecuting: false,
+        // other executions may still be in flight within the window
+        isExecuting: this.asyncRetryers.size > 0,
         settleCount: this.store.state.settleCount + 1,
       })
       this.options.onSettled?.(args, this)

package/src/async-retryer.ts

@@ -1,6 +1,5 @@
 import { Store } from '@tanstack/store'
 import { parseFunctionOrValue } from './utils'
-import { emitChange, pacerEventClient } from './event-client'
 import type { AnyAsyncFunction } from './types'
 
 export interface AsyncRetryerState<TFn extends AnyAsyncFunction> {
@@ -87,7 +86,10 @@ export interface AsyncRetryerOptions<TFn extends AnyAsyncFunction> {
   jitter?: number
   /**
    * Optional key to identify this async retryer instance.
-   * If provided, the async retryer will be identified by this key in the devtools and PacerProvider if applicable.
+   * Note: async retryers are not currently surfaced in the devtools, so this key
+   * is only a plain identifier. Retryer instances are often created per-execution
+   * (including internally by the other async utilities), so they intentionally do
+   * not register with the devtools event bus.
    */
   key?: string
   /**
@@ -319,18 +321,6 @@ export class AsyncRetryer<TFn extends AnyAsyncFunction> {
         (initialOptions.onError ? false : defaultOptions.throwOnError),
     }
     this.#setState(this.options.initialState ?? {})
-
-    if (this.key) {
-      pacerEventClient.on('d-AsyncRetryer', (event) => {
-        if (event.payload.key !== this.key) return
-        this.#setState(
-          event.payload.store.state as Partial<AsyncRetryerState<TFn>>,
-        )
-        this.setOptions(
-          event.payload.options as Partial<AsyncRetryerOptions<TFn>>,
-        )
-      })
-    }
   }
 
   /**
@@ -359,7 +349,6 @@ export class AsyncRetryer<TFn extends AnyAsyncFunction> {
               : 'idle',
       }
     })
-    emitChange('AsyncRetryer', this)
   }
 
   #getEnabled = (): boolean => {

package/src/async-throttler.ts

@@ -29,7 +29,7 @@ export interface AsyncThrottlerState<TFn extends AnyAsyncFunction> {
   /**
    * The result from the most recent successful function execution
    */
-  lastResult: ReturnType<TFn> | undefined
+  lastResult: Awaited<ReturnType<TFn>> | undefined
   /**
    * Number of times maybeExecute has been called (for reduction calculations)
    */
@@ -119,7 +119,7 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
    * Optional function to call when the throttled function is executed
    */
   onSuccess?: (
-    result: ReturnType<TFn>,
+    result: Awaited<ReturnType<TFn>>,
     args: Parameters<TFn>,
     asyncThrottler: AsyncThrottler<TFn>,
   ) => void
@@ -236,8 +236,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   asyncRetryers = new Map<number, AsyncRetryer<TFn>>()
   #timeoutId: ReturnType<typeof setTimeout> | null = null
   #resolvePreviousPromise:
-    | ((value?: ReturnType<TFn> | undefined) => void)
-    | null = null
+    ((value?: Awaited<ReturnType<TFn>> | undefined) => void) | null = null
 
   constructor(
     public fn: TFn,
@@ -337,7 +336,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
    */
   maybeExecute = async (
     ...args: Parameters<TFn>
-  ): Promise<ReturnType<TFn> | undefined> => {
+  ): Promise<Awaited<ReturnType<TFn>> | undefined> => {
     if (!this.#getEnabled()) return undefined
 
     this.#resolvePreviousPromiseInternal()
@@ -380,51 +379,53 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
       })
 
       // Set up new trailing execution
-      return new Promise((resolve, reject) => {
-        this.#resolvePreviousPromise = resolve
-
-        const newTimeSinceLastExecution = this.store.state.lastExecutionTime
-          ? now - this.store.state.lastExecutionTime
-          : 0
-        const timeoutDuration = Math.max(0, wait - newTimeSinceLastExecution)
-
-        this.#timeoutId = setTimeout(async () => {
-          this.#clearTimeout()
-          if (this.store.state.lastArgs !== undefined) {
-            try {
-              await this.#execute(...this.store.state.lastArgs) // Trailing EXECUTE!
-            } catch (error) {
-              reject(error)
+      return new Promise<Awaited<ReturnType<TFn>> | undefined>(
+        (resolve, reject) => {
+          this.#resolvePreviousPromise = resolve
+
+          const newTimeSinceLastExecution = this.store.state.lastExecutionTime
+            ? now - this.store.state.lastExecutionTime
+            : 0
+          const timeoutDuration = Math.max(0, wait - newTimeSinceLastExecution)
+
+          this.#timeoutId = setTimeout(async () => {
+            this.#clearTimeout()
+            if (this.store.state.lastArgs !== undefined) {
+              try {
+                await this.#execute(...this.store.state.lastArgs) // Trailing EXECUTE!
+              } catch (error) {
+                reject(error)
+              }
             }
-          }
-          this.#resolvePreviousPromise = null
-          resolve(this.store.state.lastResult)
-        }, timeoutDuration)
-      })
+            this.#resolvePreviousPromise = null
+            resolve(this.store.state.lastResult)
+          }, timeoutDuration)
+        },
+      )
     }
     return this.store.state.lastResult
   }
 
   #execute = async (
     ...args: Parameters<TFn>
-  ): Promise<ReturnType<TFn> | undefined> => {
+  ): Promise<Awaited<ReturnType<TFn>> | undefined> => {
     if (!this.#getEnabled()) return undefined
 
     const currentMaybeExecute = this.store.state.maybeExecuteCount
 
     try {
       this.#setState({ isExecuting: true })
-      const currentAsyncRetryer = new AsyncRetryer(this.fn, {
-        ...this.options.asyncRetryerOptions,
-        key: `${this.key}-retryer-${currentMaybeExecute}`,
-      })
+      const currentAsyncRetryer = new AsyncRetryer(
+        this.fn,
+        this.options.asyncRetryerOptions,
+      )
       this.asyncRetryers.set(currentMaybeExecute, currentAsyncRetryer)
       const result = await currentAsyncRetryer.execute(...args) // EXECUTE!
       this.#setState({
         lastResult: result,
         successCount: this.store.state.successCount + 1,
       })
-      this.options.onSuccess?.(result as ReturnType<TFn>, args, this)
+      this.options.onSuccess?.(result as Awaited<ReturnType<TFn>>, args, this)
     } catch (error) {
       this.#setState({
         errorCount: this.store.state.errorCount + 1,
@@ -459,7 +460,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   /**
    * Processes the current pending execution immediately
    */
-  flush = async (): Promise<ReturnType<TFn> | undefined> => {
+  flush = async (): Promise<Awaited<ReturnType<TFn>> | undefined> => {
     if (this.store.state.isPending && this.store.state.lastArgs) {
       // Store the pending promise resolver before clearing timeout
       const resolvePromise = this.#resolvePreviousPromise

package/src/queuer.ts

@@ -390,6 +390,7 @@ export class Queuer<TValue> {
 
   /**
    * Adds an item to the queue. If the queue is full, the item is rejected and onReject is called.
+   * `undefined` cannot be queued (it is the internal "no item" sentinel) and is always rejected.
    * Items can be inserted based on priority or at the front/back depending on configuration.
    *
    * Returns true if the item was added, false if the queue is full.
@@ -409,6 +410,16 @@ export class Queuer<TValue> {
       addItemCount: this.store.state.addItemCount + 1,
     })
 
+    // undefined is the internal "no item" sentinel (peekNextItem/getNextItem);
+    // queuing it would break the processing loop and block items behind it
+    if (item === undefined) {
+      this.#setState({
+        rejectionCount: this.store.state.rejectionCount + 1,
+      })
+      this.options.onReject?.(item, this)
+      return false
+    }
+
     if (this.store.state.items.length >= (this.options.maxSize ?? Infinity)) {
       this.#setState({
         rejectionCount: this.store.state.rejectionCount + 1,
@@ -421,7 +432,7 @@ export class Queuer<TValue> {
     const priority =
       this.options.getPriority !== defaultOptions.getPriority
         ? this.options.getPriority!(item)
-        : (item as any).priority
+        : (item as any)?.priority
 
     const items = this.store.state.items
     const itemTimestamps = this.store.state.itemTimestamps
@@ -432,7 +443,7 @@ export class Queuer<TValue> {
         const existingPriority: number =
           this.options.getPriority !== defaultOptions.getPriority
             ? this.options.getPriority!(existing)
-            : (existing as any).priority
+            : (existing as any)?.priority
         return existingPriority < priority
       })