@tanstack/pacer 0.8.0 → 0.9.0

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

@@ -1,4 +1,71 @@
+import { Store } from '@tanstack/store';
 import { QueuePosition } from './queuer.js';
+export interface AsyncQueuerState<TValue> {
+    /**
+     * Items currently being processed by the queuer
+     */
+    activeItems: Array<TValue>;
+    /**
+     * Number of task executions that have resulted in errors
+     */
+    errorCount: number;
+    /**
+     * Number of items that have been removed from the queue due to expiration
+     */
+    expirationCount: number;
+    /**
+     * Whether the queuer has no items to process (items array is empty)
+     */
+    isEmpty: boolean;
+    /**
+     * Whether the queuer has reached its maximum capacity
+     */
+    isFull: boolean;
+    /**
+     * Whether the queuer is not currently processing any items
+     */
+    isIdle: boolean;
+    /**
+     * Whether the queuer is active and will process items automatically
+     */
+    isRunning: boolean;
+    /**
+     * Timestamps when items were added to the queue for expiration tracking
+     */
+    itemTimestamps: Array<number>;
+    /**
+     * Array of items currently waiting to be processed
+     */
+    items: Array<TValue>;
+    /**
+     * The result from the most recent task execution
+     */
+    lastResult: any;
+    /**
+     * Whether the queuer has a pending timeout for processing the next item
+     */
+    pendingTick: boolean;
+    /**
+     * Number of items that have been rejected from being added to the queue
+     */
+    rejectionCount: number;
+    /**
+     * Number of task executions that have completed (either successfully or with errors)
+     */
+    settledCount: number;
+    /**
+     * Number of items currently in the queue
+     */
+    size: number;
+    /**
+     * Current processing status - 'idle' when not processing, 'running' when active, 'stopped' when paused
+     */
+    status: 'idle' | 'running' | 'stopped';
+    /**
+     * Number of task executions that have completed successfully
+     */
+    successCount: number;
+}
 export interface AsyncQueuerOptions<TValue> {
     /**
      * Default position to add items to the queuer
@@ -36,6 +103,10 @@ export interface AsyncQueuerOptions<TValue> {
      * Initial items to populate the queuer with
      */
     initialItems?: Array<TValue>;
+    /**
+     * Initial state for the async queuer
+     */
+    initialState?: Partial<AsyncQueuerState<TValue>>;
     /**
      * Maximum number of items allowed in the queuer
      */
@@ -50,10 +121,6 @@ export interface AsyncQueuerOptions<TValue> {
      * 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
-     */
-    onIsRunningChange?: (queuer: AsyncQueuer<TValue>) => void;
     /**
      * Callback fired whenever an item is added or removed from the queuer
      */
@@ -109,6 +176,19 @@ export interface AsyncQueuerOptions<TValue> {
  * - 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
  *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the async queuer
+ * - Use `onSuccess` callback to react to successful task execution and implement custom logic
+ * - Use `onError` callback to react to task execution errors and implement custom error handling
+ * - Use `onSettled` callback to react to task execution completion (success or error) and implement custom logic
+ * - Use `onItemsChange` callback to react to items being added or removed from the queue
+ * - Use `onExpire` callback to react to items expiring and implement custom logic
+ * - Use `onReject` callback to react to items being rejected when the queue is full
+ * - The state includes error count, expiration count, rejection count, running status, and success/settle counts
+ * - State can be accessed via `asyncQueuer.store.state` when using the class directly
+ * - When using framework adapters (React/Solid), state is accessed from `asyncQueuer.state`
+ *
  * Example usage:
  * ```ts
  * const asyncQueuer = new AsyncQueuer<string>(async (item) => {
@@ -126,59 +206,15 @@ export interface AsyncQueuerOptions<TValue> {
  * ```
  */
 export declare class AsyncQueuer<TValue> {
+    #private;
     private fn;
-    private _options;
-    private _activeItems;
-    private _successCount;
-    private _errorCount;
-    private _settledCount;
-    private _rejectionCount;
-    private _expirationCount;
-    private _items;
-    private _itemTimestamps;
-    private _pendingTick;
-    private _running;
-    private _lastResult;
-    constructor(fn: (value: TValue) => Promise<any>, initialOptions: AsyncQueuerOptions<TValue>);
+    readonly store: Store<Readonly<AsyncQueuerState<TValue>>>;
+    options: AsyncQueuerOptions<TValue>;
+    constructor(fn: (item: TValue) => Promise<any>, initialOptions?: AsyncQueuerOptions<TValue>);
     /**
      * Updates the queuer options. New options are merged with existing options.
      */
-    setOptions(newOptions: Partial<AsyncQueuerOptions<TValue>>): void;
-    /**
-     * Returns the current queuer options, including defaults and any overrides.
-     */
-    getOptions(): AsyncQueuerOptions<TValue>;
-    /**
-     * 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 for processing items.
-     * If a function is provided, it is called with the queuer instance.
-     */
-    getConcurrency(): number;
-    /**
-     * Processes items in the queue up to the concurrency limit. Internal use only.
-     */
-    private tick;
-    /**
-     * Starts processing items in the queue. If already running, does nothing.
-     */
-    start(): void;
-    /**
-     * Stops processing items in the queue. Does not clear the queue.
-     */
-    stop(): void;
-    /**
-     * Removes all pending items from the queue. Does not affect active tasks.
-     */
-    clear(): void;
-    /**
-     * Resets the queuer to its initial state. Optionally repopulates with initial items.
-     * Does not affect callbacks or options.
-     */
-    reset(withInitialItems?: boolean): void;
+    setOptions: (newOptions: Partial<AsyncQueuerOptions<TValue>>) => void;
     /**
      * 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.
@@ -189,9 +225,7 @@ export declare class AsyncQueuer<TValue> {
      * queuer.addItem('task2', 'front');
      * ```
      */
-    addItem(item: TValue & {
-        priority?: number;
-    }, position?: QueuePosition, runOnItemsChange?: boolean): void;
+    addItem: (item: TValue, position?: QueuePosition, runOnItemsChange?: boolean) => boolean;
     /**
      * 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.
@@ -204,7 +238,7 @@ export declare class AsyncQueuer<TValue> {
      * queuer.getNextItem('back');
      * ```
      */
-    getNextItem(position?: QueuePosition): TValue | undefined;
+    getNextItem: (position?: QueuePosition) => TValue | undefined;
     /**
      * Removes and returns the next item from the queue and executes the task function with it.
      *
@@ -215,12 +249,12 @@ export declare class AsyncQueuer<TValue> {
      * queuer.execute('back');
      * ```
      */
-    execute(position?: QueuePosition): Promise<any>;
+    execute: (position?: QueuePosition) => Promise<any>;
     /**
-     * Checks for expired items in the queue and removes them. Calls onExpire for each expired item.
-     * Internal use only.
+     * Processes a specified number of items to execute immediately with no wait time
+     * If no numberOfItems is provided, all items will be processed
      */
-    private checkExpiredItems;
+    flush: (numberOfItems?: number, position?: QueuePosition) => void;
     /**
      * Returns the next item in the queue without removing it.
      *
@@ -230,59 +264,35 @@ export declare class AsyncQueuer<TValue> {
      * queuer.peekNextItem('back'); // back
      * ```
      */
-    peekNextItem(position?: QueuePosition): TValue | undefined;
-    /**
-     * Returns true if the queue is empty (no pending items).
-     */
-    getIsEmpty(): boolean;
-    /**
-     * Returns true if the queue is full (reached maxSize).
-     */
-    getIsFull(): boolean;
-    /**
-     * Returns the number of pending items in the queue.
-     */
-    getSize(): number;
+    peekNextItem: (position?: QueuePosition) => TValue | undefined;
     /**
      * Returns a copy of all items in the queue, including active and pending items.
      */
-    peekAllItems(): Array<TValue>;
+    peekAllItems: () => Array<TValue>;
     /**
      * Returns the items currently being processed (active tasks).
      */
-    peekActiveItems(): Array<TValue>;
+    peekActiveItems: () => Array<TValue>;
     /**
      * Returns the items waiting to be processed (pending tasks).
      */
-    peekPendingItems(): Array<TValue>;
-    /**
-     * Returns the number of items that have been successfully processed.
-     */
-    getSuccessCount(): number;
-    /**
-     * Returns the number of items that have failed processing.
-     */
-    getErrorCount(): number;
-    /**
-     * Returns the number of items that have completed processing (success or error).
-     */
-    getSettledCount(): number;
+    peekPendingItems: () => Array<TValue>;
     /**
-     * Returns the number of items that have been rejected from being added to the queue.
+     * Starts processing items in the queue. If already running, does nothing.
      */
-    getRejectionCount(): number;
+    start: () => void;
     /**
-     * Returns true if the queuer is currently running (processing items).
+     * Stops processing items in the queue. Does not clear the queue.
      */
-    getIsRunning(): boolean;
+    stop: () => void;
     /**
-     * Returns true if the queuer is running but has no items to process and no active tasks.
+     * Removes all pending items from the queue. Does not affect active tasks.
      */
-    getIsIdle(): boolean;
+    clear: () => void;
     /**
-     * Returns the number of items that have expired and been removed from the queue.
+     * Resets the queuer state to its default values
      */
-    getExpirationCount(): number;
+    reset: () => void;
 }
 /**
  * Creates a new AsyncQueuer instance and returns a bound addItem function for adding tasks.
@@ -295,6 +305,19 @@ export declare class AsyncQueuer<TValue> {
  * - 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
  *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the async queuer
+ * - Use `onSuccess` callback to react to successful task execution and implement custom logic
+ * - Use `onError` callback to react to task execution errors and implement custom error handling
+ * - Use `onSettled` callback to react to task execution completion (success or error) and implement custom logic
+ * - Use `onItemsChange` callback to react to items being added or removed from the queue
+ * - Use `onExpire` callback to react to items expiring and implement custom logic
+ * - Use `onReject` callback to react to items being rejected when the queue is full
+ * - The state includes error count, expiration count, rejection count, running status, and success/settle counts
+ * - 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:
  * ```ts
  * const enqueue = asyncQueue<string>(async (item) => {
@@ -304,6 +327,4 @@ export declare class AsyncQueuer<TValue> {
  * enqueue('hello');
  * ```
  */
-export declare function asyncQueue<TValue>(fn: (value: TValue) => Promise<any>, initialOptions: AsyncQueuerOptions<TValue>): (item: TValue & {
-    priority?: number;
-}, position?: QueuePosition, runOnItemsChange?: boolean) => void;
+export declare function asyncQueue<TValue>(fn: (value: TValue) => Promise<any>, initialOptions: AsyncQueuerOptions<TValue>): (item: TValue, position?: QueuePosition, runOnItemsChange?: boolean) => boolean;