@tanstack/pacer 0.1.0 → 0.2.0

package/dist/esm/queuer.js.map

@@ -1 +1 @@
-{"version":3,"file":"queuer.js","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.js","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 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  initialItems: [],\n  maxSize: Infinity,\n  onGetNextItem: () => {},\n  onIsRunningChange: () => {},\n  onItemsChange: () => {},\n  onReject: () => {},\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 * @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 _executionCount = 0\n  private _rejectionCount = 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(\n    newOptions: Partial<QueuerOptions<TValue>>,\n  ): QueuerOptions<TValue> {\n    this._options = { ...this._options, ...newOptions }\n    return this._options\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    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   * 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      } 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.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    } else {\n      item = this._items.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 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/esm/rate-limiter.d.ts

@@ -1,28 +1,8 @@
-/**
- * Information about a rate limit rejection
- */
-export interface RateLimitRejectionInfo {
-    /**
-     * Number of milliseconds until the next execution will be possible
-     */
-    msUntilNextWindow: number;
-    /**
-     * Current number of executions in the window
-     */
-    currentExecutions: number;
-    /**
-     * Maximum allowed executions per window
-     */
-    limit: number;
-    /**
-     * Total number of rejections that have occurred
-     */
-    rejectionCount: number;
-}
+import { AnyFunction } from './types.js';
 /**
  * Options for configuring a rate-limited function
  */
-export interface RateLimiterOptions {
+export interface RateLimiterOptions<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
     /**
      * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
      * Defaults to true.
@@ -33,13 +13,17 @@ export interface RateLimiterOptions {
      */
     limit: number;
     /**
-     * Time window in milliseconds within which the limit applies
+     * Callback function that is called after the function is executed
      */
-    window: number;
+    onExecute?: (rateLimiter: RateLimiter<TFn, TArgs>) => void;
     /**
      * Optional callback function that is called when an execution is rejected due to rate limiting
      */
-    onReject?: (info: RateLimitRejectionInfo) => void;
+    onReject?: (rateLimiter: RateLimiter<TFn, TArgs>) => void;
+    /**
+     * Time window in milliseconds within which the limit applies
+     */
+    window: number;
 }
 /**
  * A class that creates a rate-limited function.
@@ -66,30 +50,22 @@ export interface RateLimiterOptions {
  * rateLimiter.maybeExecute('123');
  * ```
  */
-export declare class RateLimiter<TFn extends (...args: Array<any>) => any, TArgs extends Parameters<TFn>> {
+export declare class RateLimiter<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
     private fn;
-    private executionCount;
-    private rejectionCount;
-    private executionTimes;
-    private options;
-    constructor(fn: TFn, initialOptions: RateLimiterOptions);
+    private _executionCount;
+    private _rejectionCount;
+    private _executionTimes;
+    private _options;
+    constructor(fn: TFn, initialOptions: RateLimiterOptions<TFn, TArgs>);
     /**
      * Updates the rate limiter options
      * Returns the new options state
      */
-    setOptions(newOptions: Partial<RateLimiterOptions>): RateLimiterOptions;
-    /**
-     * Returns the number of times the function has been executed
-     */
-    getExecutionCount(): number;
+    setOptions(newOptions: Partial<RateLimiterOptions<TFn, TArgs>>): RateLimiterOptions<TFn, TArgs>;
     /**
-     * Returns the number of times the function has been rejected
+     * Returns the current rate limiter options
      */
-    getRejectionCount(): number;
-    /**
-     * Returns the number of remaining executions allowed in the current window
-     */
-    getRemainingInWindow(): number;
+    getOptions(): Required<RateLimiterOptions<TFn, TArgs>>;
     /**
      * Attempts to execute the rate-limited function if within the configured limits.
      * Will reject execution if the number of calls in the current window exceeds the limit.
@@ -109,6 +85,22 @@ export declare class RateLimiter<TFn extends (...args: Array<any>) => any, TArgs
     private executeFunction;
     private rejectFunction;
     private cleanupOldExecutions;
+    /**
+     * Returns the number of times the function has been executed
+     */
+    getExecutionCount(): number;
+    /**
+     * Returns the number of times the function has been rejected
+     */
+    getRejectionCount(): number;
+    /**
+     * Returns the number of remaining executions allowed in the current window
+     */
+    getRemainingInWindow(): number;
+    /**
+     * Returns the number of milliseconds until the next execution will be possible
+     */
+    getMsUntilNextWindow(): number;
     /**
      * Resets the rate limiter state
      */
@@ -131,8 +123,8 @@ export declare class RateLimiter<TFn extends (...args: Array<any>) => any, TArgs
  * const rateLimited = rateLimit(makeApiCall, {
  *   limit: 5,
  *   window: 60000,
- *   onReject: ({ msUntilNextWindow }) => {
- *     console.log(`Rate limit exceeded. Try again in ${msUntilNextWindow}ms`);
+ *   onReject: (rateLimiter) => {
+ *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  *   }
  * });
  *
@@ -144,4 +136,4 @@ export declare class RateLimiter<TFn extends (...args: Array<any>) => any, TArgs
  * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
  * ```
  */
-export declare function rateLimit<TFn extends (...args: Array<any>) => any>(fn: TFn, initialOptions: Omit<RateLimiterOptions, 'enabled'>): (...args: Parameters<TFn>) => boolean;
+export declare function rateLimit<TFn extends AnyFunction>(fn: TFn, initialOptions: Omit<RateLimiterOptions<TFn, Parameters<TFn>>, 'enabled'>): (...args: Parameters<TFn>) => boolean;

package/dist/esm/rate-limiter.js

@@ -1,15 +1,19 @@
 const defaultOptions = {
   enabled: true,
   limit: 1,
+  onExecute: () => {
+  },
+  onReject: () => {
+  },
   window: 0
 };
 class RateLimiter {
   constructor(fn, initialOptions) {
     this.fn = fn;
-    this.executionCount = 0;
-    this.rejectionCount = 0;
-    this.executionTimes = [];
-    this.options = {
+    this._executionCount = 0;
+    this._rejectionCount = 0;
+    this._executionTimes = [];
+    this._options = {
       ...defaultOptions,
       ...initialOptions
     };
@@ -19,30 +23,17 @@ class RateLimiter {
    * Returns the new options state
    */
   setOptions(newOptions) {
-    this.options = {
-      ...this.options,
+    this._options = {
+      ...this._options,
       ...newOptions
     };
-    return this.options;
+    return this._options;
   }
   /**
-   * Returns the number of times the function has been executed
-   */
-  getExecutionCount() {
-    return this.executionCount;
-  }
-  /**
-   * Returns the number of times the function has been rejected
-   */
-  getRejectionCount() {
-    return this.rejectionCount;
-  }
-  /**
-   * Returns the number of remaining executions allowed in the current window
+   * Returns the current rate limiter options
    */
-  getRemainingInWindow() {
-    this.cleanupOldExecutions();
-    return Math.max(0, this.options.limit - this.executionTimes.length);
+  getOptions() {
+    return this._options;
   }
   /**
    * Attempts to execute the rate-limited function if within the configured limits.
@@ -61,7 +52,7 @@ class RateLimiter {
    */
   maybeExecute(...args) {
     this.cleanupOldExecutions();
-    if (this.executionTimes.length < this.options.limit) {
+    if (this._executionTimes.length < this._options.limit) {
       this.executeFunction(...args);
       return true;
     }
@@ -69,39 +60,60 @@ class RateLimiter {
     return false;
   }
   executeFunction(...args) {
-    if (!this.options.enabled) return;
+    var _a, _b;
+    if (!this._options.enabled) return;
     const now = Date.now();
-    this.executionCount++;
-    this.executionTimes.push(now);
+    this._executionCount++;
+    this._executionTimes.push(now);
     this.fn(...args);
+    (_b = (_a = this._options).onExecute) == null ? void 0 : _b.call(_a, this);
   }
   rejectFunction() {
-    this.rejectionCount++;
-    if (this.options.onReject) {
-      const oldestExecution = Math.min(...this.executionTimes);
-      const msUntilNextWindow = oldestExecution + this.options.window - Date.now();
-      this.options.onReject({
-        msUntilNextWindow,
-        currentExecutions: this.executionTimes.length,
-        limit: this.options.limit,
-        rejectionCount: this.rejectionCount
-      });
+    this._rejectionCount++;
+    if (this._options.onReject) {
+      this._options.onReject(this);
     }
   }
   cleanupOldExecutions() {
     const now = Date.now();
-    const windowStart = now - this.options.window;
-    this.executionTimes = this.executionTimes.filter(
+    const windowStart = now - this._options.window;
+    this._executionTimes = this._executionTimes.filter(
       (time) => time > windowStart
     );
   }
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount() {
+    return this._executionCount;
+  }
+  /**
+   * Returns the number of times the function has been rejected
+   */
+  getRejectionCount() {
+    return this._rejectionCount;
+  }
+  /**
+   * Returns the number of remaining executions allowed in the current window
+   */
+  getRemainingInWindow() {
+    this.cleanupOldExecutions();
+    return Math.max(0, this._options.limit - this._executionTimes.length);
+  }
+  /**
+   * Returns the number of milliseconds until the next execution will be possible
+   */
+  getMsUntilNextWindow() {
+    const oldestExecution = Math.min(...this._executionTimes);
+    return oldestExecution + this._options.window - Date.now();
+  }
   /**
    * Resets the rate limiter state
    */
   reset() {
-    this.executionTimes = [];
-    this.executionCount = 0;
-    this.rejectionCount = 0;
+    this._executionTimes = [];
+    this._executionCount = 0;
+    this._rejectionCount = 0;
   }
 }
 function rateLimit(fn, initialOptions) {

package/dist/esm/rate-limiter.js.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.js","sources":["../../src/rate-limiter.ts"],"sourcesContent":["/**\n * Information about a rate limit rejection\n */\nexport interface RateLimitRejectionInfo {\n  /**\n   * Number of milliseconds until the next execution will be possible\n   */\n  msUntilNextWindow: number\n  /**\n   * Current number of executions in the window\n   */\n  currentExecutions: number\n  /**\n   * Maximum allowed executions per window\n   */\n  limit: number\n  /**\n   * Total number of rejections that have occurred\n   */\n  rejectionCount: number\n}\n\n/**\n * Options for configuring a rate-limited function\n */\nexport interface RateLimiterOptions {\n  /**\n   * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Defaults to true.\n   */\n  enabled?: boolean\n  /**\n   * Maximum number of executions allowed within the time window\n   */\n  limit: number\n  /**\n   * Time window in milliseconds within which the limit applies\n   */\n  window: number\n  /**\n   * Optional callback function that is called when an execution is rejected due to rate limiting\n   */\n  onReject?: (info: RateLimitRejectionInfo) => void\n}\n\nconst defaultOptions: Required<Omit<RateLimiterOptions, 'onReject'>> = {\n  enabled: true,\n  limit: 1,\n  window: 0,\n}\n\n/**\n * A class that creates a rate-limited function.\n *\n * Rate limiting is a simple approach that allows a function to execute up to a limit within a time window,\n * then blocks all subsequent calls until the window passes. This can lead to \"bursty\" behavior where\n * all executions happen immediately, followed by a complete block.\n *\n * For smoother execution patterns, consider using:\n * - Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)\n * - Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)\n *\n * Rate limiting is best used for hard API limits or resource constraints. For UI updates or\n * smoothing out frequent events, throttling or debouncing usually provide better user experience.\n *\n * @example\n * ```ts\n * const rateLimiter = new RateLimiter(\n *   (id: string) => api.getData(id),\n *   { limit: 5, window: 1000 } // 5 calls per second\n * );\n *\n * // Will execute immediately until limit reached, then block\n * rateLimiter.maybeExecute('123');\n * ```\n */\nexport class RateLimiter<\n  TFn extends (...args: Array<any>) => any,\n  TArgs extends Parameters<TFn>,\n> {\n  private executionCount = 0\n  private rejectionCount = 0\n  private executionTimes: Array<number> = []\n  private options: RateLimiterOptions\n\n  constructor(\n    private fn: TFn,\n    initialOptions: RateLimiterOptions,\n  ) {\n    this.options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the rate limiter options\n   * Returns the new options state\n   */\n  setOptions(newOptions: Partial<RateLimiterOptions>): RateLimiterOptions {\n    this.options = {\n      ...this.options,\n      ...newOptions,\n    }\n    return this.options\n  }\n\n  /**\n   * Returns the number of times the function has been executed\n   */\n  getExecutionCount(): number {\n    return this.executionCount\n  }\n\n  /**\n   * Returns the number of times the function has been rejected\n   */\n  getRejectionCount(): number {\n    return this.rejectionCount\n  }\n\n  /**\n   * Returns the number of remaining executions allowed in the current window\n   */\n  getRemainingInWindow(): number {\n    this.cleanupOldExecutions()\n    return Math.max(0, this.options.limit - this.executionTimes.length)\n  }\n\n  /**\n   * Attempts to execute the rate-limited function if within the configured limits.\n   * Will reject execution if the number of calls in the current window exceeds the limit.\n   *\n   * @example\n   * ```ts\n   * const rateLimiter = new RateLimiter(fn, { limit: 5, window: 1000 });\n   *\n   * // First 5 calls will return true\n   * rateLimiter.maybeExecute('arg1', 'arg2'); // true\n   *\n   * // Additional calls within the window will return false\n   * rateLimiter.maybeExecute('arg1', 'arg2'); // false\n   * ```\n   */\n  maybeExecute(...args: TArgs): boolean {\n    this.cleanupOldExecutions()\n\n    if (this.executionTimes.length < this.options.limit) {\n      this.executeFunction(...args)\n      return true\n    }\n\n    this.rejectFunction()\n\n    return false\n  }\n\n  private executeFunction(...args: TArgs): void {\n    if (!this.options.enabled) return\n    const now = Date.now()\n    this.executionCount++\n    this.executionTimes.push(now)\n    this.fn(...args)\n  }\n\n  private rejectFunction(): void {\n    this.rejectionCount++\n    if (this.options.onReject) {\n      const oldestExecution = Math.min(...this.executionTimes)\n      const msUntilNextWindow =\n        oldestExecution + this.options.window - Date.now()\n\n      this.options.onReject({\n        msUntilNextWindow,\n        currentExecutions: this.executionTimes.length,\n        limit: this.options.limit,\n        rejectionCount: this.rejectionCount,\n      })\n    }\n  }\n\n  private cleanupOldExecutions(): void {\n    const now = Date.now()\n    const windowStart = now - this.options.window\n    this.executionTimes = this.executionTimes.filter(\n      (time) => time > windowStart,\n    )\n  }\n\n  /**\n   * Resets the rate limiter state\n   */\n  reset(): void {\n    this.executionTimes = []\n    this.executionCount = 0\n    this.rejectionCount = 0\n  }\n}\n\n/**\n * Creates a rate-limited function that will execute the provided function up to a maximum number of times within a time window.\n *\n * Note that rate limiting is a simpler form of execution control compared to throttling or debouncing:\n * - A rate limiter will allow all executions until the limit is reached, then block all subsequent calls until the window resets\n * - A throttler ensures even spacing between executions, which can be better for consistent performance\n * - A debouncer collapses multiple calls into one, which is better for handling bursts of events\n *\n * Consider using throttle() or debounce() if you need more intelligent execution control. Use rate limiting when you specifically\n * need to enforce a hard limit on the number of executions within a time period.\n *\n * @example\n * ```ts\n * // Rate limit to 5 calls per minute\n * const rateLimited = rateLimit(makeApiCall, {\n *   limit: 5,\n *   window: 60000,\n *   onReject: ({ msUntilNextWindow }) => {\n *     console.log(`Rate limit exceeded. Try again in ${msUntilNextWindow}ms`);\n *   }\n * });\n *\n * // First 5 calls will execute immediately\n * // Additional calls will be rejected until the minute window resets\n * rateLimited();\n *\n * // For more even execution, consider using throttle instead:\n * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds\n * ```\n */\nexport function rateLimit<TFn extends (...args: Array<any>) => any>(\n  fn: TFn,\n  initialOptions: Omit<RateLimiterOptions, 'enabled'>,\n) {\n  const rateLimiter = new RateLimiter(fn, initialOptions)\n  return rateLimiter.maybeExecute.bind(rateLimiter)\n}\n"],"names":[],"mappings":"AA6CA,MAAM,iBAAiE;AAAA,EACrE,SAAS;AAAA,EACT,OAAO;AAAA,EACP,QAAQ;AACV;AA2BO,MAAM,YAGX;AAAA,EAMA,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AANV,SAAQ,iBAAiB;AACzB,SAAQ,iBAAiB;AACzB,SAAQ,iBAAgC,CAAC;AAOvC,SAAK,UAAU;AAAA,MACb,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WAAW,YAA6D;AACtE,SAAK,UAAU;AAAA,MACb,GAAG,KAAK;AAAA,MACR,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,uBAA+B;AAC7B,SAAK,qBAAqB;AACnB,WAAA,KAAK,IAAI,GAAG,KAAK,QAAQ,QAAQ,KAAK,eAAe,MAAM;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBpE,gBAAgB,MAAsB;AACpC,SAAK,qBAAqB;AAE1B,QAAI,KAAK,eAAe,SAAS,KAAK,QAAQ,OAAO;AAC9C,WAAA,gBAAgB,GAAG,IAAI;AACrB,aAAA;AAAA,IAAA;AAGT,SAAK,eAAe;AAEb,WAAA;AAAA,EAAA;AAAA,EAGD,mBAAmB,MAAmB;AACxC,QAAA,CAAC,KAAK,QAAQ,QAAS;AACrB,UAAA,MAAM,KAAK,IAAI;AAChB,SAAA;AACA,SAAA,eAAe,KAAK,GAAG;AACvB,SAAA,GAAG,GAAG,IAAI;AAAA,EAAA;AAAA,EAGT,iBAAuB;AACxB,SAAA;AACD,QAAA,KAAK,QAAQ,UAAU;AACzB,YAAM,kBAAkB,KAAK,IAAI,GAAG,KAAK,cAAc;AACvD,YAAM,oBACJ,kBAAkB,KAAK,QAAQ,SAAS,KAAK,IAAI;AAEnD,WAAK,QAAQ,SAAS;AAAA,QACpB;AAAA,QACA,mBAAmB,KAAK,eAAe;AAAA,QACvC,OAAO,KAAK,QAAQ;AAAA,QACpB,gBAAgB,KAAK;AAAA,MAAA,CACtB;AAAA,IAAA;AAAA,EACH;AAAA,EAGM,uBAA6B;AAC7B,UAAA,MAAM,KAAK,IAAI;AACf,UAAA,cAAc,MAAM,KAAK,QAAQ;AAClC,SAAA,iBAAiB,KAAK,eAAe;AAAA,MACxC,CAAC,SAAS,OAAO;AAAA,IACnB;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMF,QAAc;AACZ,SAAK,iBAAiB,CAAC;AACvB,SAAK,iBAAiB;AACtB,SAAK,iBAAiB;AAAA,EAAA;AAE1B;AAgCgB,SAAA,UACd,IACA,gBACA;AACA,QAAM,cAAc,IAAI,YAAY,IAAI,cAAc;AAC/C,SAAA,YAAY,aAAa,KAAK,WAAW;AAClD;"}
+{"version":3,"file":"rate-limiter.js","sources":["../../src/rate-limiter.ts"],"sourcesContent":["import type { AnyFunction } from './types'\n\n/**\n * Options for configuring a rate-limited function\n */\nexport interface RateLimiterOptions<\n  TFn extends AnyFunction,\n  TArgs extends Parameters<TFn>,\n> {\n  /**\n   * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Defaults to true.\n   */\n  enabled?: boolean\n  /**\n   * Maximum number of executions allowed within the time window\n   */\n  limit: number\n  /**\n   * Callback function that is called after the function is executed\n   */\n  onExecute?: (rateLimiter: RateLimiter<TFn, TArgs>) => void\n  /**\n   * Optional callback function that is called when an execution is rejected due to rate limiting\n   */\n  onReject?: (rateLimiter: RateLimiter<TFn, TArgs>) => void\n  /**\n   * Time window in milliseconds within which the limit applies\n   */\n  window: number\n}\n\nconst defaultOptions: Required<RateLimiterOptions<any, any>> = {\n  enabled: true,\n  limit: 1,\n  onExecute: () => {},\n  onReject: () => {},\n  window: 0,\n}\n\n/**\n * A class that creates a rate-limited function.\n *\n * Rate limiting is a simple approach that allows a function to execute up to a limit within a time window,\n * then blocks all subsequent calls until the window passes. This can lead to \"bursty\" behavior where\n * all executions happen immediately, followed by a complete block.\n *\n * For smoother execution patterns, consider using:\n * - Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)\n * - Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)\n *\n * Rate limiting is best used for hard API limits or resource constraints. For UI updates or\n * smoothing out frequent events, throttling or debouncing usually provide better user experience.\n *\n * @example\n * ```ts\n * const rateLimiter = new RateLimiter(\n *   (id: string) => api.getData(id),\n *   { limit: 5, window: 1000 } // 5 calls per second\n * );\n *\n * // Will execute immediately until limit reached, then block\n * rateLimiter.maybeExecute('123');\n * ```\n */\nexport class RateLimiter<\n  TFn extends AnyFunction,\n  TArgs extends Parameters<TFn>,\n> {\n  private _executionCount = 0\n  private _rejectionCount = 0\n  private _executionTimes: Array<number> = []\n  private _options: RateLimiterOptions<TFn, TArgs>\n\n  constructor(\n    private fn: TFn,\n    initialOptions: RateLimiterOptions<TFn, TArgs>,\n  ) {\n    this._options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the rate limiter options\n   * Returns the new options state\n   */\n  setOptions(\n    newOptions: Partial<RateLimiterOptions<TFn, TArgs>>,\n  ): RateLimiterOptions<TFn, TArgs> {\n    this._options = {\n      ...this._options,\n      ...newOptions,\n    }\n    return this._options\n  }\n\n  /**\n   * Returns the current rate limiter options\n   */\n  getOptions(): Required<RateLimiterOptions<TFn, TArgs>> {\n    return this._options as Required<RateLimiterOptions<TFn, TArgs>>\n  }\n\n  /**\n   * Attempts to execute the rate-limited function if within the configured limits.\n   * Will reject execution if the number of calls in the current window exceeds the limit.\n   *\n   * @example\n   * ```ts\n   * const rateLimiter = new RateLimiter(fn, { limit: 5, window: 1000 });\n   *\n   * // First 5 calls will return true\n   * rateLimiter.maybeExecute('arg1', 'arg2'); // true\n   *\n   * // Additional calls within the window will return false\n   * rateLimiter.maybeExecute('arg1', 'arg2'); // false\n   * ```\n   */\n  maybeExecute(...args: TArgs): boolean {\n    this.cleanupOldExecutions()\n\n    if (this._executionTimes.length < this._options.limit) {\n      this.executeFunction(...args)\n      return true\n    }\n\n    this.rejectFunction()\n\n    return false\n  }\n\n  private executeFunction(...args: TArgs): void {\n    if (!this._options.enabled) return\n    const now = Date.now()\n    this._executionCount++\n    this._executionTimes.push(now)\n    this.fn(...args) // execute the function\n    this._options.onExecute?.(this)\n  }\n\n  private rejectFunction(): void {\n    this._rejectionCount++\n    if (this._options.onReject) {\n      this._options.onReject(this)\n    }\n  }\n\n  private cleanupOldExecutions(): void {\n    const now = Date.now()\n    const windowStart = now - this._options.window\n    this._executionTimes = this._executionTimes.filter(\n      (time) => time > windowStart,\n    )\n  }\n\n  /**\n   * Returns the number of times the function has been executed\n   */\n  getExecutionCount(): number {\n    return this._executionCount\n  }\n\n  /**\n   * Returns the number of times the function has been rejected\n   */\n  getRejectionCount(): number {\n    return this._rejectionCount\n  }\n\n  /**\n   * Returns the number of remaining executions allowed in the current window\n   */\n  getRemainingInWindow(): number {\n    this.cleanupOldExecutions()\n    return Math.max(0, this._options.limit - this._executionTimes.length)\n  }\n\n  /**\n   * Returns the number of milliseconds until the next execution will be possible\n   */\n  getMsUntilNextWindow(): number {\n    const oldestExecution = Math.min(...this._executionTimes)\n    return oldestExecution + this._options.window - Date.now()\n  }\n\n  /**\n   * Resets the rate limiter state\n   */\n  reset(): void {\n    this._executionTimes = []\n    this._executionCount = 0\n    this._rejectionCount = 0\n  }\n}\n\n/**\n * Creates a rate-limited function that will execute the provided function up to a maximum number of times within a time window.\n *\n * Note that rate limiting is a simpler form of execution control compared to throttling or debouncing:\n * - A rate limiter will allow all executions until the limit is reached, then block all subsequent calls until the window resets\n * - A throttler ensures even spacing between executions, which can be better for consistent performance\n * - A debouncer collapses multiple calls into one, which is better for handling bursts of events\n *\n * Consider using throttle() or debounce() if you need more intelligent execution control. Use rate limiting when you specifically\n * need to enforce a hard limit on the number of executions within a time period.\n *\n * @example\n * ```ts\n * // Rate limit to 5 calls per minute\n * const rateLimited = rateLimit(makeApiCall, {\n *   limit: 5,\n *   window: 60000,\n *   onReject: (rateLimiter) => {\n *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);\n *   }\n * });\n *\n * // First 5 calls will execute immediately\n * // Additional calls will be rejected until the minute window resets\n * rateLimited();\n *\n * // For more even execution, consider using throttle instead:\n * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds\n * ```\n */\nexport function rateLimit<TFn extends AnyFunction>(\n  fn: TFn,\n  initialOptions: Omit<RateLimiterOptions<TFn, Parameters<TFn>>, 'enabled'>,\n) {\n  const rateLimiter = new RateLimiter(fn, initialOptions)\n  return rateLimiter.maybeExecute.bind(rateLimiter)\n}\n"],"names":[],"mappings":"AAgCA,MAAM,iBAAyD;AAAA,EAC7D,SAAS;AAAA,EACT,OAAO;AAAA,EACP,WAAW,MAAM;AAAA,EAAC;AAAA,EAClB,UAAU,MAAM;AAAA,EAAC;AAAA,EACjB,QAAQ;AACV;AA2BO,MAAM,YAGX;AAAA,EAMA,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AANV,SAAQ,kBAAkB;AAC1B,SAAQ,kBAAkB;AAC1B,SAAQ,kBAAiC,CAAC;AAOxC,SAAK,WAAW;AAAA,MACd,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WACE,YACgC;AAChC,SAAK,WAAW;AAAA,MACd,GAAG,KAAK;AAAA,MACR,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,aAAuD;AACrD,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBd,gBAAgB,MAAsB;AACpC,SAAK,qBAAqB;AAE1B,QAAI,KAAK,gBAAgB,SAAS,KAAK,SAAS,OAAO;AAChD,WAAA,gBAAgB,GAAG,IAAI;AACrB,aAAA;AAAA,IAAA;AAGT,SAAK,eAAe;AAEb,WAAA;AAAA,EAAA;AAAA,EAGD,mBAAmB,MAAmB;AArGhD;AAsGQ,QAAA,CAAC,KAAK,SAAS,QAAS;AACtB,UAAA,MAAM,KAAK,IAAI;AAChB,SAAA;AACA,SAAA,gBAAgB,KAAK,GAAG;AACxB,SAAA,GAAG,GAAG,IAAI;AACV,qBAAA,UAAS,cAAT,4BAAqB;AAAA,EAAI;AAAA,EAGxB,iBAAuB;AACxB,SAAA;AACD,QAAA,KAAK,SAAS,UAAU;AACrB,WAAA,SAAS,SAAS,IAAI;AAAA,IAAA;AAAA,EAC7B;AAAA,EAGM,uBAA6B;AAC7B,UAAA,MAAM,KAAK,IAAI;AACf,UAAA,cAAc,MAAM,KAAK,SAAS;AACnC,SAAA,kBAAkB,KAAK,gBAAgB;AAAA,MAC1C,CAAC,SAAS,OAAO;AAAA,IACnB;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMF,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,uBAA+B;AAC7B,SAAK,qBAAqB;AACnB,WAAA,KAAK,IAAI,GAAG,KAAK,SAAS,QAAQ,KAAK,gBAAgB,MAAM;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMtE,uBAA+B;AAC7B,UAAM,kBAAkB,KAAK,IAAI,GAAG,KAAK,eAAe;AACxD,WAAO,kBAAkB,KAAK,SAAS,SAAS,KAAK,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAM3D,QAAc;AACZ,SAAK,kBAAkB,CAAC;AACxB,SAAK,kBAAkB;AACvB,SAAK,kBAAkB;AAAA,EAAA;AAE3B;AAgCgB,SAAA,UACd,IACA,gBACA;AACA,QAAM,cAAc,IAAI,YAAY,IAAI,cAAc;AAC/C,SAAA,YAAY,aAAa,KAAK,WAAW;AAClD;"}

package/dist/esm/throttler.d.ts

@@ -1,7 +1,8 @@
+import { AnyFunction } from './types.js';
 /**
  * Options for configuring a throttled function
  */
-export interface ThrottlerOptions {
+export interface ThrottlerOptions<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
     /**
      * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
      * Defaults to true.
@@ -12,6 +13,10 @@ export interface ThrottlerOptions {
      * Defaults to true.
      */
     leading?: boolean;
+    /**
+     * Callback function that is called after the function is executed
+     */
+    onExecute?: (throttler: Throttler<TFn, TArgs>) => void;
     /**
      * Whether to execute on the trailing edge of the timeout.
      * Defaults to true.
@@ -33,8 +38,7 @@ export interface ThrottlerOptions {
  * - Leading: Execute immediately on first call (default: true)
  * - Trailing: Execute after wait period if called during throttle (default: true)
  *
- * For rate limiting or hard API limits, consider using RateLimiter instead.
- * For collapsing rapid-fire events, consider using Debouncer.
+ * For collapsing rapid-fire events where you only care about the last call, consider using Debouncer.
  *
  * @example
  * ```ts
@@ -50,31 +54,24 @@ export interface ThrottlerOptions {
  * throttler.maybeExecute('123'); // Throttled
  * ```
  */
-export declare class Throttler<TFn extends (...args: Array<any>) => any, TArgs extends Parameters<TFn>> {
+export declare class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
     private fn;
-    private executionCount;
-    private lastArgs;
-    private lastExecutionTime;
-    private options;
-    private timeoutId;
-    constructor(fn: TFn, initialOptions: ThrottlerOptions);
+    private _executionCount;
+    private _lastArgs;
+    private _lastExecutionTime;
+    private _options;
+    private _timeoutId;
+    private _isPending;
+    constructor(fn: TFn, initialOptions: ThrottlerOptions<TFn, TArgs>);
     /**
      * Updates the throttler options
      * Returns the new options state
      */
-    setOptions(newOptions: Partial<ThrottlerOptions>): Required<ThrottlerOptions>;
+    setOptions(newOptions: Partial<ThrottlerOptions<TFn, TArgs>>): Required<ThrottlerOptions<TFn, TArgs>>;
     /**
-     * Returns the number of times the function has been executed
+     * Returns the current throttler options
      */
-    getExecutionCount(): number;
-    /**
-     * Returns the last execution time
-     */
-    getLastExecutionTime(): number;
-    /**
-     * Returns the next execution time
-     */
-    getNextExecutionTime(): number;
+    getOptions(): Required<ThrottlerOptions<TFn, TArgs>>;
     /**
      * Attempts to execute the throttled function. The execution behavior depends on the throttler options:
      *
@@ -109,6 +106,22 @@ export declare class Throttler<TFn extends (...args: Array<any>) => any, TArgs e
      * Has no effect if there is no pending execution.
      */
     cancel(): void;
+    /**
+     * Returns the number of times the function has been executed
+     */
+    getExecutionCount(): number;
+    /**
+     * Returns `true` if there is a pending execution
+     */
+    getIsPending(): boolean;
+    /**
+     * Returns the last execution time
+     */
+    getLastExecutionTime(): number;
+    /**
+     * Returns the next execution time
+     */
+    getNextExecutionTime(): number;
 }
 /**
  * Creates a throttled function that limits how often the provided function can execute.
@@ -136,4 +149,4 @@ export declare class Throttler<TFn extends (...args: Array<any>) => any, TArgs e
  * });
  * ```
  */
-export declare function throttle<TFn extends (...args: Array<any>) => any>(fn: TFn, initialOptions: Omit<ThrottlerOptions, 'enabled'>): (...args: Parameters<TFn>) => void;
+export declare function throttle<TFn extends AnyFunction, TArgs extends Parameters<TFn>>(fn: TFn, initialOptions: Omit<ThrottlerOptions<TFn, TArgs>, 'enabled'>): (...args: TArgs) => void;

package/dist/esm/throttler.js

@@ -2,14 +2,17 @@ const defaultOptions = {
   enabled: true,
   leading: true,
   trailing: true,
-  wait: 0
+  wait: 0,
+  onExecute: () => {
+  }
 };
 class Throttler {
   constructor(fn, initialOptions) {
     this.fn = fn;
-    this.executionCount = 0;
-    this.lastExecutionTime = 0;
-    this.options = {
+    this._executionCount = 0;
+    this._lastExecutionTime = 0;
+    this._isPending = false;
+    this._options = {
       ...defaultOptions,
       ...initialOptions
     };
@@ -19,29 +22,17 @@ class Throttler {
    * Returns the new options state
    */
   setOptions(newOptions) {
-    this.options = {
-      ...this.options,
+    this._options = {
+      ...this._options,
       ...newOptions
     };
-    return this.options;
-  }
-  /**
-   * Returns the number of times the function has been executed
-   */
-  getExecutionCount() {
-    return this.executionCount;
-  }
-  /**
-   * Returns the last execution time
-   */
-  getLastExecutionTime() {
-    return this.lastExecutionTime;
+    return this._options;
   }
   /**
-   * Returns the next execution time
+   * Returns the current throttler options
    */
-  getNextExecutionTime() {
-    return this.lastExecutionTime + this.options.wait;
+  getOptions() {
+    return this._options;
   }
   /**
    * Attempts to execute the throttled function. The execution behavior depends on the throttler options:
@@ -67,30 +58,34 @@ class Throttler {
    */
   maybeExecute(...args) {
     const now = Date.now();
-    const timeSinceLastExecution = now - this.lastExecutionTime;
-    if (timeSinceLastExecution >= this.options.wait) {
-      if (this.options.leading) {
+    const timeSinceLastExecution = now - this._lastExecutionTime;
+    if (timeSinceLastExecution >= this._options.wait) {
+      if (this._options.leading) {
         this.executeFunction(...args);
       }
-      this.lastExecutionTime = now;
+      this._lastExecutionTime = now;
+      this._isPending = false;
     } else {
-      this.lastArgs = args;
-      if (!this.timeoutId && this.options.trailing) {
-        this.timeoutId = setTimeout(() => {
-          if (this.lastArgs) {
-            this.executeFunction(...this.lastArgs);
-            this.lastArgs = void 0;
+      this._lastArgs = args;
+      if (!this._timeoutId && this._options.trailing) {
+        this._isPending = true;
+        this._timeoutId = setTimeout(() => {
+          if (this._lastArgs) {
+            this.executeFunction(...this._lastArgs);
+            this._lastArgs = void 0;
           }
-          this.lastExecutionTime = Date.now();
-          this.timeoutId = void 0;
-        }, this.options.wait - timeSinceLastExecution);
+          this._lastExecutionTime = Date.now();
+          this._timeoutId = void 0;
+          this._isPending = false;
+          this._options.onExecute(this);
+        }, this._options.wait - timeSinceLastExecution);
       }
     }
   }
   executeFunction(...args) {
-    if (!this.options.enabled) return;
-    this.executionCount++;
+    if (!this._options.enabled) return;
     this.fn(...args);
+    this._executionCount++;
   }
   /**
    * Cancels any pending trailing execution and clears internal state.
@@ -102,12 +97,37 @@ class Throttler {
    * Has no effect if there is no pending execution.
    */
   cancel() {
-    if (this.timeoutId) {
-      clearTimeout(this.timeoutId);
-      this.timeoutId = void 0;
-      this.lastArgs = void 0;
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId);
+      this._timeoutId = void 0;
+      this._lastArgs = void 0;
+      this._isPending = false;
     }
   }
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount() {
+    return this._executionCount;
+  }
+  /**
+   * Returns `true` if there is a pending execution
+   */
+  getIsPending() {
+    return this._options.enabled && this._isPending;
+  }
+  /**
+   * Returns the last execution time
+   */
+  getLastExecutionTime() {
+    return this._lastExecutionTime;
+  }
+  /**
+   * Returns the next execution time
+   */
+  getNextExecutionTime() {
+    return this._lastExecutionTime + this._options.wait;
+  }
 }
 function throttle(fn, initialOptions) {
   const throttler = new Throttler(fn, initialOptions);