@tanstack/pacer 0.15.4 → 0.16.1

package/src/async-debouncer.ts

@@ -1,6 +1,8 @@
 import { Store } from '@tanstack/store'
-import { createKey, parseFunctionOrValue } from './utils'
+import { AsyncRetryer } from './async-retryer'
+import { parseFunctionOrValue } from './utils'
 import { emitChange, pacerEventClient } from './event-client'
+import type { AsyncRetryerOptions } from './async-retryer'
 import type { AnyAsyncFunction, OptionalKeys } from './types'
 
 export interface AsyncDebouncerState<TFn extends AnyAsyncFunction> {
@@ -67,6 +69,10 @@ function getDefaultAsyncDebouncerState<
  * Options for configuring an async debounced function
  */
 export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
+  /**
+   * Options for configuring the underlying async retryer
+   */
+  asyncRetryerOptions?: AsyncRetryerOptions<TFn>
   /**
    * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
    * Can be a boolean or a function that returns a boolean.
@@ -93,7 +99,7 @@ export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
    * This can be used alongside throwOnError - the handler will be called before any error is thrown.
    */
   onError?: (
-    error: unknown,
+    error: Error,
     args: Parameters<TFn>,
     debouncer: AsyncDebouncer<TFn>,
   ) => void
@@ -128,12 +134,27 @@ export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
   wait: number | ((debouncer: AsyncDebouncer<TFn>) => number)
 }
 
+/**
+ * Utility function for sharing common `AsyncDebouncerOptions` options between different `AsyncDebouncer` instances.
+ */
+export function asyncDebouncerOptions<
+  TFn extends AnyAsyncFunction = AnyAsyncFunction,
+  TOptions extends Partial<AsyncDebouncerOptions<TFn>> = Partial<
+    AsyncDebouncerOptions<TFn>
+  >,
+>(options: TOptions): TOptions {
+  return options
+}
+
 type AsyncDebouncerOptionsWithOptionalCallbacks = OptionalKeys<
   AsyncDebouncerOptions<any>,
   'initialState' | 'onError' | 'onSettled' | 'onSuccess' | 'key'
 >
 
 const defaultOptions: AsyncDebouncerOptionsWithOptionalCallbacks = {
+  asyncRetryerOptions: {
+    maxAttempts: 1,
+  },
   enabled: true,
   leading: false,
   trailing: true,
@@ -143,6 +164,19 @@ const defaultOptions: AsyncDebouncerOptionsWithOptionalCallbacks = {
 /**
  * A class that creates an async debounced function.
  *
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync Debouncer:
+ * - Returns promises that can be awaited for debounced function results
+ * - Built-in retry support via AsyncRetryer integration
+ * - Abort support to cancel in-flight executions
+ * - Cancel support to prevent pending executions from starting
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ *
+ * The sync Debouncer is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Debouncing?
  * Debouncing ensures that a function is only executed after a specified delay has passed since its last invocation.
  * 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.
@@ -150,10 +184,6 @@ const defaultOptions: AsyncDebouncerOptionsWithOptionalCallbacks = {
  * 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
@@ -189,9 +219,9 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
   readonly store: Store<Readonly<AsyncDebouncerState<TFn>>> = new Store<
     AsyncDebouncerState<TFn>
   >(getDefaultAsyncDebouncerState<TFn>())
-  key: string
+  key: string | undefined
   options: AsyncDebouncerOptions<TFn>
-  #abortController: AbortController | null = null
+  asyncRetryers = new Map<number, AsyncRetryer<TFn>>()
   #timeoutId: NodeJS.Timeout | null = null
   #resolvePreviousPromise:
     | ((value?: ReturnType<TFn> | undefined) => void)
@@ -201,7 +231,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     public fn: TFn,
     initialOptions: AsyncDebouncerOptions<TFn>,
   ) {
-    this.key = createKey(initialOptions.key)
+    this.key = initialOptions.key
     this.options = {
       ...defaultOptions,
       ...initialOptions,
@@ -326,31 +356,37 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     ...args: Parameters<TFn>
   ): Promise<ReturnType<TFn> | undefined> => {
     if (!this.#getEnabled()) return undefined
-    this.#abortController = new AbortController()
+    const currentMaybeExecuteCount = this.store.state.maybeExecuteCount + 1
+
     try {
       this.#setState({ isExecuting: true })
-      const result = await this.fn(...args) // EXECUTE!
+      const currentAsyncRetryer = new AsyncRetryer(this.fn, {
+        ...this.options.asyncRetryerOptions,
+        key: `${this.key}-retryer-${currentMaybeExecuteCount}`,
+      })
+      this.asyncRetryers.set(currentMaybeExecuteCount, currentAsyncRetryer)
+      const result = await currentAsyncRetryer.execute(...args) // EXECUTE!
       this.#setState({
         lastResult: result,
         successCount: this.store.state.successCount + 1,
       })
-      this.options.onSuccess?.(result, args, this)
+      this.options.onSuccess?.(result as ReturnType<TFn>, args, this)
     } catch (error) {
       this.#setState({
         errorCount: this.store.state.errorCount + 1,
       })
-      this.options.onError?.(error, args, this)
+      this.options.onError?.(error as Error, args, this)
       if (this.options.throwOnError) {
         throw error
       }
     } finally {
+      this.asyncRetryers.delete(currentMaybeExecuteCount) // dispose retryer
       this.#setState({
         isExecuting: false,
         isPending: false,
         lastArgs: undefined,
         settleCount: this.store.state.settleCount + 1,
       })
-      this.#abortController = null
       this.options.onSettled?.(args, this)
     }
     return this.store.state.lastResult
@@ -361,14 +397,9 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
    */
   flush = async (): Promise<ReturnType<TFn> | undefined> => {
     if (this.store.state.isPending && this.store.state.lastArgs) {
-      this.#abortExecution() // abort any current execution
-      this.#clearTimeout() // clear any existing timeout
-      const result = await this.#execute(...this.store.state.lastArgs)
-
-      // Resolve any pending promise from maybeExecute
-      this.#resolvePreviousPromiseInternal()
-
-      return result
+      const { lastArgs } = this.store.state
+      this.#cancelPendingExecution()
+      return await this.#execute(...lastArgs)
     }
     return undefined
   }
@@ -387,29 +418,62 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     }
   }
 
