@tanstack/pacer 0.5.0 → 0.7.0

package/dist/esm/queuer.d.ts

@@ -1,5 +1,7 @@
 /**
- * Options for configuring a Queuer instance
+ * Options for configuring a Queuer instance.
+ *
+ * These options control queue behavior, item expiration, callbacks, and more.
  */
 export interface QueuerOptions<TValue> {
     /**
@@ -42,7 +44,7 @@ export interface QueuerOptions<TValue> {
     /**
      * Callback fired whenever an item is removed from the queuer
      */
-    onGetNextItem?: (item: TValue, queuer: Queuer<TValue>) => void;
+    onExecute?: (item: TValue, queuer: Queuer<TValue>) => void;
     /**
      * Callback fired whenever the queuer's running state changes
      */
@@ -67,64 +69,75 @@ export interface QueuerOptions<TValue> {
     wait?: number | ((queuer: Queuer<TValue>) => number);
 }
 /**
- * Position type for addItem and getNextItem operations
+ * Position type for addItem and getNextItem operations.
+ *
+ * - 'front': Operate on the front of the queue (FIFO)
+ * - 'back': Operate on the back of the queue (LIFO)
  */
 export type QueuePosition = 'front' | 'back';
 /**
- * A flexible queue data structure that defaults to FIFO (First In First Out) behavior
- * with optional position overrides for stack-like or double-ended operations.
+ * A flexible queue that processes items with configurable wait times, expiration, and priority.
  *
- * The queuer can automatically process items as they are added, with configurable
- * wait times between processing each item. Processing can be started/stopped
- * and the queuer will maintain its state.
+ * Features:
+ * - Automatic or manual processing of items
+ * - FIFO (First In First Out), LIFO (Last In First Out), or double-ended queue behavior
+ * - Priority-based ordering when getPriority is provided
+ * - Item expiration and removal of stale items
+ * - Callbacks for queue state changes, execution, rejection, and expiration
  *
- * Supports priority-based ordering when a getPriority function is provided.
- * Items with higher priority values will be processed first.
+ * Running behavior:
+ * - `start()`: Begins automatically processing items in the queue (defaults to running)
+ * - `stop()`: Pauses processing but maintains queue state
+ * - `wait`: Configurable delay between processing items
+ * - `onItemsChange`/`onExecute`: Callbacks for monitoring queue state
  *
- * Default queue behavior:
- * - addItem(item): adds to back of queuer
- * - getNextItem(): removes and returns from front of queuer
+ * Manual processing is also supported when automatic processing is disabled:
+ * - `execute()`: Processes the next item using the provided function
+ * - `getNextItem()`: Removes and returns the next item without processing
  *
- * Stack (LIFO) behavior:
- * - addItem(item, 'back'): adds to back
- * - getNextItem('back'): removes and returns from back
+ * Queue behavior defaults to FIFO:
+ * - `addItem(item)`: Adds to the back of the queue
+ * - Items processed from the front of the queue
  *
- * Double-ended queuer behavior:
- * - addItem(item, position): adds to specified position ('front' or 'back')
- * - getNextItem(position): removes and returns from specified position
+ * Priority queue:
+ * - Provide a `getPriority` function; higher values are processed first
  *
- * Processing behavior:
- * - start(): begins processing items in the queuer
- * - stop(): pauses processing
- * - wait: configurable delay between processing items
- * - onItemsChange/onGetNextItem: callbacks for monitoring queuer state
+ * Stack (LIFO):
+ * - `addItem(item, 'back')`: Adds to the back
+ * - `getNextItem('back')`: Removes from the back
  *
- * Supports item expiration to clear stale items from the queuer
- * - expirationDuration: maximum time in milliseconds that an item can stay in the queue
- * - getIsExpired: function to override default expiration behavior
- * - onExpire: callback for when an item expires
+ * Double-ended queue:
+ * - `addItem(item, position)`: Adds to specified position ('front'/'back')
+ * - `getNextItem(position)`: Removes from specified position
  *
- * @example
- * ```ts
- * // FIFO queuer
- * const queuer = new Queuer<number>();
- * queuer.addItem(1); // [1]
- * queuer.addItem(2); // [1, 2]
- * queuer.getNextItem(); // returns 1, queuer is [2]
+ * Item expiration:
+ * - `expirationDuration`: Maximum time items can stay in the queue
+ * - `getIsExpired`: Function to override default expiration
+ * - `onExpire`: Callback for expired items
  *
- * // Priority queuer with processing
- * const priorityQueue = new Queuer<number>({
- *   getPriority: (n) => n, // Higher numbers have priority
+ * Example usage:
+ * ```ts
+ * // Auto-processing queue with wait time
+ * const autoQueue = new Queuer<number>((n) => console.log(n), {
  *   started: true, // Begin processing immediately
  *   wait: 1000, // Wait 1s between items
- *   onGetNextItem: (item, queuer) => console.log(item)
+ *   onExecute: (item) => console.log(`Processed ${item}`)
  * });
- * priorityQueue.addItem(1); // [1]
- * priorityQueue.addItem(3); // [3, 1] - 3 processed first
- * priorityQueue.addItem(2); // [3, 2, 1]
+ * autoQueue.addItem(1); // Will process after 1s
+ * autoQueue.addItem(2); // Will process 1s after first item
+ *
+ * // Manual processing queue
+ * const manualQueue = new Queuer<number>((n) => console.log(n), {
+ *   started: false
+ * });
+ * manualQueue.addItem(1); // [1]
+ * manualQueue.addItem(2); // [1, 2]
+ * manualQueue.execute(); // logs 1, queue is [2]
+ * manualQueue.getNextItem(); // returns 2, queue is empty
  * ```
  */
 export declare class Queuer<TValue> {
+    private fn;
     private _options;
     private _items;
     private _itemTimestamps;
@@ -134,136 +147,154 @@ export declare class Queuer<TValue> {
     private _onItemsChanges;
     private _running;
     private _pendingTick;
-    constructor(initialOptions?: QueuerOptions<TValue>);
+    constructor(fn: (item: TValue) => void, initialOptions?: QueuerOptions<TValue>);
     /**
-     * Updates the queuer options
-     * Returns the new options state
+     * Updates the queuer options. New options are merged with existing options.
      */
     setOptions(newOptions: Partial<QueuerOptions<TValue>>): void;
     /**
-     * Returns the current queuer options
+     * Returns the current queuer options, including defaults and any overrides.
      */
     getOptions(): Required<QueuerOptions<TValue>>;
     /**
-     * Returns the current wait time in milliseconds
+     * Returns the current wait time (in milliseconds) between processing items.
+     * If a function is provided, it is called with the queuer instance.
      */
     getWait(): number;
     /**
-     * Processes items in the queuer
+     * Processes items in the queue up to the wait interval. Internal use only.
      */
     private tick;
     /**
-     * Checks for and removes expired items from the queuer
+     * Checks for expired items in the queue and removes them. Calls onExpire for each expired item.
+     * Internal use only.
      */
     private checkExpiredItems;
     /**
-     * Stops the queuer from processing items
+     * Stops processing items in the queue. Does not clear the queue.
      */
     stop(): void;
     /**
-     * Starts the queuer and processes items
+     * Starts processing items in the queue. If already running, does nothing.
      */
     start(): void;
     /**
-     * Removes all items from the queuer
+     * Removes all pending items from the queue. Does not affect items being processed.
      */
     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 an item to the queuer and starts processing if not already running
-     * @returns true if item was added, false if queuer is full
+     * 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.
+     *
+     * Returns true if the item was added, false if the queue is full.
+     *
+     * Example usage:
+     * ```ts
+     * queuer.addItem('task');
+     * queuer.addItem('task2', 'front');
+     * ```
      */
     addItem(item: TValue, position?: QueuePosition, runOnUpdate?: boolean): boolean;
     /**
-     * Removes and returns an item from the queuer using shift (default) or pop
+     * Removes and returns the next item from the queue without executing the function.
+     * Use for manual queue management. Normally, use execute() to process items.
      *
-     * @example
+     * Example usage:
      * ```ts
-     * // Standard FIFO queuer
-     * queuer.getNextItem()
-     * // Stack-like behavior (LIFO)
-     * queuer.getNextItem('back')
+     * // FIFO
+     * queuer.getNextItem();
+     * // LIFO
+     * queuer.getNextItem('back');
      * ```
      */
     getNextItem(position?: QueuePosition): TValue | undefined;
     /**
-     * Returns an item without removing it
+     * Removes and returns the next item from the queue and processes it using the provided function.
+     *
+     * Example usage:
+     * ```ts
+     * queuer.execute();
+     * // LIFO
+     * queuer.execute('back');
+     * ```
+     */
+    execute(position?: QueuePosition): TValue | undefined;
+    /**
+     * Returns the next item in the queue without removing it.
      *
-     * @example
+     * Example usage:
      * ```ts
-     * // Look at next item to getNextItem
-     * queuer.getPeek()
-     * // Look at last item (like stack top)
-     * queuer.getPeek('back')
+     * queuer.getPeek(); // front
+     * queuer.getPeek('back'); // back
      * ```
      */
     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.
      */
     getAllItems(): Array<TValue>;
     /**
-     * Returns the number of items that have been removed from the queuer
+     * Returns the number of items that have been processed and removed from the queue.
      */
     getExecutionCount(): number;
     /**
-     * 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;
     /**
-     * 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;
     /**
-     * Returns true if the queuer is running
+     * Returns true if the queuer is currently running (processing items).
      */
     getIsRunning(): boolean;
     /**
-     * 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.
      */
     getIsIdle(): boolean;
 }
 /**
- * Creates a queue that processes items in a queuer immediately upon addition.
+ * Creates a queue that processes items immediately upon addition.
  * Items are processed sequentially in FIFO order by default.
  *
  * This is a simplified wrapper around the Queuer class that only exposes the
- * `addItem` method. This queue is always running and will process items as they are added.
- * For more control over queuer processing, use the Queuer class
- * directly which provides methods like `start`, `stop`, `reset`, and more.
+ * `addItem` method. The queue is always running and will process items as they are added.
+ * For more control over queue processing, use the Queuer class directly.
  *
- * @example
+ * Example usage:
  * ```ts
  * // Basic sequential processing
- * const processItems = queuer<number>({
+ * const processItems = queue<number>((n) => console.log(n), {
  *   wait: 1000,
  *   onItemsChange: (queuer) => console.log(queuer.getAllItems())
- * })
- * processItems(1) // Logs: 1
- * processItems(2) // Logs: 2 after 1 completes
+ * });
+ * processItems(1); // Logs: 1
+ * processItems(2); // Logs: 2 after 1 completes
  *
- * // Priority queuer
- * const processPriority = queuer<number>({
- *   process: async (n) => console.log(n),
+ * // Priority queue
+ * const processPriority = queue<number>((n) => console.log(n), {
  *   getPriority: n => n // Higher numbers processed first
- * })
- * processPriority(1)
- * processPriority(3) // Processed before 1
+ * });
+ * processPriority(1);
+ * processPriority(3); // Processed before 1
  * ```
  */
-export declare function queue<TValue>(options: QueuerOptions<TValue>): (item: TValue, position?: QueuePosition, runOnUpdate?: boolean) => boolean;
+export declare function queue<TValue>(fn: (item: TValue) => void, options: QueuerOptions<TValue>): (item: TValue, position?: QueuePosition, runOnUpdate?: boolean) => boolean;

package/dist/esm/queuer.js

@@ -7,7 +7,7 @@ const defaultOptions = {
   expirationDuration: Infinity,
   initialItems: [],
   maxSize: Infinity,
-  onGetNextItem: () => {
+  onExecute: () => {
   },
   onIsRunningChange: () => {
   },
@@ -21,7 +21,8 @@ const defaultOptions = {
   wait: 0
 };
 class Queuer {
-  constructor(initialOptions = defaultOptions) {
+  constructor(fn, initialOptions = {}) {
+    this.fn = fn;
     this._items = [];
     this._itemTimestamps = [];
     this._executionCount = 0;
@@ -38,26 +39,26 @@ class Queuer {
     }
   }
   /**
-   * Updates the queuer options
-   * Returns the new options state
+   * Updates the queuer options. New options are merged with existing options.
    */
   setOptions(newOptions) {
     this._options = { ...this._options, ...newOptions };
   }
   /**
-   * Returns the current queuer options
+   * Returns the current queuer options, including defaults and any overrides.
    */
   getOptions() {
     return this._options;
   }
   /**
-   * Returns the current wait time in milliseconds
+   * Returns the current wait time (in milliseconds) between processing items.
+   * If a function is provided, it is called with the queuer instance.
    */
   getWait() {
     return parseFunctionOrValue(this._options.wait, this);
   }
   /**
-   * Processes items in the queuer
+   * Processes items in the queue up to the wait interval. Internal use only.
    */
   tick() {
     if (!this._running) {
@@ -66,7 +67,7 @@ class Queuer {
     }
     this.checkExpiredItems();
     while (!this.getIsEmpty()) {
-      const nextItem = this.getNextItem(this._options.getItemsFrom);
+      const nextItem = this.execute(this._options.getItemsFrom);
       if (nextItem === void 0) {
         break;
       }
@@ -81,7 +82,8 @@ class Queuer {
     this._pendingTick = false;
   }
   /**
-   * Checks for and removes expired items from the queuer
+   * Checks for expired items in the queue and removes them. Calls onExpire for each expired item.
+   * Internal use only.
    */
   checkExpiredItems() {
     if (this._options.expirationDuration === Infinity && this._options.getIsExpired === defaultOptions.getIsExpired)
@@ -113,7 +115,7 @@ class Queuer {
     }
   }
   /**
-   * Stops the queuer from processing items
+   * Stops processing items in the queue. Does not clear the queue.
    */
   stop() {
     this._running = false;
@@ -121,7 +123,7 @@ class Queuer {
     this._options.onIsRunningChange(this);
   }
   /**
-   * Starts the queuer and processes items
+   * Starts processing items in the queue. If already running, does nothing.
    */
   start() {
     this._running = true;
@@ -132,14 +134,15 @@ class Queuer {
     this._options.onIsRunningChange(this);
   }
   /**
-   * Removes all items from the queuer
+   * Removes all pending items from the queue. Does not affect items being processed.
    */
   clear() {
     this._items = [];
     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) {
     this.clear();
@@ -150,8 +153,16 @@ class Queuer {
     this._running = this._options.started;
   }
   /**
-   * Adds an item to the queuer and starts processing if not already running
-   * @returns true if item was added, false if queuer is full
+   * 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.
+   *
+   * Returns true if the item was added, false if the queue is full.
+   *
+   * Example usage:
+   * ```ts
+   * queuer.addItem('task');
+   * queuer.addItem('task2', 'front');
+   * ```
    */
   addItem(item, position = this._options.addItemsTo, runOnUpdate = true) {
     if (this.getIsFull()) {
@@ -162,7 +173,7 @@ class Queuer {
     if (this._options.getPriority !== defaultOptions.getPriority) {
       const priority = this._options.getPriority(item);
       const insertIndex = this._items.findIndex(
-        (existing) => this._options.getPriority(existing) > priority
+        (existing) => this._options.getPriority(existing) < priority
       );
       if (insertIndex === -1) {
         this._items.push(item);
@@ -190,14 +201,15 @@ class Queuer {
     return true;
   }
   /**
-   * Removes and returns an item from the queuer using shift (default) or pop
+   * Removes and returns the next item from the queue without executing the function.
+   * Use for manual queue management. Normally, use execute() to process items.
    *
-   * @example
+   * Example usage:
    * ```ts
-   * // Standard FIFO queuer
-   * queuer.getNextItem()
-   * // Stack-like behavior (LIFO)
-   * queuer.getNextItem('back')
+   * // FIFO
+   * queuer.getNextItem();
+   * // LIFO
+   * queuer.getNextItem('back');
    * ```
    */
   getNextItem(position = this._options.getItemsFrom) {
@@ -210,21 +222,36 @@ class Queuer {
       this._itemTimestamps.pop();
     }
     if (item !== void 0) {
-      this._executionCount++;
       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 processes it using the provided function.
+   *
+   * Example usage:
+   * ```ts
+   * queuer.execute();
+   * // LIFO
+   * queuer.execute('back');
+   * ```
+   */
+  execute(position) {
+    const item = this.getNextItem(position);
+    if (item !== void 0) {
+      this.fn(item);
+      this._executionCount++;
+      this._options.onExecute(item, this);
+    }
+    return item;
+  }
+  /**
+   * Returns the next item in the queue without removing it.
    *
-   * @example
+   * Example usage:
    * ```ts
-   * // Look at next item to getNextItem
-   * queuer.getPeek()
-   * // Look at last item (like stack top)
-   * queuer.getPeek('back')
+   * queuer.getPeek(); // front
+   * queuer.getPeek('back'); // back
    * ```
    */
   getPeek(position = this._options.getItemsFrom) {
@@ -234,62 +261,62 @@ class Queuer {
     return this._items[this._items.length - 1];
   }
   /**
-   * Returns true if the queuer is empty
+   * Returns true if the queue is empty (no pending items).
    */
   getIsEmpty() {
     return this._items.length === 0;
   }
   /**
-   * Returns true if the queuer is full
+   * Returns true if the queue is full (reached maxSize).
    */
   getIsFull() {
     return this._items.length >= this._options.maxSize;
   }
   /**
-   * Returns the current size of the queuer
+   * Returns the number of pending items in the queue.
    */
   getSize() {
     return this._items.length;
   }
   /**
-   * Returns a copy of all items in the queuer
+   * Returns a copy of all items in the queue.
    */
   getAllItems() {
     return [...this._items];
   }
   /**
-   * Returns the number of items that have been removed from the queuer
+   * Returns the number of items that have been processed and removed from the queue.
    */
   getExecutionCount() {
     return this._executionCount;
   }
   /**
-   * 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() {
     return this._rejectionCount;
   }
   /**
-   * 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() {
     return this._expirationCount;
   }
   /**
-   * Returns true if the queuer is running
+   * Returns true if the queuer is currently running (processing items).
    */
   getIsRunning() {
     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.
    */
   getIsIdle() {
     return this._running && this.getIsEmpty();
   }
 }
-function queue(options) {
-  const queuer = new Queuer(options);
+function queue(fn, options) {
+  const queuer = new Queuer(fn, options);
   return queuer.addItem.bind(queuer);
 }
 export {