@tanstack/pacer 0.1.0 → 0.3.0

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/index.d.cts

@@ -7,3 +7,5 @@ export * from './debouncer.cjs';
 export * from './queuer.cjs';
 export * from './rate-limiter.cjs';
 export * from './throttler.cjs';
+export * from './types.cjs';
+export * from './utils.cjs';

package/dist/cjs/queuer.cjs

@@ -3,91 +3,183 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const defaultOptions = {
   addItemsTo: "back",
   getItemsFrom: "front",
-  getPriority: () => 0,
+  getPriority: (item) => (item == null ? void 0 : item.priority) ?? 0,
+  getIsExpired: () => false,
+  expirationDuration: Infinity,
   initialItems: [],
   maxSize: Infinity,
   onGetNextItem: () => {
   },
-  onUpdate: () => {
+  onIsRunningChange: () => {
+  },
+  onItemsChange: () => {
+  },
+  onReject: () => {
+  },
+  onExpire: () => {
   },
   started: false,
   wait: 0
 };
 class Queuer {
   constructor(initialOptions = defaultOptions) {
-    this.items = [];
-    this.executionCount = 0;
-    this.onUpdates = [];
-    this.pendingTick = false;
-    this.options = { ...defaultOptions, ...initialOptions };
-    this.running = this.options.started;
-    for (let i = 0; i < this.options.initialItems.length; i++) {
-      const item = this.options.initialItems[i];
-      const isLast = i === this.options.initialItems.length - 1;
-      this.addItem(item, this.options.addItemsTo, isLast);
+    this._items = [];
+    this._itemTimestamps = [];
+    this._executionCount = 0;
+    this._rejectionCount = 0;
+    this._expirationCount = 0;
+    this._onItemsChanges = [];
+    this._pendingTick = false;
+    this._options = { ...defaultOptions, ...initialOptions };
+    this._running = this._options.started;
+    for (let i = 0; i < this._options.initialItems.length; i++) {
+      const item = this._options.initialItems[i];
+      const isLast = i === this._options.initialItems.length - 1;
+      this.addItem(item, this._options.addItemsTo, isLast);
     }
   }
+  /**
+   * Updates the queuer options
+   * Returns the new options state
+   */
+  setOptions(newOptions) {
+    this._options = { ...this._options, ...newOptions };
+  }
+  /**
+   * Returns the current queuer options
+   */
+  getOptions() {
+    return this._options;
+  }
   /**
    * Processes items in the queuer
    */
   tick() {
-    if (!this.running) {
-      this.pendingTick = false;
+    if (!this._running) {
+      this._pendingTick = false;
       return;
     }
-    while (!this.isEmpty()) {
-      const nextItem = this.getNextItem(this.options.getItemsFrom);
+    this.checkExpiredItems();
+    while (!this.getIsEmpty()) {
+      const nextItem = this.getNextItem(this._options.getItemsFrom);
       if (nextItem === void 0) {
         break;
       }
-      this.onUpdates.forEach((cb) => cb(nextItem));
-      if (this.options.wait > 0) {
-        setTimeout(() => this.tick(), this.options.wait);
+      this._onItemsChanges.forEach((cb) => cb(nextItem));
+      if (this._options.wait > 0) {
+        setTimeout(() => this.tick(), this._options.wait);
         return;
       }
       this.tick();
     }
-    this.pendingTick = false;
+    this._pendingTick = false;
   }
   /**
-   * Updates the queuer options
-   * Returns the new options state
+   * Checks for and removes expired items from the queuer
    */
-  setOptions(newOptions) {
-    this.options = { ...this.options, ...newOptions };
-    return this.options;
+  checkExpiredItems() {
+    if (this._options.expirationDuration === Infinity && this._options.getIsExpired === defaultOptions.getIsExpired)
+      return;
+    const now = Date.now();
+    const expiredIndices = [];
+    for (let i = 0; i < this._items.length; i++) {
+      const timestamp = this._itemTimestamps[i];
+      if (timestamp === void 0) continue;
+      const item = this._items[i];
+      if (item === void 0) continue;
+      const isExpired = this._options.getIsExpired !== defaultOptions.getIsExpired ? this._options.getIsExpired(item, timestamp) : now - timestamp > this._options.expirationDuration;
+      if (isExpired) {
+        expiredIndices.push(i);
+      }
+    }
+    for (let i = expiredIndices.length - 1; i >= 0; i--) {
+      const index = expiredIndices[i];
+      if (index === void 0) continue;
+      const expiredItem = this._items[index];
+      if (expiredItem === void 0) 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);
+    }
+  }
+  /**
+   * Stops the queuer from processing items
+   */
+  stop() {
+    this._running = false;
+    this._pendingTick = false;
+    this._options.onIsRunningChange(this);
+  }
+  /**
+   * Starts the queuer and processes items
+   */
+  start() {
+    this._running = true;
+    if (!this._pendingTick && !this.getIsEmpty()) {
+      this._pendingTick = true;
+      this.tick();
+    }
+    this._options.onIsRunningChange(this);
+  }
+  /**
+   * Removes all items from the queuer
+   */
+  clear() {
+    this._items = [];
+    this._options.onItemsChange(this);
+  }
+  /**
+   * Resets the queuer to its initial state
+   */
+  reset(withInitialItems) {
+    this.clear();
+    this._executionCount = 0;
+    if (withInitialItems) {
+      this._items = [...this._options.initialItems];
+    }
+    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
    */
-  addItem(item, position = this.options.addItemsTo, runOnUpdate = true) {
-    if (this.isFull()) {
+  addItem(item, position = this._options.addItemsTo, runOnUpdate = true) {
+    if (this.getIsFull()) {
+      this._rejectionCount++;
+      this._options.onReject(item, this);
       return false;
     }
-    if (this.options.getPriority !== defaultOptions.getPriority) {
-      const priority = this.options.getPriority(item);
-      const insertIndex = this.items.findIndex(
-        (existing) => this.options.getPriority(existing) > priority
+    if (this._options.getPriority !== defaultOptions.getPriority) {
+      const priority = this._options.getPriority(item);
+      const insertIndex = this._items.findIndex(
+        (existing) => this._options.getPriority(existing) > priority
       );
       if (insertIndex === -1) {
-        this.items.push(item);
+        this._items.push(item);
+        this._itemTimestamps.push(Date.now());
       } else {
-        this.items.splice(insertIndex, 0, item);
+        this._items.splice(insertIndex, 0, item);
+        this._itemTimestamps.splice(insertIndex, 0, Date.now());
       }
     } else {
       if (position === "front") {
-        this.items.unshift(item);
+        this._items.unshift(item);
+        this._itemTimestamps.unshift(Date.now());
       } else {
-        this.items.push(item);
+        this._items.push(item);
+        this._itemTimestamps.push(Date.now());
       }
     }
-    if (this.running && !this.pendingTick) {
-      this.pendingTick = true;
+    if (this._running && !this._pendingTick) {
+      this._pendingTick = true;
       this.tick();
     }
     if (runOnUpdate) {
-      this.options.onUpdate(this);
+      this._options.onItemsChange(this);
     }
     return true;
   }
@@ -102,17 +194,19 @@ class Queuer {
    * queuer.getNextItem('back')
    * ```
    */
-  getNextItem(position = this.options.getItemsFrom) {
+  getNextItem(position = this._options.getItemsFrom) {
     let item;
     if (position === "front") {
-      item = this.items.shift();
+      item = this._items.shift();
+      this._itemTimestamps.shift();
     } else {
-      item = this.items.pop();
+      item = this._items.pop();
+      this._itemTimestamps.pop();
     }
     if (item !== void 0) {
-      this.executionCount++;
-      this.options.onUpdate(this);
-      this.options.onGetNextItem(item, this);
+      this._executionCount++;
+      this._options.onItemsChange(this);
+      this._options.onGetNextItem(item, this);
     }
     return item;
   }
@@ -122,104 +216,70 @@ class Queuer {
    * @example
    * ```ts
    * // Look at next item to getNextItem
-   * queuer.peek()
+   * queuer.getPeek()
    * // Look at last item (like stack top)
-   * queuer.peek('back')
+   * queuer.getPeek('back')
    * ```
    */
-  peek(position = this.options.getItemsFrom) {
+  getPeek(position = this._options.getItemsFrom) {
     if (position === "front") {
-      return this.items[0];
+      return this._items[0];
     }
-    return this.items[this.items.length - 1];
+    return this._items[this._items.length - 1];
   }
   /**
    * Returns true if the queuer is empty
    */
-  isEmpty() {
-    return this.items.length === 0;
+  getIsEmpty() {
+    return this._items.length === 0;
   }
   /**
    * Returns true if the queuer is full
    */
-  isFull() {
-    return this.items.length >= this.options.maxSize;
+  getIsFull() {
+    return this._items.length >= this._options.maxSize;
   }
   /**
    * Returns the current size of the queuer
    */
-  size() {
-    return this.items.length;
-  }
-  /**
-   * Removes all items from the queuer
-   */
-  clear() {
-    this.items = [];
-    this.options.onUpdate(this);
-  }
-  /**
-   * Resets the queuer to its initial state
-   */
-  reset(withInitialItems) {
-    this.clear();
-    this.executionCount = 0;
-    if (withInitialItems) {
-      this.items = [...this.options.initialItems];
-    }
-    this.running = this.options.started;
+  getSize() {
+    return this._items.length;
   }
   /**
    * Returns a copy of all items in the queuer
    */
   getAllItems() {
-    return [...this.items];
+    return [...this._items];
   }
   /**
    * Returns the number of items that have been removed from the queuer
    */
   getExecutionCount() {
-    return this.executionCount;
-  }
-  /**
-   * Adds a callback to be called when an item is processed
-   */
-  onUpdate(cb) {
-    this.onUpdates.push(cb);
-    return () => {
-      this.onUpdates = this.onUpdates.filter((d) => d !== cb);
-    };
+    return this._executionCount;
   }
   /**
-   * Stops the queuer from processing items
+   * Returns the number of items that have been rejected from the queuer
    */
-  stop() {
-    this.running = false;
-    this.pendingTick = false;
-    this.options.onUpdate(this);
+  getRejectionCount() {
+    return this._rejectionCount;
   }
   /**
-   * Starts the queuer and processes items
+   * Returns the number of items that have expired from the queuer
    */
-  start() {
-    this.running = true;
-    if (!this.pendingTick && !this.isEmpty()) {
-      this.pendingTick = true;
-      this.tick();
-    }
-    this.options.onUpdate(this);
+  getExpirationCount() {
+    return this._expirationCount;
   }
   /**
    * Returns true if the queuer is running
    */
-  isRunning() {
-    return this.running;
+  getIsRunning() {
+    return this._running;
   }
   /**
    * Returns true if the queuer is running but has no items to process
    */
-  isIdle() {
-    return this.running && this.isEmpty();
+  getIsIdle() {
+    return this._running && this.getIsEmpty();
   }
 }
 function queue(options = {}) {

package/dist/cjs/queuer.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"queuer.cjs","sources":["../../src/queuer.ts"],"sourcesContent":["/**\n * Options for configuring a Queuer instance\n */\nexport interface QueuerOptions<TValue> {\n  /**\n   * Default position to add items to the queuer\n   * @default 'back'\n   */\n  addItemsTo?: QueuePosition\n  /**\n   * Default position to get items from during processing\n   * @default 'front'\n   */\n  getItemsFrom?: QueuePosition\n  /**\n   * Function to determine priority of items in the queuer\n   * Higher priority items will be processed first\n   */\n  getPriority?: (item: TValue) => number\n  /**\n   * Initial items to populate the queuer with\n   */\n  initialItems?: Array<TValue>\n  /**\n   * Maximum number of items allowed in the queuer\n   */\n  maxSize?: number\n  /**\n   * Callback fired whenever an item is removed from the queuer\n   */\n  onGetNextItem?: (item: TValue, queuer: Queuer<TValue>) => void\n  /**\n   * Callback fired whenever an item is added or removed from the queuer\n   */\n  onUpdate?: (queuer: Queuer<TValue>) => void\n  /**\n   * Whether the queuer should start processing tasks immediately\n   */\n  started?: boolean\n  /**\n   * Time in milliseconds to wait between processing items\n   */\n  wait?: number\n}\n\nconst defaultOptions: Required<QueuerOptions<any>> = {\n  addItemsTo: 'back',\n  getItemsFrom: 'front',\n  getPriority: () => 0,\n  initialItems: [],\n  maxSize: Infinity,\n  onGetNextItem: () => {},\n  onUpdate: () => {},\n  started: false,\n  wait: 0,\n}\n\n/**\n * Position type for addItem and getNextItem operations\n */\nexport type QueuePosition = 'front' | 'back'\n\n/**\n * A flexible queue data structure that defaults to FIFO (First In First Out) behavior\n * with optional position overrides for stack-like or double-ended operations.\n *\n * The queuer can automatically process items as they are added, with configurable\n * wait times between processing each item. Processing can be started/stopped\n * and the queuer will maintain its state.\n *\n * Supports priority-based ordering when a getPriority function is provided.\n * Items with higher priority values will be processed first.\n *\n * Default queue behavior:\n * - addItem(item): adds to back of queuer\n * - getNextItem(): removes and returns from front of queuer\n *\n * Stack (LIFO) behavior:\n * - addItem(item, 'back'): adds to back\n * - getNextItem('back'): removes and returns from back\n *\n * Double-ended queuer behavior:\n * - addItem(item, position): adds to specified position ('front' or 'back')\n * - getNextItem(position): removes and returns from specified position\n *\n * Processing behavior:\n * - start(): begins processing items in the queuer\n * - stop(): pauses processing\n * - wait: configurable delay between processing items\n * - onUpdate/onGetNextItem: callbacks for monitoring queuer state\n *\n * @example\n * ```ts\n * // FIFO queuer\n * const queuer = new Queuer<number>();\n * queuer.addItem(1); // [1]\n * queuer.addItem(2); // [1, 2]\n * queuer.getNextItem(); // returns 1, queuer is [2]\n *\n * // Priority queuer with processing\n * const priorityQueue = new Queuer<number>({\n *   getPriority: (n) => n, // Higher numbers have priority\n *   started: true, // Begin processing immediately\n *   wait: 1000, // Wait 1s between items\n *   onGetNextItem: (item) => console.log(item)\n * });\n * priorityQueue.addItem(1); // [1]\n * priorityQueue.addItem(3); // [3, 1] - 3 processed first\n * priorityQueue.addItem(2); // [3, 2, 1]\n * ```\n */\nexport class Queuer<TValue> {\n  protected options: Required<QueuerOptions<TValue>>\n  private items: Array<TValue> = []\n  private executionCount = 0\n  private onUpdates: Array<(item: TValue) => void> = []\n  private running: boolean\n  private pendingTick = false\n\n  constructor(initialOptions: QueuerOptions<TValue> = defaultOptions) {\n    this.options = { ...defaultOptions, ...initialOptions }\n    this.running = this.options.started\n\n    for (let i = 0; i < this.options.initialItems.length; i++) {\n      const item = this.options.initialItems[i]!\n      const isLast = i === this.options.initialItems.length - 1\n      this.addItem(item, this.options.addItemsTo, isLast)\n    }\n  }\n\n  /**\n   * Processes items in the queuer\n   */\n  protected tick() {\n    if (!this.running) {\n      this.pendingTick = false\n      return\n    }\n    while (!this.isEmpty()) {\n      const nextItem = this.getNextItem(this.options.getItemsFrom)\n      if (nextItem === undefined) {\n        break\n      }\n      this.onUpdates.forEach((cb) => cb(nextItem))\n\n      if (this.options.wait > 0) {\n        // Use setTimeout to wait before processing next item\n        setTimeout(() => this.tick(), this.options.wait)\n        return\n      }\n\n      this.tick()\n    }\n    this.pendingTick = false\n  }\n\n  /**\n   * Updates the queuer options\n   * Returns the new options state\n   */\n  setOptions(\n    newOptions: Partial<QueuerOptions<TValue>>,\n  ): QueuerOptions<TValue> {\n    this.options = { ...this.options, ...newOptions }\n    return this.options\n  }\n\n  /**\n   * Adds an item to the queuer and starts processing if not already running\n   * @returns true if item was added, false if queuer is full\n   */\n  addItem(\n    item: TValue,\n    position: QueuePosition = this.options.addItemsTo,\n    runOnUpdate: boolean = true,\n  ): boolean {\n    if (this.isFull()) {\n      return false\n    }\n\n    if (this.options.getPriority !== defaultOptions.getPriority) {\n      // If custom priority function is provided, insert based on priority\n      const priority = this.options.getPriority(item)\n      const insertIndex = this.items.findIndex(\n        (existing) => this.options.getPriority(existing) > priority,\n      )\n\n      if (insertIndex === -1) {\n        this.items.push(item)\n      } else {\n        this.items.splice(insertIndex, 0, item)\n      }\n    } else {\n      // Default FIFO/LIFO behavior\n      if (position === 'front') {\n        this.items.unshift(item)\n      } else {\n        this.items.push(item)\n      }\n    }\n\n    if (this.running && !this.pendingTick) {\n      this.pendingTick = true\n      this.tick()\n    }\n    if (runOnUpdate) {\n      this.options.onUpdate(this)\n    }\n    return true\n  }\n\n  /**\n   * Removes and returns an item from the queuer using shift (default) or pop\n   *\n   * @example\n   * ```ts\n   * // Standard FIFO queuer\n   * queuer.getNextItem()\n   * // Stack-like behavior (LIFO)\n   * queuer.getNextItem('back')\n   * ```\n   */\n  getNextItem(\n    position: QueuePosition = this.options.getItemsFrom,\n  ): TValue | undefined {\n    let item: TValue | undefined\n\n    if (position === 'front') {\n      item = this.items.shift()\n    } else {\n      item = this.items.pop()\n    }\n\n    if (item !== undefined) {\n      this.executionCount++\n      this.options.onUpdate(this)\n      this.options.onGetNextItem(item, this)\n    }\n    return item\n  }\n\n  /**\n   * Returns an item without removing it\n   *\n   * @example\n   * ```ts\n   * // Look at next item to getNextItem\n   * queuer.peek()\n   * // Look at last item (like stack top)\n   * queuer.peek('back')\n   * ```\n   */\n  peek(\n    position: QueuePosition = this.options.getItemsFrom,\n  ): TValue | undefined {\n    if (position === 'front') {\n      return this.items[0]\n    }\n    return this.items[this.items.length - 1]\n  }\n\n  /**\n   * Returns true if the queuer is empty\n   */\n  isEmpty(): boolean {\n    return this.items.length === 0\n  }\n\n  /**\n   * Returns true if the queuer is full\n   */\n  isFull(): boolean {\n    return this.items.length >= this.options.maxSize\n  }\n\n  /**\n   * Returns the current size of the queuer\n   */\n  size(): number {\n    return this.items.length\n  }\n\n  /**\n   * Removes all items from the queuer\n   */\n  clear(): void {\n    this.items = []\n    this.options.onUpdate(this)\n  }\n\n  /**\n   * Resets the queuer to its initial state\n   */\n  reset(withInitialItems?: boolean): void {\n    this.clear()\n    this.executionCount = 0\n    if (withInitialItems) {\n      this.items = [...this.options.initialItems]\n    }\n    this.running = this.options.started\n  }\n\n  /**\n   * Returns a copy of all items in the queuer\n   */\n  getAllItems(): Array<TValue> {\n    return [...this.items]\n  }\n\n  /**\n   * Returns the number of items that have been removed from the queuer\n   */\n  getExecutionCount(): number {\n    return this.executionCount\n  }\n\n  /**\n   * Adds a callback to be called when an item is processed\n   */\n  onUpdate(cb: (item: TValue) => void) {\n    this.onUpdates.push(cb)\n    return () => {\n      this.onUpdates = this.onUpdates.filter((d) => d !== cb)\n    }\n  }\n\n  /**\n   * Stops the queuer from processing items\n   */\n  stop() {\n    this.running = false\n    this.pendingTick = false\n    this.options.onUpdate(this)\n  }\n\n  /**\n   * Starts the queuer and processes items\n   */\n  start() {\n    this.running = true\n    if (!this.pendingTick && !this.isEmpty()) {\n      this.pendingTick = true\n      this.tick()\n    }\n    this.options.onUpdate(this)\n  }\n\n  /**\n   * Returns true if the queuer is running\n   */\n  isRunning() {\n    return this.running\n  }\n\n  /**\n   * Returns true if the queuer is running but has no items to process\n   */\n  isIdle() {\n    return this.running && this.isEmpty()\n  }\n}\n\n/**\n * Creates a queue that processes items in a queuer immediately upon addition.\n * Items are processed sequentially in FIFO order by default.\n *\n * This is a simplified wrapper around the Queuer class that only exposes the\n * `addItem` method. This queue is always running and will process items as they are added.\n * For more control over queuer processing, use the Queuer class\n * directly which provides methods like `start`, `stop`, `reset`, and more.\n *\n * @example\n * ```ts\n * // Basic sequential processing\n * const processItems = queuer<number>({\n *   wait: 1000,\n *   onUpdate: (queuer) => console.log(queuer.getAllItems())\n * })\n * processItems(1) // Logs: 1\n * processItems(2) // Logs: 2 after 1 completes\n *\n * // Priority queuer\n * const processPriority = queuer<number>({\n *   process: async (n) => console.log(n),\n *   getPriority: n => n // Higher numbers processed first\n * })\n * processPriority(1)\n * processPriority(3) // Processed before 1\n * ```\n */\nexport function queue<TValue>(options: QueuerOptions<TValue> = {}) {\n  const queuer = new Queuer<TValue>({ ...options, started: true })\n  return queuer.addItem.bind(queuer)\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"queuer.cjs","sources":["../../src/queuer.ts"],"sourcesContent":["/**\n * Options for configuring a Queuer instance\n */\nexport interface QueuerOptions<TValue> {\n  /**\n   * Default position to add items to the queuer\n   * @default 'back'\n   */\n  addItemsTo?: QueuePosition\n  /**\n   * Maximum time in milliseconds that an item can stay in the queue\n   * If not provided, items will never expire\n   */\n  expirationDuration?: number\n  /**\n   * Function to determine if an item has expired\n   * If provided, this overrides the expirationDuration behavior\n   */\n  getIsExpired?: (item: TValue, addedAt: number) => boolean\n  /**\n   * Default position to get items from during processing\n   * @default 'front'\n   */\n  getItemsFrom?: QueuePosition\n  /**\n   * Function to determine priority of items in the queuer\n   * Higher priority items will be processed first\n   */\n  getPriority?: (item: TValue) => number\n  /**\n   * Initial items to populate the queuer with\n   */\n  initialItems?: Array<TValue>\n  /**\n   * Maximum number of items allowed in the queuer\n   */\n  maxSize?: number\n  /**\n   * Callback fired whenever an item expires in the queuer\n   */\n  onExpire?: (item: TValue, queuer: Queuer<TValue>) => void\n  /**\n   * Callback fired whenever an item is removed from the queuer\n   */\n  onGetNextItem?: (item: TValue, queuer: Queuer<TValue>) => void\n  /**\n   * Callback fired whenever the queuer's running state changes\n   */\n  onIsRunningChange?: (queuer: Queuer<TValue>) => void\n  /**\n   * Callback fired whenever an item is added or removed from the queuer\n   */\n  onItemsChange?: (queuer: Queuer<TValue>) => void\n  /**\n   * Callback fired whenever an item is rejected from being added to the queuer\n   */\n  onReject?: (item: TValue, queuer: Queuer<TValue>) => void\n  /**\n   * Whether the queuer should start processing tasks immediately\n   */\n  started?: boolean\n  /**\n   * Time in milliseconds to wait between processing items\n   */\n  wait?: number\n}\n\nconst defaultOptions: Required<QueuerOptions<any>> = {\n  addItemsTo: 'back',\n  getItemsFrom: 'front',\n  getPriority: (item) => item?.priority ?? 0,\n  getIsExpired: () => false,\n  expirationDuration: Infinity,\n  initialItems: [],\n  maxSize: Infinity,\n  onGetNextItem: () => {},\n  onIsRunningChange: () => {},\n  onItemsChange: () => {},\n  onReject: () => {},\n  onExpire: () => {},\n  started: false,\n  wait: 0,\n}\n\n/**\n * Position type for addItem and getNextItem operations\n */\nexport type QueuePosition = 'front' | 'back'\n\n/**\n * A flexible queue data structure that defaults to FIFO (First In First Out) behavior\n * with optional position overrides for stack-like or double-ended operations.\n *\n * The queuer can automatically process items as they are added, with configurable\n * wait times between processing each item. Processing can be started/stopped\n * and the queuer will maintain its state.\n *\n * Supports priority-based ordering when a getPriority function is provided.\n * Items with higher priority values will be processed first.\n *\n * Default queue behavior:\n * - addItem(item): adds to back of queuer\n * - getNextItem(): removes and returns from front of queuer\n *\n * Stack (LIFO) behavior:\n * - addItem(item, 'back'): adds to back\n * - getNextItem('back'): removes and returns from back\n *\n * Double-ended queuer behavior:\n * - addItem(item, position): adds to specified position ('front' or 'back')\n * - getNextItem(position): removes and returns from specified position\n *\n * Processing behavior:\n * - start(): begins processing items in the queuer\n * - stop(): pauses processing\n * - wait: configurable delay between processing items\n * - onItemsChange/onGetNextItem: callbacks for monitoring queuer state\n *\n * Supports item expiration to clear stale items from the queuer\n * - expirationDuration: maximum time in milliseconds that an item can stay in the queue\n * - getIsExpired: function to override default expiration behavior\n * - onExpire: callback for when an item expires\n *\n * @example\n * ```ts\n * // FIFO queuer\n * const queuer = new Queuer<number>();\n * queuer.addItem(1); // [1]\n * queuer.addItem(2); // [1, 2]\n * queuer.getNextItem(); // returns 1, queuer is [2]\n *\n * // Priority queuer with processing\n * const priorityQueue = new Queuer<number>({\n *   getPriority: (n) => n, // Higher numbers have priority\n *   started: true, // Begin processing immediately\n *   wait: 1000, // Wait 1s between items\n *   onGetNextItem: (item, queuer) => console.log(item)\n * });\n * priorityQueue.addItem(1); // [1]\n * priorityQueue.addItem(3); // [3, 1] - 3 processed first\n * priorityQueue.addItem(2); // [3, 2, 1]\n * ```\n */\nexport class Queuer<TValue> {\n  private _options: Required<QueuerOptions<TValue>>\n  private _items: Array<TValue> = []\n  private _itemTimestamps: Array<number> = []\n  private _executionCount = 0\n  private _rejectionCount = 0\n  private _expirationCount = 0\n  private _onItemsChanges: Array<(item: TValue) => void> = []\n  private _running: boolean\n  private _pendingTick = false\n\n  constructor(initialOptions: QueuerOptions<TValue> = defaultOptions) {\n    this._options = { ...defaultOptions, ...initialOptions }\n    this._running = this._options.started\n\n    for (let i = 0; i < this._options.initialItems.length; i++) {\n      const item = this._options.initialItems[i]!\n      const isLast = i === this._options.initialItems.length - 1\n      this.addItem(item, this._options.addItemsTo, isLast)\n    }\n  }\n\n  /**\n   * Updates the queuer options\n   * Returns the new options state\n   */\n  setOptions(newOptions: Partial<QueuerOptions<TValue>>): void {\n    this._options = { ...this._options, ...newOptions }\n  }\n\n  /**\n   * Returns the current queuer options\n   */\n  getOptions(): Required<QueuerOptions<TValue>> {\n    return this._options\n  }\n\n  /**\n   * Processes items in the queuer\n   */\n  private tick() {\n    if (!this._running) {\n      this._pendingTick = false\n      return\n    }\n\n    // Check for expired items\n    this.checkExpiredItems()\n\n    while (!this.getIsEmpty()) {\n      const nextItem = this.getNextItem(this._options.getItemsFrom)\n      if (nextItem === undefined) {\n        break\n      }\n      this._onItemsChanges.forEach((cb) => cb(nextItem))\n\n      if (this._options.wait > 0) {\n        // Use setTimeout to wait before processing next item\n        setTimeout(() => this.tick(), this._options.wait)\n        return\n      }\n\n      this.tick()\n    }\n    this._pendingTick = false\n  }\n\n  /**\n   * Checks for and removes expired items from the queuer\n   */\n  private checkExpiredItems() {\n    if (\n      this._options.expirationDuration === Infinity &&\n      this._options.getIsExpired === defaultOptions.getIsExpired\n    )\n      return\n\n    const now = Date.now()\n    const expiredIndices: Array<number> = []\n\n    // Find indices of expired items\n    for (let i = 0; i < this._items.length; i++) {\n      const timestamp = this._itemTimestamps[i]\n      if (timestamp === undefined) continue\n\n      const item = this._items[i]\n      if (item === undefined) continue\n\n      const isExpired =\n        this._options.getIsExpired !== defaultOptions.getIsExpired\n          ? this._options.getIsExpired(item, timestamp)\n          : now - timestamp > this._options.expirationDuration\n\n      if (isExpired) {\n        expiredIndices.push(i)\n      }\n    }\n\n    // Remove expired items from back to front to maintain indices\n    for (let i = expiredIndices.length - 1; i >= 0; i--) {\n      const index = expiredIndices[i]\n      if (index === undefined) continue\n\n      const expiredItem = this._items[index]\n      if (expiredItem === undefined) continue\n\n      this._items.splice(index, 1)\n      this._itemTimestamps.splice(index, 1)\n      this._expirationCount++\n      this._options.onExpire(expiredItem, this)\n    }\n\n    if (expiredIndices.length > 0) {\n      this._options.onItemsChange(this)\n    }\n  }\n\n  /**\n   * Stops the queuer from processing items\n   */\n  stop() {\n    this._running = false\n    this._pendingTick = false\n    this._options.onIsRunningChange(this)\n  }\n\n  /**\n   * Starts the queuer and processes items\n   */\n  start() {\n    this._running = true\n    if (!this._pendingTick && !this.getIsEmpty()) {\n      this._pendingTick = true\n      this.tick()\n    }\n    this._options.onIsRunningChange(this)\n  }\n\n  /**\n   * Removes all items from the queuer\n   */\n  clear(): void {\n    this._items = []\n    this._options.onItemsChange(this)\n  }\n\n  /**\n   * Resets the queuer to its initial state\n   */\n  reset(withInitialItems?: boolean): void {\n    this.clear()\n    this._executionCount = 0\n    if (withInitialItems) {\n      this._items = [...this._options.initialItems]\n    }\n    this._running = this._options.started\n  }\n\n  /**\n   * Adds an item to the queuer and starts processing if not already running\n   * @returns true if item was added, false if queuer is full\n   */\n  addItem(\n    item: TValue,\n    position: QueuePosition = this._options.addItemsTo,\n    runOnUpdate: boolean = true,\n  ): boolean {\n    if (this.getIsFull()) {\n      this._rejectionCount++\n      this._options.onReject(item, this)\n      return false\n    }\n\n    if (this._options.getPriority !== defaultOptions.getPriority) {\n      // If custom priority function is provided, insert based on priority\n      const priority = this._options.getPriority(item)\n      const insertIndex = this._items.findIndex(\n        (existing) => this._options.getPriority(existing) > priority,\n      )\n\n      if (insertIndex === -1) {\n        this._items.push(item)\n        this._itemTimestamps.push(Date.now())\n      } else {\n        this._items.splice(insertIndex, 0, item)\n        this._itemTimestamps.splice(insertIndex, 0, Date.now())\n      }\n    } else {\n      // Default FIFO/LIFO behavior\n      if (position === 'front') {\n        this._items.unshift(item)\n        this._itemTimestamps.unshift(Date.now())\n      } else {\n        this._items.push(item)\n        this._itemTimestamps.push(Date.now())\n      }\n    }\n\n    if (this._running && !this._pendingTick) {\n      this._pendingTick = true\n      this.tick()\n    }\n    if (runOnUpdate) {\n      this._options.onItemsChange(this)\n    }\n    return true\n  }\n\n  /**\n   * Removes and returns an item from the queuer using shift (default) or pop\n   *\n   * @example\n   * ```ts\n   * // Standard FIFO queuer\n   * queuer.getNextItem()\n   * // Stack-like behavior (LIFO)\n   * queuer.getNextItem('back')\n   * ```\n   */\n  getNextItem(\n    position: QueuePosition = this._options.getItemsFrom,\n  ): TValue | undefined {\n    let item: TValue | undefined\n\n    if (position === 'front') {\n      item = this._items.shift()\n      this._itemTimestamps.shift()\n    } else {\n      item = this._items.pop()\n      this._itemTimestamps.pop()\n    }\n\n    if (item !== undefined) {\n      this._executionCount++\n      this._options.onItemsChange(this)\n      this._options.onGetNextItem(item, this)\n    }\n    return item\n  }\n\n  /**\n   * Returns an item without removing it\n   *\n   * @example\n   * ```ts\n   * // Look at next item to getNextItem\n   * queuer.getPeek()\n   * // Look at last item (like stack top)\n   * queuer.getPeek('back')\n   * ```\n   */\n  getPeek(\n    position: QueuePosition = this._options.getItemsFrom,\n  ): TValue | undefined {\n    if (position === 'front') {\n      return this._items[0]\n    }\n    return this._items[this._items.length - 1]\n  }\n\n  /**\n   * Returns true if the queuer is empty\n   */\n  getIsEmpty(): boolean {\n    return this._items.length === 0\n  }\n\n  /**\n   * Returns true if the queuer is full\n   */\n  getIsFull(): boolean {\n    return this._items.length >= this._options.maxSize\n  }\n\n  /**\n   * Returns the current size of the queuer\n   */\n  getSize(): number {\n    return this._items.length\n  }\n\n  /**\n   * Returns a copy of all items in the queuer\n   */\n  getAllItems(): Array<TValue> {\n    return [...this._items]\n  }\n\n  /**\n   * Returns the number of items that have been removed from the queuer\n   */\n  getExecutionCount(): number {\n    return this._executionCount\n  }\n\n  /**\n   * Returns the number of items that have been rejected from the queuer\n   */\n  getRejectionCount(): number {\n    return this._rejectionCount\n  }\n\n  /**\n   * Returns the number of items that have expired from the queuer\n   */\n  getExpirationCount(): number {\n    return this._expirationCount\n  }\n\n  /**\n   * Returns true if the queuer is running\n   */\n  getIsRunning() {\n    return this._running\n  }\n\n  /**\n   * Returns true if the queuer is running but has no items to process\n   */\n  getIsIdle() {\n    return this._running && this.getIsEmpty()\n  }\n}\n\n/**\n * Creates a queue that processes items in a queuer immediately upon addition.\n * Items are processed sequentially in FIFO order by default.\n *\n * This is a simplified wrapper around the Queuer class that only exposes the\n * `addItem` method. This queue is always running and will process items as they are added.\n * For more control over queuer processing, use the Queuer class\n * directly which provides methods like `start`, `stop`, `reset`, and more.\n *\n * @example\n * ```ts\n * // Basic sequential processing\n * const processItems = queuer<number>({\n *   wait: 1000,\n *   onItemsChange: (queuer) => console.log(queuer.getAllItems())\n * })\n * processItems(1) // Logs: 1\n * processItems(2) // Logs: 2 after 1 completes\n *\n * // Priority queuer\n * const processPriority = queuer<number>({\n *   process: async (n) => console.log(n),\n *   getPriority: n => n // Higher numbers processed first\n * })\n * processPriority(1)\n * processPriority(3) // Processed before 1\n * ```\n */\nexport function queue<TValue>(options: QueuerOptions<TValue> = {}) {\n  const queuer = new Queuer<TValue>({ ...options, started: true })\n  return queuer.addItem.bind(queuer)\n}\n"],"names":[],"mappings":"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"}

package/dist/cjs/queuer.d.cts

@@ -7,6 +7,16 @@ export interface QueuerOptions<TValue> {
      * @default 'back'
      */
     addItemsTo?: QueuePosition;
+    /**
+     * 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'
@@ -25,14 +35,26 @@ export interface QueuerOptions<TValue> {
      * Maximum number of items allowed in the queuer
      */
     maxSize?: number;
+    /**
+     * Callback fired whenever an item expires in the queuer
+     */
+    onExpire?: (item: TValue, queuer: Queuer<TValue>) => void;
     /**
      * Callback fired whenever an item is removed from the queuer
      */
     onGetNextItem?: (item: TValue, queuer: Queuer<TValue>) => void;
+    /**
+     * Callback fired whenever the queuer's running state changes
+     */
+    onIsRunningChange?: (queuer: Queuer<TValue>) => void;
     /**
      * Callback fired whenever an item is added or removed from the queuer
      */
-    onUpdate?: (queuer: Queuer<TValue>) => void;
+    onItemsChange?: (queuer: Queuer<TValue>) => void;
+    /**
+     * Callback fired whenever an item is rejected from being added to the queuer
+     */
+    onReject?: (item: TValue, queuer: Queuer<TValue>) => void;
     /**
      * Whether the queuer should start processing tasks immediately
      */
@@ -73,7 +95,12 @@ export type QueuePosition = 'front' | 'back';
  * - start(): begins processing items in the queuer
  * - stop(): pauses processing
  * - wait: configurable delay between processing items
- * - onUpdate/onGetNextItem: callbacks for monitoring queuer state
+ * - onItemsChange/onGetNextItem: callbacks for monitoring queuer state
+ *
+ * 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
  *
  * @example
  * ```ts
@@ -88,7 +115,7 @@ export type QueuePosition = 'front' | 'back';
  *   getPriority: (n) => n, // Higher numbers have priority
  *   started: true, // Begin processing immediately
  *   wait: 1000, // Wait 1s between items
- *   onGetNextItem: (item) => console.log(item)
+ *   onGetNextItem: (item, queuer) => console.log(item)
  * });
  * priorityQueue.addItem(1); // [1]
  * priorityQueue.addItem(3); // [3, 1] - 3 processed first
@@ -96,22 +123,49 @@ export type QueuePosition = 'front' | 'back';
  * ```
  */
 export declare class Queuer<TValue> {
-    protected options: Required<QueuerOptions<TValue>>;
-    private items;
-    private executionCount;
-    private onUpdates;
-    private running;
-    private pendingTick;
+    private _options;
+    private _items;
+    private _itemTimestamps;
+    private _executionCount;
+    private _rejectionCount;
+    private _expirationCount;
+    private _onItemsChanges;
+    private _running;
+    private _pendingTick;
     constructor(initialOptions?: QueuerOptions<TValue>);
+    /**
+     * Updates the queuer options
+     * Returns the new options state
+     */
+    setOptions(newOptions: Partial<QueuerOptions<TValue>>): void;
+    /**
+     * Returns the current queuer options
+     */
+    getOptions(): Required<QueuerOptions<TValue>>;
     /**
      * Processes items in the queuer
      */
-    protected tick(): void;
+    private tick;
     /**
-     * Updates the queuer options
-     * Returns the new options state
+     * Checks for and removes expired items from the queuer
      */
-    setOptions(newOptions: Partial<QueuerOptions<TValue>>): QueuerOptions<TValue>;
+    private checkExpiredItems;
+    /**
+     * Stops the queuer from processing items
+     */
+    stop(): void;
+    /**
+     * Starts the queuer and processes items
+     */
+    start(): void;
+    /**
+     * Removes all items from the queuer
+     */
+    clear(): void;
+    /**
+     * Resets the queuer to its initial state
+     */
+    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
@@ -135,32 +189,24 @@ export declare class Queuer<TValue> {
      * @example
      * ```ts
      * // Look at next item to getNextItem
-     * queuer.peek()
+     * queuer.getPeek()
      * // Look at last item (like stack top)
-     * queuer.peek('back')
+     * queuer.getPeek('back')
      * ```
      */
-    peek(position?: QueuePosition): TValue | undefined;
+    getPeek(position?: QueuePosition): TValue | undefined;
     /**
      * Returns true if the queuer is empty
      */
-    isEmpty(): boolean;
+    getIsEmpty(): boolean;
     /**
      * Returns true if the queuer is full
      */
-    isFull(): boolean;
+    getIsFull(): boolean;
     /**
      * Returns the current size of the queuer
      */
-    size(): number;
-    /**
-     * Removes all items from the queuer
-     */
-    clear(): void;
-    /**
-     * Resets the queuer to its initial state
-     */
-    reset(withInitialItems?: boolean): void;
+    getSize(): number;
     /**
      * Returns a copy of all items in the queuer
      */
@@ -170,25 +216,21 @@ export declare class Queuer<TValue> {
      */
     getExecutionCount(): number;
     /**
-     * Adds a callback to be called when an item is processed
+     * Returns the number of items that have been rejected from the queuer
      */
-    onUpdate(cb: (item: TValue) => void): () => void;
+    getRejectionCount(): number;
     /**
-     * Stops the queuer from processing items
-     */
-    stop(): void;
-    /**
-     * Starts the queuer and processes items
+     * Returns the number of items that have expired from the queuer
      */
-    start(): void;
+    getExpirationCount(): number;
     /**
      * Returns true if the queuer is running
      */
-    isRunning(): boolean;
+    getIsRunning(): boolean;
     /**
      * Returns true if the queuer is running but has no items to process
      */
-    isIdle(): boolean;
+    getIsIdle(): boolean;
 }
 /**
  * Creates a queue that processes items in a queuer immediately upon addition.
@@ -204,7 +246,7 @@ export declare class Queuer<TValue> {
  * // Basic sequential processing
  * const processItems = queuer<number>({
  *   wait: 1000,
- *   onUpdate: (queuer) => console.log(queuer.getAllItems())
+ *   onItemsChange: (queuer) => console.log(queuer.getAllItems())
  * })
  * processItems(1) // Logs: 1
  * processItems(2) // Logs: 2 after 1 completes