@tanstack/pacer 0.5.0 → 0.7.0

package/dist/esm/async-queuer.d.ts

@@ -1,4 +1,3 @@
-import { AnyAsyncFunction } from './types.js';
 import { QueuePosition } from './queuer.js';
 export interface AsyncQueuerOptions<TValue> {
     /**
@@ -21,7 +20,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'
@@ -32,21 +31,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.
+     */
+    onError?: (error: unknown, queuer: AsyncQueuer<TValue>) => void;
+    /**
+     * Callback fired whenever an item expires in the queuer
      */
-    onGetNextItem?: (item: () => Promise<TValue>, queuer: AsyncQueuer<TValue>) => void;
+    onExpire?: (item: TValue, queuer: AsyncQueuer<TValue>) => void;
     /**
      * Callback fired whenever the queuer's running state changes
      */
@@ -58,15 +61,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.
@@ -75,178 +88,222 @@ export interface AsyncQueuerOptions<TValue> {
     wait?: number | ((queuer: AsyncQueuer<TValue>) => number);
 }
 /**
- * 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 declare class AsyncQueuer<TValue> {
+    private fn;
     private _options;
     private _activeItems;
-    private _executionCount;
+    private _successCount;
+    private _errorCount;
+    private _settledCount;
     private _rejectionCount;
     private _expirationCount;
     private _items;
     private _itemTimestamps;
-    private _onErrorCallbacks;
-    private _onSettledCallbacks;
-    private _onSuccessCallbacks;
     private _pendingTick;
     private _running;
-    constructor(initialOptions?: AsyncQueuerOptions<TValue>);
+    private _lastResult;
+    constructor(fn: (value: TValue) => Promise<any>, initialOptions: AsyncQueuerOptions<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;
     /**
-     * Returns the current queuer options
+     * Returns the current queuer options, including defaults and any overrides.
      */
-    getOptions(): Required<AsyncQueuerOptions<TValue>>;
+    getOptions(): AsyncQueuerOptions<TValue>;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * Processes items in the queuer
+     * Processes items in the queue up to the concurrency limit. Internal use only.
      */
     private tick;
     /**
-     * Checks for and removes expired items from the queuer
+     * Starts processing items in the queue. If already running, does nothing.
      */
-    private checkExpiredItems;
+    start(): void;
     /**
-     * Starts the queuer and processes items
-     */
-    start(): Promise<void>;
-    /**
-     * Stops the queuer from processing items
+     * Stops processing items in the queue. Does not clear the queue.
      */
     stop(): void;
     /**
-     * Removes all items from the queuer
+     * Removes all pending items from the queue. Does not affect active tasks.
      */
     clear(): void;
     /**
-     * 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;
     /**
-     * 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 & {
+    addItem(item: TValue & {
         priority?: number;
-    }, position?: QueuePosition, runOnItemsChange?: boolean): Promise<TValue>;
-    /**
-     * Removes and returns an item from the queuer
+    }, position?: QueuePosition, runOnItemsChange?: boolean): void;
+    /**
+     * 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): TValue | undefined;
+    /**
+     * Removes and returns the next item from the queue and executes the task function with it.
+     *
+     * @example
+     * ```ts
+     * queuer.execute();
+     * // LIFO
+     * queuer.execute('back');
+     * ```
+     */
+    execute(position?: QueuePosition): Promise<any>;
+    /**
+     * Checks for expired items in the queue and removes them. Calls onExpire for each expired item.
+     * Internal use only.
      */
-    getNextItem(position?: QueuePosition): (() => Promise<TValue>) | undefined;
+    private checkExpiredItems;
     /**
-     * Returns an item without removing it
+     * Returns the next item in the queue without removing it.
+     *
+     * @example
+     * ```ts
+     * queuer.getPeek(); // front
+     * queuer.getPeek('back'); // back
+     * ```
      */
-    getPeek(position?: QueuePosition): (() => Promise<TValue>) | undefined;
+    getPeek(position?: QueuePosition): TValue | undefined;
     /**
-     * Returns true if the queuer is empty
+     * Returns true if the queue is empty (no pending items).
      */
     getIsEmpty(): boolean;
     /**
-     * Returns true if the queuer is full
+     * Returns true if the queue is full (reached maxSize).
      */
     getIsFull(): boolean;
     /**
-     * Returns the current size of the queuer
+     * Returns the number of pending items in the queue.
      */
     getSize(): number;
     /**
-     * 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>;
     /**
-     * Returns the active items
+     * Returns the items currently being processed (active tasks).
      */
-    getActiveItems(): Array<() => Promise<TValue>>;
+    getActiveItems(): Array<TValue>;
     /**
-     * Returns the pending items
+     * Returns the items waiting to be processed (pending tasks).
      */
-    getPendingItems(): Array<() => Promise<TValue>>;
+    getPendingItems(): Array<TValue>;
     /**
-     * Returns the number of items that have been removed from the queuer
+     * Returns the number of items that have been successfully processed.
      */
-    getExecutionCount(): number;
+    getSuccessCount(): number;
     /**
-     * Returns the number of items that have been rejected from the queuer
+     * Returns the number of items that have failed processing.
      */
-    getRejectionCount(): number;
-    /**
-     * Returns true if the queuer is running
-     */
-    getIsRunning(): boolean;
+    getErrorCount(): number;
     /**
-     * Returns true if the queuer is running but has no items to process
+     * Returns the number of items that have completed processing (success or error).
      */
-    getIsIdle(): boolean;
+    getSettledCount(): number;
     /**
-     * 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): () => void;
+    getRejectionCount(): number;
     /**
-     * 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): () => void;
+    getIsRunning(): boolean;
     /**
-     * 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): () => void;
+    getIsIdle(): boolean;
     /**
-     * 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;
 }
 /**
- * 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.
  *
- * @example
+ * 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 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 declare function asyncQueue<TValue>(options: AsyncQueuerOptions<TValue>): (fn: AnyAsyncFunction & {
+export declare function asyncQueue<TValue>(fn: (value: TValue) => Promise<any>, initialOptions: AsyncQueuerOptions<TValue>): (item: TValue & {
     priority?: number;
-}, position?: QueuePosition, runOnItemsChange?: boolean) => Promise<TValue>;
+}, position?: QueuePosition, runOnItemsChange?: boolean) => void;