@tanstack/pacer 0.6.0 → 0.8.0

package/src/async-queuer.ts

@@ -1,10 +1,8 @@
 import { parseFunctionOrValue } from './utils'
-import type { AnyAsyncFunction, OptionalKeys } from './types'
+import type { OptionalKeys } from './types'
 import type { QueuePosition } from './queuer'
 
-export type AsyncQueuerFn = AnyAsyncFunction & { priority?: number }
-
-export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
+export interface AsyncQueuerOptions<TValue> {
   /**
    * Default position to add items to the queuer
    * @default 'back'
@@ -15,7 +13,7 @@ export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
    * Can be a number or a function that returns a number.
    * @default 1
    */
-  concurrency?: number | ((queuer: AsyncQueuer<TFn>) => number)
+  concurrency?: number | ((queuer: AsyncQueuer<TValue>) => number)
   /**
    * Maximum time in milliseconds that an item can stay in the queue
    * If not provided, items will never expire
@@ -25,7 +23,7 @@ export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
    * Function to determine if an item has expired
    * If provided, this overrides the expirationDuration behavior
    */
-  getIsExpired?: (item: TFn, addedAt: number) => boolean
+  getIsExpired?: (item: TValue, addedAt: number) => boolean
   /**
    * Default position to get items from during processing
    * @default 'front'
@@ -36,11 +34,11 @@ export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
    * Higher priority items will be processed first
    * If not provided, will use static priority values attached to tasks
    */
-  getPriority?: (item: TFn) => number
+  getPriority?: (item: TValue) => number
   /**
    * Initial items to populate the queuer with
    */
-  initialItems?: Array<TFn & { priority?: number }>
+  initialItems?: Array<TValue>
   /**
    * Maximum number of items allowed in the queuer
    */
@@ -50,35 +48,31 @@ export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
    * 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, queuer: AsyncQueuer<TFn>) => void
+  onError?: (error: unknown, queuer: AsyncQueuer<TValue>) => void
   /**
    * Callback fired whenever an item expires in the queuer
    */
-  onExpire?: (item: TFn, queuer: AsyncQueuer<TFn>) => void
-  /**
-   * Callback fired whenever an item is removed from the queuer
-   */
-  onGetNextItem?: (item: TFn, queuer: AsyncQueuer<TFn>) => void
+  onExpire?: (item: TValue, queuer: AsyncQueuer<TValue>) => void
   /**
    * Callback fired whenever the queuer's running state changes
    */
-  onIsRunningChange?: (queuer: AsyncQueuer<TFn>) => void
+  onIsRunningChange?: (queuer: AsyncQueuer<TValue>) => void
   /**
    * Callback fired whenever an item is added or removed from the queuer
    */
-  onItemsChange?: (queuer: AsyncQueuer<TFn>) => void
+  onItemsChange?: (queuer: AsyncQueuer<TValue>) => void
   /**
    * Callback fired whenever an item is rejected from being added to the queuer
    */
-  onReject?: (item: TFn, queuer: AsyncQueuer<TFn>) => void
+  onReject?: (item: TValue, queuer: AsyncQueuer<TValue>) => void
   /**
    * Optional callback to call when a task is settled
    */
-  onSettled?: (queuer: AsyncQueuer<TFn>) => void
+  onSettled?: (queuer: AsyncQueuer<TValue>) => void
   /**
    * Optional callback to call when a task succeeds
    */
-  onSuccess?: (result: TFn, queuer: AsyncQueuer<TFn>) => void
+  onSuccess?: (result: TValue, queuer: AsyncQueuer<TValue>) => void
   /**
    * Whether the queuer should start processing tasks immediately or not.
    */
