@tanstack/pacer 0.2.0 → 0.3.0

package/src/debouncer.ts

@@ -3,10 +3,7 @@ import type { AnyFunction } from './types'
 /**
  * Options for configuring a debounced function
  */
-export interface DebouncerOptions<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
-> {
+export interface DebouncerOptions<TFn extends AnyFunction> {
   /**
    * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -14,13 +11,14 @@ export interface DebouncerOptions<
   enabled?: boolean
   /**
    * Whether to execute on the leading edge of the timeout.
+   * The first call will execute immediately and the rest will wait the delay.
    * Defaults to false.
    */
   leading?: boolean
   /**
    * Callback function that is called after the function is executed
    */
-  onExecute?: (debouncer: Debouncer<TFn, TArgs>) => void
+  onExecute?: (debouncer: Debouncer<TFn>) => void
   /**
    * Whether to execute on the trailing edge of the timeout.
    * Defaults to true.
@@ -33,12 +31,12 @@ export interface DebouncerOptions<
   wait: number
 }
 
-const defaultOptions: Required<DebouncerOptions<any, any>> = {
+const defaultOptions: Required<DebouncerOptions<any>> = {
   enabled: true,
   leading: false,
+  onExecute: () => {},
   trailing: true,
   wait: 0,
-  onExecute: () => {},
 }
 
 /**
@@ -64,16 +62,16 @@ const defaultOptions: Required<DebouncerOptions<any, any>> = {
  * });
  * ```
  */
-export class Debouncer<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
+export class Debouncer<TFn extends AnyFunction> {
   private _canLeadingExecute = true
-  private _isPending = false
   private _executionCount = 0
-  private _options: Required<DebouncerOptions<TFn, TArgs>>
+  private _isPending = false
+  private _options: Required<DebouncerOptions<TFn>>
   private _timeoutId: NodeJS.Timeout | undefined
 
   constructor(
     private fn: TFn,
-    initialOptions: DebouncerOptions<TFn, TArgs>,
+    initialOptions: DebouncerOptions<TFn>,
   ) {
     this._options = {
       ...defaultOptions,
@@ -85,26 +83,19 @@ export class Debouncer<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
    * Updates the debouncer options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<DebouncerOptions<TFn, TArgs>>,
-  ): Required<DebouncerOptions<TFn, TArgs>> {
-    this._options = {
-      ...this._options,
-      ...newOptions,
-    }
+  setOptions(newOptions: Partial<DebouncerOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
 
     // End the pending state if the debouncer is disabled
     if (!this._options.enabled) {
       this._isPending = false
     }
-
-    return this._options
   }
 
   /**
    * Returns the current debouncer options
    */
-  getOptions(): Required<DebouncerOptions<TFn, TArgs>> {
+  getOptions(): Required<DebouncerOptions<TFn>> {
     return this._options
   }
 
@@ -112,35 +103,37 @@ export class Debouncer<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
    * Attempts to execute the debounced function
    * If a call is already in progress, it will be queued
    */
-  maybeExecute(...args: TArgs): void {
+  maybeExecute(...args: Parameters<TFn>): void {
+    let _didLeadingExecute = false
+
     // Handle leading execution
     if (this._options.leading && this._canLeadingExecute) {
-      this.executeFunction(...args)
       this._canLeadingExecute = false
+      _didLeadingExecute = true
+      this.executeFunction(...args)
     }
 
-    // Start pending state
-    if (this._options.leading || this._options.trailing) {
+    // Start pending state to indicate that the debouncer is waiting for the trailing edge
+    if (this._options.trailing) {
       this._isPending = true
     }
 
     // Clear any existing timeout
     if (this._timeoutId) clearTimeout(this._timeoutId)
 
-    // Set new timeout that will reset canLeadingExecute
+    // Set new timeout that will reset canLeadingExecute and execute trailing only if enabled and did not execute leading
     this._timeoutId = setTimeout(() => {
       this._canLeadingExecute = true
-      this._isPending = false
-      // Execute trailing only if enabled
-      if (this._options.trailing) {
+      if (this._options.trailing && !_didLeadingExecute) {
         this.executeFunction(...args)
       }
     }, this._options.wait)
   }
 
-  private executeFunction(...args: TArgs): void {
-    if (!this._options.enabled) return
+  private executeFunction(...args: Parameters<TFn>): void {
+    if (!this._options.enabled) return undefined
     this.fn(...args) // EXECUTE!
+    this._isPending = false
     this._executionCount++
     this._options.onExecute(this)
   }
@@ -193,8 +186,8 @@ export class Debouncer<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
  */
 export function debounce<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<DebouncerOptions<TFn, Parameters<TFn>>, 'enabled'>,
-) {
+  initialOptions: Omit<DebouncerOptions<TFn>, 'enabled'>,
+): (...args: Parameters<TFn>) => void {
   const debouncer = new Debouncer(fn, initialOptions)
   return debouncer.maybeExecute.bind(debouncer)
 }

package/src/queuer.ts

@@ -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,6 +35,10 @@ 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
    */
@@ -55,12 +69,15 @@ const defaultOptions: Required<QueuerOptions<any>> = {
   addItemsTo: 'back',
   getItemsFrom: 'front',
   getPriority: (item) => item?.priority ?? 0,
+  getIsExpired: () => false,
+  expirationDuration: Infinity,
   initialItems: [],
   maxSize: Infinity,
   onGetNextItem: () => {},
   onIsRunningChange: () => {},
   onItemsChange: () => {},
   onReject: () => {},
+  onExpire: () => {},
   started: false,
   wait: 0,
 }
@@ -99,6 +116,11 @@ export type QueuePosition = 'front' | 'back'
  * - wait: configurable delay between processing items
  * - 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
  * // FIFO queuer
@@ -122,8 +144,10 @@ export type QueuePosition = 'front' | 'back'
 export class Queuer<TValue> {
   private _options: Required<QueuerOptions<TValue>>
   private _items: Array<TValue> = []
+  private _itemTimestamps: Array<number> = []
   private _executionCount = 0
   private _rejectionCount = 0
+  private _expirationCount = 0
   private _onItemsChanges: Array<(item: TValue) => void> = []
   private _running: boolean
   private _pendingTick = false
@@ -143,11 +167,8 @@ export class Queuer<TValue> {
    * Updates the queuer options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<QueuerOptions<TValue>>,
-  ): QueuerOptions<TValue> {
+  setOptions(newOptions: Partial<QueuerOptions<TValue>>): void {
     this._options = { ...this._options, ...newOptions }
-    return this._options
   }
 
   /**
@@ -165,6 +186,10 @@ export class Queuer<TValue> {
       this._pendingTick = false
       return
     }
+
+    // Check for expired items
+    this.checkExpiredItems()
+
     while (!this.getIsEmpty()) {
       const nextItem = this.getNextItem(this._options.getItemsFrom)
       if (nextItem === undefined) {
@@ -183,6 +208,56 @@ export class Queuer<TValue> {
     this._pendingTick = false
   }
 
+  /**
+   * Checks for and removes expired items from the queuer
+   */
+  private checkExpiredItems() {
+    if (
+      this._options.expirationDuration === Infinity &&
+      this._options.getIsExpired === defaultOptions.getIsExpired
+    )
+      return
+
+    const now = Date.now()
+    const expiredIndices: Array<number> = []
+
+    // Find indices of expired items
+    for (let i = 0; i < this._items.length; i++) {
+      const timestamp = this._itemTimestamps[i]
+      if (timestamp === undefined) continue
+
+      const item = this._items[i]
+      if (item === undefined) continue
+
+      const isExpired =
+        this._options.getIsExpired !== defaultOptions.getIsExpired
+          ? this._options.getIsExpired(item, timestamp)
+          : now - timestamp > this._options.expirationDuration
+
+      if (isExpired) {
+        expiredIndices.push(i)
+      }
+    }
+
+    // Remove expired items from back to front to maintain indices
+    for (let i = expiredIndices.length - 1; i >= 0; i--) {
+      const index = expiredIndices[i]
+      if (index === undefined) continue
+
+      const expiredItem = this._items[index]
+      if (expiredItem === undefined) 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
    */
@@ -248,15 +323,19 @@ export class Queuer<TValue> {
 
       if (insertIndex === -1) {
         this._items.push(item)
+        this._itemTimestamps.push(Date.now())
       } else {
         this._items.splice(insertIndex, 0, item)
+        this._itemTimestamps.splice(insertIndex, 0, Date.now())
       }
     } else {
       // Default FIFO/LIFO behavior
       if (position === 'front') {
         this._items.unshift(item)
+        this._itemTimestamps.unshift(Date.now())
       } else {
         this._items.push(item)
+        this._itemTimestamps.push(Date.now())
       }
     }
 
@@ -288,8 +367,10 @@ export class Queuer<TValue> {
 
     if (position === 'front') {
       item = this._items.shift()
+      this._itemTimestamps.shift()
     } else {
       item = this._items.pop()
+      this._itemTimestamps.pop()
     }
 
     if (item !== undefined) {
@@ -362,6 +443,13 @@ export class Queuer<TValue> {
     return this._rejectionCount
   }
 
+  /**
+   * Returns the number of items that have expired from the queuer
+   */
+  getExpirationCount(): number {
+    return this._expirationCount
+  }
+
   /**
    * Returns true if the queuer is running
    */

package/src/rate-limiter.ts

@@ -3,10 +3,7 @@ import type { AnyFunction } from './types'
 /**
  * Options for configuring a rate-limited function
  */
-export interface RateLimiterOptions<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
-> {
+export interface RateLimiterOptions<TFn extends AnyFunction> {
   /**
    * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -19,18 +16,18 @@ export interface RateLimiterOptions<
   /**
    * Callback function that is called after the function is executed
    */
-  onExecute?: (rateLimiter: RateLimiter<TFn, TArgs>) => void
+  onExecute?: (rateLimiter: RateLimiter<TFn>) => void
   /**
    * Optional callback function that is called when an execution is rejected due to rate limiting
    */
-  onReject?: (rateLimiter: RateLimiter<TFn, TArgs>) => void
+  onReject?: (rateLimiter: RateLimiter<TFn>) => void
   /**
    * Time window in milliseconds within which the limit applies
    */
   window: number
 }
 
-const defaultOptions: Required<RateLimiterOptions<any, any>> = {
+const defaultOptions: Required<RateLimiterOptions<any>> = {
   enabled: true,
   limit: 1,
   onExecute: () => {},
@@ -63,18 +60,15 @@ const defaultOptions: Required<RateLimiterOptions<any, any>> = {
  * rateLimiter.maybeExecute('123');
  * ```
  */
-export class RateLimiter<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
-> {
+export class RateLimiter<TFn extends AnyFunction> {
   private _executionCount = 0
   private _rejectionCount = 0
   private _executionTimes: Array<number> = []
-  private _options: RateLimiterOptions<TFn, TArgs>
+  private _options: RateLimiterOptions<TFn>
 
   constructor(
     private fn: TFn,
-    initialOptions: RateLimiterOptions<TFn, TArgs>,
+    initialOptions: RateLimiterOptions<TFn>,
   ) {
     this._options = {
       ...defaultOptions,
@@ -86,21 +80,15 @@ export class RateLimiter<
    * Updates the rate limiter options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<RateLimiterOptions<TFn, TArgs>>,
-  ): RateLimiterOptions<TFn, TArgs> {
-    this._options = {
-      ...this._options,
-      ...newOptions,
-    }
-    return this._options
+  setOptions(newOptions: Partial<RateLimiterOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
   }
 
   /**
    * Returns the current rate limiter options
    */
-  getOptions(): Required<RateLimiterOptions<TFn, TArgs>> {
-    return this._options as Required<RateLimiterOptions<TFn, TArgs>>
+  getOptions(): Required<RateLimiterOptions<TFn>> {
+    return this._options as Required<RateLimiterOptions<TFn>>
   }
 
   /**
@@ -118,7 +106,7 @@ export class RateLimiter<
    * rateLimiter.maybeExecute('arg1', 'arg2'); // false
    * ```
    */
-  maybeExecute(...args: TArgs): boolean {
+  maybeExecute(...args: Parameters<TFn>): boolean {
     this.cleanupOldExecutions()
 
     if (this._executionTimes.length < this._options.limit) {
@@ -131,7 +119,7 @@ export class RateLimiter<
     return false
   }
 
-  private executeFunction(...args: TArgs): void {
+  private executeFunction(...args: Parameters<TFn>): void {
     if (!this._options.enabled) return
     const now = Date.now()
     this._executionCount++
@@ -227,7 +215,7 @@ export class RateLimiter<
  */
 export function rateLimit<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<RateLimiterOptions<TFn, Parameters<TFn>>, 'enabled'>,
+  initialOptions: Omit<RateLimiterOptions<TFn>, 'enabled'>,
 ) {
   const rateLimiter = new RateLimiter(fn, initialOptions)
   return rateLimiter.maybeExecute.bind(rateLimiter)

package/src/throttler.ts

@@ -3,10 +3,7 @@ import type { AnyFunction } from './types'
 /**
  * Options for configuring a throttled function
  */
-export interface ThrottlerOptions<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
-> {
+export interface ThrottlerOptions<TFn extends AnyFunction> {
   /**
    * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
    * Defaults to true.
@@ -20,7 +17,7 @@ export interface ThrottlerOptions<
   /**
    * Callback function that is called after the function is executed
    */
-  onExecute?: (throttler: Throttler<TFn, TArgs>) => void
+  onExecute?: (throttler: Throttler<TFn>) => void
   /**
    * Whether to execute on the trailing edge of the timeout.
    * Defaults to true.
@@ -32,12 +29,12 @@ export interface ThrottlerOptions<
   wait: number
 }
 
-const defaultOptions: Required<ThrottlerOptions<any, any>> = {
+const defaultOptions: Required<ThrottlerOptions<any>> = {
   enabled: true,
   leading: true,
+  onExecute: () => {},
   trailing: true,
   wait: 0,
-  onExecute: () => {},
 }
 
 /**
@@ -67,17 +64,16 @@ const defaultOptions: Required<ThrottlerOptions<any, any>> = {
  * throttler.maybeExecute('123'); // Throttled
  * ```
  */
-export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
+export class Throttler<TFn extends AnyFunction> {
   private _executionCount = 0
-  private _lastArgs: TArgs | undefined
+  private _lastArgs: Parameters<TFn> | undefined
   private _lastExecutionTime = 0
-  private _options: Required<ThrottlerOptions<TFn, TArgs>>
+  private _options: Required<ThrottlerOptions<TFn>>
   private _timeoutId: NodeJS.Timeout | undefined
-  private _isPending = false
 
   constructor(
     private fn: TFn,
-    initialOptions: ThrottlerOptions<TFn, TArgs>,
+    initialOptions: ThrottlerOptions<TFn>,
   ) {
     this._options = {
       ...defaultOptions,
@@ -89,20 +85,19 @@ export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
    * Updates the throttler options
    * Returns the new options state
    */
-  setOptions(
-    newOptions: Partial<ThrottlerOptions<TFn, TArgs>>,
-  ): Required<ThrottlerOptions<TFn, TArgs>> {
-    this._options = {
-      ...this._options,
-      ...newOptions,
+  setOptions(newOptions: Partial<ThrottlerOptions<TFn>>): void {
+    this._options = { ...this._options, ...newOptions }
+
+    // End the pending state if the debouncer is disabled
+    if (!this._options.enabled) {
+      this.cancel()
     }
-    return this._options
   }
 
   /**
    * Returns the current throttler options
    */
-  getOptions(): Required<ThrottlerOptions<TFn, TArgs>> {
+  getOptions(): Required<ThrottlerOptions<TFn>> {
     return this._options
   }
 
@@ -128,42 +123,40 @@ export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
    * throttled.maybeExecute('c', 'd');
    * ```
    */
-  maybeExecute(...args: TArgs): void {
+  maybeExecute(...args: Parameters<TFn>): void {
     const now = Date.now()
     const timeSinceLastExecution = now - this._lastExecutionTime
 
     // Handle leading execution
-    if (timeSinceLastExecution >= this._options.wait) {
-      if (this._options.leading) {
-        this.executeFunction(...args)
-      }
-      this._lastExecutionTime = now
-      this._isPending = false
+    if (this._options.leading && timeSinceLastExecution >= this._options.wait) {
+      this.executeFunction(...args)
     } else {
       // Store the most recent arguments for potential trailing execution
       this._lastArgs = args
 
       // Set up trailing execution if not already scheduled
       if (!this._timeoutId && this._options.trailing) {
-        this._isPending = true
+        const _timeSinceLastExecution = this._lastExecutionTime
+          ? now - this._lastExecutionTime
+          : 0
+        const timeoutDuration = this._options.wait - _timeSinceLastExecution
         this._timeoutId = setTimeout(() => {
-          if (this._lastArgs) {
+          if (this._lastArgs !== undefined) {
             this.executeFunction(...this._lastArgs)
-            this._lastArgs = undefined
           }
-          this._lastExecutionTime = Date.now()
-          this._timeoutId = undefined
-          this._isPending = false
-          this._options.onExecute(this)
-        }, this._options.wait - timeSinceLastExecution)
+        }, timeoutDuration)
       }
     }
   }
 
-  private executeFunction(...args: TArgs): void {
+  private executeFunction(...args: Parameters<TFn>): void {
     if (!this._options.enabled) return
     this.fn(...args) // EXECUTE!
     this._executionCount++
+    this._lastExecutionTime = Date.now()
+    this._timeoutId = undefined
+    this._lastArgs = undefined
+    this._options.onExecute(this)
   }
 
   /**
@@ -180,36 +173,35 @@ export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
       clearTimeout(this._timeoutId)
       this._timeoutId = undefined
       this._lastArgs = undefined
-      this._isPending = false
     }
   }
 
   /**
-   * Returns the number of times the function has been executed
+   * Returns the last execution time
    */
-  getExecutionCount(): number {
-    return this._executionCount
+  getLastExecutionTime(): number {
+    return this._lastExecutionTime
   }
 
   /**
-   * Returns `true` if there is a pending execution
+   * Returns the next execution time
    */
-  getIsPending(): boolean {
-    return this._options.enabled && this._isPending
+  getNextExecutionTime(): number {
+    return this._lastExecutionTime + this._options.wait
   }
 
   /**
-   * Returns the last execution time
+   * Returns the number of times the function has been executed
    */
-  getLastExecutionTime(): number {
-    return this._lastExecutionTime
+  getExecutionCount(): number {
+    return this._executionCount
   }
 
   /**
-   * Returns the next execution time
+   * Returns `true` if there is a pending execution
    */
-  getNextExecutionTime(): number {
-    return this._lastExecutionTime + this._options.wait
+  getIsPending(): boolean {
+    return this._options.enabled && !!this._timeoutId
   }
 }
 
@@ -239,10 +231,10 @@ export class Throttler<TFn extends AnyFunction, TArgs extends Parameters<TFn>> {
  * });
  * ```
  */
-export function throttle<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
->(fn: TFn, initialOptions: Omit<ThrottlerOptions<TFn, TArgs>, 'enabled'>) {
+export function throttle<TFn extends AnyFunction>(
+  fn: TFn,
+  initialOptions: Omit<ThrottlerOptions<TFn>, 'enabled'>,
+) {
   const throttler = new Throttler(fn, initialOptions)
   return throttler.maybeExecute.bind(throttler)
 }

package/src/types.ts

@@ -1,17 +1,9 @@
 /**
  * Represents a function that can be called with any arguments and returns any value.
- * @template TArgs - The type of the arguments the function can be called with.
- * @returns The return value of the function.
  */
-export type AnyFunction<TArgs extends Array<any> = Array<any>> = (
-  ...args: TArgs
-) => any
+export type AnyFunction = (...args: Array<any>) => any
 
 /**
  * Represents an asynchronous function that can be called with any arguments and returns a promise.
- * @template TArgs - The type of the arguments the function can be called with.
- * @returns A promise that resolves to the return value of the function.
  */
-export type AnyAsyncFunction<TArgs extends Array<any> = Array<any>> = (
-  ...args: TArgs
-) => Promise<any>
+export type AnyAsyncFunction = (...args: Array<any>) => Promise<any>

package/src/utils.ts

@@ -1,6 +1,6 @@
 export function bindInstanceMethods<T extends Record<string, any>>(
   instance: T,
-) {
+): T {
   return Object.getOwnPropertyNames(Object.getPrototypeOf(instance))
     .filter((key) => typeof instance[key as keyof T] === 'function')
     .reduce((acc: any, key) => {