@tanstack/pacer 0.5.0 → 0.7.0

package/src/async-queuer.ts

@@ -1,5 +1,5 @@
 import { parseFunctionOrValue } from './utils'
-import type { AnyAsyncFunction } from './types'
+import type { OptionalKeys } from './types'
 import type { QueuePosition } from './queuer'
 
 export interface AsyncQueuerOptions<TValue> {
@@ -23,7 +23,7 @@ export interface AsyncQueuerOptions<TValue> {
    * Function to determine if an item has expired
    * If provided, this overrides the expirationDuration behavior
    */
-  getIsExpired?: (item: () => Promise<TValue>, addedAt: number) => boolean
+  getIsExpired?: (item: TValue, addedAt: number) => boolean
   /**
    * Default position to get items from during processing
    * @default 'front'
@@ -34,22 +34,25 @@ export interface AsyncQueuerOptions<TValue> {
    * Higher priority items will be processed first
    * If not provided, will use static priority values attached to tasks
    */
-  getPriority?: (item: () => Promise<TValue>) => number
+  getPriority?: (item: TValue) => number
   /**
    * Initial items to populate the queuer with
    */
-  initialItems?: Array<(() => Promise<TValue>) & { priority?: number }>
+  initialItems?: Array<TValue>
   /**
    * Maximum number of items allowed in the queuer
    */
   maxSize?: number
   /**
-   * Callback fired whenever an item is removed from the queuer
+   * Optional error handler for when a task throws.
+   * 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.
    */
-  onGetNextItem?: (
-    item: () => Promise<TValue>,
-    queuer: AsyncQueuer<TValue>,
-  ) => void
+  onError?: (error: unknown, queuer: AsyncQueuer<TValue>) => void
+  /**
+   * Callback fired whenever an item expires in the queuer
+   */
+  onExpire?: (item: TValue, queuer: AsyncQueuer<TValue>) => void
   /**
    * Callback fired whenever the queuer's running state changes
    */
@@ -61,15 +64,25 @@ export interface AsyncQueuerOptions<TValue> {
   /**
    * Callback fired whenever an item is rejected from being added to the queuer
    */
-  onReject?: (item: () => Promise<TValue>, queuer: AsyncQueuer<TValue>) => void
+  onReject?: (item: TValue, queuer: AsyncQueuer<TValue>) => void
   /**
-   * Callback fired whenever an item expires in the queuer
+   * Optional callback to call when a task is settled
+   */
+  onSettled?: (queuer: AsyncQueuer<TValue>) => void
+  /**
+   * Optional callback to call when a task succeeds
    */
-  onExpire?: (item: () => Promise<TValue>, queuer: AsyncQueuer<TValue>) => void
+  onSuccess?: (result: TValue, queuer: AsyncQueuer<TValue>) => void
   /**
    * Whether the queuer should start processing tasks immediately or not.
    */
   started?: boolean
+  /**
+   * Whether to throw errors when they occur.
+   * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+   * Can be explicitly set to override these defaults.
+   */
+  throwOnError?: boolean
   /**
    * Time in milliseconds to wait between processing items.
    * Can be a number or a function that returns a number.
@@ -78,70 +91,92 @@ export interface AsyncQueuerOptions<TValue> {
   wait?: number | ((queuer: AsyncQueuer<TValue>) => number)
 }
 
-const defaultOptions: Required<AsyncQueuerOptions<any>> = {
+type AsyncQueuerOptionsWithOptionalCallbacks = OptionalKeys<
+  Required<AsyncQueuerOptions<any>>,
+  | 'throwOnError'
+  | 'onSuccess'
+  | 'onSettled'
+  | 'onReject'
+  | 'onItemsChange'
+  | 'onIsRunningChange'
+  | 'onExpire'
+  | 'onError'
+>
+
+const defaultOptions: AsyncQueuerOptionsWithOptionalCallbacks = {
   addItemsTo: 'back',
   concurrency: 1,
   expirationDuration: Infinity,
   getIsExpired: () => false,
   getItemsFrom: 'front',
-  getPriority: (item) => (item as any)?.priority ?? 0,
+  getPriority: (item: any) => item?.priority ?? 0,
   initialItems: [],
   maxSize: Infinity,
-  onGetNextItem: () => {},
-  onIsRunningChange: () => {},
-  onItemsChange: () => {},
-  onReject: () => {},
-  onExpire: () => {},
   started: true,
   wait: 0,
 }
 
 /**
- * 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.
  *
- * @example
- * ```ts
- * const asyncQueuer = new AsyncQueuer<string>({ concurrency: 2 });
+ * 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 AsyncQueuer instance
  *
- * asyncQueuer.addItem(async () => {
- *   return 'Hello';
+ * Example usage:
+ * ```ts
+ * const asyncQueuer = new AsyncQueuer<string>(async (item) => {
+ *   // process item
+ *   return item.toUpperCase();
+ * }, {
+ *   concurrency: 2,
+ *   onSuccess: (result) => {
+ *     console.log(result);
+ *   }
  * });
  *
+ * asyncQueuer.addItem('hello');
  * asyncQueuer.start();
- *
- * asyncQueuer.onSuccess((result) => {
- *   console.log(result); // 'Hello'
- * });
  * ```
  */
 export class AsyncQueuer<TValue> {
-  private _options: Required<AsyncQueuerOptions<TValue>>
-  private _activeItems: Set<() => Promise<TValue>> = new Set()
-  private _executionCount = 0
+  private _options: AsyncQueuerOptionsWithOptionalCallbacks
+  private _activeItems: Set<TValue> = new Set()
+  private _successCount = 0
+  private _errorCount = 0
+  private _settledCount = 0
   private _rejectionCount = 0
   private _expirationCount = 0
-  private _items: Array<() => Promise<TValue>> = []
+  private _items: Array<TValue> = []
   private _itemTimestamps: Array<number> = []
-  private _onErrorCallbacks: Array<(error: Error) => void> = []
-  private _onSettledCallbacks: Array<(result: TValue | Error) => void> = []
-  private _onSuccessCallbacks: Array<(result: TValue) => void> = []
   private _pendingTick = false
   private _running: boolean
-
-  constructor(initialOptions: AsyncQueuerOptions<TValue> = defaultOptions) {
-    this._options = { ...defaultOptions, ...initialOptions }
+  private _lastResult: any
+
+  constructor(
+    private fn: (value: TValue) => Promise<any>,
+    initialOptions: AsyncQueuerOptions<TValue>,
+  ) {
+    this._options = {
+      ...defaultOptions,
+      ...initialOptions,
+      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,
+    }
     this._running = this._options.started
 
     for (let i = 0; i < this._options.initialItems.length; i++) {
@@ -152,36 +187,37 @@ export class AsyncQueuer<TValue> {
   }
 
   /**
-   * Updates the queuer options
-   * Returns the new options state
+   * Updates the queuer options. New options are merged with existing options.
    */
   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(): Required<AsyncQueuerOptions<TValue>> {
+  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) {
@@ -192,37 +228,19 @@ export class AsyncQueuer<TValue> {
     // 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.getPeek()
+      if (!nextItem) {
         break
       }
-      this._activeItems.add(nextFn)
-      this._options.onItemsChange(this)
+      this._activeItems.add(nextItem)
+      this._options.onItemsChange?.(this)
       ;(async () => {
-        let success = false
-        let res!: TValue
-        let error: Error | undefined
-
-        try {
-          res = await nextFn()
-          success = true
-        } catch (e) {
-          error = e as Error
-        } finally {
-          this._activeItems.delete(nextFn)
-          this._options.onItemsChange(this)
-        }
-
-        if (success) {
-          this._onSuccessCallbacks.forEach((cb) => cb(res))
-        } else {
-          this._onErrorCallbacks.forEach((cb) => cb(error!))
-        }
-        this._onSettledCallbacks.forEach((cb) => cb(success ? res : error!))
+        this._lastResult = await this.execute()
 
         const wait = this.getWait()
         if (wait > 0) {
@@ -238,101 +256,43 @@ export class AsyncQueuer<TValue> {
   }
 
   /**
-   * Checks for and removes expired items from the queuer
+   * Starts processing items in the queue. If already running, does nothing.
    */
-  private checkExpiredItems() {
-    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
-   */
-  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()
-    })
+    this._options.onIsRunningChange?.(this)
   }
 
   /**
-   * Stops the queuer from processing items
+   * Stops processing items in the queue. Does not clear the queue.
    */
   stop(): void {
     this._running = false
     this._pendingTick = false
-    this._options.onIsRunningChange(this)
+    this._options.onIsRunningChange?.(this)
   }
 
   /**
-   * Removes all items from the queuer
+   * Removes all pending items from the queue. Does not affect active tasks.
    */
   clear(): void {
     this._items = []
-    this._options.onItemsChange(this)
+    this._options.onItemsChange?.(this)
   }
 
   /**
-   * 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()
-    this._executionCount = 0
+    this._successCount = 0
+    this._errorCount = 0
+    this._settledCount = 0
     if (withInitialItems) {
       this._items = [...this._options.initialItems]
     }
@@ -340,86 +300,87 @@ export class AsyncQueuer<TValue> {
   }
 
   /**
-   * 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: AnyAsyncFunction & { priority?: number },
+    item: TValue & { priority?: number },
     position: QueuePosition = this._options.addItemsTo,
     runOnItemsChange: boolean = true,
-  ): Promise<TValue> {
+  ): void {
     if (this.getIsFull()) {
       this._rejectionCount++
-      this._options.onReject(fn, this)
-      return Promise.reject(new Error('Queuer is full'))
+      this._options.onReject?.(item, this)
+      return
     }
 
-    return new Promise<TValue>((resolve, reject) => {
-      const task = Object.assign(
-        async () => {
-          try {
-            const result = await fn()
-            resolve(result)
-            return result
-          } catch (error) {
-            reject(error)
-            throw error
-          }
-        },
-        { priority: fn.priority ?? undefined },
-      )
-
-      // Get priority either from the function or from getPriority option
-      const priority =
-        this._options.getPriority !== defaultOptions.getPriority
-          ? this._options.getPriority(task)
-          : task.priority
-
-      if (priority !== undefined) {
-        // Insert based on priority
-        const insertIndex = this._items.findIndex((existing) => {
-          const existingPriority =
-            this._options.getPriority !== defaultOptions.getPriority
-              ? this._options.getPriority(existing)
-              : (existing as any).priority
-          return existingPriority > priority
-        })
-
-        if (insertIndex === -1) {
-          this._items.push(task)
-          this._itemTimestamps.push(Date.now())
-        } else {
-          this._items.splice(insertIndex, 0, task)
-          this._itemTimestamps.splice(insertIndex, 0, Date.now())
-        }
+    // Get priority either from the function or from getPriority option
+    const priority =
+      this._options.getPriority !== defaultOptions.getPriority
+        ? this._options.getPriority(item)
+        : item.priority
+
+    if (priority !== undefined) {
+      // 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
+      })
+
+      if (insertIndex === -1) {
+        this._items.push(item)
+        this._itemTimestamps.push(Date.now())
       } else {
+        this._items.splice(insertIndex, 0, item)
+        this._itemTimestamps.splice(insertIndex, 0, Date.now())
+      }
+    } else {
+      if (position === 'front') {
         // Default FIFO/LIFO behavior
-        if (position === 'front') {
-          this._items.unshift(task)
-          this._itemTimestamps.unshift(Date.now())
-        } else {
-          this._items.push(task)
-          this._itemTimestamps.push(Date.now())
-        }
+        this._items.unshift(item)
+        this._itemTimestamps.unshift(Date.now())
+      } else {
+        // LIFO
+        this._items.push(item)
+        this._itemTimestamps.push(Date.now())
       }
+    }
 
-      if (runOnItemsChange) {
-        this._options.onItemsChange(this)
-      }
+    if (runOnItemsChange) {
+      this._options.onItemsChange?.(this)
+    }
 
-      if (this._running && !this._pendingTick) {
-        this._pendingTick = true
-        this.tick()
-      }
-    })
+    if (this._running && !this._pendingTick) {
+      this._pendingTick = true
+      this.tick()
+    }
   }
 
   /**
-   * 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,
-  ): (() => Promise<TValue>) | undefined {
-    let item: (() => Promise<TValue>) | undefined
+  ): TValue | undefined {
+    let item: TValue | undefined
 
     if (position === 'front') {
       item = this._items.shift()
@@ -430,19 +391,106 @@ export class AsyncQueuer<TValue> {
     }
 
     if (item !== undefined) {
-      this._executionCount++
-      this._options.onItemsChange(this)
-      this._options.onGetNextItem(item, this)
+      this._options.onItemsChange?.(this)
+    }
+
+    return item
+  }
+
+  /**
+   * Removes and returns the next item from the queue and executes the task function with it.
+   *
+   * @example
+   * ```ts
+   * queuer.execute();
+   * // LIFO
+   * queuer.execute('back');
+   * ```
+   */
+  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
   }
 
   /**
-   * Returns an item without removing it
+   * 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.getPeek(); // front
+   * queuer.getPeek('back'); // back
+   * ```
    */
-  getPeek(
-    position: QueuePosition = 'front',
-  ): (() => Promise<TValue>) | undefined {
+  getPeek(position: QueuePosition = 'front'): TValue | undefined {
     if (position === 'front') {
       return this._items[0]
     }
@@ -450,111 +498,91 @@ export class AsyncQueuer<TValue> {
   }
 
   /**
-   * 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<() => Promise<TValue>> {
+  getAllItems(): Array<TValue> {
     return [...this.getActiveItems(), ...this.getPendingItems()]
   }
 
   /**
-   * Returns the active items
+   * Returns the items currently being processed (active tasks).
    */
-  getActiveItems(): Array<() => Promise<TValue>> {
+  getActiveItems(): Array<TValue> {
     return Array.from(this._activeItems)
   }
 
   /**
-   * Returns the pending items
+   * Returns the items waiting to be processed (pending tasks).
    */
-  getPendingItems(): Array<() => Promise<TValue>> {
+  getPendingItems(): Array<TValue> {
     return [...this._items]
   }
 
   /**
-   * Returns the number of items that have been removed from the queuer
+   * Returns the number of items that have been successfully processed.
    */
-  getExecutionCount(): number {
-    return this._executionCount
+  getSuccessCount(): number {
+    return this._successCount
   }
 
   /**
-   * Returns the number of items that have been rejected from the queuer
+   * Returns the number of items that have failed processing.
    */
-  getRejectionCount(): number {
-    return this._rejectionCount
+  getErrorCount(): number {
+    return this._errorCount
   }
 
   /**
-   * Returns true if the queuer is running
+   * Returns the number of items that have completed processing (success or error).
    */
-  getIsRunning(): boolean {
-    return this._running
-  }
-
-  /**
-   * Returns true if the queuer is running but has no items to process
-   */
-  getIsIdle(): boolean {
-    return this._running && this.getIsEmpty() && this._activeItems.size === 0
+  getSettledCount(): number {
+    return this._settledCount
   }
 
   /**
-   * Adds a callback to be called when a task succeeds
+   * Returns the number of items that have been rejected from being added to the queue.
    */
-  onSuccess(cb: (result: TValue) => void) {
-    this._onSuccessCallbacks.push(cb)
-    return () => {
-      this._onSuccessCallbacks = this._onSuccessCallbacks.filter(
-        (d) => d !== cb,
-      )
-    }
+  getRejectionCount(): number {
+    return this._rejectionCount
   }
 
   /**
-   * Adds a callback to be called when a task errors
+   * Returns true if the queuer is currently running (processing items).
    */
-  onError(cb: (error: Error) => void) {
-    this._onErrorCallbacks.push(cb)
-    return () => {
-      this._onErrorCallbacks = this._onErrorCallbacks.filter((d) => d !== cb)
-    }
+  getIsRunning(): boolean {
+    return this._running
   }
 
   /**
-   * Adds a callback to be called when a task is settled
+   * Returns true if the queuer is running but has no items to process and no active tasks.
    */
-  onSettled(cb: (result: TValue | Error) => void) {
-    this._onSettledCallbacks.push(cb)
-    return () => {
-      this._onSettledCallbacks = this._onSettledCallbacks.filter(
-        (d) => d !== cb,
-      )
-    }
+  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
@@ -562,23 +590,29 @@ export class AsyncQueuer<TValue> {
 }
 
 /**
- * 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
+ * - 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<TValue>(options: AsyncQueuerOptions<TValue>) {
-  const queuer = new AsyncQueuer<TValue>(options)
-  return queuer.addItem.bind(queuer)
+export function asyncQueue<TValue>(
+  fn: (value: TValue) => Promise<any>,
+  initialOptions: AsyncQueuerOptions<TValue>,
+) {
+  const asyncQueuer = new AsyncQueuer<TValue>(fn, initialOptions)
+  return asyncQueuer.addItem.bind(asyncQueuer)
 }