+  /**
+   * Internal cancel without resetting the leading execute state
+   */
   #cancelPendingExecution = (): void => {
     this.#clearTimeout()
     this.#resolvePreviousPromiseInternal()
     this.#setState({
       isPending: false,
-      isExecuting: false,
       lastArgs: undefined,
     })
   }
 
-  #abortExecution = (): void => {
-    if (this.#abortController) {
-      this.#abortController.abort()
-      this.#abortController = null
-    }
+  /**
+   * Returns the AbortSignal for a specific execution.
+   * If no maybeExecuteCount is provided, returns the signal for the most recent execution.
+   * Returns null if no execution is found or not currently executing.
+   *
+   * @param maybeExecuteCount - Optional specific execution to get signal for
+   * @example
+   * ```typescript
+   * const debouncer = new AsyncDebouncer(
+   *   async (searchTerm: string) => {
+   *     const signal = debouncer.getAbortSignal()
+   *     if (signal) {
+   *       const response = await fetch(`/api/search?q=${searchTerm}`, { signal })
+   *       return response.json()
+   *     }
+   *   },
+   *   { wait: 300 }
+   * )
+   * ```
+   */
+  getAbortSignal(maybeExecuteCount?: number): AbortSignal | null {
+    const count = maybeExecuteCount ?? this.store.state.maybeExecuteCount
+    const retryer = this.asyncRetryers.get(count)
+    return retryer?.getAbortSignal() ?? null
+  }
+
+  /**
+   * Aborts all ongoing executions with the internal abort controllers.
+   * Does NOT cancel any pending execution that have not started yet.
+   */
+  abort = (): void => {
+    this.asyncRetryers.forEach((retryer) => retryer.abort())
+    this.asyncRetryers.clear()
+    this.#setState({
+      isExecuting: false,
+    })
   }
 
   /**
-   * Cancels any pending execution or aborts any execution in progress
+   * Cancels any pending execution that have not started yet.
+   * Does NOT abort any execution already in progress.
    */
   cancel = (): void => {
     this.#cancelPendingExecution()
-    this.#abortExecution()
     this.#setState({ canLeadingExecute: true })
   }
 
