@tanstack/pacer 0.4.0 → 0.6.0

package/src/async-rate-limiter.ts

@@ -1,4 +1,5 @@
-import type { AnyAsyncFunction } from './types'
+import { parseFunctionOrValue } from './utils'
+import type { AnyAsyncFunction, OptionalKeys } from './types'
 
 /**
  * Options for configuring an async rate-limited function
@@ -6,15 +7,19 @@ import type { AnyAsyncFunction } from './types'
 export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
   /**
    * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
+   * Can be a boolean or a function that returns a boolean.
    * Defaults to true.
    */
-  enabled?: boolean
+  enabled?: boolean | ((rateLimiter: AsyncRateLimiter<TFn>) => boolean)
   /**
-   * Maximum number of executions allowed within the time window
+   * Maximum number of executions allowed within the time window.
+   * Can be a number or a function that returns a number.
    */
-  limit: number
+  limit: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number)
   /**
-   * Optional error handler for when the rate-limited function throws
+   * Optional error handler for when the rate-limited function throws.
+   * If provided, the handler will be called with the error and rate limiter instance.
+   * This can be used alongside throwOnError - the handler will be called before any error is thrown.
    */
   onError?: (error: unknown, rateLimiter: AsyncRateLimiter<TFn>) => void
   /**
@@ -33,9 +38,16 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
     rateLimiter: AsyncRateLimiter<TFn>,
   ) => void
   /**
-   * Time window in milliseconds within which the limit applies
+   * Whether to throw errors when they occur.
+   * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+   * Can be explicitly set to override these defaults.
    */
-  window: number
+  throwOnError?: boolean
+  /**
+   * Time window in milliseconds within which the limit applies.
+   * Can be a number or a function that returns a number.
+   */
+  window: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number)
   /**
    * Type of window to use for rate limiting
    * - 'fixed': Uses a fixed window that resets after the window period
@@ -45,14 +57,16 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
   windowType?: 'fixed' | 'sliding'
 }
 
-const defaultOptions: Required<
-  Omit<AsyncRateLimiterOptions<any>, 'limit' | 'window'>
+type AsyncRateLimiterOptionsWithOptionalCallbacks = OptionalKeys<
+  AsyncRateLimiterOptions<any>,
+  'onError' | 'onReject' | 'onSettled' | 'onSuccess'
+>
+
+const defaultOptions: Omit<
+  AsyncRateLimiterOptionsWithOptionalCallbacks,
+  'limit' | 'window'
 > = {
   enabled: true,
-  onError: () => {},
-  onReject: () => {},
-  onSettled: () => {},
-  onSuccess: () => {},
   windowType: 'fixed',
 }
 
@@ -80,11 +94,29 @@ const defaultOptions: Required<
  * Rate limiting is best used for hard API limits or resource constraints. For UI updates or
  * smoothing out frequent events, throttling or debouncing usually provide better user experience.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and rate limiter instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncRateLimiter instance
+ * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler
+ *
  * @example
  * ```ts
  * const rateLimiter = new AsyncRateLimiter(
  *   async (id: string) => await api.getData(id),
- *   { limit: 5, window: 1000, windowType: 'sliding' } // 5 calls per second with sliding window
+ *   {
+ *     limit: 5,
+ *     window: 1000,
+ *     windowType: 'sliding',
+ *     onError: (error) => {
+ *       console.error('API call failed:', error);
+ *     },
+ *     onReject: (limiter) => {
+ *       console.log(`Rate limit exceeded. Try again in ${limiter.getMsUntilNextWindow()}ms`);
+ *     }
+ *   }
  * );
  *
  * // Will execute immediately until limit reached, then block
@@ -93,7 +125,7 @@ const defaultOptions: Required<
  * ```
  */
 export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
-  private _options: AsyncRateLimiterOptions<TFn>
+  private _options: AsyncRateLimiterOptionsWithOptionalCallbacks
   private _errorCount = 0
   private _executionTimes: Array<number> = []
   private _lastResult: ReturnType<TFn> | undefined
@@ -109,6 +141,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     this._options = {
       ...defaultOptions,
       ...initialOptions,
+      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,
     }
   }
 
@@ -123,8 +156,29 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
   /**
    * Returns the current rate limiter options
    */
