@tanstack/pacer 0.16.3 → 0.17.0

package/dist/async-throttler.d.cts

@@ -0,0 +1,320 @@
+import { AnyAsyncFunction } from "./types.cjs";
+import { AsyncRetryer, AsyncRetryerOptions } from "./async-retryer.cjs";
+import { Store } from "@tanstack/store";
+
+//#region src/async-throttler.d.ts
+interface AsyncThrottlerState<TFn extends AnyAsyncFunction> {
+  /**
+   * Number of function executions that have resulted in errors
+   */
+  errorCount: number;
+  /**
+   * Whether the throttled function is currently executing asynchronously
+   */
+  isExecuting: boolean;
+  /**
+   * Whether the throttler is waiting for the timeout to trigger execution
+   */
+  isPending: boolean;
+  /**
+   * The arguments from the most recent call to maybeExecute
+   */
+  lastArgs: Parameters<TFn> | undefined;
+  /**
+   * Timestamp of the last function execution in milliseconds
+   */
+  lastExecutionTime: number;
+  /**
+   * The result from the most recent successful function execution
+   */
+  lastResult: ReturnType<TFn> | undefined;
+  /**
+   * Number of times maybeExecute has been called (for reduction calculations)
+   */
+  maybeExecuteCount: number;
+  /**
+   * Timestamp when the next execution can occur in milliseconds
+   */
+  nextExecutionTime: number | undefined;
+  /**
+   * Number of function executions that have completed (either successfully or with errors)
+   */
+  settleCount: number;
+  /**
+   * Current execution status - 'idle' when not active, 'pending' when waiting, 'executing' when running, 'settled' when completed
+   */
+  status: 'disabled' | 'idle' | 'pending' | 'executing' | 'settled';
+  /**
+   * Number of function executions that have completed successfully
+   */
+  successCount: number;
+}
+/**
+ * Options for configuring an async throttled function
+ */
+interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
+  /**
+   * Options for configuring the underlying async retryer
+   */
+  asyncRetryerOptions?: AsyncRetryerOptions<TFn>;
+  /**
+   * 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 | ((throttler: AsyncThrottler<TFn>) => boolean);
+  /**
+   * Initial state for the async throttler
+   */
+  initialState?: Partial<AsyncThrottlerState<TFn>>;
+  /**
+   * Optional key to identify this async throttler instance.
+   * If provided, the async throttler will be identified by this key in the devtools and PacerProvider if applicable.
+   */
+  key?: string;
+  /**
+   * Whether to execute the function immediately when called
+   * Defaults to true
+   */
+  leading?: boolean;
+  /**
+   * Optional error handler for when the throttled function throws.
+   * If provided, the handler will be called with the error and throttler instance.
+   * This can be used alongside throwOnError - the handler will be called before any error is thrown.
+   */
+  onError?: (error: Error, args: Parameters<TFn>, asyncThrottler: AsyncThrottler<TFn>) => void;
+  /**
+   * Optional function to call when the throttled function is executed
+   */
+  onSettled?: (args: Parameters<TFn>, asyncThrottler: AsyncThrottler<TFn>) => void;
+  /**
+   * Optional function to call when the throttled function is executed
+   */
+  onSuccess?: (result: ReturnType<TFn>, args: Parameters<TFn>, asyncThrottler: AsyncThrottler<TFn>) => void;
+  /**
+   * Whether to throw errors when they occur.
+   * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+   * Can be explicitly set to override these defaults.
+   */
+  throwOnError?: boolean;
+  /**
+   * Whether to execute the function on the trailing edge of the wait period
+   * Defaults to true
+   */
+  trailing?: boolean;
+  /**
+   * Time window in milliseconds during which the function can only be executed once.
+   * Can be a number or a function that returns a number.
+   * Defaults to 0ms
+   */
+  wait: number | ((throttler: AsyncThrottler<TFn>) => number);
+}
+/**
+ * Utility function for sharing common `AsyncThrottlerOptions` options between different `AsyncThrottler` instances.
+ */
+declare function asyncThrottlerOptions<TFn extends AnyAsyncFunction = AnyAsyncFunction, TOptions extends Partial<AsyncThrottlerOptions<TFn>> = Partial<AsyncThrottlerOptions<TFn>>>(options: TOptions): TOptions;
+/**
+ * A class that creates an async throttled function.
+ *
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync Throttler:
+ * - Returns promises that can be awaited for throttled function results
+ * - Built-in retry support via AsyncRetryer integration
+ * - Abort support to cancel in-flight executions
+ * - Cancel support to prevent pending executions from starting
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ * - Waits for ongoing executions to complete before scheduling the next one
+ *
+ * The sync Throttler is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Throttling?
+ * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.
+ * 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.
+ *
+ * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to
+ * ensure a maximum execution frequency.
+ *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the async throttler
+ * - Use `onSuccess` callback to react to successful function execution and implement custom logic
+ * - Use `onError` callback to react to function execution errors and implement custom error handling
+ * - Use `onSettled` callback to react to function execution completion (success or error) and implement custom logic
+ * - The state includes error count, execution status, last execution time, and success/settle counts
+ * - State can be accessed via `asyncThrottler.store.state` when using the class directly
+ * - When using framework adapters (React/Solid), state is accessed from `asyncThrottler.state`
+ *
+ * @example
+ * ```ts
+ * const throttler = new AsyncThrottler(async (value: string) => {
+ *   const result = await saveToAPI(value);
+ *   return result; // Return value is preserved
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   }
+ * });
+ *
+ * // Will only execute once per second no matter how often called
+ * // Returns the API response directly
+ * const result = await throttler.maybeExecute(inputElement.value);
+ * ```
+ */
+declare class AsyncThrottler<TFn extends AnyAsyncFunction> {
+  #private;
+  fn: TFn;
+  readonly store: Store<Readonly<AsyncThrottlerState<TFn>>>;
+  key: string | undefined;
+  options: AsyncThrottlerOptions<TFn>;
+  asyncRetryers: Map<number, AsyncRetryer<TFn>>;
+  constructor(fn: TFn, initialOptions: AsyncThrottlerOptions<TFn>);
+  /**
+   * Updates the async throttler options
+   */
+  setOptions: (newOptions: Partial<AsyncThrottlerOptions<TFn>>) => void;
+  /**
+   * Attempts to execute the throttled function. The execution behavior depends on the throttler options:
+   *
+   * - If enough time has passed since the last execution (>= wait period):
+   *   - With leading=true: Executes immediately
+   *   - With leading=false: Waits for the next trailing execution
+   *
+   * - If within the wait period:
+   *   - With trailing=true: Schedules execution for end of wait period
+   *   - With trailing=false: Drops the execution
+   *
+   * @example
+   * ```ts
+   * const throttled = new AsyncThrottler(fn, { wait: 1000 });
+   *
+   * // First call executes immediately
+   * await throttled.maybeExecute('a', 'b');
+   *
+   * // Call during wait period - gets throttled
+   * await throttled.maybeExecute('c', 'd');
+   * ```
+   */
+  maybeExecute: (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
+  /**
+   * Processes the current pending execution immediately
+   */
+  flush: () => Promise<ReturnType<TFn> | undefined>;
+  /**
+   * 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 throttler = new AsyncThrottler(
+   *   async (data: string) => {
+   *     const signal = throttler.getAbortSignal()
+   *     if (signal) {
+   *       const response = await fetch('/api/save', {
+   *         method: 'POST',
+   *         body: data,
+   *         signal
+   *       })
+   *       return response.json()
+   *     }
+   *   },
+   *   { wait: 1000 }
+   * )
+   * ```
+   */
+  getAbortSignal(maybeExecuteCount?: number): AbortSignal | null;
+  /**
+   * Aborts all ongoing executions with the internal abort controllers.
+   * Does NOT cancel any pending execution that have not started yet.
+   */
+  abort: () => void;
+  /**
+   * Cancels any pending execution that have not started yet.
+   * Does NOT abort any execution already in progress.
+   */
+  cancel: () => void;
+  /**
+   * Resets the debouncer state to its default values
+   */
+  reset: () => void;
+}
+/**
+ * Creates an async throttled function that limits how often the function can execute.
+ * 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.
+ *
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync throttle function:
+ * - Returns promises that can be awaited for throttled function results
+ * - Built-in retry support via AsyncRetryer integration
+ * - Abort support to cancel in-flight executions
+ * - Cancel support to prevent pending executions from starting
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ * - Waits for ongoing executions to complete before scheduling the next one
+ *
+ * The sync throttle function is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Throttling?
+ * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.
+ * 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.
+ *
+ * Configuration Options:
+ * - `wait`: Time window in milliseconds during which the function can only execute once (required)
+ * - `leading`: Execute immediately when called (default: true)
+ * - `trailing`: Execute on the trailing edge of the wait period (default: true)
+ * - `enabled`: Whether the throttler is enabled (default: true)
+ * - `asyncRetryerOptions`: Configure retry behavior for executions
+ *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the async throttler
+ * - Use `onSuccess` callback to react to successful function execution and implement custom logic
+ * - Use `onError` callback to react to function execution errors and implement custom error handling
+ * - Use `onSettled` callback to react to function execution completion (success or error) and implement custom logic
+ * - The state includes error count, execution status, last execution time, and success/settle counts
+ * - State can be accessed via the underlying AsyncThrottler instance's `store.state` property
+ * - When using framework adapters (React/Solid), state is accessed from the hook's state property
+ *
+ * @example
+ * ```ts
+ * const throttled = asyncThrottle(async (value: string) => {
+ *   const result = await saveToAPI(value);
+ *   return result; // Return value is preserved
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   }
+ * });
+ *
+ * // This will execute at most once per second
+ * // Returns the API response directly
+ * const result = await throttled(inputElement.value);
+ * ```
+ */
+declare function asyncThrottle<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions: AsyncThrottlerOptions<TFn>): (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
+//#endregion
+export { AsyncThrottler, AsyncThrottlerOptions, AsyncThrottlerState, asyncThrottle, asyncThrottlerOptions };
+//# sourceMappingURL=async-throttler.d.cts.map

package/dist/async-throttler.d.ts

@@ -0,0 +1,320 @@
+import { AnyAsyncFunction } from "./types.js";
+import { AsyncRetryer, AsyncRetryerOptions } from "./async-retryer.js";
+import { Store } from "@tanstack/store";
+
+//#region src/async-throttler.d.ts
+interface AsyncThrottlerState<TFn extends AnyAsyncFunction> {
+  /**
+   * Number of function executions that have resulted in errors
+   */
+  errorCount: number;
+  /**
+   * Whether the throttled function is currently executing asynchronously
+   */
+  isExecuting: boolean;
+  /**
+   * Whether the throttler is waiting for the timeout to trigger execution
+   */
+  isPending: boolean;
+  /**
+   * The arguments from the most recent call to maybeExecute
+   */
+  lastArgs: Parameters<TFn> | undefined;
+  /**
+   * Timestamp of the last function execution in milliseconds
+   */
+  lastExecutionTime: number;
+  /**
+   * The result from the most recent successful function execution
+   */
+  lastResult: ReturnType<TFn> | undefined;
+  /**
+   * Number of times maybeExecute has been called (for reduction calculations)
+   */
+  maybeExecuteCount: number;
+  /**
+   * Timestamp when the next execution can occur in milliseconds
+   */
+  nextExecutionTime: number | undefined;
+  /**
+   * Number of function executions that have completed (either successfully or with errors)
+   */
+  settleCount: number;
+  /**
+   * Current execution status - 'idle' when not active, 'pending' when waiting, 'executing' when running, 'settled' when completed
+   */
+  status: 'disabled' | 'idle' | 'pending' | 'executing' | 'settled';
+  /**
+   * Number of function executions that have completed successfully
+   */
+  successCount: number;
+}
+/**
+ * Options for configuring an async throttled function
+ */
+interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
+  /**
+   * Options for configuring the underlying async retryer
+   */
+  asyncRetryerOptions?: AsyncRetryerOptions<TFn>;
+  /**
+   * 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 | ((throttler: AsyncThrottler<TFn>) => boolean);
+  /**
+   * Initial state for the async throttler
+   */
+  initialState?: Partial<AsyncThrottlerState<TFn>>;
+  /**
+   * Optional key to identify this async throttler instance.
+   * If provided, the async throttler will be identified by this key in the devtools and PacerProvider if applicable.
+   */
+  key?: string;
+  /**
+   * Whether to execute the function immediately when called
+   * Defaults to true
+   */
+  leading?: boolean;
+  /**
+   * Optional error handler for when the throttled function throws.
+   * If provided, the handler will be called with the error and throttler instance.
+   * This can be used alongside throwOnError - the handler will be called before any error is thrown.
+   */
+  onError?: (error: Error, args: Parameters<TFn>, asyncThrottler: AsyncThrottler<TFn>) => void;
+  /**
+   * Optional function to call when the throttled function is executed
+   */
+  onSettled?: (args: Parameters<TFn>, asyncThrottler: AsyncThrottler<TFn>) => void;
+  /**
+   * Optional function to call when the throttled function is executed
+   */
+  onSuccess?: (result: ReturnType<TFn>, args: Parameters<TFn>, asyncThrottler: AsyncThrottler<TFn>) => void;
+  /**
+   * Whether to throw errors when they occur.
+   * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+   * Can be explicitly set to override these defaults.
+   */
+  throwOnError?: boolean;
+  /**
+   * Whether to execute the function on the trailing edge of the wait period
+   * Defaults to true
+   */
+  trailing?: boolean;
+  /**
+   * Time window in milliseconds during which the function can only be executed once.
+   * Can be a number or a function that returns a number.
+   * Defaults to 0ms
+   */
+  wait: number | ((throttler: AsyncThrottler<TFn>) => number);
+}
+/**
+ * Utility function for sharing common `AsyncThrottlerOptions` options between different `AsyncThrottler` instances.
+ */
+declare function asyncThrottlerOptions<TFn extends AnyAsyncFunction = AnyAsyncFunction, TOptions extends Partial<AsyncThrottlerOptions<TFn>> = Partial<AsyncThrottlerOptions<TFn>>>(options: TOptions): TOptions;
+/**
+ * A class that creates an async throttled function.
+ *
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync Throttler:
+ * - Returns promises that can be awaited for throttled function results
+ * - Built-in retry support via AsyncRetryer integration
+ * - Abort support to cancel in-flight executions
+ * - Cancel support to prevent pending executions from starting
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ * - Waits for ongoing executions to complete before scheduling the next one
+ *
+ * The sync Throttler is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Throttling?
+ * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.
+ * 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.
+ *
+ * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to
+ * ensure a maximum execution frequency.
+ *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the async throttler
+ * - Use `onSuccess` callback to react to successful function execution and implement custom logic
+ * - Use `onError` callback to react to function execution errors and implement custom error handling
+ * - Use `onSettled` callback to react to function execution completion (success or error) and implement custom logic
+ * - The state includes error count, execution status, last execution time, and success/settle counts
+ * - State can be accessed via `asyncThrottler.store.state` when using the class directly
+ * - When using framework adapters (React/Solid), state is accessed from `asyncThrottler.state`
+ *
+ * @example
+ * ```ts
+ * const throttler = new AsyncThrottler(async (value: string) => {
+ *   const result = await saveToAPI(value);
+ *   return result; // Return value is preserved
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   }
+ * });
+ *
+ * // Will only execute once per second no matter how often called
+ * // Returns the API response directly
+ * const result = await throttler.maybeExecute(inputElement.value);
+ * ```
+ */
+declare class AsyncThrottler<TFn extends AnyAsyncFunction> {
+  #private;
+  fn: TFn;
+  readonly store: Store<Readonly<AsyncThrottlerState<TFn>>>;
+  key: string | undefined;
+  options: AsyncThrottlerOptions<TFn>;
+  asyncRetryers: Map<number, AsyncRetryer<TFn>>;
+  constructor(fn: TFn, initialOptions: AsyncThrottlerOptions<TFn>);
+  /**
+   * Updates the async throttler options
+   */
+  setOptions: (newOptions: Partial<AsyncThrottlerOptions<TFn>>) => void;
+  /**
+   * Attempts to execute the throttled function. The execution behavior depends on the throttler options:
+   *
+   * - If enough time has passed since the last execution (>= wait period):
+   *   - With leading=true: Executes immediately
+   *   - With leading=false: Waits for the next trailing execution
+   *
+   * - If within the wait period:
+   *   - With trailing=true: Schedules execution for end of wait period
+   *   - With trailing=false: Drops the execution
+   *
+   * @example
+   * ```ts
+   * const throttled = new AsyncThrottler(fn, { wait: 1000 });
+   *
+   * // First call executes immediately
+   * await throttled.maybeExecute('a', 'b');
+   *
+   * // Call during wait period - gets throttled
+   * await throttled.maybeExecute('c', 'd');
+   * ```
+   */
+  maybeExecute: (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
+  /**
+   * Processes the current pending execution immediately
+   */
+  flush: () => Promise<ReturnType<TFn> | undefined>;
+  /**
+   * 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 throttler = new AsyncThrottler(
+   *   async (data: string) => {
+   *     const signal = throttler.getAbortSignal()
+   *     if (signal) {
+   *       const response = await fetch('/api/save', {
+   *         method: 'POST',
+   *         body: data,
+   *         signal
+   *       })
+   *       return response.json()
+   *     }
+   *   },
+   *   { wait: 1000 }
+   * )
+   * ```
+   */
+  getAbortSignal(maybeExecuteCount?: number): AbortSignal | null;
+  /**
+   * Aborts all ongoing executions with the internal abort controllers.
+   * Does NOT cancel any pending execution that have not started yet.
+   */
+  abort: () => void;
+  /**
+   * Cancels any pending execution that have not started yet.
+   * Does NOT abort any execution already in progress.
+   */
+  cancel: () => void;
+  /**
+   * Resets the debouncer state to its default values
+   */
+  reset: () => void;
+}
+/**
+ * Creates an async throttled function that limits how often the function can execute.
+ * 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.
+ *
+ * Async vs Sync Versions:
+ * The async version provides advanced features over the sync throttle function:
+ * - Returns promises that can be awaited for throttled function results
+ * - Built-in retry support via AsyncRetryer integration
+ * - Abort support to cancel in-flight executions
+ * - Cancel support to prevent pending executions from starting
+ * - Comprehensive error handling with onError callbacks and throwOnError control
+ * - Detailed execution tracking (success/error/settle counts)
+ * - Waits for ongoing executions to complete before scheduling the next one
+ *
+ * The sync throttle function is lighter weight and simpler when you don't need async features,
+ * return values, or execution control.
+ *
+ * What is Throttling?
+ * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.
+ * 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.
+ *
+ * Configuration Options:
+ * - `wait`: Time window in milliseconds during which the function can only execute once (required)
+ * - `leading`: Execute immediately when called (default: true)
+ * - `trailing`: Execute on the trailing edge of the wait period (default: true)
+ * - `enabled`: Whether the throttler is enabled (default: true)
+ * - `asyncRetryerOptions`: Configure retry behavior for executions
+ *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the async throttler
+ * - Use `onSuccess` callback to react to successful function execution and implement custom logic
+ * - Use `onError` callback to react to function execution errors and implement custom error handling
+ * - Use `onSettled` callback to react to function execution completion (success or error) and implement custom logic
+ * - The state includes error count, execution status, last execution time, and success/settle counts
+ * - State can be accessed via the underlying AsyncThrottler instance's `store.state` property
+ * - When using framework adapters (React/Solid), state is accessed from the hook's state property
+ *
+ * @example
+ * ```ts
+ * const throttled = asyncThrottle(async (value: string) => {
+ *   const result = await saveToAPI(value);
+ *   return result; // Return value is preserved
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   }
+ * });
+ *
+ * // This will execute at most once per second
+ * // Returns the API response directly
+ * const result = await throttled(inputElement.value);
+ * ```
+ */
+declare function asyncThrottle<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions: AsyncThrottlerOptions<TFn>): (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
+//#endregion
+export { AsyncThrottler, AsyncThrottlerOptions, AsyncThrottlerState, asyncThrottle, asyncThrottlerOptions };
+//# sourceMappingURL=async-throttler.d.ts.map