@@ -418,6 +482,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
    */
   reset = (): void => {
     this.#setState(getDefaultAsyncDebouncerState<TFn>())
+    this.asyncRetryers.forEach((retryer) => retryer.reset())
   }
 }
 
@@ -426,9 +491,29 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
  * The debounced function will only execute once the wait period has elapsed without any new calls.
  * If called again during the wait period, the timer resets and a new wait period begins.
  *
- * 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.
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync debounce function:
+ * - Returns promises that can be awaited for debounced function results
+ * - Built-in retry support via AsyncRetryer integration
+ * - Abort support to cancel in-flight executions
+ * - Cancel support to prevent pending executions from starting
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ *
+ * The sync debounce function is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Debouncing?
+ * Debouncing ensures that a function is only executed after a specified delay has passed since its last invocation.
+ * 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.
+ *
+ * Configuration Options:
+ * - `wait`: Delay in milliseconds to wait after the last call (required)
+ * - `leading`: Execute on the leading edge of the timeout (default: false)
+ * - `trailing`: Execute on the trailing edge of the timeout (default: true)
+ * - `enabled`: Whether the debouncer is enabled (default: true)
+ * - `asyncRetryerOptions`: Configure retry behavior for executions
  *
  * Error Handling:
  * - If an `onError` handler is provided, it will be called with the error and debouncer instance

package/src/async-queuer.ts

@@ -1,6 +1,8 @@
 import { Store } from '@tanstack/store'
-import { createKey, parseFunctionOrValue } from './utils'
+import { AsyncRetryer } from './async-retryer'
+import { parseFunctionOrValue } from './utils'
 import { emitChange, pacerEventClient } from './event-client'
+import type { AsyncRetryerOptions } from './async-retryer'
 import type { OptionalKeys } from './types'
 import type { QueuePosition } from './queuer'
 