-  getOptions(): Required<AsyncRateLimiterOptions<TFn>> {
-    return this._options as Required<AsyncRateLimiterOptions<TFn>>
+  getOptions(): AsyncRateLimiterOptions<TFn> {
+    return this._options
+  }
+
+  /**
+   * Returns the current enabled state of the rate limiter
+   */
+  getEnabled(): boolean {
+    return !!parseFunctionOrValue(this._options.enabled, this)
+  }
+
+  /**
+   * Returns the current limit of executions allowed within the time window
+   */
+  getLimit(): number {
+    return parseFunctionOrValue(this._options.limit, this)
+  }
+
+  /**
+   * Returns the current time window in milliseconds
+   */
+  getWindow(): number {
+    return parseFunctionOrValue(this._options.window, this)
   }
 
   /**
@@ -132,6 +186,19 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
    * Will reject execution if the number of calls in the current window exceeds the limit.
    * If execution is allowed, waits for any previous execution to complete before proceeding.
    *
+   * Error Handling:
+   * - If the rate-limited function throws and no `onError` handler is configured,
+   *   the error will be thrown from this method.
+   * - If an `onError` handler is configured, errors will be caught and passed to the handler,
+   *   and this method will return undefined.
+   * - If the rate limit is exceeded, the execution will be rejected and the `onReject` handler
+   *   will be called if configured.
+   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
+   * - Rate limit rejections can be tracked using `getRejectionCount()`.
+   *
+   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
+   * @throws The error from the rate-limited function if no onError handler is configured
+   *
    * @example
    * ```ts
    * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
@@ -148,9 +215,12 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
   ): Promise<ReturnType<TFn> | undefined> {
     this.cleanupOldExecutions()
 
+    const limit = this.getLimit()
+    const window = this.getWindow()
+
     if (this._options.windowType === 'sliding') {
       // For sliding window, we can execute if we have capacity in the current window
-      if (this._executionTimes.length < this._options.limit) {
+      if (this._executionTimes.length < limit) {
         await this.executeFunction(...args)
         return this._lastResult
       }
@@ -158,9 +228,9 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
       // For fixed window, we need to check if we're in a new window
       const now = Date.now()
       const oldestExecution = Math.min(...this._executionTimes)
-      const isNewWindow = oldestExecution + this._options.window <= now
+      const isNewWindow = oldestExecution + window <= now
 
-      if (isNewWindow || this._executionTimes.length < this._options.limit) {
+      if (isNewWindow || this._executionTimes.length < limit) {
         await this.executeFunction(...args)
         return this._lastResult
       }
@@ -173,7 +243,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
   private async executeFunction(
     ...args: Parameters<TFn>
   ): Promise<ReturnType<TFn> | undefined> {
-    if (!this._options.enabled) return
+    if (!this.getEnabled()) return
     this._isExecuting = true
     const now = Date.now()
     this._executionTimes.push(now)
@@ -185,6 +255,11 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     } catch (error) {
       this._errorCount++
       this._options.onError?.(error, this)
+      if (this._options.throwOnError) {
+        throw error
+      } else {
+        console.error(error)
+      }
     } finally {
       this._isExecuting = false
       this._settleCount++
@@ -203,7 +278,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
 
   private cleanupOldExecutions(): void {
     const now = Date.now()
-    const windowStart = now - this._options.window
+    const windowStart = now - this.getWindow()
     this._executionTimes = this._executionTimes.filter(
       (time) => time > windowStart,
     )
@@ -214,7 +289,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
    */
   getRemainingInWindow(): number {
     this.cleanupOldExecutions()
-    return Math.max(0, this._options.limit - this._executionTimes.length)
+    return Math.max(0, this.getLimit() - this._executionTimes.length)
   }
 
   /**
@@ -227,7 +302,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
       return 0
     }
     const oldestExecution = Math.min(...this._executionTimes)
-    return oldestExecution + this._options.window - Date.now()
+    return oldestExecution + this.getWindow() - Date.now()
   }
 
   /**
@@ -298,6 +373,14 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  * Consider using throttle() or debounce() if you need more intelligent execution control. Use rate limiting when you specifically
  * need to enforce a hard limit on the number of executions within a time period.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and rate limiter instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncRateLimiter instance
+ * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler
+ *
  * @example
  * ```ts
  * // Rate limit to 5 calls per minute with a sliding window
@@ -305,6 +388,9 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  *   limit: 5,
  *   window: 60000,
  *   windowType: 'sliding',
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   },
  *   onReject: (rateLimiter) => {
  *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  *   }
@@ -321,7 +407,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  */
 export function asyncRateLimit<TFn extends AnyAsyncFunction>(
   fn: TFn,
-  initialOptions: Omit<AsyncRateLimiterOptions<TFn>, 'enabled'>,
+  initialOptions: AsyncRateLimiterOptions<TFn>,
 ) {
   const rateLimiter = new AsyncRateLimiter(fn, initialOptions)
   return rateLimiter.maybeExecute.bind(rateLimiter)

package/src/async-throttler.ts

@@ -1,4 +1,5 @@
-import type { AnyAsyncFunction } from './types'
+import { parseFunctionOrValue } from './utils'
+import type { AnyAsyncFunction, OptionalKeys } from './types'
 
 /**
  * Options for configuring an async throttled function
@@ -6,16 +7,19 @@ import type { AnyAsyncFunction } from './types'
 export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
   /**
    * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
+   * Can be a boolean or a function that returns a boolean.
    * Defaults to true.
    */
-  enabled?: boolean
+  enabled?: boolean | ((throttler: AsyncThrottler<TFn>) => boolean)
   /**
    * Whether to execute the function immediately when called
    * Defaults to true
    */
   leading?: boolean
   /**
-   * Optional error handler for when the throttled function throws
+   * Optional error handler for when the throttled function throws.
+   * If provided, the handler will be called with the error and throttler instance.
+   * This can be used alongside throwOnError - the handler will be called before any error is thrown.
    */
   onError?: (error: unknown, asyncThrottler: AsyncThrottler<TFn>) => void
   /**
@@ -29,24 +33,33 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
     result: ReturnType<TFn>,
     asyncThrottler: AsyncThrottler<TFn>,
   ) => void
+  /**
+   * Whether to throw errors when they occur.
+   * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+   * Can be explicitly set to override these defaults.
+   */
+  throwOnError?: boolean
   /**
    * Whether to execute the function on the trailing edge of the wait period
    * Defaults to true
    */
   trailing?: boolean
   /**
-   * Time window in milliseconds during which the function can only be executed once
+   * Time window in milliseconds during which the function can only be executed once.
+   * Can be a number or a function that returns a number.
    * Defaults to 0ms
    */
-  wait: number
+  wait: number | ((throttler: AsyncThrottler<TFn>) => number)
 }
 
-const defaultOptions: Required<AsyncThrottlerOptions<any>> = {
+type AsyncThrottlerOptionsWithOptionalCallbacks = OptionalKeys<
+  AsyncThrottlerOptions<any>,
+  'onError' | 'onSettled' | 'onSuccess'
+>
+
+const defaultOptions: AsyncThrottlerOptionsWithOptionalCallbacks = {
   enabled: true,
   leading: true,
-  onError: () => {},
-  onSettled: () => {},
-  onSuccess: () => {},
   trailing: true,
   wait: 0,
 }
@@ -65,12 +78,24 @@ const defaultOptions: Required<AsyncThrottlerOptions<any>> = {
  * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to
  * ensure a maximum execution frequency.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
  * @example
  * ```ts
  * const throttler = new AsyncThrottler(async (value: string) => {
  *   const result = await saveToAPI(value);
  *   return result; // Return value is preserved
- * }, { wait: 1000 });
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   }
+ * });
  *
  * // Will only execute once per second no matter how often called
  * // Returns the API response directly
@@ -78,7 +103,7 @@ const defaultOptions: Required<AsyncThrottlerOptions<any>> = {
  * ```
  */
 export class AsyncThrottler<TFn extends AnyAsyncFunction> {
-  private _options: Required<AsyncThrottlerOptions<TFn>>
+  private _options: AsyncThrottlerOptionsWithOptionalCallbacks
   private _abortController: AbortController | null = null
   private _errorCount = 0
   private _isExecuting = false
@@ -97,6 +122,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     this._options = {
       ...defaultOptions,
       ...initialOptions,
+      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,
     }
   }
 
@@ -116,22 +142,47 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   /**
    * Returns the current options
    */
-  getOptions(): Required<AsyncThrottlerOptions<TFn>> {
+  getOptions(): AsyncThrottlerOptions<TFn> {
     return this._options
   }
 
   /**
-   * Attempts to execute the throttled function
-   * If a call is already in progress, it may be blocked or queued depending on the `wait` option
+   * Returns the current enabled state of the throttler
+   */
+  getEnabled(): boolean {
+    return !!parseFunctionOrValue(this._options.enabled, this)
+  }
+
+  /**
+   * Returns the current wait time in milliseconds
+   */
+  getWait(): number {
+    return parseFunctionOrValue(this._options.wait, this)
+  }
+
+  /**
+   * Attempts to execute the throttled function.
+   * If a call is already in progress, it may be blocked or queued depending on the `wait` option.
+   *
+   * Error Handling:
+   * - If the throttled function throws and no `onError` handler is configured,
+   *   the error will be thrown from this method.
+   * - If an `onError` handler is configured, errors will be caught and passed to the handler,
+   *   and this method will return undefined.
+   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
+   *
+   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
+   * @throws The error from the throttled function if no onError handler is configured
    */
   async maybeExecute(
     ...args: Parameters<TFn>
   ): Promise<ReturnType<TFn> | undefined> {
     const now = Date.now()
     const timeSinceLastExecution = now - this._lastExecutionTime
+    const wait = this.getWait()
 
     // Handle leading execution
-    if (this._options.leading && timeSinceLastExecution >= this._options.wait) {
+    if (this._options.leading && timeSinceLastExecution >= wait) {
       await this.executeFunction(...args)
       return this._lastResult
     } else {
@@ -149,7 +200,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
           const _timeSinceLastExecution = this._lastExecutionTime
             ? now - this._lastExecutionTime
             : 0
-          const timeoutDuration = this._options.wait - _timeSinceLastExecution
+          const timeoutDuration = wait - _timeSinceLastExecution
           this._timeoutId = setTimeout(async () => {
             if (this._lastArgs !== undefined) {
               await this.executeFunction(...this._lastArgs)
@@ -164,23 +215,28 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   private async executeFunction(
     ...args: Parameters<TFn>
   ): Promise<ReturnType<TFn> | undefined> {
-    if (!this._options.enabled || this._isExecuting) return undefined
+    if (!this.getEnabled() || this._isExecuting) return undefined
     this._abortController = new AbortController()
     try {
       this._isExecuting = true
       this._lastResult = await this.fn(...args) // EXECUTE!
       this._successCount++
-      this._options.onSuccess(this._lastResult!, this)
+      this._options.onSuccess?.(this._lastResult!, this)
     } catch (error) {
       this._errorCount++
-      this._options.onError(error, this)
+      this._options.onError?.(error, this)
+      if (this._options.throwOnError) {
+        throw error
+      } else {
+        console.error(error)
+      }
     } finally {
       this._isExecuting = false
       this._settleCount++
       this._abortController = null
       this._lastExecutionTime = Date.now()
-      this._nextExecutionTime = this._lastExecutionTime + this._options.wait
-      this._options.onSettled(this)
+      this._nextExecutionTime = this._lastExecutionTime + this.getWait()
+      this._options.onSettled?.(this)
     }
     return this._lastResult
   }
@@ -246,7 +302,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
    * Returns the current pending state
    */
   getIsPending(): boolean {
-    return this._options.enabled && !!this._timeoutId
+    return this.getEnabled() && !!this._timeoutId
   }
 
   /**
@@ -266,12 +322,24 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
  * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
  * instead of setting the result on a state variable from within the throttled function.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
  * @example
  * ```ts
  * const throttled = asyncThrottle(async (value: string) => {
  *   const result = await saveToAPI(value);
  *   return result; // Return value is preserved
- * }, { wait: 1000 });
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   }
+ * });
  *
  * // This will execute at most once per second
  * // Returns the API response directly
@@ -280,7 +348,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
  */
 export function asyncThrottle<TFn extends AnyAsyncFunction>(
   fn: TFn,
-  initialOptions: Omit<AsyncThrottlerOptions<TFn>, 'enabled'>,
+  initialOptions: AsyncThrottlerOptions<TFn>,
 ) {
   const asyncThrottler = new AsyncThrottler(fn, initialOptions)
   return asyncThrottler.maybeExecute.bind(asyncThrottler)

package/src/debouncer.ts

@@ -1,3 +1,4 @@
+import { parseFunctionOrValue } from './utils'
 import type { AnyFunction } from './types'
 
 /**
@@ -6,9 +7,10 @@ import type { AnyFunction } from './types'
 export interface DebouncerOptions<TFn extends AnyFunction> {
   /**
    * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
+   * Can be a boolean or a function that returns a boolean.
    * Defaults to true.
    */
-  enabled?: boolean
+  enabled?: boolean | ((debouncer: Debouncer<TFn>) => boolean)
   /**
    * Whether to execute on the leading edge of the timeout.
    * The first call will execute immediately and the rest will wait the delay.
@@ -25,10 +27,11 @@ export interface DebouncerOptions<TFn extends AnyFunction> {
    */
   trailing?: boolean
   /**
-   * Delay in milliseconds before executing the function
+   * Delay in milliseconds before executing the function.
+   * Can be a number or a function that returns a number.
    * Defaults to 0ms
    */
-  wait: number
+  wait: number | ((debouncer: Debouncer<TFn>) => number)
 }
 
 const defaultOptions: Required<DebouncerOptions<any>> = {
@@ -99,6 +102,20 @@ export class Debouncer<TFn extends AnyFunction> {
     return this._options
   }
 
+  /**
+   * Returns the current enabled state of the debouncer
+   */
+  getEnabled(): boolean {
+    return parseFunctionOrValue(this._options.enabled, this)
+  }
+
+  /**
+   * Returns the current wait time in milliseconds
+   */
+  getWait(): number {
+    return parseFunctionOrValue(this._options.wait, this)
+  }
+
   /**
    * Attempts to execute the debounced function
    * If a call is already in progress, it will be queued
@@ -127,11 +144,11 @@ export class Debouncer<TFn extends AnyFunction> {
       if (this._options.trailing && !_didLeadingExecute) {
         this.executeFunction(...args)
       }
-    }, this._options.wait)
+    }, this.getWait())
   }
 
   private executeFunction(...args: Parameters<TFn>): void {
-    if (!this._options.enabled) return undefined
+    if (!this.getEnabled()) return undefined
     this.fn(...args) // EXECUTE!
     this._isPending = false
     this._executionCount++
@@ -160,7 +177,7 @@ export class Debouncer<TFn extends AnyFunction> {
    * Returns `true` if debouncing
    */
   getIsPending(): boolean {
-    return this._options.enabled && this._isPending
+    return this.getEnabled() && this._isPending
   }
 }
 
@@ -186,7 +203,7 @@ export class Debouncer<TFn extends AnyFunction> {
  */
 export function debounce<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: Omit<DebouncerOptions<TFn>, 'enabled'>,
+  initialOptions: DebouncerOptions<TFn>,
 ): (...args: Parameters<TFn>) => void {
   const debouncer = new Debouncer(fn, initialOptions)
   return debouncer.maybeExecute.bind(debouncer)

package/src/queuer.ts

@@ -1,3 +1,5 @@
+import { parseFunctionOrValue } from './utils'
+
 /**
  * Options for configuring a Queuer instance
  */
@@ -60,9 +62,11 @@ export interface QueuerOptions<TValue> {
    */
   started?: boolean
   /**
-   * Time in milliseconds to wait between processing items
+   * Time in milliseconds to wait between processing items.
+   * Can be a number or a function that returns a number.
+   * @default 0
    */
-  wait?: number
+  wait?: number | ((queuer: Queuer<TValue>) => number)
 }
 
 const defaultOptions: Required<QueuerOptions<any>> = {
@@ -78,7 +82,7 @@ const defaultOptions: Required<QueuerOptions<any>> = {
   onItemsChange: () => {},
   onReject: () => {},
   onExpire: () => {},
-  started: false,
+  started: true,
   wait: 0,
 }
 
@@ -178,6 +182,13 @@ export class Queuer<TValue> {
     return this._options
   }
 
+  /**
+   * Returns the current wait time in milliseconds
+   */
+  getWait(): number {
+    return parseFunctionOrValue(this._options.wait, this)
+  }
+
   /**
    * Processes items in the queuer
    */
@@ -197,9 +208,10 @@ export class Queuer<TValue> {
       }
       this._onItemsChanges.forEach((cb) => cb(nextItem))
 
-      if (this._options.wait > 0) {
+      const wait = this.getWait()
+      if (wait > 0) {
         // Use setTimeout to wait before processing next item
-        setTimeout(() => this.tick(), this._options.wait)
+        setTimeout(() => this.tick(), wait)
         return
       }
 
@@ -493,7 +505,7 @@ export class Queuer<TValue> {
  * processPriority(3) // Processed before 1
  * ```
  */
-export function queue<TValue>(options: QueuerOptions<TValue> = {}) {
-  const queuer = new Queuer<TValue>({ ...options, started: true })
+export function queue<TValue>(options: QueuerOptions<TValue>) {
+  const queuer = new Queuer<TValue>(options)
   return queuer.addItem.bind(queuer)
 }