@tanstack/pacer 0.15.3 → 0.16.0

package/dist/cjs/async-queuer.d.cts

@@ -1,4 +1,5 @@
 import { Store } from '@tanstack/store';
+import { AsyncRetryer, AsyncRetryerOptions } from './async-retryer.cjs';
 import { QueuePosition } from './queuer.cjs';
 export interface AsyncQueuerState<TValue> {
     /**
@@ -13,6 +14,10 @@ export interface AsyncQueuerState<TValue> {
      * Number of task executions that have resulted in errors
      */
     errorCount: number;
+    /**
+     * Number of times execute has been called
+     */
+    executeCount: number;
     /**
      * Number of items that have been removed from the queue due to expiration
      */
@@ -21,6 +26,10 @@ export interface AsyncQueuerState<TValue> {
      * Whether the queuer has no items to process (items array is empty)
      */
     isEmpty: boolean;
+    /**
+     * Whether the queuer is currently executing
+     */
+    isExecuting: boolean;
     /**
      * Whether the queuer has reached its maximum capacity
      */
@@ -71,6 +80,10 @@ export interface AsyncQueuerState<TValue> {
     successCount: number;
 }
 export interface AsyncQueuerOptions<TValue> {
+    /**
+     * Options for configuring the underlying async retryer
+     */
+    asyncRetryerOptions?: AsyncRetryerOptions<(item: TValue) => Promise<any>>;
     /**
      * Default position to add items to the queuer
      * @default 'back'
@@ -125,7 +138,7 @@ export interface AsyncQueuerOptions<TValue> {
      * If provided, the handler will be called with the error and queuer instance.
      * This can be used alongside throwOnError - the handler will be called before any error is thrown.
      */
-    onError?: (error: unknown, item: TValue, queuer: AsyncQueuer<TValue>) => void;
+    onError?: (error: Error, item: TValue, queuer: AsyncQueuer<TValue>) => void;
     /**
      * Callback fired whenever an item expires in the queuer
      */
@@ -163,21 +176,38 @@ export interface AsyncQueuerOptions<TValue> {
      */
     wait?: number | ((queuer: AsyncQueuer<TValue>) => number);
 }
+/**
+ * Utility function for sharing common `AsyncQueuerOptions` options between different `AsyncQueuer` instances.
+ */
+export declare function asyncQueuerOptions<TValue = any, TOptions extends Partial<AsyncQueuerOptions<TValue>> = Partial<AsyncQueuerOptions<TValue>>>(options: TOptions): TOptions;
 /**
  * A flexible asynchronous queue for processing tasks with configurable concurrency, priority, and expiration.
  *
- * Features:
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync Queuer:
+ * - Returns promises that can be awaited for task results
+ * - Built-in retry support via AsyncRetryer integration for each queued task
+ * - Abort support to cancel in-flight task executions
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ * - Concurrent execution support (process multiple items simultaneously)
+ *
+ * The sync Queuer is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Queuing?
+ * Queuing is a technique for managing and processing items sequentially or with controlled concurrency.
+ * Tasks are processed up to the configured concurrency limit. When a task completes,
+ * the next pending task is processed if the concurrency limit allows.
+ *
+ * Key Features:
  * - Priority queue support via the getPriority option
  * - Configurable concurrency limit
  * - Callbacks for task success, error, completion, and queue state changes
  * - FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
  * - Pause and resume processing
- * - Task cancellation
  * - Item expiration to remove stale items from the queue
  *
- * Tasks are processed concurrently up to the configured concurrency limit. When a task completes,
- * the next pending task is processed if the concurrency limit allows.
- *
  * Error Handling:
  * - If an `onError` handler is provided, it will be called with the error and queuer instance
  * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
@@ -220,7 +250,12 @@ export declare class AsyncQueuer<TValue> {
     readonly store: Store<Readonly<AsyncQueuerState<TValue>>>;
     key: string;
     options: AsyncQueuerOptions<TValue>;
+    asyncRetryers: Map<number, AsyncRetryer<(item: TValue) => Promise<any>>>;
     constructor(fn: (item: TValue) => Promise<any>, initialOptions?: AsyncQueuerOptions<TValue>);
+    /**
+     * Emits a change event for the async queuer instance. Mostly useful for devtools.
+     */
+    _emit: () => void;
     /**
      * Updates the queuer options. New options are merged with existing options.
      */
@@ -301,9 +336,36 @@ export declare class AsyncQueuer<TValue> {
      */
     stop: () => void;
     /**
-     * Removes all pending items from the queue. Does not affect active tasks.
+     * Removes all pending items from the queue.
+     * Does NOT affect active tasks.
      */
     clear: () => void;
+    /**
+     * Returns the AbortSignal for a specific execution.
+     * If no executeCount is provided, returns the signal for the most recent execution.
+     * Returns null if no execution is found or not currently executing.
+     *
+     * @param executeCount - Optional specific execution to get signal for
+     * @example
+     * ```typescript
+     * const queuer = new AsyncQueuer(
+     *   async (item: string) => {
+     *     const signal = queuer.getAbortSignal()
+     *     if (signal) {
+     *       const response = await fetch(`/api/process/${item}`, { signal })
+     *       return response.json()
+     *     }
+     *   },
+     *   { concurrency: 2 }
+     * )
+     * ```
+     */
+    getAbortSignal(executeCount?: number): AbortSignal | null;
+    /**
+     * Aborts all ongoing executions with the internal abort controllers.
+     * Does NOT clear out the items.
+     */
+    abort: () => void;
     /**
      * Resets the queuer state to its default values
      */
@@ -313,6 +375,34 @@ export declare class AsyncQueuer<TValue> {
  * Creates a new AsyncQueuer instance and returns a bound addItem function for adding tasks.
  * The queuer is started automatically and ready to process items.
  *
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync queue function:
+ * - Returns promises that can be awaited for task results
+ * - Built-in retry support via AsyncRetryer integration for each queued task
+ * - Abort support to cancel in-flight task executions
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ * - Concurrent execution support (process multiple items simultaneously)
+ *
+ * The sync queue function is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Queuing?
+ * Queuing is a technique for managing and processing items sequentially or with controlled concurrency.
+ * Tasks are processed up to the configured concurrency limit. When a task completes,
+ * the next pending task is processed if the concurrency limit allows.
+ *
+ * Configuration Options:
+ * - `concurrency`: Maximum number of concurrent tasks (default: 1)
+ * - `wait`: Time to wait between processing items (default: 0)
+ * - `maxSize`: Maximum number of items allowed in the queue (default: Infinity)
+ * - `getPriority`: Function to determine item priority
+ * - `addItemsTo`: Default position to add items ('back' or 'front', default: 'back')
+ * - `getItemsFrom`: Default position to get items ('front' or 'back', default: 'front')
+ * - `expirationDuration`: Maximum time items can stay in queue
+ * - `started`: Whether to start processing immediately (default: true)
+ * - `asyncRetryerOptions`: Configure retry behavior for task executions
+ *
  * Error Handling:
  * - If an `onError` handler is provided, it will be called with the error and queuer instance
  * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
@@ -333,11 +423,15 @@ export declare class AsyncQueuer<TValue> {
  * - State can be accessed via the underlying AsyncQueuer instance's `store.state` property
  * - When using framework adapters (React/Solid), state is accessed from the hook's state property
  *
- * Example usage:
+ * @example
  * ```ts
  * const enqueue = asyncQueue<string>(async (item) => {
  *   return item.toUpperCase();
- * }, {...options});
+ * }, {
+ *   concurrency: 2,
+ *   wait: 100,
+ *   onSuccess: (result) => console.log('Processed:', result)
+ * });
  *
  * enqueue('hello');
  * ```

package/dist/cjs/async-rate-limiter.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const store = require("@tanstack/store");
+const asyncRetryer = require("./async-retryer.cjs");
 const utils = require("./utils.cjs");
 const eventClient = require("./event-client.cjs");
 function getDefaultAsyncRateLimiterState() {
@@ -17,7 +18,13 @@ function getDefaultAsyncRateLimiterState() {
     successCount: 0
   };
 }
+function asyncRateLimiterOptions(options) {
+  return options;
+}
 const defaultOptions = {
+  asyncRetryerOptions: {
+    maxAttempts: 1
+  },
   enabled: true,
   limit: 1,
   window: 0,
@@ -28,7 +35,9 @@ class AsyncRateLimiter {
   constructor(fn, initialOptions) {
     this.fn = fn;
     this.store = new store.Store(getDefaultAsyncRateLimiterState());
+    this.asyncRetryers = /* @__PURE__ */ new Map();
     this.#timeoutIds = /* @__PURE__ */ new Set();
+    this._emit = () => eventClient.emitChange("AsyncRateLimiter", this);
     this.setOptions = (newOptions) => {
       this.options = { ...this.options, ...newOptions };
     };
@@ -75,6 +84,7 @@ class AsyncRateLimiter {
     };
     this.#execute = async (...args) => {
       if (!this.#getEnabled()) return;
+      const currentMaybeExecute = this.store.state.maybeExecuteCount;
       const now = Date.now();
       const executionTimes = [...this.store.state.executionTimes, now];
       this.#setState({
@@ -82,7 +92,12 @@ class AsyncRateLimiter {
         executionTimes
       });
       try {
-        const result = await this.fn(...args);
+        const currentAsyncRetryer = new asyncRetryer.AsyncRetryer(this.fn, {
+          ...this.options.asyncRetryerOptions,
+          key: `${this.key}-retryer-${currentMaybeExecute}`
+        });
+        this.asyncRetryers.set(currentMaybeExecute, currentAsyncRetryer);
+        const result = await currentAsyncRetryer.execute(...args);
         this.#setCleanupTimeout(now);
         this.#setState({
           successCount: this.store.state.successCount + 1,
@@ -98,6 +113,7 @@ class AsyncRateLimiter {
           throw error;
         }
       } finally {
+        this.asyncRetryers.delete(currentMaybeExecute);
         this.#setState({
           isExecuting: false,
           settleCount: this.store.state.settleCount + 1
@@ -162,9 +178,17 @@ class AsyncRateLimiter {
       const oldestExecution = this.store.state.executionTimes[0] ?? Infinity;
       return oldestExecution + this.#getWindow() - Date.now();
     };
+    this.abort = () => {
+      this.asyncRetryers.forEach((retryer) => retryer.abort());
+      this.asyncRetryers.clear();
+      this.#setState({
+        isExecuting: false
+      });
+    };
     this.reset = () => {
       this.#setState(getDefaultAsyncRateLimiterState());
       this.#clearTimeouts();
+      this.asyncRetryers.forEach((retryer) => retryer.reset());
     };
     this.key = utils.createKey(initialOptions.key);
     this.options = {
@@ -193,6 +217,31 @@ class AsyncRateLimiter {
   #clearTimeout;
   #clearTimeouts;
   #cleanupOldExecutions;
+  /**
+   * Returns the AbortSignal for a specific execution.
+   * If no maybeExecuteCount is provided, returns the signal for the most recent execution.
+   * Returns null if no execution is found or not currently executing.
+   *
+   * @param maybeExecuteCount - Optional specific execution to get signal for
+   * @example
+   * ```typescript
+   * const rateLimiter = new AsyncRateLimiter(
+   *   async (userId: string) => {
+   *     const signal = rateLimiter.getAbortSignal()
+   *     if (signal) {
+   *       const response = await fetch(`/api/users/${userId}`, { signal })
+   *       return response.json()
+   *     }
+   *   },
+   *   { limit: 5, window: 1000 }
+   * )
+   * ```
+   */
+  getAbortSignal(maybeExecuteCount) {
+    const count = maybeExecuteCount ?? this.store.state.maybeExecuteCount;
+    const retryer = this.asyncRetryers.get(count);
+    return retryer?.getAbortSignal() ?? null;
+  }
 }
 function asyncRateLimit(fn, initialOptions) {
   const rateLimiter = new AsyncRateLimiter(fn, initialOptions);
@@ -200,4 +249,5 @@ function asyncRateLimit(fn, initialOptions) {
 }
 exports.AsyncRateLimiter = AsyncRateLimiter;
 exports.asyncRateLimit = asyncRateLimit;
+exports.asyncRateLimiterOptions = asyncRateLimiterOptions;
 //# sourceMappingURL=async-rate-limiter.cjs.map

package/dist/cjs/async-rate-limiter.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"async-rate-limiter.cjs","sources":["../../src/async-rate-limiter.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { createKey, parseFunctionOrValue } from './utils'\nimport { emitChange, pacerEventClient } from './event-client'\nimport type { AnyAsyncFunction } from './types'\n\nexport interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {\n  /**\n   * Number of function executions that have resulted in errors\n   */\n  errorCount: number\n  /**\n   * Array of timestamps when executions occurred for rate limiting calculations\n   */\n  executionTimes: Array<number>\n  /**\n   * Whether the rate limiter has exceeded the limit\n   */\n  isExceeded: boolean\n  /**\n   * Whether the rate-limited function is currently executing asynchronously\n   */\n  isExecuting: boolean\n  /**\n   * The result from the most recent successful function execution\n   */\n  lastResult: ReturnType<TFn> | undefined\n  /**\n   * Number of function executions that have been rejected due to rate limiting\n   */\n  rejectionCount: number\n  /**\n   * Number of function executions that have completed (either successfully or with errors)\n   */\n  settleCount: number\n  /**\n   * Current execution status - 'disabled' when not active, 'executing' when executing, 'idle' when not executing, 'exceeded' when rate limit is exceeded\n   */\n  status: 'disabled' | 'executing' | 'exceeded' | 'idle'\n  /**\n   * Number of function executions that have completed successfully\n   */\n  successCount: number\n  /**\n   * Number of times maybeExecute has been called (for reduction calculations)\n   */\n  maybeExecuteCount: number\n}\n\nfunction getDefaultAsyncRateLimiterState<\n  TFn extends AnyAsyncFunction,\n>(): AsyncRateLimiterState<TFn> {\n  return {\n    errorCount: 0,\n    executionTimes: [],\n    isExceeded: false,\n    isExecuting: false,\n    lastResult: undefined,\n    maybeExecuteCount: 0,\n    rejectionCount: 0,\n    settleCount: 0,\n    status: 'idle',\n    successCount: 0,\n  }\n}\n\n/**\n * Options for configuring an async rate-limited function\n */\nexport interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {\n  /**\n   * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Can be a boolean or a function that returns a boolean.\n   * Defaults to true.\n   */\n  enabled?: boolean | ((rateLimiter: AsyncRateLimiter<TFn>) => boolean)\n  /**\n   * Initial state for the rate limiter\n   */\n  initialState?: Partial<AsyncRateLimiterState<TFn>>\n  /**\n   * Optional key to identify this async rate limiter instance.\n   * If provided, the async rate limiter will be identified by this key in the devtools and PacerProvider if applicable.\n   */\n  key?: string\n  /**\n   * Maximum number of executions allowed within the time window.\n   * Can be a number or a function that returns a number.\n   */\n  limit: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number)\n  /**\n   * Optional error handler for when the rate-limited function throws.\n   * If provided, the handler will be called with the error and rate limiter instance.\n   * This can be used alongside throwOnError - the handler will be called before any error is thrown.\n   */\n  onError?: (\n    error: unknown,\n    args: Parameters<TFn>,\n    rateLimiter: AsyncRateLimiter<TFn>,\n  ) => void\n  /**\n   * Optional callback function that is called when an execution is rejected due to rate limiting\n   */\n  onReject?: (args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void\n  /**\n   * Optional function to call when the rate-limited function is executed\n   */\n  onSettled?: (\n    args: Parameters<TFn>,\n    rateLimiter: AsyncRateLimiter<TFn>,\n  ) => void\n  /**\n   * Optional function to call when the rate-limited function is executed\n   */\n  onSuccess?: (\n    result: ReturnType<TFn>,\n    args: Parameters<TFn>,\n    rateLimiter: AsyncRateLimiter<TFn>,\n  ) => void\n  /**\n   * Whether to throw errors when they occur.\n   * Defaults to true if no onError handler is provided, false if an onError handler is provided.\n   * Can be explicitly set to override these defaults.\n   */\n  throwOnError?: boolean\n  /**\n   * Time window in milliseconds within which the limit applies.\n   * Can be a number or a function that returns a number.\n   */\n  window: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number)\n  /**\n   * Type of window to use for rate limiting\n   * - 'fixed': Uses a fixed window that resets after the window period\n   * - 'sliding': Uses a sliding window that allows executions as old ones expire\n   * Defaults to 'fixed'\n   */\n  windowType?: 'fixed' | 'sliding'\n}\n\nconst defaultOptions: Omit<\n  Required<AsyncRateLimiterOptions<any>>,\n  'initialState' | 'onError' | 'onReject' | 'onSettled' | 'onSuccess' | 'key'\n> = {\n  enabled: true,\n  limit: 1,\n  window: 0,\n  windowType: 'fixed',\n  throwOnError: true,\n}\n\n/**\n * A class that creates an async 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 * The rate limiter supports two types of windows:\n * - 'fixed': A strict window that resets after the window period. All executions within the window count\n *   towards the limit, and the window resets completely after the period.\n * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more\n *   consistent rate of execution over time.\n *\n * Unlike the non-async RateLimiter, this async version supports returning values from the rate-limited function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the rate-limited function.\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 * State Management:\n * - Uses TanStack Store for reactive state management\n * - Use `initialState` to provide initial state values when creating the rate limiter\n * - `initialState` can be a partial state object\n * - Use `onSuccess` callback to react to successful function execution and implement custom logic\n * - Use `onError` callback to react to function execution errors and implement custom error handling\n * - Use `onSettled` callback to react to function execution completion (success or error) and implement custom logic\n * - Use `onReject` callback to react to executions being rejected when rate limit is exceeded\n * - The state includes execution times, success/error counts, and current execution status\n * - State can be accessed via `asyncRateLimiter.store.state` when using the class directly\n * - When using framework adapters (React/Solid), state is accessed from `asyncRateLimiter.state`\n *\n * Error Handling:\n * - If an `onError` handler is provided, it will be called with the error and rate limiter instance\n * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown\n * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed\n * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown\n * - The error state can be checked using the underlying AsyncRateLimiter instance\n * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler\n *\n * @example\n * ```ts\n * const rateLimiter = new AsyncRateLimiter(\n *   async (id: string) => await api.getData(id),\n *   {\n *     limit: 5,\n *     window: 1000,\n *     windowType: 'sliding',\n *     onError: (error) => {\n *       console.error('API call failed:', error);\n *     },\n *     onReject: (limiter) => {\n *       console.log(`Rate limit exceeded. Try again in ${limiter.getMsUntilNextWindow()}ms`);\n *     }\n *   }\n * );\n *\n * // Will execute immediately until limit reached, then block\n * // Returns the API response directly\n * const data = await rateLimiter.maybeExecute('123');\n * ```\n */\nexport class AsyncRateLimiter<TFn extends AnyAsyncFunction> {\n  readonly store: Store<Readonly<AsyncRateLimiterState<TFn>>> = new Store<\n    AsyncRateLimiterState<TFn>\n  >(getDefaultAsyncRateLimiterState<TFn>())\n  key: string\n  options: AsyncRateLimiterOptions<TFn>\n  #timeoutIds: Set<NodeJS.Timeout> = new Set()\n\n  constructor(\n    public fn: TFn,\n    initialOptions: AsyncRateLimiterOptions<TFn>,\n  ) {\n    this.key = createKey(initialOptions.key)\n    this.options = {\n      ...defaultOptions,\n      ...initialOptions,\n      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,\n    }\n    this.#setState(this.options.initialState ?? {})\n    for (const executionTime of this.#getExecutionTimesInWindow()) {\n      this.#setCleanupTimeout(executionTime)\n    }\n\n    pacerEventClient.on('d-AsyncRateLimiter', (event) => {\n      if (event.payload.key !== this.key) return\n      this.#setState(event.payload.store.state)\n      this.setOptions(event.payload.options)\n    })\n  }\n\n  /**\n   * Updates the async rate limiter options\n   */\n  setOptions = (newOptions: Partial<AsyncRateLimiterOptions<TFn>>): void => {\n    this.options = { ...this.options, ...newOptions }\n  }\n\n  #setState = (newState: Partial<AsyncRateLimiterState<TFn>>): void => {\n    this.store.setState((state) => {\n      const combinedState = {\n        ...state,\n        ...newState,\n      }\n      const isExceeded = combinedState.executionTimes.length >= this.#getLimit()\n      const status = !this.#getEnabled()\n        ? 'disabled'\n        : combinedState.isExecuting\n          ? 'executing'\n          : isExceeded\n            ? 'exceeded'\n            : 'idle'\n      return {\n        ...combinedState,\n        isExceeded,\n        status,\n      }\n    })\n    emitChange('AsyncRateLimiter', this)\n  }\n\n  /**\n   * Returns the current enabled state of the async rate limiter\n   */\n  #getEnabled = (): boolean => {\n    return !!parseFunctionOrValue(this.options.enabled, this)\n  }\n\n  /**\n   * Returns the current limit of executions allowed within the time window\n   */\n  #getLimit = (): number => {\n    return parseFunctionOrValue(this.options.limit, this)\n  }\n\n  /**\n   * Returns the current time window in milliseconds\n   */\n  #getWindow = (): number => {\n    return parseFunctionOrValue(this.options.window, this)\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   * Error Handling:\n   * - If the rate-limited function throws and no `onError` handler is configured,\n   *   the error will be thrown from this method.\n   * - If an `onError` handler is configured, errors will be caught and passed to the handler,\n   *   and this method will return undefined.\n   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.\n   *\n   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError\n   * @throws The error from the rate-limited function if no onError handler is configured\n   *\n   * @example\n   * ```ts\n   * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });\n   *\n   * // First 5 calls will return a promise that resolves with the result\n   * const result = await rateLimiter.maybeExecute('arg1', 'arg2');\n   *\n   * // Additional calls within the window will return undefined\n   * const result2 = await rateLimiter.maybeExecute('arg1', 'arg2'); // undefined\n   * ```\n   */\n  maybeExecute = async (\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> => {\n    this.#setState({\n      maybeExecuteCount: this.store.state.maybeExecuteCount + 1,\n    })\n\n    this.#cleanupOldExecutions()\n\n    const relevantExecutionTimes = this.#getExecutionTimesInWindow()\n\n    if (relevantExecutionTimes.length < this.#getLimit()) {\n      await this.#execute(...args)\n      return this.store.state.lastResult\n    }\n\n    this.#setState({\n      rejectionCount: this.store.state.rejectionCount + 1,\n    })\n    this.options.onReject?.(args, this)\n    return undefined\n  }\n\n  #execute = async (\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> => {\n    if (!this.#getEnabled()) return\n\n    const now = Date.now()\n    const executionTimes = [...this.store.state.executionTimes, now]\n    this.#setState({\n      isExecuting: true,\n      executionTimes,\n    })\n\n    try {\n      const result = await this.fn(...args) // EXECUTE!\n      this.#setCleanupTimeout(now)\n      this.#setState({\n        successCount: this.store.state.successCount + 1,\n        lastResult: result,\n      })\n      this.options.onSuccess?.(result, args, this)\n    } catch (error) {\n      this.#setState({\n        errorCount: this.store.state.errorCount + 1,\n      })\n      this.options.onError?.(error, args, this)\n      if (this.options.throwOnError) {\n        throw error\n      }\n    } finally {\n      this.#setState({\n        isExecuting: false,\n        settleCount: this.store.state.settleCount + 1,\n      })\n      this.options.onSettled?.(args, this)\n    }\n\n    return this.store.state.lastResult\n  }\n\n  #getExecutionTimesInWindow = (): Array<number> => {\n    if (this.options.windowType === 'sliding') {\n      // For sliding window, return all executions within the current window\n      return this.store.state.executionTimes.filter(\n        (time) => time > Date.now() - this.#getWindow(),\n      )\n    } else {\n      // For fixed window, return all executions in the current window\n      // The window starts from the oldest execution time\n      if (this.store.state.executionTimes.length === 0) {\n        return []\n      }\n      const oldestExecution = Math.min(...this.store.state.executionTimes)\n      const windowStart = oldestExecution\n      const windowEnd = windowStart + this.#getWindow()\n      const now = Date.now()\n\n      // If the window has expired, return empty array\n      if (now > windowEnd) {\n        return []\n      }\n\n      // Otherwise, return all executions in the current window\n      return this.store.state.executionTimes.filter(\n        (time) => time >= windowStart && time <= windowEnd,\n      )\n    }\n  }\n\n  #setCleanupTimeout = (executionTime: number): void => {\n    if (\n      this.options.windowType === 'sliding' ||\n      this.#timeoutIds.size === 0 // new fixed window\n    ) {\n      const now = Date.now()\n      const timeUntilExpiration = executionTime - now + this.#getWindow() + 1\n      const timeoutId = setTimeout(() => {\n        this.#cleanupOldExecutions()\n        this.#clearTimeout(timeoutId)\n      }, timeUntilExpiration)\n      this.#timeoutIds.add(timeoutId)\n    }\n  }\n\n  #clearTimeout = (timeoutId: NodeJS.Timeout): void => {\n    clearTimeout(timeoutId)\n    this.#timeoutIds.delete(timeoutId)\n  }\n\n  #clearTimeouts = (): void => {\n    this.#timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId))\n    this.#timeoutIds.clear()\n  }\n\n  #cleanupOldExecutions = (): void => {\n    this.#setState({\n      executionTimes: this.#getExecutionTimesInWindow(),\n    })\n  }\n\n  /**\n   * Returns the number of remaining executions allowed in the current window\n   */\n  getRemainingInWindow = (): number => {\n    const relevantExecutionTimes = this.#getExecutionTimesInWindow()\n    return Math.max(0, this.#getLimit() - relevantExecutionTimes.length)\n  }\n\n  /**\n   * Returns the number of milliseconds until the next execution will be possible\n   * For fixed windows, this is the time until the current window resets\n   * For sliding windows, this is the time until the oldest execution expires\n   */\n  getMsUntilNextWindow = (): number => {\n    if (this.getRemainingInWindow() > 0) {\n      return 0\n    }\n    const oldestExecution = this.store.state.executionTimes[0] ?? Infinity\n    return oldestExecution + this.#getWindow() - Date.now()\n  }\n\n  /**\n   * Resets the rate limiter state\n   */\n  reset = (): void => {\n    this.#setState(getDefaultAsyncRateLimiterState())\n    this.#clearTimeouts()\n  }\n}\n\n/**\n * Creates an async rate-limited function that will execute the provided function up to a maximum number of times within a time window.\n *\n * Unlike the non-async rate limiter, this async version supports returning values from the rate-limited function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the rate-limited function.\n *\n * The rate limiter supports two types of windows:\n * - 'fixed': A strict window that resets after the window period. All executions within the window count\n *   towards the limit, and the window resets completely after the period.\n * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more\n *   consistent rate of execution over time.\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 * State Management:\n * - Uses TanStack Store for reactive state management\n * - Use `initialState` to provide initial state values when creating the rate limiter\n * - `initialState` can be a partial state object\n * - Use `onSuccess` callback to react to successful function execution and implement custom logic\n * - Use `onError` callback to react to function execution errors and implement custom error handling\n * - Use `onSettled` callback to react to function execution completion (success or error) and implement custom logic\n * - Use `onReject` callback to react to executions being rejected when rate limit is exceeded\n * - The state includes execution times, success/error counts, and current execution status\n * - State can be accessed via the underlying AsyncRateLimiter instance's `store.state` property\n * - When using framework adapters (React/Solid), state is accessed from the hook's state property\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 * Error Handling:\n * - If an `onError` handler is provided, it will be called with the error and rate limiter instance\n * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown\n * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed\n * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown\n * - The error state can be checked using the underlying AsyncRateLimiter instance\n * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler\n *\n * @example\n * ```ts\n * // Rate limit to 5 calls per minute with a sliding window\n * const rateLimited = asyncRateLimit(makeApiCall, {\n *   limit: 5,\n *   window: 60000,\n *   windowType: 'sliding',\n *   onError: (error) => {\n *     console.error('API call failed:', error);\n *   },\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 * // Returns the API response directly\n * const result = await 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 asyncRateLimit<TFn extends AnyAsyncFunction>(\n  fn: TFn,\n  initialOptions: AsyncRateLimiterOptions<TFn>,\n) {\n  const rateLimiter = new AsyncRateLimiter(fn, initialOptions)\n  return rateLimiter.maybeExecute\n}\n"],"names":["Store","emitChange","parseFunctionOrValue","createKey","pacerEventClient"],"mappings":"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"}
+{"version":3,"file":"async-rate-limiter.cjs","sources":["../../src/async-rate-limiter.ts"],"sourcesContent":["import { Store } from '@tanstack/store'\nimport { AsyncRetryer } from './async-retryer'\nimport { createKey, parseFunctionOrValue } from './utils'\nimport { emitChange, pacerEventClient } from './event-client'\nimport type { AsyncRetryerOptions } from './async-retryer'\nimport type { AnyAsyncFunction } from './types'\n\nexport interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {\n  /**\n   * Number of function executions that have resulted in errors\n   */\n  errorCount: number\n  /**\n   * Array of timestamps when executions occurred for rate limiting calculations\n   */\n  executionTimes: Array<number>\n  /**\n   * Whether the rate limiter has exceeded the limit\n   */\n  isExceeded: boolean\n  /**\n   * Whether the rate-limited function is currently executing asynchronously\n   */\n  isExecuting: boolean\n  /**\n   * The result from the most recent successful function execution\n   */\n  lastResult: ReturnType<TFn> | undefined\n  /**\n   * Number of function executions that have been rejected due to rate limiting\n   */\n  rejectionCount: number\n  /**\n   * Number of function executions that have completed (either successfully or with errors)\n   */\n  settleCount: number\n  /**\n   * Current execution status - 'disabled' when not active, 'executing' when executing, 'idle' when not executing, 'exceeded' when rate limit is exceeded\n   */\n  status: 'disabled' | 'executing' | 'exceeded' | 'idle'\n  /**\n   * Number of function executions that have completed successfully\n   */\n  successCount: number\n  /**\n   * Number of times maybeExecute has been called (for reduction calculations)\n   */\n  maybeExecuteCount: number\n}\n\nfunction getDefaultAsyncRateLimiterState<\n  TFn extends AnyAsyncFunction,\n>(): AsyncRateLimiterState<TFn> {\n  return {\n    errorCount: 0,\n    executionTimes: [],\n    isExceeded: false,\n    isExecuting: false,\n    lastResult: undefined,\n    maybeExecuteCount: 0,\n    rejectionCount: 0,\n    settleCount: 0,\n    status: 'idle',\n    successCount: 0,\n  }\n}\n\n/**\n * Options for configuring an async rate-limited function\n */\nexport interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {\n  /**\n   * Options for configuring the underlying async retryer\n   */\n  asyncRetryerOptions?: AsyncRetryerOptions<TFn>\n  /**\n   * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Can be a boolean or a function that returns a boolean.\n   * Defaults to true.\n   */\n  enabled?: boolean | ((rateLimiter: AsyncRateLimiter<TFn>) => boolean)\n  /**\n   * Initial state for the rate limiter\n   */\n  initialState?: Partial<AsyncRateLimiterState<TFn>>\n  /**\n   * Optional key to identify this async rate limiter instance.\n   * If provided, the async rate limiter will be identified by this key in the devtools and PacerProvider if applicable.\n   */\n  key?: string\n  /**\n   * Maximum number of executions allowed within the time window.\n   * Can be a number or a function that returns a number.\n   */\n  limit: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number)\n  /**\n   * Optional error handler for when the rate-limited function throws.\n   * If provided, the handler will be called with the error and rate limiter instance.\n   * This can be used alongside throwOnError - the handler will be called before any error is thrown.\n   */\n  onError?: (\n    error: Error,\n    args: Parameters<TFn>,\n    rateLimiter: AsyncRateLimiter<TFn>,\n  ) => void\n  /**\n   * Optional callback function that is called when an execution is rejected due to rate limiting\n   */\n  onReject?: (args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void\n  /**\n   * Optional function to call when the rate-limited function is executed\n   */\n  onSettled?: (\n    args: Parameters<TFn>,\n    rateLimiter: AsyncRateLimiter<TFn>,\n  ) => void\n  /**\n   * Optional function to call when the rate-limited function is executed\n   */\n  onSuccess?: (\n    result: ReturnType<TFn>,\n    args: Parameters<TFn>,\n    rateLimiter: AsyncRateLimiter<TFn>,\n  ) => void\n  /**\n   * Whether to throw errors when they occur.\n   * Defaults to true if no onError handler is provided, false if an onError handler is provided.\n   * Can be explicitly set to override these defaults.\n   */\n  throwOnError?: boolean\n  /**\n   * Time window in milliseconds within which the limit applies.\n   * Can be a number or a function that returns a number.\n   */\n  window: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number)\n  /**\n   * Type of window to use for rate limiting\n   * - 'fixed': Uses a fixed window that resets after the window period\n   * - 'sliding': Uses a sliding window that allows executions as old ones expire\n   * Defaults to 'fixed'\n   */\n  windowType?: 'fixed' | 'sliding'\n}\n\n/**\n * Utility function for sharing common `AsyncRateLimiterOptions` options between different `AsyncRateLimiter` instances.\n */\nexport function asyncRateLimiterOptions<\n  TFn extends AnyAsyncFunction = AnyAsyncFunction,\n  TOptions extends Partial<AsyncRateLimiterOptions<TFn>> = Partial<\n    AsyncRateLimiterOptions<TFn>\n  >,\n>(options: TOptions): TOptions {\n  return options\n}\n\nconst defaultOptions: Omit<\n  Required<AsyncRateLimiterOptions<any>>,\n  'initialState' | 'onError' | 'onReject' | 'onSettled' | 'onSuccess' | 'key'\n> = {\n  asyncRetryerOptions: {\n    maxAttempts: 1,\n  },\n  enabled: true,\n  limit: 1,\n  window: 0,\n  windowType: 'fixed',\n  throwOnError: true,\n}\n\n/**\n * A class that creates an async rate-limited function.\n *\n * Async vs Sync Versions:\n * The async version provides advanced features over the sync RateLimiter:\n * - Returns promises that can be awaited for rate-limited function results\n * - Built-in retry support via AsyncRetryer integration\n * - Abort support to cancel in-flight executions\n * - Comprehensive error handling with onError callbacks and throwOnError control\n * - Detailed execution tracking (success/error/settle counts, rejection counts)\n * - More sophisticated window management with automatic cleanup\n *\n * The sync RateLimiter is lighter weight and simpler when you don't need async features,\n * return values, or execution control.\n *\n * What is Rate Limiting?\n * Rate limiting 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 * Window Types:\n * - 'fixed': A strict window that resets after the window period. All executions within the window count\n *   towards the limit, and the window resets completely after the period.\n * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more\n *   consistent rate of execution over time.\n *\n * When to Use Rate Limiting:\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 * - 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 * State Management:\n * - Uses TanStack Store for reactive state management\n * - Use `initialState` to provide initial state values when creating the rate limiter\n * - `initialState` can be a partial state object\n * - Use `onSuccess` callback to react to successful function execution and implement custom logic\n * - Use `onError` callback to react to function execution errors and implement custom error handling\n * - Use `onSettled` callback to react to function execution completion (success or error) and implement custom logic\n * - Use `onReject` callback to react to executions being rejected when rate limit is exceeded\n * - The state includes execution times, success/error counts, and current execution status\n * - State can be accessed via `asyncRateLimiter.store.state` when using the class directly\n * - When using framework adapters (React/Solid), state is accessed from `asyncRateLimiter.state`\n *\n * Error Handling:\n * - If an `onError` handler is provided, it will be called with the error and rate limiter instance\n * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown\n * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed\n * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown\n * - The error state can be checked using the underlying AsyncRateLimiter instance\n * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler\n *\n * @example\n * ```ts\n * const rateLimiter = new AsyncRateLimiter(\n *   async (id: string) => await api.getData(id),\n *   {\n *     limit: 5,\n *     window: 1000,\n *     windowType: 'sliding',\n *     onError: (error) => {\n *       console.error('API call failed:', error);\n *     },\n *     onReject: (limiter) => {\n *       console.log(`Rate limit exceeded. Try again in ${limiter.getMsUntilNextWindow()}ms`);\n *     }\n *   }\n * );\n *\n * // Will execute immediately until limit reached, then block\n * // Returns the API response directly\n * const data = await rateLimiter.maybeExecute('123');\n * ```\n */\nexport class AsyncRateLimiter<TFn extends AnyAsyncFunction> {\n  readonly store: Store<Readonly<AsyncRateLimiterState<TFn>>> = new Store<\n    AsyncRateLimiterState<TFn>\n  >(getDefaultAsyncRateLimiterState<TFn>())\n  key: string\n  options: AsyncRateLimiterOptions<TFn>\n  asyncRetryers = new Map<number, AsyncRetryer<TFn>>()\n  #timeoutIds: Set<NodeJS.Timeout> = new Set()\n\n  constructor(\n    public fn: TFn,\n    initialOptions: AsyncRateLimiterOptions<TFn>,\n  ) {\n    this.key = createKey(initialOptions.key)\n    this.options = {\n      ...defaultOptions,\n      ...initialOptions,\n      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,\n    }\n    this.#setState(this.options.initialState ?? {})\n    for (const executionTime of this.#getExecutionTimesInWindow()) {\n      this.#setCleanupTimeout(executionTime)\n    }\n\n    pacerEventClient.on('d-AsyncRateLimiter', (event) => {\n      if (event.payload.key !== this.key) return\n      this.#setState(event.payload.store.state)\n      this.setOptions(event.payload.options)\n    })\n  }\n\n  /**\n   * Emits a change event for the async rate limiter instance. Mostly useful for devtools.\n   */\n  _emit = () => emitChange('AsyncRateLimiter', this)\n\n  /**\n   * Updates the async rate limiter options\n   */\n  setOptions = (newOptions: Partial<AsyncRateLimiterOptions<TFn>>): void => {\n    this.options = { ...this.options, ...newOptions }\n  }\n\n  #setState = (newState: Partial<AsyncRateLimiterState<TFn>>): void => {\n    this.store.setState((state) => {\n      const combinedState = {\n        ...state,\n        ...newState,\n      }\n      const isExceeded = combinedState.executionTimes.length >= this.#getLimit()\n      const status = !this.#getEnabled()\n        ? 'disabled'\n        : combinedState.isExecuting\n          ? 'executing'\n          : isExceeded\n            ? 'exceeded'\n            : 'idle'\n      return {\n        ...combinedState,\n        isExceeded,\n        status,\n      }\n    })\n    emitChange('AsyncRateLimiter', this)\n  }\n\n  /**\n   * Returns the current enabled state of the async rate limiter\n   */\n  #getEnabled = (): boolean => {\n    return !!parseFunctionOrValue(this.options.enabled, this)\n  }\n\n  /**\n   * Returns the current limit of executions allowed within the time window\n   */\n  #getLimit = (): number => {\n    return parseFunctionOrValue(this.options.limit, this)\n  }\n\n  /**\n   * Returns the current time window in milliseconds\n   */\n  #getWindow = (): number => {\n    return parseFunctionOrValue(this.options.window, this)\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   * Error Handling:\n   * - If the rate-limited function throws and no `onError` handler is configured,\n   *   the error will be thrown from this method.\n   * - If an `onError` handler is configured, errors will be caught and passed to the handler,\n   *   and this method will return undefined.\n   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.\n   *\n   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError\n   * @throws The error from the rate-limited function if no onError handler is configured\n   *\n   * @example\n   * ```ts\n   * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });\n   *\n   * // First 5 calls will return a promise that resolves with the result\n   * const result = await rateLimiter.maybeExecute('arg1', 'arg2');\n   *\n   * // Additional calls within the window will return undefined\n   * const result2 = await rateLimiter.maybeExecute('arg1', 'arg2'); // undefined\n   * ```\n   */\n  maybeExecute = async (\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> => {\n    this.#setState({\n      maybeExecuteCount: this.store.state.maybeExecuteCount + 1,\n    })\n\n    this.#cleanupOldExecutions()\n\n    const relevantExecutionTimes = this.#getExecutionTimesInWindow()\n\n    if (relevantExecutionTimes.length < this.#getLimit()) {\n      await this.#execute(...args)\n      return this.store.state.lastResult\n    }\n\n    this.#setState({\n      rejectionCount: this.store.state.rejectionCount + 1,\n    })\n    this.options.onReject?.(args, this)\n    return undefined\n  }\n\n  #execute = async (\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> => {\n    if (!this.#getEnabled()) return\n\n    const currentMaybeExecute = this.store.state.maybeExecuteCount\n    const now = Date.now()\n    const executionTimes = [...this.store.state.executionTimes, now]\n    this.#setState({\n      isExecuting: true,\n      executionTimes,\n    })\n\n    try {\n      // Create a new AsyncRetryer for this execution to avoid cancelling concurrent executions\n      const currentAsyncRetryer = new AsyncRetryer(this.fn, {\n        ...this.options.asyncRetryerOptions,\n        key: `${this.key}-retryer-${currentMaybeExecute}`,\n      })\n      this.asyncRetryers.set(currentMaybeExecute, currentAsyncRetryer)\n      const result = await currentAsyncRetryer.execute(...args) // EXECUTE!\n      this.#setCleanupTimeout(now)\n      this.#setState({\n        successCount: this.store.state.successCount + 1,\n        lastResult: result,\n      })\n      this.options.onSuccess?.(result as ReturnType<TFn>, args, this)\n    } catch (error) {\n      this.#setState({\n        errorCount: this.store.state.errorCount + 1,\n      })\n      this.options.onError?.(error as Error, args, this)\n      if (this.options.throwOnError) {\n        throw error\n      }\n    } finally {\n      this.asyncRetryers.delete(currentMaybeExecute) // dispose retryer\n      this.#setState({\n        isExecuting: false,\n        settleCount: this.store.state.settleCount + 1,\n      })\n      this.options.onSettled?.(args, this)\n    }\n\n    return this.store.state.lastResult\n  }\n\n  #getExecutionTimesInWindow = (): Array<number> => {\n    if (this.options.windowType === 'sliding') {\n      // For sliding window, return all executions within the current window\n      return this.store.state.executionTimes.filter(\n        (time) => time > Date.now() - this.#getWindow(),\n      )\n    } else {\n      // For fixed window, return all executions in the current window\n      // The window starts from the oldest execution time\n      if (this.store.state.executionTimes.length === 0) {\n        return []\n      }\n      const oldestExecution = Math.min(...this.store.state.executionTimes)\n      const windowStart = oldestExecution\n      const windowEnd = windowStart + this.#getWindow()\n      const now = Date.now()\n\n      // If the window has expired, return empty array\n      if (now > windowEnd) {\n        return []\n      }\n\n      // Otherwise, return all executions in the current window\n      return this.store.state.executionTimes.filter(\n        (time) => time >= windowStart && time <= windowEnd,\n      )\n    }\n  }\n\n  #setCleanupTimeout = (executionTime: number): void => {\n    if (\n      this.options.windowType === 'sliding' ||\n      this.#timeoutIds.size === 0 // new fixed window\n    ) {\n      const now = Date.now()\n      const timeUntilExpiration = executionTime - now + this.#getWindow() + 1\n      const timeoutId = setTimeout(() => {\n        this.#cleanupOldExecutions()\n        this.#clearTimeout(timeoutId)\n      }, timeUntilExpiration)\n      this.#timeoutIds.add(timeoutId)\n    }\n  }\n\n  #clearTimeout = (timeoutId: NodeJS.Timeout): void => {\n    clearTimeout(timeoutId)\n    this.#timeoutIds.delete(timeoutId)\n  }\n\n  #clearTimeouts = (): void => {\n    this.#timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId))\n    this.#timeoutIds.clear()\n  }\n\n  #cleanupOldExecutions = (): void => {\n    this.#setState({\n      executionTimes: this.#getExecutionTimesInWindow(),\n    })\n  }\n\n  /**\n   * Returns the number of remaining executions allowed in the current window\n   */\n  getRemainingInWindow = (): number => {\n    const relevantExecutionTimes = this.#getExecutionTimesInWindow()\n    return Math.max(0, this.#getLimit() - relevantExecutionTimes.length)\n  }\n\n  /**\n   * Returns the number of milliseconds until the next execution will be possible\n   * For fixed windows, this is the time until the current window resets\n   * For sliding windows, this is the time until the oldest execution expires\n   */\n  getMsUntilNextWindow = (): number => {\n    if (this.getRemainingInWindow() > 0) {\n      return 0\n    }\n    const oldestExecution = this.store.state.executionTimes[0] ?? Infinity\n    return oldestExecution + this.#getWindow() - Date.now()\n  }\n\n  /**\n   * Returns the AbortSignal for a specific execution.\n   * If no maybeExecuteCount is provided, returns the signal for the most recent execution.\n   * Returns null if no execution is found or not currently executing.\n   *\n   * @param maybeExecuteCount - Optional specific execution to get signal for\n   * @example\n   * ```typescript\n   * const rateLimiter = new AsyncRateLimiter(\n   *   async (userId: string) => {\n   *     const signal = rateLimiter.getAbortSignal()\n   *     if (signal) {\n   *       const response = await fetch(`/api/users/${userId}`, { signal })\n   *       return response.json()\n   *     }\n   *   },\n   *   { limit: 5, window: 1000 }\n   * )\n   * ```\n   */\n  getAbortSignal(maybeExecuteCount?: number): AbortSignal | null {\n    const count = maybeExecuteCount ?? this.store.state.maybeExecuteCount\n    const retryer = this.asyncRetryers.get(count)\n    return retryer?.getAbortSignal() ?? null\n  }\n\n  /**\n   * Aborts all ongoing executions with the internal abort controllers.\n   * Does NOT clear out the execution times or reset the rate limiter.\n   */\n  abort = (): void => {\n    this.asyncRetryers.forEach((retryer) => retryer.abort())\n    this.asyncRetryers.clear()\n    this.#setState({\n      isExecuting: false,\n    })\n  }\n\n  /**\n   * Resets the rate limiter state\n   */\n  reset = (): void => {\n    this.#setState(getDefaultAsyncRateLimiterState())\n    this.#clearTimeouts()\n    this.asyncRetryers.forEach((retryer) => retryer.reset())\n  }\n}\n\n/**\n * Creates an async rate-limited function that will execute the provided function up to a maximum number of times within a time window.\n *\n * Async vs Sync Versions:\n * The async version provides advanced features over the sync rate limit function:\n * - Returns promises that can be awaited for rate-limited function results\n * - Built-in retry support via AsyncRetryer integration\n * - Abort support to cancel in-flight executions\n * - Comprehensive error handling with onError callbacks and throwOnError control\n * - Detailed execution tracking (success/error/settle counts, rejection counts)\n * - More sophisticated window management with automatic cleanup\n *\n * The sync rate limit function is lighter weight and simpler when you don't need async features,\n * return values, or execution control.\n *\n * What is Rate Limiting?\n * Rate limiting 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 * Window Types:\n * - 'fixed': A strict window that resets after the window period. All executions within the window count\n *   towards the limit, and the window resets completely after the period.\n * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more\n *   consistent rate of execution over time.\n *\n * Configuration Options:\n * - `limit`: Maximum number of executions allowed within the window (required)\n * - `window`: Time window in milliseconds (required)\n * - `windowType`: 'fixed' or 'sliding' (default: 'fixed')\n * - `enabled`: Whether the rate limiter is enabled (default: true)\n * - `asyncRetryerOptions`: Configure retry behavior for executions\n *\n * When to Use Rate Limiting:\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 * - 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 * Error Handling:\n * - If an `onError` handler is provided, it will be called with the error and rate limiter instance\n * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown\n * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed\n * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown\n * - The error state can be checked using the underlying AsyncRateLimiter instance\n * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler\n *\n * State Management:\n * - Uses TanStack Store for reactive state management\n * - Use `initialState` to provide initial state values when creating the rate limiter\n * - `initialState` can be a partial state object\n * - Use `onSuccess` callback to react to successful function execution and implement custom logic\n * - Use `onError` callback to react to function execution errors and implement custom error handling\n * - Use `onSettled` callback to react to function execution completion (success or error) and implement custom logic\n * - Use `onReject` callback to react to executions being rejected when rate limit is exceeded\n * - The state includes execution times, success/error counts, and current execution status\n * - State can be accessed via the underlying AsyncRateLimiter instance's `store.state` property\n * - When using framework adapters (React/Solid), state is accessed from the hook's state property\n *\n * @example\n * ```ts\n * // Rate limit to 5 calls per minute with a sliding window\n * const rateLimited = asyncRateLimit(makeApiCall, {\n *   limit: 5,\n *   window: 60000,\n *   windowType: 'sliding',\n *   onError: (error) => {\n *     console.error('API call failed:', error);\n *   },\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 * // Returns the API response directly\n * const result = await 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 asyncRateLimit<TFn extends AnyAsyncFunction>(\n  fn: TFn,\n  initialOptions: AsyncRateLimiterOptions<TFn>,\n) {\n  const rateLimiter = new AsyncRateLimiter(fn, initialOptions)\n  return rateLimiter.maybeExecute\n}\n"],"names":["Store","emitChange","parseFunctionOrValue","AsyncRetryer","createKey","pacerEventClient"],"mappings":"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"}

package/dist/cjs/async-rate-limiter.d.cts

@@ -1,4 +1,5 @@
 import { Store } from '@tanstack/store';
+import { AsyncRetryer, AsyncRetryerOptions } from './async-retryer.cjs';
 import { AnyAsyncFunction } from './types.cjs';
 export interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {
     /**
@@ -46,6 +47,10 @@ export interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {
  * Options for configuring an async rate-limited function
  */
 export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
+    /**
+     * Options for configuring the underlying async retryer
+     */
+    asyncRetryerOptions?: AsyncRetryerOptions<TFn>;
     /**
      * 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.
@@ -71,7 +76,7 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
      * 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, args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
+    onError?: (error: Error, args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
     /**
      * Optional callback function that is called when an execution is rejected due to rate limiting
      */
@@ -103,29 +108,41 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
      */
     windowType?: 'fixed' | 'sliding';
 }
+/**
+ * Utility function for sharing common `AsyncRateLimiterOptions` options between different `AsyncRateLimiter` instances.
+ */
+export declare function asyncRateLimiterOptions<TFn extends AnyAsyncFunction = AnyAsyncFunction, TOptions extends Partial<AsyncRateLimiterOptions<TFn>> = Partial<AsyncRateLimiterOptions<TFn>>>(options: TOptions): TOptions;
 /**
  * A class that creates an async rate-limited function.
  *
- * Rate limiting is a simple approach that allows a function to execute up to a limit within a time window,
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync RateLimiter:
+ * - Returns promises that can be awaited for rate-limited function results
+ * - Built-in retry support via AsyncRetryer integration
+ * - Abort support to cancel in-flight executions
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts, rejection counts)
+ * - More sophisticated window management with automatic cleanup
+ *
+ * The sync RateLimiter is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Rate Limiting?
+ * Rate limiting allows a function to execute up to a limit within a time window,
  * 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:
+ * Window Types:
  * - '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)
- *
+ * When to Use Rate Limiting:
  * 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.
+ * - 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)
  *
  * State Management:
  * - Uses TanStack Store for reactive state management
@@ -175,7 +192,12 @@ export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     readonly store: Store<Readonly<AsyncRateLimiterState<TFn>>>;
     key: string;
     options: AsyncRateLimiterOptions<TFn>;
+    asyncRetryers: Map<number, AsyncRetryer<TFn>>;
     constructor(fn: TFn, initialOptions: AsyncRateLimiterOptions<TFn>);
+    /**
+     * Emits a change event for the async rate limiter instance. Mostly useful for devtools.
+     */
+    _emit: () => void;
     /**
      * Updates the async rate limiter options
      */
@@ -216,6 +238,32 @@ export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
      * For sliding windows, this is the time until the oldest execution expires
      */
     getMsUntilNextWindow: () => number;
+    /**
+     * Returns the AbortSignal for a specific execution.
+     * If no maybeExecuteCount is provided, returns the signal for the most recent execution.
+     * Returns null if no execution is found or not currently executing.
+     *
+     * @param maybeExecuteCount - Optional specific execution to get signal for
+     * @example
+     * ```typescript
+     * const rateLimiter = new AsyncRateLimiter(
+     *   async (userId: string) => {
+     *     const signal = rateLimiter.getAbortSignal()
+     *     if (signal) {
+     *       const response = await fetch(`/api/users/${userId}`, { signal })
+     *       return response.json()
+     *     }
+     *   },
+     *   { limit: 5, window: 1000 }
+     * )
+     * ```
+     */
+    getAbortSignal(maybeExecuteCount?: number): AbortSignal | null;
+    /**
+     * Aborts all ongoing executions with the internal abort controllers.
+     * Does NOT clear out the execution times or reset the rate limiter.
+     */
+    abort: () => void;
     /**
      * Resets the rate limiter state
      */
@@ -224,21 +272,51 @@ export declare 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.
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync rate limit function:
+ * - Returns promises that can be awaited for rate-limited function results
+ * - Built-in retry support via AsyncRetryer integration
+ * - Abort support to cancel in-flight executions
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts, rejection counts)
+ * - More sophisticated window management with automatic cleanup
  *
- * The rate limiter supports two types of windows:
+ * The sync rate limit function is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Rate Limiting?
+ * Rate limiting allows a function to execute up to a limit within a time window,
+ * 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.
+ *
+ * Window Types:
  * - '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:
+ * Configuration Options:
+ * - `limit`: Maximum number of executions allowed within the window (required)
+ * - `window`: Time window in milliseconds (required)
+ * - `windowType`: 'fixed' or 'sliding' (default: 'fixed')
+ * - `enabled`: Whether the rate limiter is enabled (default: true)
+ * - `asyncRetryerOptions`: Configure retry behavior for executions
+ *
+ * When to Use Rate Limiting:
+ * 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.
  * - 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
  * - A debouncer collapses multiple calls into one, which is better for handling bursts of events
  *
+ * 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
+ *
  * State Management:
  * - Uses TanStack Store for reactive state management
  * - Use `initialState` to provide initial state values when creating the rate limiter
@@ -251,17 +329,6 @@ export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  * - State can be accessed via the underlying AsyncRateLimiter instance's `store.state` property
  * - When using framework adapters (React/Solid), state is accessed from the hook's state property
  *
- * 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