@@ -17,6 +19,10 @@ export interface AsyncQueuerState<TValue> {
    * Number of task executions that have resulted in errors
    */
   errorCount: number
+  /**
+   * Number of times execute has been called
+   */
+  executeCount: number
   /**
    * Number of items that have been removed from the queue due to expiration
    */
@@ -25,6 +31,10 @@ export interface AsyncQueuerState<TValue> {
    * Whether the queuer has no items to process (items array is empty)
    */
   isEmpty: boolean
+  /**
+   * Whether the queuer is currently executing
+   */
+  isExecuting: boolean
   /**
    * Whether the queuer has reached its maximum capacity
    */
@@ -80,8 +90,10 @@ function getDefaultAsyncQueuerState<TValue>(): AsyncQueuerState<TValue> {
     activeItems: [],
     addItemCount: 0,
     errorCount: 0,
+    executeCount: 0,
     expirationCount: 0,
     isEmpty: true,
+    isExecuting: false,
     isFull: false,
     isIdle: true,
     isRunning: true,
@@ -98,6 +110,10 @@ function getDefaultAsyncQueuerState<TValue>(): AsyncQueuerState<TValue> {
 }
 
 export interface AsyncQueuerOptions<TValue> {
+  /**
+   * Options for configuring the underlying async retryer
+   */
+  asyncRetryerOptions?: AsyncRetryerOptions<(item: TValue) => Promise<any>>
   /**
    * Default position to add items to the queuer
    * @default 'back'
@@ -152,7 +168,7 @@ export interface AsyncQueuerOptions<TValue> {
    * If provided, the handler will be called with the error and queuer instance.
    * This can be used alongside throwOnError - the handler will be called before any error is thrown.
    */
-  onError?: (error: unknown, item: TValue, queuer: AsyncQueuer<TValue>) => void
+  onError?: (error: Error, item: TValue, queuer: AsyncQueuer<TValue>) => void
   /**
    * Callback fired whenever an item expires in the queuer
    */
@@ -191,6 +207,18 @@ export interface AsyncQueuerOptions<TValue> {
   wait?: number | ((queuer: AsyncQueuer<TValue>) => number)
 }
 
+/**
+ * Utility function for sharing common `AsyncQueuerOptions` options between different `AsyncQueuer` instances.
+ */
+export function asyncQueuerOptions<
+  TValue = any,
+  TOptions extends Partial<AsyncQueuerOptions<TValue>> = Partial<
+    AsyncQueuerOptions<TValue>
+  >,
+>(options: TOptions): TOptions {
+  return options
+}
+
 type AsyncQueuerOptionsWithOptionalCallbacks = OptionalKeys<
   Required<AsyncQueuerOptions<any>>,
   | 'initialState'
@@ -206,6 +234,9 @@ type AsyncQueuerOptionsWithOptionalCallbacks = OptionalKeys<
 
 const defaultOptions: AsyncQueuerOptionsWithOptionalCallbacks = {
   addItemsTo: 'back',
+  asyncRetryerOptions: {
+    maxAttempts: 1,
+  },
   concurrency: 1,
   expirationDuration: Infinity,
   getIsExpired: () => false,
@@ -220,18 +251,31 @@ const defaultOptions: AsyncQueuerOptionsWithOptionalCallbacks = {
 /**
  * A flexible asynchronous queue for processing tasks with configurable concurrency, priority, and expiration.
  *
- * Features:
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync Queuer:
+ * - Returns promises that can be awaited for task results
+ * - Built-in retry support via AsyncRetryer integration for each queued task
+ * - Abort support to cancel in-flight task executions
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ * - Concurrent execution support (process multiple items simultaneously)
+ *
+ * The sync Queuer is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Queuing?
+ * Queuing is a technique for managing and processing items sequentially or with controlled concurrency.
+ * Tasks are processed up to the configured concurrency limit. When a task completes,
+ * the next pending task is processed if the concurrency limit allows.
+ *
+ * Key Features:
  * - Priority queue support via the getPriority option
  * - Configurable concurrency limit
  * - Callbacks for task success, error, completion, and queue state changes
  * - FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
  * - Pause and resume processing
- * - Task cancellation
  * - Item expiration to remove 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 the concurrency limit allows.
- *
  * 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
@@ -272,15 +316,19 @@ export class AsyncQueuer<TValue> {
   readonly store: Store<Readonly<AsyncQueuerState<TValue>>> = new Store<
     AsyncQueuerState<TValue>
   >(getDefaultAsyncQueuerState<TValue>())
-  key: string
+  key: string | undefined
   options: AsyncQueuerOptions<TValue>
+  asyncRetryers = new Map<
+    number,
+    AsyncRetryer<(item: TValue) => Promise<any>>
+  >()
   #timeoutIds: Set<NodeJS.Timeout> = new Set()
 
   constructor(
     public fn: (item: TValue) => Promise<any>,
     initialOptions: AsyncQueuerOptions<TValue> = {},
   ) {
-    this.key = createKey(initialOptions.key)
+    this.key = initialOptions.key
     this.options = {
       ...defaultOptions,
       ...initialOptions,
@@ -555,9 +603,20 @@ export class AsyncQueuer<TValue> {
    */
   execute = async (position?: QueuePosition): Promise<any> => {
     const item = this.getNextItem(position)
+
     if (item !== undefined) {
+      const currentExecuteCount = this.store.state.executeCount + 1
+      this.#setState({
+        executeCount: currentExecuteCount,
+        isExecuting: true,
+      })
       try {
-        const lastResult = await this.fn(item) // EXECUTE!
+        const currentAsyncRetryer = new AsyncRetryer(this.fn, {
+          ...this.options.asyncRetryerOptions,
+          key: `${this.key}-retryer-${currentExecuteCount}`,
+        })
+        this.asyncRetryers.set(currentExecuteCount, currentAsyncRetryer)
+        const lastResult = await currentAsyncRetryer.execute(item) // EXECUTE!
         this.#setState({
           successCount: this.store.state.successCount + 1,
           lastResult,
@@ -567,15 +626,17 @@ export class AsyncQueuer<TValue> {
         this.#setState({
           errorCount: this.store.state.errorCount + 1,
         })
-        this.options.onError?.(error, item, this)
+        this.options.onError?.(error as Error, item, this)
         if (this.options.throwOnError) {
           throw error
         }
       } finally {
+        this.asyncRetryers.delete(currentExecuteCount) // dispose retryer
         this.#setState({
           activeItems: this.store.state.activeItems.filter(
             (activeItem) => activeItem !== item,
           ),
+          isExecuting: false,
           settledCount: this.store.state.settledCount + 1,
         })
         this.options.onSettled?.(item, this)
@@ -729,19 +790,59 @@ export class AsyncQueuer<TValue> {
   }
 
   /**
-   * Removes all pending items from the queue. Does not affect active tasks.
+   * Removes all pending items from the queue.
+   * Does NOT affect active tasks.
    */
   clear = (): void => {
     this.#setState({ items: [], itemTimestamps: [] })
     this.options.onItemsChange?.(this)
   }
 
+  /**
+   * Returns the AbortSignal for a specific execution.
+   * If no executeCount is provided, returns the signal for the most recent execution.
+   * Returns null if no execution is found or not currently executing.
+   *
+   * @param executeCount - Optional specific execution to get signal for
+   * @example
+   * ```typescript
+   * const queuer = new AsyncQueuer(
+   *   async (item: string) => {
+   *     const signal = queuer.getAbortSignal()
+   *     if (signal) {
+   *       const response = await fetch(`/api/process/${item}`, { signal })
+   *       return response.json()
+   *     }
+   *   },
+   *   { concurrency: 2 }
+   * )
+   * ```
+   */
+  getAbortSignal(executeCount?: number): AbortSignal | null {
+    const count = executeCount ?? this.store.state.executeCount
+    const retryer = this.asyncRetryers.get(count)
+    return retryer?.getAbortSignal() ?? null
+  }
+
+  /**
+   * Aborts all ongoing executions with the internal abort controllers.
+   * Does NOT clear out the items.
+   */
+  abort = (): void => {
+    this.asyncRetryers.forEach((retryer) => retryer.abort())
+    this.asyncRetryers.clear()
+    this.#setState({
+      isExecuting: false,
+    })
+  }
+
   /**
    * Resets the queuer state to its default values
    */
   reset = (): void => {
     this.#setState(getDefaultAsyncQueuerState<TValue>())
     this.options.onItemsChange?.(this)
+    this.asyncRetryers.forEach((retryer) => retryer.reset())
   }
 }
 
@@ -749,6 +850,34 @@ export class AsyncQueuer<TValue> {
  * Creates a new AsyncQueuer instance and returns a bound addItem function for adding tasks.
  * The queuer is started automatically and ready to process items.
  *
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync queue function:
+ * - Returns promises that can be awaited for task results
+ * - Built-in retry support via AsyncRetryer integration for each queued task
+ * - Abort support to cancel in-flight task executions
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ * - Concurrent execution support (process multiple items simultaneously)
+ *
+ * The sync queue function is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Queuing?
+ * Queuing is a technique for managing and processing items sequentially or with controlled concurrency.
+ * Tasks are processed up to the configured concurrency limit. When a task completes,
+ * the next pending task is processed if the concurrency limit allows.
+ *
+ * Configuration Options:
+ * - `concurrency`: Maximum number of concurrent tasks (default: 1)
+ * - `wait`: Time to wait between processing items (default: 0)
+ * - `maxSize`: Maximum number of items allowed in the queue (default: Infinity)
+ * - `getPriority`: Function to determine item priority
+ * - `addItemsTo`: Default position to add items ('back' or 'front', default: 'back')
+ * - `getItemsFrom`: Default position to get items ('front' or 'back', default: 'front')
+ * - `expirationDuration`: Maximum time items can stay in queue
+ * - `started`: Whether to start processing immediately (default: true)
+ * - `asyncRetryerOptions`: Configure retry behavior for task executions
+ *
  * 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
@@ -769,11 +898,15 @@ export class AsyncQueuer<TValue> {
  * - State can be accessed via the underlying AsyncQueuer instance's `store.state` property
  * - When using framework adapters (React/Solid), state is accessed from the hook's state property
  *
- * Example usage:
+ * @example
  * ```ts
  * const enqueue = asyncQueue<string>(async (item) => {
  *   return item.toUpperCase();
- * }, {...options});
+ * }, {
+ *   concurrency: 2,
+ *   wait: 100,
+ *   onSuccess: (result) => console.log('Processed:', result)
+ * });
  *
  * enqueue('hello');
  * ```