@tanstack/pacer 0.16.3 → 0.17.0

package/dist/{esm/async-rate-limiter.d.ts → async-rate-limiter.d.ts}

@@ -1,117 +1,119 @@
-import { Store } from '@tanstack/store';
-import { AsyncRetryer, AsyncRetryerOptions } from './async-retryer.js';
-import { AnyAsyncFunction } from './types.js';
-export interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {
-    /**
-     * Number of function executions that have resulted in errors
-     */
-    errorCount: number;
-    /**
-     * Array of timestamps when executions occurred for rate limiting calculations
-     */
-    executionTimes: Array<number>;
-    /**
-     * Whether the rate limiter has exceeded the limit
-     */
-    isExceeded: boolean;
-    /**
-     * Whether the rate-limited function is currently executing asynchronously
-     */
-    isExecuting: boolean;
-    /**
-     * The result from the most recent successful function execution
-     */
-    lastResult: ReturnType<TFn> | undefined;
-    /**
-     * Number of function executions that have been rejected due to rate limiting
-     */
-    rejectionCount: number;
-    /**
-     * Number of function executions that have completed (either successfully or with errors)
-     */
-    settleCount: number;
-    /**
-     * Current execution status - 'disabled' when not active, 'executing' when executing, 'idle' when not executing, 'exceeded' when rate limit is exceeded
-     */
-    status: 'disabled' | 'executing' | 'exceeded' | 'idle';
-    /**
-     * Number of function executions that have completed successfully
-     */
-    successCount: number;
-    /**
-     * Number of times maybeExecute has been called (for reduction calculations)
-     */
-    maybeExecuteCount: number;
+import { AnyAsyncFunction } from "./types.js";
+import { AsyncRetryer, AsyncRetryerOptions } from "./async-retryer.js";
+import { Store } from "@tanstack/store";
+
+//#region src/async-rate-limiter.d.ts
+interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {
+  /**
+   * Number of function executions that have resulted in errors
+   */
+  errorCount: number;
+  /**
+   * Array of timestamps when executions occurred for rate limiting calculations
+   */
+  executionTimes: Array<number>;
+  /**
+   * Whether the rate limiter has exceeded the limit
+   */
+  isExceeded: boolean;
+  /**
+   * Whether the rate-limited function is currently executing asynchronously
+   */
+  isExecuting: boolean;
+  /**
+   * The result from the most recent successful function execution
+   */
+  lastResult: ReturnType<TFn> | undefined;
+  /**
+   * Number of function executions that have been rejected due to rate limiting
+   */
+  rejectionCount: number;
+  /**
+   * Number of function executions that have completed (either successfully or with errors)
+   */
+  settleCount: number;
+  /**
+   * Current execution status - 'disabled' when not active, 'executing' when executing, 'idle' when not executing, 'exceeded' when rate limit is exceeded
+   */
+  status: 'disabled' | 'executing' | 'exceeded' | 'idle';
+  /**
+   * Number of function executions that have completed successfully
+   */
+  successCount: number;
+  /**
+   * Number of times maybeExecute has been called (for reduction calculations)
+   */
+  maybeExecuteCount: number;
 }
 /**
  * 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.
-     * Defaults to true.
-     */
-    enabled?: boolean | ((rateLimiter: AsyncRateLimiter<TFn>) => boolean);
-    /**
-     * Initial state for the rate limiter
-     */
-    initialState?: Partial<AsyncRateLimiterState<TFn>>;
-    /**
-     * Optional key to identify this async rate limiter instance.
-     * If provided, the async rate limiter will be identified by this key in the devtools and PacerProvider if applicable.
-     */
-    key?: string;
-    /**
-     * Maximum number of executions allowed within the time window.
-     * Can be a number or a function that returns a number.
-     */
-    limit: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number);
-    /**
-     * Optional error handler for when the rate-limited function throws.
-     * If provided, the handler will be called with the error and rate limiter instance.
-     * This can be used alongside throwOnError - the handler will be called before any error is thrown.
-     */
-    onError?: (error: Error, args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
-    /**
-     * Optional callback function that is called when an execution is rejected due to rate limiting
-     */
-    onReject?: (args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
-    /**
-     * Optional function to call when the rate-limited function is executed
-     */
-    onSettled?: (args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
-    /**
-     * Optional function to call when the rate-limited function is executed
-     */
-    onSuccess?: (result: ReturnType<TFn>, args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
-    /**
-     * Whether to throw errors when they occur.
-     * Defaults to true if no onError handler is provided, false if an onError handler is provided.
-     * Can be explicitly set to override these defaults.
-     */
-    throwOnError?: boolean;
-    /**
-     * Time window in milliseconds within which the limit applies.
-     * Can be a number or a function that returns a number.
-     */
-    window: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number);
-    /**
-     * Type of window to use for rate limiting
-     * - 'fixed': Uses a fixed window that resets after the window period
-     * - 'sliding': Uses a sliding window that allows executions as old ones expire
-     * Defaults to 'fixed'
-     */
-    windowType?: 'fixed' | 'sliding';
+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.
+   * Defaults to true.
+   */
+  enabled?: boolean | ((rateLimiter: AsyncRateLimiter<TFn>) => boolean);
+  /**
+   * Initial state for the rate limiter
+   */
+  initialState?: Partial<AsyncRateLimiterState<TFn>>;
+  /**
+   * Optional key to identify this async rate limiter instance.
+   * If provided, the async rate limiter will be identified by this key in the devtools and PacerProvider if applicable.
+   */
+  key?: string;
+  /**
+   * Maximum number of executions allowed within the time window.
+   * Can be a number or a function that returns a number.
+   */
+  limit: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number);
+  /**
+   * Optional error handler for when the rate-limited function throws.
+   * If provided, the handler will be called with the error and rate limiter instance.
+   * This can be used alongside throwOnError - the handler will be called before any error is thrown.
+   */
+  onError?: (error: Error, args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
+  /**
+   * Optional callback function that is called when an execution is rejected due to rate limiting
+   */
+  onReject?: (args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
+  /**
+   * Optional function to call when the rate-limited function is executed
+   */
+  onSettled?: (args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
+  /**
+   * Optional function to call when the rate-limited function is executed
+   */
+  onSuccess?: (result: ReturnType<TFn>, args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
+  /**
+   * Whether to throw errors when they occur.
+   * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+   * Can be explicitly set to override these defaults.
+   */
+  throwOnError?: boolean;
+  /**
+   * Time window in milliseconds within which the limit applies.
+   * Can be a number or a function that returns a number.
+   */
+  window: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number);
+  /**
+   * Type of window to use for rate limiting
+   * - 'fixed': Uses a fixed window that resets after the window period
+   * - 'sliding': Uses a sliding window that allows executions as old ones expire
+   * Defaults to 'fixed'
+   */
+  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;
+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.
  *
@@ -186,84 +188,84 @@ export declare function asyncRateLimiterOptions<TFn extends AnyAsyncFunction = A
  * const data = await rateLimiter.maybeExecute('123');
  * ```
  */
-export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
-    #private;
-    fn: TFn;
-    readonly store: Store<Readonly<AsyncRateLimiterState<TFn>>>;
-    key: string | undefined;
-    options: AsyncRateLimiterOptions<TFn>;
-    asyncRetryers: Map<number, AsyncRetryer<TFn>>;
-    constructor(fn: TFn, initialOptions: AsyncRateLimiterOptions<TFn>);
-    /**
-     * Updates the async rate limiter options
-     */
-    setOptions: (newOptions: Partial<AsyncRateLimiterOptions<TFn>>) => void;
-    /**
-     * 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.
-     *
-     * Error Handling:
-     * - If the rate-limited function throws and no `onError` handler is configured,
-     *   the error will be thrown from this method.
-     * - If an `onError` handler is configured, errors will be caught and passed to the handler,
-     *   and this method will return undefined.
-     * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
-     *
-     * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
-     * @throws The error from the rate-limited function if no onError handler is configured
-     *
-     * @example
-     * ```ts
-     * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
-     *
-     * // First 5 calls will return a promise that resolves with the result
-     * const result = await rateLimiter.maybeExecute('arg1', 'arg2');
-     *
-     * // Additional calls within the window will return undefined
-     * const result2 = await rateLimiter.maybeExecute('arg1', 'arg2'); // undefined
-     * ```
-     */
-    maybeExecute: (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
-    /**
-     * Returns the number of remaining executions allowed in the current window
-     */
-    getRemainingInWindow: () => number;
-    /**
-     * Returns the number of milliseconds until the next execution will be possible
-     * 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;
-    /**
-     * 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
-     */
-    reset: () => void;
+declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
+  #private;
+  fn: TFn;
+  readonly store: Store<Readonly<AsyncRateLimiterState<TFn>>>;
+  key: string | undefined;
+  options: AsyncRateLimiterOptions<TFn>;
+  asyncRetryers: Map<number, AsyncRetryer<TFn>>;
+  constructor(fn: TFn, initialOptions: AsyncRateLimiterOptions<TFn>);
+  /**
+   * Updates the async rate limiter options
+   */
+  setOptions: (newOptions: Partial<AsyncRateLimiterOptions<TFn>>) => void;
+  /**
+   * 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.
+   *
+   * Error Handling:
+   * - If the rate-limited function throws and no `onError` handler is configured,
+   *   the error will be thrown from this method.
+   * - If an `onError` handler is configured, errors will be caught and passed to the handler,
+   *   and this method will return undefined.
+   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
+   *
+   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
+   * @throws The error from the rate-limited function if no onError handler is configured
+   *
+   * @example
+   * ```ts
+   * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
+   *
+   * // First 5 calls will return a promise that resolves with the result
+   * const result = await rateLimiter.maybeExecute('arg1', 'arg2');
+   *
+   * // Additional calls within the window will return undefined
+   * const result2 = await rateLimiter.maybeExecute('arg1', 'arg2'); // undefined
+   * ```
+   */
+  maybeExecute: (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
+  /**
+   * Returns the number of remaining executions allowed in the current window
+   */
+  getRemainingInWindow: () => number;
+  /**
+   * Returns the number of milliseconds until the next execution will be possible
+   * 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;
+  /**
+   * 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
+   */
+  reset: () => void;
 }
 /**
  * Creates an async rate-limited function that will execute the provided function up to a maximum number of times within a time window.
@@ -349,4 +351,7 @@ export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
  * ```
  */
-export declare function asyncRateLimit<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions: AsyncRateLimiterOptions<TFn>): (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
+declare function asyncRateLimit<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions: AsyncRateLimiterOptions<TFn>): (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
+//#endregion
+export { AsyncRateLimiter, AsyncRateLimiterOptions, AsyncRateLimiterState, asyncRateLimit, asyncRateLimiterOptions };
+//# sourceMappingURL=async-rate-limiter.d.ts.map