@tanstack/pacer 0.3.0 → 0.5.0

package/src/async-debouncer.ts

@@ -1,3 +1,4 @@
+import { parseFunctionOrValue } from './utils'
 import type { AnyAsyncFunction } from './types'
 
 /**
@@ -6,9 +7,10 @@ import type { AnyAsyncFunction } from './types'
 export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
   /**
    * 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: AsyncDebouncer<TFn>) => boolean)
   /**
    * Whether to execute on the leading edge of the timeout.
    * Defaults to false.
@@ -32,10 +34,11 @@ export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
    */
   trailing?: boolean
   /**
-   * Delay in milliseconds to wait after the last call before executing
+   * Delay in milliseconds to wait after the last call before executing.
+   * Can be a number or a function that returns a number.
    * Defaults to 0ms
    */
-  wait: number
+  wait: number | ((debouncer: AsyncDebouncer<TFn>) => number)
 }
 
 const defaultOptions: Required<AsyncDebouncerOptions<any>> = {
@@ -58,16 +61,20 @@ const defaultOptions: Required<AsyncDebouncerOptions<any>> = {
  * Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until
  * the function stops being called for the specified delay period.
  *
+ * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,
+ * 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 debounced function.
+ *
  * @example
  * ```ts
  * const asyncDebouncer = new AsyncDebouncer(async (value: string) => {
- *   await searchAPI(value);
+ *   const results = await searchAPI(value);
+ *   return results; // Return value is preserved
  * }, { wait: 500 });
  *
  * // Called on each keystroke but only executes after 500ms of no typing
- * inputElement.addEventListener('input', () => {
- *   asyncDebouncer.maybeExecute(inputElement.value);
- * });
+ * // Returns the API response directly
+ * const results = await asyncDebouncer.maybeExecute(inputElement.value);
  * ```
  */
 export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
@@ -113,6 +120,20 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
     return this._options
   }
 
+  /**
+   * Returns the current debouncer enabled state
+   */
+  getEnabled(): boolean {
+    return parseFunctionOrValue(this._options.enabled, this)
+  }
+
+  /**
+   * Returns the current debouncer wait state
+   */
+  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
@@ -145,14 +166,14 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
         // Reset state and resolve
         this._canLeadingExecute = true
         resolve(this._lastResult)
-      }, this._options.wait)
+      }, this.getWait())
     })
   }
 
   private async executeFunction(
     ...args: Parameters<TFn>
   ): Promise<ReturnType<TFn> | undefined> {
-    if (!this._options.enabled) return undefined
+    if (!this.getEnabled()) return undefined
     this._abortController = new AbortController()
     try {
       this._isExecuting = true
@@ -229,7 +250,7 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
    * Returns `true` if there is a pending execution queued up for trailing execution
    */
   getIsPending(): boolean {
-    return this._options.enabled && this._isPending
+    return this.getEnabled() && this._isPending
   }
 
   /**
@@ -245,21 +266,25 @@ export class AsyncDebouncer<TFn extends AnyAsyncFunction> {
  * The debounced function will only execute once the wait period has elapsed without any new calls.
  * If called again during the wait period, the timer resets and a new wait period begins.
  *
+ * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,
+ * 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 debounced function.
+ *
  * @example
  * ```ts
  * const debounced = asyncDebounce(async (value: string) => {
- *   await saveToAPI(value);
+ *   const result = await saveToAPI(value);
+ *   return result; // Return value is preserved
  * }, { wait: 1000 });
  *
  * // Will only execute once, 1 second after the last call
- * await debounced("first");  // Cancelled
- * await debounced("second"); // Cancelled
- * await debounced("third");  // Executes after 1s
+ * // Returns the API response directly
+ * const result = await debounced("third");
  * ```
  */
 export function asyncDebounce<TFn extends AnyAsyncFunction>(
   fn: TFn,
-  initialOptions: Omit<AsyncDebouncerOptions<TFn>, 'enabled'>,
+  initialOptions: AsyncDebouncerOptions<TFn>,
 ) {
   const asyncDebouncer = new AsyncDebouncer(fn, initialOptions)
   return asyncDebouncer.maybeExecute.bind(asyncDebouncer)

package/src/async-queuer.ts

@@ -1,3 +1,5 @@
+import { parseFunctionOrValue } from './utils'
+import type { AnyAsyncFunction } from './types'
 import type { QueuePosition } from './queuer'
 
 export interface AsyncQueuerOptions<TValue> {
@@ -7,9 +9,11 @@ export interface AsyncQueuerOptions<TValue> {
    */
   addItemsTo?: QueuePosition
   /**
-   * Maximum number of concurrent tasks to process
+   * Maximum number of concurrent tasks to process.
+   * Can be a number or a function that returns a number.
+   * @default 1
    */
-  concurrency?: number
+  concurrency?: number | ((queuer: AsyncQueuer<TValue>) => number)
   /**
    * Maximum time in milliseconds that an item can stay in the queue
    * If not provided, items will never expire
@@ -67,9 +71,11 @@ export interface AsyncQueuerOptions<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: AsyncQueuer<TValue>) => number)
 }
 
 const defaultOptions: Required<AsyncQueuerOptions<any>> = {
@@ -160,6 +166,20 @@ export class AsyncQueuer<TValue> {
     return this._options
   }
 
+  /**
+   * Returns the current wait time between processing items
+   */
+  getWait(): number {
+    return parseFunctionOrValue(this._options.wait, this)
+  }
+
+  /**
+   * Returns the current concurrency limit
+   */
+  getConcurrency(): number {
+    return parseFunctionOrValue(this._options.concurrency, this)
+  }
+
   /**
    * Processes items in the queuer
    */
@@ -173,7 +193,7 @@ export class AsyncQueuer<TValue> {
     this.checkExpiredItems()
 
     while (
-      this._activeItems.size < this._options.concurrency &&
+      this._activeItems.size < this.getConcurrency() &&
       !this.getIsEmpty()
     ) {
       const nextFn = this.getNextItem()
@@ -204,8 +224,9 @@ export class AsyncQueuer<TValue> {
         }
         this._onSettledCallbacks.forEach((cb) => cb(success ? res : error!))
 
-        if (this._options.wait > 0) {
-          setTimeout(() => this.tick(), this._options.wait)
+        const wait = this.getWait()
+        if (wait > 0) {
+          setTimeout(() => this.tick(), wait)
           return
         }
 
@@ -322,9 +343,9 @@ export class AsyncQueuer<TValue> {
    * Adds a task to the queuer
    */
   addItem(
-    fn: (() => Promise<TValue>) & { priority?: number },
+    fn: AnyAsyncFunction & { priority?: number },
     position: QueuePosition = this._options.addItemsTo,
-    runOnUpdate: boolean = true,
+    runOnItemsChange: boolean = true,
   ): Promise<TValue> {
     if (this.getIsFull()) {
       this._rejectionCount++
@@ -381,7 +402,7 @@ export class AsyncQueuer<TValue> {
         }
       }
 
-      if (runOnUpdate) {
+      if (runOnItemsChange) {
         this._options.onItemsChange(this)
       }
 
@@ -557,9 +578,7 @@ export class AsyncQueuer<TValue> {
  * @param options - Configuration options for the AsyncQueuer
  * @returns A bound addItem function that can be used to add tasks to the queuer
  */
-export function asyncQueue<TValue>(
-  options: Omit<AsyncQueuerOptions<TValue>, 'started'> = {},
-) {
+export function asyncQueue<TValue>(options: AsyncQueuerOptions<TValue>) {
   const queuer = new AsyncQueuer<TValue>(options)
   return queuer.addItem.bind(queuer)
 }

package/src/async-rate-limiter.ts

@@ -1,3 +1,4 @@
+import { parseFunctionOrValue } from './utils'
 import type { AnyAsyncFunction } from './types'
 
 /**
@@ -6,17 +7,23 @@ 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
    */
   onError?: (error: unknown, rateLimiter: AsyncRateLimiter<TFn>) => void
+  /**
+   * Optional callback function that is called when an execution is rejected due to rate limiting
+   */
+  onReject?: (rateLimiter: AsyncRateLimiter<TFn>) => void
   /**
    * Optional function to call when the rate-limited function is executed
    */
@@ -29,13 +36,17 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
     rateLimiter: AsyncRateLimiter<TFn>,
   ) => void
   /**
-   * Optional callback function that is called when an execution is rejected due to rate limiting
+   * Time window in milliseconds within which the limit applies.
+   * Can be a number or a function that returns a number.
    */
-  onReject?: (rateLimiter: AsyncRateLimiter<TFn>) => void
+  window: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number)
   /**
-   * Time window in milliseconds within which the limit applies
+   * Type of window to use for rate limiting
+   * - 'fixed': Uses a fixed window that resets after the window period
+   * - 'sliding': Uses a sliding window that allows executions as old ones expire
+   * Defaults to 'fixed'
    */
-  window: number
+  windowType?: 'fixed' | 'sliding'
 }
 
 const defaultOptions: Required<
@@ -46,6 +57,7 @@ const defaultOptions: Required<
   onReject: () => {},
   onSettled: () => {},
   onSuccess: () => {},
+  windowType: 'fixed',
 }
 
 /**
@@ -55,6 +67,16 @@ const defaultOptions: Required<
  * then blocks all subsequent calls until the window passes. This can lead to "bursty" behavior where
  * all executions happen immediately, followed by a complete block.
  *
+ * The rate limiter supports two types of windows:
+ * - 'fixed': A strict window that resets after the window period. All executions within the window count
+ *   towards the limit, and the window resets completely after the period.
+ * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more
+ *   consistent rate of execution over time.
+ *
+ * Unlike the non-async RateLimiter, this async version supports returning values from the rate-limited function,
+ * 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 rate-limited function.
+ *
  * For smoother execution patterns, consider using:
  * - Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)
  * - Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)
@@ -66,11 +88,12 @@ const defaultOptions: Required<
  * ```ts
  * const rateLimiter = new AsyncRateLimiter(
  *   async (id: string) => await api.getData(id),
- *   { limit: 5, window: 1000 } // 5 calls per second
+ *   { limit: 5, window: 1000, windowType: 'sliding' } // 5 calls per second with sliding window
  * );
  *
  * // Will execute immediately until limit reached, then block
- * await rateLimiter.maybeExecute('123');
+ * // Returns the API response directly
+ * const data = await rateLimiter.maybeExecute('123');
  * ```
  */
 export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
@@ -81,6 +104,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
   private _rejectionCount = 0
   private _settleCount = 0
   private _successCount = 0
+  private _isExecuting = false
 
   constructor(
     private fn: TFn,
@@ -107,6 +131,27 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     return this._options as Required<AsyncRateLimiterOptions<TFn>>
   }
 
+  /**
+   * 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)
+  }
+
   /**
    * 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.
@@ -128,9 +173,25 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
   ): Promise<ReturnType<TFn> | undefined> {
     this.cleanupOldExecutions()
 
-    if (this._executionTimes.length < this._options.limit) {
-      await this.executeFunction(...args)
-      return this._lastResult
+    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 < limit) {
+        await this.executeFunction(...args)
+        return this._lastResult
+      }
+    } else {
+      // 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 + window <= now
+
+      if (isNewWindow || this._executionTimes.length < limit) {
+        await this.executeFunction(...args)
+        return this._lastResult
+      }
     }
 
     this.rejectFunction()
@@ -140,7 +201,8 @@ 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)
 
@@ -152,6 +214,7 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
       this._errorCount++
       this._options.onError?.(error, this)
     } finally {
+      this._isExecuting = false
       this._settleCount++
       this._options.onSettled?.(this)
     }
@@ -168,7 +231,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,
     )
@@ -179,14 +242,20 @@ 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)
   }
 
   /**
    * Returns the number of milliseconds until the next execution will be possible
+   * For fixed windows, this is the time until the current window resets
+   * For sliding windows, this is the time until the oldest execution expires
    */
   getMsUntilNextWindow(): number {
-    return this.getRemainingInWindow() * this._options.window
+    if (this.getRemainingInWindow() > 0) {
+      return 0
+    }
+    const oldestExecution = Math.min(...this._executionTimes)
+    return oldestExecution + this.getWindow() - Date.now()
   }
 
   /**
@@ -217,6 +286,13 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     return this._rejectionCount
   }
 
+  /**
+   * Returns whether the function is currently executing
+   */
+  getIsExecuting(): boolean {
+    return this._isExecuting
+  }
+
   /**
    * Resets the rate limiter state
    */
@@ -232,6 +308,16 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
 /**
  * Creates an async rate-limited function that will execute the provided function up to a maximum number of times within a time window.
  *
+ * Unlike the non-async rate limiter, this async version supports returning values from the rate-limited function,
+ * 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 rate-limited function.
+ *
+ * The rate limiter supports two types of windows:
+ * - 'fixed': A strict window that resets after the window period. All executions within the window count
+ *   towards the limit, and the window resets completely after the period.
+ * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more
+ *   consistent rate of execution over time.
+ *
  * Note that rate limiting is a simpler form of execution control compared to throttling or debouncing:
  * - A rate limiter will allow all executions until the limit is reached, then block all subsequent calls until the window resets
  * - A throttler ensures even spacing between executions, which can be better for consistent performance
@@ -242,10 +328,11 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  *
  * @example
  * ```ts
- * // Rate limit to 5 calls per minute
+ * // Rate limit to 5 calls per minute with a sliding window
  * const rateLimited = asyncRateLimit(makeApiCall, {
  *   limit: 5,
  *   window: 60000,
+ *   windowType: 'sliding',
  *   onReject: (rateLimiter) => {
  *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  *   }
@@ -253,7 +340,8 @@ export class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  *
  * // First 5 calls will execute immediately
  * // Additional calls will be rejected until the minute window resets
- * await rateLimited();
+ * // Returns the API response directly
+ * const result = await rateLimited();
  *
  * // For more even execution, consider using throttle instead:
  * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
@@ -261,7 +349,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,3 +1,4 @@
+import { parseFunctionOrValue } from './utils'
 import type { AnyAsyncFunction } from './types'
 
 /**
@@ -6,9 +7,10 @@ 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
@@ -35,10 +37,11 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
    */
   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>> = {
@@ -58,19 +61,23 @@ const defaultOptions: Required<AsyncThrottlerOptions<any>> = {
  * Unlike debouncing which resets the delay timer on each call, throttling ensures the function executes at a
  * regular interval regardless of how often it's called.
  *
+ * Unlike the non-async Throttler, this async version supports returning values from the throttled function,
+ * 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.
+ *
  * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to
  * ensure a maximum execution frequency.
  *
  * @example
  * ```ts
  * const throttler = new AsyncThrottler(async (value: string) => {
- *   await saveToAPI(value);
+ *   const result = await saveToAPI(value);
+ *   return result; // Return value is preserved
  * }, { wait: 1000 });
  *
  * // Will only execute once per second no matter how often called
- * inputElement.addEventListener('input', () => {
- *   throttler.maybeExecute(inputElement.value);
- * });
+ * // Returns the API response directly
+ * const result = await throttler.maybeExecute(inputElement.value);
  * ```
  */
 export class AsyncThrottler<TFn extends AnyAsyncFunction> {
@@ -116,6 +123,20 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
     return this._options
   }
 
+  /**
+   * 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
@@ -125,9 +146,10 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
   ): 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 {
@@ -145,7 +167,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)
@@ -160,7 +182,7 @@ 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
@@ -175,7 +197,7 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
       this._settleCount++
       this._abortController = null
       this._lastExecutionTime = Date.now()
-      this._nextExecutionTime = this._lastExecutionTime + this._options.wait
+      this._nextExecutionTime = this._lastExecutionTime + this.getWait()
       this._options.onSettled(this)
     }
     return this._lastResult
@@ -242,7 +264,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
   }
 
   /**
@@ -258,20 +280,25 @@ export class AsyncThrottler<TFn extends AnyAsyncFunction> {
  * The throttled function will execute at most once per wait period, even if called multiple times.
  * If called while executing, it will wait until execution completes before scheduling the next call.
  *
+ * Unlike the non-async Throttler, this async version supports returning values from the throttled function,
+ * 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.
+ *
  * @example
  * ```ts
- * const throttled = asyncThrottle(async () => {
- *   await someAsyncOperation();
+ * const throttled = asyncThrottle(async (value: string) => {
+ *   const result = await saveToAPI(value);
+ *   return result; // Return value is preserved
  * }, { wait: 1000 });
  *
  * // This will execute at most once per second
- * await throttled();
- * await throttled(); // Waits 1 second before executing
+ * // Returns the API response directly
+ * const result = await throttled(inputElement.value);
  * ```
  */
 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)