@tanstack/pacer 0.16.3 → 0.16.4

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

@@ -1,435 +0,0 @@
-import { Store } from '@tanstack/store';
-import { AsyncRetryer, AsyncRetryerOptions } from './async-retryer.js';
-import { QueuePosition } from './queuer.js';
-export interface AsyncQueuerState<TValue> {
-    /**
-     * Items currently being processed by the queuer
-     */
-    activeItems: Array<TValue>;
-    /**
-     * Number of times addItem has been called (for reduction calculations)
-     */
-    addItemCount: number;
-    /**
-     * 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
-     */
-    expirationCount: number;
-    /**
-     * 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
-     */
-    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;
-    /**
-     * Array of items currently waiting to be processed
-     */
-    items: Array<TValue>;
-    /**
-     * Timestamps when items were added to the queue for expiration tracking
-     */
-    itemTimestamps: Array<number>;
-    /**
-     * 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> {
-    /**
-     * Options for configuring the underlying async retryer
-     */
-    asyncRetryerOptions?: AsyncRetryerOptions<(item: TValue) => Promise<any>>;
-    /**
-     * Default position to add items to the queuer
-     * @default 'back'
-     */
-    addItemsTo?: QueuePosition;
-    /**
-     * Maximum number of concurrent tasks to process.
-     * Can be a number or a function that returns a number.
-     * @default 1
-     */
-    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
-     */
-    expirationDuration?: number;
-    /**
-     * Function to determine if an item has expired
-     * If provided, this overrides the expirationDuration behavior
-     */
-    getIsExpired?: (item: TValue, addedAt: number) => boolean;
-    /**
-     * Default position to get items from during processing
-     * @default 'front'
-     */
-    getItemsFrom?: QueuePosition;
-    /**
-     * Function to determine priority of items in the queuer
-     * Higher priority items will be processed first
-     * If not provided, will use static priority values attached to tasks
-     */
-    getPriority?: (item: TValue) => number;
-    /**
-     * Initial items to populate the queuer with
-     */
-    initialItems?: Array<TValue>;
-    /**
-     * Initial state for the async queuer
-     */
-    initialState?: Partial<AsyncQueuerState<TValue>>;
-    /**
-     * Optional key to identify this async queuer instance.
-     * If provided, the async queuer will be identified by this key in the devtools and PacerProvider if applicable.
-     */
-    key?: string;
-    /**
-     * Maximum number of items allowed in the queuer
-     */
-    maxSize?: number;
-    /**
-     * 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: Error, item: TValue, queuer: AsyncQueuer<TValue>) => void;
-    /**
-     * Callback fired whenever an item expires in the queuer
-     */
-    onExpire?: (item: TValue, queuer: AsyncQueuer<TValue>) => void;
-    /**
-     * Callback fired whenever an item is added or removed from the queuer
-     */
-    onItemsChange?: (queuer: AsyncQueuer<TValue>) => void;
-    /**
-     * Callback fired whenever an item is rejected from being added to the queuer
-     */
-    onReject?: (item: TValue, queuer: AsyncQueuer<TValue>) => void;
-    /**
-     * Optional callback to call when a task is settled
-     */
-    onSettled?: (item: TValue, queuer: AsyncQueuer<TValue>) => void;
-    /**
-     * Optional callback to call when a task succeeds
-     */
-    onSuccess?: (result: any, item: 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.
-     * @default 0
-     */
-    wait?: number | ((queuer: AsyncQueuer<TValue>) => number);
-}
-/**
- * Utility function for sharing common `AsyncQueuerOptions` options between different `AsyncQueuer` instances.
- */
-export declare function asyncQueuerOptions<TValue = any, TOptions extends Partial<AsyncQueuerOptions<TValue>> = Partial<AsyncQueuerOptions<TValue>>>(options: TOptions): TOptions;
-/**
- * A flexible asynchronous queue for processing tasks with configurable concurrency, priority, and expiration.
- *
- * 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
- * - Item expiration to remove stale items from the queue
- *
- * 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
- *
- * 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) => {
- *   // process item
- *   return item.toUpperCase();
- * }, {
- *   concurrency: 2,
- *   onSuccess: (result) => {
- *     console.log(result);
- *   }
- * });
- *
- * asyncQueuer.addItem('hello');
- * asyncQueuer.start();
- * ```
- */
-export declare class AsyncQueuer<TValue> {
-    #private;
-    fn: (item: TValue) => Promise<any>;
-    readonly store: Store<Readonly<AsyncQueuerState<TValue>>>;
-    key: string | undefined;
-    options: AsyncQueuerOptions<TValue>;
-    asyncRetryers: Map<number, AsyncRetryer<(item: TValue) => Promise<any>>>;
-    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;
-    /**
-     * 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: (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.
-     *
-     * @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>;
-    /**
-     * Processes a specified number of items to execute immediately with no wait time
-     * If no numberOfItems is provided, all items will be processed
-     */
-    flush: (numberOfItems?: number, position?: QueuePosition) => Promise<void>;
-    /**
-     * Processes all items in the queue as a batch using the provided function as an argument
-     * The queue is cleared after processing
-     */
-    flushAsBatch: (batchFunction: (items: Array<TValue>) => Promise<any>) => Promise<void>;
-    /**
-     * Returns the next item in the queue without removing it.
-     *
-     * @example
-     * ```ts
-     * queuer.peekNextItem(); // front
-     * queuer.peekNextItem('back'); // back
-     * ```
-     */
-    peekNextItem: (position?: QueuePosition) => TValue | undefined;
-    /**
-     * Returns a copy of all items in the queue, including active and pending items.
-     */
-    peekAllItems: () => Array<TValue>;
-    /**
-     * Returns the items currently being processed (active tasks).
-     */
-    peekActiveItems: () => Array<TValue>;
-    /**
-     * Returns the items waiting to be processed (pending tasks).
-     */
-    peekPendingItems: () => Array<TValue>;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * Aborts all ongoing executions with the internal abort controllers.
-     * Does NOT clear out the items.
-     */
-    abort: () => void;
-    /**
-     * Resets the queuer state to its default values
-     */
-    reset: () => void;
-}
-/**
- * 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
- * - 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
- *
- * 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
- * ```ts
- * const enqueue = asyncQueue<string>(async (item) => {
- *   return item.toUpperCase();
- * }, {
- *   concurrency: 2,
- *   wait: 100,
- *   onSuccess: (result) => console.log('Processed:', result)
- * });
- *
- * enqueue('hello');
- * ```
- */
-export declare function asyncQueue<TValue>(fn: (value: TValue) => Promise<any>, initialOptions: AsyncQueuerOptions<TValue>): (item: TValue, position?: QueuePosition, runOnItemsChange?: boolean) => boolean;