@@ -94,20 +88,19 @@ export interface AsyncQueuerOptions<TFn extends AsyncQueuerFn> {
    * Can be a number or a function that returns a number.
    * @default 0
    */
-  wait?: number | ((queuer: AsyncQueuer<TFn>) => number)
+  wait?: number | ((queuer: AsyncQueuer<TValue>) => number)
 }
 
 type AsyncQueuerOptionsWithOptionalCallbacks = OptionalKeys<
   Required<AsyncQueuerOptions<any>>,
-  | 'onError'
-  | 'onExpire'
-  | 'onGetNextItem'
-  | 'onIsRunningChange'
-  | 'onItemsChange'
-  | 'onReject'
-  | 'onSettled'
-  | 'onSuccess'
   | 'throwOnError'
+  | 'onSuccess'
+  | 'onSettled'
+  | 'onReject'
+  | 'onItemsChange'
+  | 'onIsRunningChange'
+  | 'onExpire'
+  | 'onError'
 >
 
 const defaultOptions: AsyncQueuerOptionsWithOptionalCallbacks = {
@@ -124,57 +117,61 @@ const defaultOptions: AsyncQueuerOptionsWithOptionalCallbacks = {
 }
 
 /**
- * A flexible asynchronous queue that processes tasks with configurable concurrency control.
+ * A flexible asynchronous queue for processing tasks with configurable concurrency, priority, and expiration.
  *
  * Features:
- * - Priority queue support via getPriority option
+ * - Priority queue support via the getPriority option
  * - Configurable concurrency limit
- * - Task success/error/completion callbacks
+ * - Callbacks for task success, error, completion, and queue state changes
  * - FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
- * - Pause/resume task processing
+ * - Pause and resume processing
  * - Task cancellation
- * - Item expiration to clear stale items from the queue
+ * - 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 below the concurrency limit.
+ * 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
  * - 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
+ * - 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 AsyncQueuer instance
  *
- * @example
+ * Example usage:
  * ```ts
- * const asyncQueuer = new AsyncQueuer<string>({
+ * const asyncQueuer = new AsyncQueuer<string>(async (item) => {
+ *   // process item
+ *   return item.toUpperCase();
+ * }, {
  *   concurrency: 2,
  *   onSuccess: (result) => {
- *     console.log(result); // 'Hello'
+ *     console.log(result);
  *   }
  * });
  *
- * asyncQueuer.addItem(async () => {
- *   return 'Hello';
- * });
- *
+ * asyncQueuer.addItem('hello');
  * asyncQueuer.start();
  * ```
  */
-export class AsyncQueuer<TFn extends AsyncQueuerFn> {
+export class AsyncQueuer<TValue> {
   private _options: AsyncQueuerOptionsWithOptionalCallbacks
-  private _activeItems: Set<TFn> = new Set()
+  private _activeItems: Set<TValue> = new Set()
   private _successCount = 0
   private _errorCount = 0
   private _settledCount = 0
   private _rejectionCount = 0
   private _expirationCount = 0
-  private _items: Array<TFn> = []
+  private _items: Array<TValue> = []
   private _itemTimestamps: Array<number> = []
   private _pendingTick = false
   private _running: boolean
+  private _lastResult: any
 
-  constructor(initialOptions: AsyncQueuerOptions<TFn> = defaultOptions) {
+  constructor(
+    private fn: (value: TValue) => Promise<any>,
+    initialOptions: AsyncQueuerOptions<TValue>,
+  ) {
     this._options = {
       ...defaultOptions,
       ...initialOptions,
@@ -190,36 +187,37 @@ export class AsyncQueuer<TFn extends AsyncQueuerFn> {
   }
 
   /**
-   * Updates the queuer options
-   * Returns the new options state
+   * Updates the queuer options. New options are merged with existing options.
    */
-  setOptions(newOptions: Partial<AsyncQueuerOptions<TFn>>): void {
+  setOptions(newOptions: Partial<AsyncQueuerOptions<TValue>>): void {
     this._options = { ...this._options, ...newOptions }
   }
 
   /**
-   * Returns the current queuer options
+   * Returns the current queuer options, including defaults and any overrides.
    */
-  getOptions(): AsyncQueuerOptions<TFn> {
+  getOptions(): AsyncQueuerOptions<TValue> {
     return this._options
   }
 
   /**
-   * Returns the current wait time between processing items
+   * Returns the current wait time (in milliseconds) between processing items.
+   * If a function is provided, it is called with the queuer instance.
    */
   getWait(): number {
     return parseFunctionOrValue(this._options.wait, this)
   }
 
   /**
-   * Returns the current concurrency limit
+   * Returns the current concurrency limit for processing items.
+   * If a function is provided, it is called with the queuer instance.
    */
   getConcurrency(): number {
     return parseFunctionOrValue(this._options.concurrency, this)
   }
 
   /**
-   * Processes items in the queuer
+   * Processes items in the queue up to the concurrency limit. Internal use only.
    */
   private tick() {
     if (!this._running) {
@@ -230,37 +228,19 @@ export class AsyncQueuer<TFn extends AsyncQueuerFn> {
     // Check for expired items
     this.checkExpiredItems()
 
+    // Process items concurrently up to the concurrency limit
     while (
       this._activeItems.size < this.getConcurrency() &&
       !this.getIsEmpty()
     ) {
-      const nextFn = this.getNextItem()
-      if (!nextFn) {
+      const nextItem = this.peekNextItem()
+      if (!nextItem) {
         break
       }
-      this._activeItems.add(nextFn)
+      this._activeItems.add(nextItem)
       this._options.onItemsChange?.(this)
       ;(async () => {
-        let res!: TFn
-
-        try {
-          res = await nextFn()
-          this._successCount++
-          this._options.onSuccess?.(res, this)
-        } catch (error) {
-          this._errorCount++
-          this._options.onError?.(error, this)
-          if (this._options.throwOnError) {
-            throw error
-          } else {
-            console.error(error)
-          }
-        } finally {
-          this._settledCount++
-          this._activeItems.delete(nextFn)
-          this._options.onItemsChange?.(this)
-          this._options.onSettled?.(this)
-        }
+        this._lastResult = await this.execute()
 
         const wait = this.getWait()
         if (wait > 0) {
@@ -276,80 +256,19 @@ export class AsyncQueuer<TFn extends AsyncQueuerFn> {
   }
 
   /**
-   * Checks for and removes expired items from the queuer
-   */
-  private checkExpiredItems(): void {
-    if (
-      this._options.expirationDuration === Infinity &&
-      this._options.getIsExpired === defaultOptions.getIsExpired
-    )
-      return
-
-    const now = Date.now()
-    const expiredIndices: Array<number> = []
-
-    // Find indices of expired items
-    for (let i = 0; i < this._items.length; i++) {
-      const timestamp = this._itemTimestamps[i]
-      if (timestamp === undefined) continue
-
-      const item = this._items[i]
-      if (item === undefined) continue
-
-      const isExpired =
-        this._options.getIsExpired !== defaultOptions.getIsExpired
-          ? this._options.getIsExpired(item, timestamp)
-          : now - timestamp > this._options.expirationDuration
-
-      if (isExpired) {
-        expiredIndices.push(i)
-      }
-    }
-
-    // Remove expired items from back to front to maintain indices
-    for (let i = expiredIndices.length - 1; i >= 0; i--) {
-      const index = expiredIndices[i]
-      if (index === undefined) continue
-
-      const expiredItem = this._items[index]
-      if (expiredItem === undefined) continue
-
-      this._items.splice(index, 1)
-      this._itemTimestamps.splice(index, 1)
-      this._expirationCount++
-      this._options.onExpire?.(expiredItem, this)
-    }
-
-    if (expiredIndices.length > 0) {
-      this._options.onItemsChange?.(this)
-    }
-  }
-
-  /**
-   * Starts the queuer and processes items
+   * Starts processing items in the queue. If already running, does nothing.
    */
-  start(): Promise<void> {
+  start(): void {
     this._running = true
     if (!this._pendingTick && !this.getIsEmpty()) {
       this._pendingTick = true
       this.tick()
     }
     this._options.onIsRunningChange?.(this)
-
-    return new Promise<void>((resolve) => {
-      const checkIdle = () => {
-        if (this.getIsIdle()) {
-          resolve()
-        } else {
-          setTimeout(checkIdle, 100)
-        }
-      }
-      checkIdle()
-    })
   }
 
   /**
-   * Stops the queuer from processing items
+   * Stops processing items in the queue. Does not clear the queue.
    */
   stop(): void {
     this._running = false
@@ -358,7 +277,7 @@ export class AsyncQueuer<TFn extends AsyncQueuerFn> {
   }
 
   /**
-   * Removes all items from the queuer
+   * Removes all pending items from the queue. Does not affect active tasks.
    */
   clear(): void {
     this._items = []
@@ -366,7 +285,8 @@ export class AsyncQueuer<TFn extends AsyncQueuerFn> {
   }
 
   /**
-   * Resets the queuer to its initial state
+   * Resets the queuer to its initial state. Optionally repopulates with initial items.
+   * Does not affect callbacks or options.
    */
   reset(withInitialItems?: boolean): void {
     this.clear()
@@ -380,50 +300,57 @@ export class AsyncQueuer<TFn extends AsyncQueuerFn> {
   }
 
   /**
-   * Adds a task to the queuer
+   * 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.
+   *
+   * @example
+   * ```ts
+   * queuer.addItem({ value: 'task', priority: 10 });
+   * queuer.addItem('task2', 'front');
+   * ```
    */
   addItem(
-    fn: TFn,
+    item: TValue & { priority?: number },
     position: QueuePosition = this._options.addItemsTo,
     runOnItemsChange: boolean = true,
   ): void {
     if (this.getIsFull()) {
       this._rejectionCount++
-      this._options.onReject?.(fn, this)
+      this._options.onReject?.(item, this)
       return
     }
 
     // Get priority either from the function or from getPriority option
     const priority =
       this._options.getPriority !== defaultOptions.getPriority
-        ? this._options.getPriority(fn)
-        : fn.priority
+        ? this._options.getPriority(item)
+        : item.priority
 
     if (priority !== undefined) {
-      // Insert based on priority
+      // Insert based on priority - higher priority items go to front
       const insertIndex = this._items.findIndex((existing) => {
         const existingPriority =
           this._options.getPriority !== defaultOptions.getPriority
             ? this._options.getPriority(existing)
             : (existing as any).priority
-        return existingPriority > priority
+        return existingPriority < priority
       })
 
       if (insertIndex === -1) {
-        this._items.push(fn)
+        this._items.push(item)
         this._itemTimestamps.push(Date.now())
       } else {
-        this._items.splice(insertIndex, 0, fn)
+        this._items.splice(insertIndex, 0, item)
         this._itemTimestamps.splice(insertIndex, 0, Date.now())
       }
     } else {
       if (position === 'front') {
         // Default FIFO/LIFO behavior
-        this._items.unshift(fn)
+        this._items.unshift(item)
         this._itemTimestamps.unshift(Date.now())
       } else {
         // LIFO
-        this._items.push(fn)
+        this._items.push(item)
         this._itemTimestamps.push(Date.now())
       }
     }
@@ -439,12 +366,21 @@ export class AsyncQueuer<TFn extends AsyncQueuerFn> {
   }
 
   /**
-   * Removes and returns an item from the queuer
+   * Removes and returns the next item from the queue without executing the task function.
+   * Use for manual queue management. Normally, use execute() to process items.
+   *
+   * @example
+   * ```ts
+   * // FIFO
+   * queuer.getNextItem();
+   * // LIFO
+   * queuer.getNextItem('back');
+   * ```
    */
   getNextItem(
     position: QueuePosition = this._options.getItemsFrom,
-  ): TFn | undefined {
-    let item: TFn | undefined
+  ): TValue | undefined {
+    let item: TValue | undefined
 
     if (position === 'front') {
       item = this._items.shift()
@@ -456,15 +392,105 @@ export class AsyncQueuer<TFn extends AsyncQueuerFn> {
 
     if (item !== undefined) {
       this._options.onItemsChange?.(this)
-      this._options.onGetNextItem?.(item, this)
     }
+
     return item
   }
 
   /**
-   * Returns an item without removing it
+   * Removes and returns the next item from the queue and executes the task function with it.
+   *
+   * @example
+   * ```ts
+   * queuer.execute();
+   * // LIFO
+   * queuer.execute('back');
+   * ```
    */
-  getPeek(position: QueuePosition = 'front'): TFn | undefined {
+  async execute(position?: QueuePosition): Promise<any> {
+    const item = this.getNextItem(position)
+    if (item !== undefined) {
+      try {
+        this._lastResult = await this.fn(item)
+        this._successCount++
+        this._options.onSuccess?.(this._lastResult, this)
+      } catch (error) {
+        this._errorCount++
+        this._options.onError?.(error, this)
+        if (this._options.throwOnError) {
+          throw error
+        }
+      } finally {
+        this._settledCount++
+        this._activeItems.delete(item)
+        this._options.onItemsChange?.(this)
+        this._options.onSettled?.(this)
+      }
+    }
+    return item
+  }
+
+  /**
+   * Checks for expired items in the queue and removes them. Calls onExpire for each expired item.
+   * Internal use only.
+   */
+  private checkExpiredItems(): void {
+    if (
+      this._options.expirationDuration === Infinity &&
+      this._options.getIsExpired === defaultOptions.getIsExpired
+    )
+      return
+
+    const now = Date.now()
+    const expiredIndices: Array<number> = []
+
+    // Find indices of expired items
+    for (let i = 0; i < this._items.length; i++) {
+      const timestamp = this._itemTimestamps[i]
+      if (timestamp === undefined) continue
+
+      const item = this._items[i]
+      if (item === undefined) continue
+
+      const isExpired =
+        this._options.getIsExpired !== defaultOptions.getIsExpired
+          ? this._options.getIsExpired(item, timestamp)
+          : now - timestamp > this._options.expirationDuration
+
+      if (isExpired) {
+        expiredIndices.push(i)
+      }
+    }
+
+    // Remove expired items from back to front to maintain indices
+    for (let i = expiredIndices.length - 1; i >= 0; i--) {
+      const index = expiredIndices[i]
+      if (index === undefined) continue
+
+      const expiredItem = this._items[index]
+      if (expiredItem === undefined) continue
+
+      this._items.splice(index, 1)
+      this._itemTimestamps.splice(index, 1)
+      this._expirationCount++
+      this._options.onExpire?.(expiredItem, this)
+    }
+
+    if (expiredIndices.length > 0) {
+      this._options.onItemsChange?.(this)
+    }
+  }
+
+  /**
+   * Returns the next item in the queue without removing it.
+   *
+   * @example
+   * ```ts
+   * queuer.peekNextItem(); // front
+   * queuer.peekNextItem('back'); // back
+   * ```
+   */
+  peekNextItem(position: QueuePosition = 'front'): TValue | undefined {
     if (position === 'front') {
       return this._items[0]
     }
@@ -472,91 +498,91 @@ export class AsyncQueuer<TFn extends AsyncQueuerFn> {
   }
 
   /**
-   * Returns true if the queuer is empty
+   * Returns true if the queue is empty (no pending items).
    */
   getIsEmpty(): boolean {
     return this._items.length === 0
   }
 
   /**
-   * Returns true if the queuer is full
+   * Returns true if the queue is full (reached maxSize).
    */
   getIsFull(): boolean {
     return this._items.length >= this._options.maxSize
   }
 
   /**
-   * Returns the current size of the queuer
+   * Returns the number of pending items in the queue.
    */
   getSize(): number {
     return this._items.length
   }
 
   /**
-   * Returns a copy of all items in the queuer
+   * Returns a copy of all items in the queue, including active and pending items.
    */
-  getAllItems(): Array<TFn> {
-    return [...this.getActiveItems(), ...this.getPendingItems()]
+  peekAllItems(): Array<TValue> {
+    return [...this.peekActiveItems(), ...this.peekPendingItems()]
   }
 
   /**
-   * Returns the active items
+   * Returns the items currently being processed (active tasks).
    */
-  getActiveItems(): Array<TFn> {
+  peekActiveItems(): Array<TValue> {
     return Array.from(this._activeItems)
   }
 
   /**
-   * Returns the pending items
+   * Returns the items waiting to be processed (pending tasks).
    */
-  getPendingItems(): Array<TFn> {
+  peekPendingItems(): Array<TValue> {
     return [...this._items]
   }
 
   /**
-   * Returns the number of items that have been successfully processed
+   * Returns the number of items that have been successfully processed.
    */
   getSuccessCount(): number {
     return this._successCount
   }
 
   /**
-   * Returns the number of items that have failed processing
+   * Returns the number of items that have failed processing.
    */
   getErrorCount(): number {
     return this._errorCount
   }
 
   /**
-   * Returns the number of items that have completed processing (success or error)
+   * Returns the number of items that have completed processing (success or error).
    */
   getSettledCount(): number {
     return this._settledCount
   }
 
   /**
-   * Returns the number of items that have been rejected from the queuer
+   * Returns the number of items that have been rejected from being added to the queue.
    */
   getRejectionCount(): number {
     return this._rejectionCount
   }
 
   /**
-   * Returns true if the queuer is running
+   * Returns true if the queuer is currently running (processing items).
    */
   getIsRunning(): boolean {
     return this._running
   }
 
   /**
-   * Returns true if the queuer is running but has no items to process
+   * Returns true if the queuer is running but has no items to process and no active tasks.
    */
   getIsIdle(): boolean {
     return this._running && this.getIsEmpty() && this._activeItems.size === 0
   }
 
   /**
-   * Returns the number of items that have expired from the queuer
+   * Returns the number of items that have expired and been removed from the queue.
    */
   getExpirationCount(): number {
     return this._expirationCount
@@ -564,32 +590,29 @@ export class AsyncQueuer<TFn extends AsyncQueuerFn> {
 }
 
 /**
- * Creates a new AsyncQueuer instance with the given options and returns a bound addItem function.
- * The queuer is automatically started and ready to process items.
+ * Creates a new AsyncQueuer instance and returns a bound addItem function for adding tasks.
+ * The queuer is started automatically and ready to process items.
  *
  * 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
+ * - 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
  *
- * @example
+ * Example usage:
  * ```ts
- * const enqueue = asyncQueue<string>();
+ * const enqueue = asyncQueue<string>(async (item) => {
+ *   return item.toUpperCase();
+ * }, {...options});
  *
- * // Add items to be processed
- * enqueue(async () => {
- *   return 'Hello';
- * });
+ * enqueue('hello');
  * ```
- *
- * @param options - Configuration options for the AsyncQueuer
- * @returns A bound addItem function that can be used to add tasks to the queuer
  */
-export function asyncQueue<TFn extends AsyncQueuerFn>(
-  options: AsyncQueuerOptions<TFn>,
+export function asyncQueue<TValue>(
+  fn: (value: TValue) => Promise<any>,
+  initialOptions: AsyncQueuerOptions<TValue>,
 ) {
-  const queuer = new AsyncQueuer<TFn>(options)
-  return queuer.addItem.bind(queuer)
+  const asyncQueuer = new AsyncQueuer<TValue>(fn, initialOptions)
+  return asyncQueuer.addItem.bind(asyncQueuer)
 }