@tanstack/pacer 0.21.1 → 0.23.0

package/dist/async-rate-limiter.d.ts

@@ -1,9 +1,8 @@
 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> {
+export interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {
   /**
    * Number of function executions that have resulted in errors
    */
@@ -23,7 +22,7 @@ interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {
   /**
    * The result from the most recent successful function execution
    */
-  lastResult: ReturnType<TFn> | undefined;
+  lastResult: Awaited<ReturnType<TFn>> | undefined;
   /**
    * Number of function executions that have been rejected due to rate limiting
    */
@@ -48,7 +47,7 @@ interface AsyncRateLimiterState<TFn extends AnyAsyncFunction> {
 /**
  * Options for configuring an async rate-limited function
  */
-interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
+export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
   /**
    * Options for configuring the underlying async retryer
    */
@@ -90,7 +89,7 @@ interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
   /**
    * Optional function to call when the rate-limited function is executed
    */
-  onSuccess?: (result: ReturnType<TFn>, args: Parameters<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
+  onSuccess?: (result: Awaited<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.
@@ -113,7 +112,7 @@ interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
 /**
  * Utility function for sharing common `AsyncRateLimiterOptions` options between different `AsyncRateLimiter` instances.
  */
-declare function asyncRateLimiterOptions<TFn extends AnyAsyncFunction = AnyAsyncFunction, TOptions extends Partial<AsyncRateLimiterOptions<TFn>> = Partial<AsyncRateLimiterOptions<TFn>>>(options: TOptions): TOptions;
+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.
  *
@@ -188,7 +187,7 @@ declare function asyncRateLimiterOptions<TFn extends AnyAsyncFunction = AnyAsync
  * const data = await rateLimiter.maybeExecute('123');
  * ```
  */
-declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
+export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
   #private;
   fn: TFn;
   readonly store: Store<Readonly<AsyncRateLimiterState<TFn>>>;
@@ -225,7 +224,7 @@ declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
    * const result2 = await rateLimiter.maybeExecute('arg1', 'arg2'); // undefined
    * ```
    */
-  maybeExecute: (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
+  maybeExecute: (...args: Parameters<TFn>) => Promise<Awaited<ReturnType<TFn>> | undefined>;
   /**
    * Returns the number of remaining executions allowed in the current window
    */
@@ -351,7 +350,5 @@ declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
  * ```
  */
-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
+export declare function asyncRateLimit<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions: AsyncRateLimiterOptions<TFn>): (...args: Parameters<TFn>) => Promise<Awaited<ReturnType<TFn>> | undefined>;
+//#endregion

package/dist/async-rate-limiter.js

@@ -1,6 +1,6 @@
 import { parseFunctionOrValue } from "./utils.js";
-import { emitChange, pacerEventClient } from "./event-client.js";
 import { AsyncRetryer } from "./async-retryer.js";
+import { emitChange, pacerEventClient } from "./event-client.js";
 import { Store } from "@tanstack/store";
 
 //#region src/async-rate-limiter.ts
@@ -107,142 +107,14 @@ const defaultOptions = {
 * ```
 */
 var AsyncRateLimiter = class {
-	#timeoutIds;
+	fn;
+	store = new Store(getDefaultAsyncRateLimiterState());
+	key;
+	options;
+	asyncRetryers = /* @__PURE__ */ new Map();
+	#timeoutIds = /* @__PURE__ */ new Set();
 	constructor(fn, initialOptions) {
 		this.fn = fn;
-		this.store = new Store(getDefaultAsyncRateLimiterState());
-		this.asyncRetryers = /* @__PURE__ */ new Map();
-		this.#timeoutIds = /* @__PURE__ */ new Set();
-		this.setOptions = (newOptions) => {
-			this.options = {
-				...this.options,
-				...newOptions
-			};
-		};
-		this.#setState = (newState) => {
-			this.store.setState((state) => {
-				const combinedState = {
-					...state,
-					...newState
-				};
-				const isExceeded = combinedState.executionTimes.length >= this.#getLimit();
-				const status = !this.#getEnabled() ? "disabled" : combinedState.isExecuting ? "executing" : isExceeded ? "exceeded" : "idle";
-				return {
-					...combinedState,
-					isExceeded,
-					status
-				};
-			});
-			emitChange("AsyncRateLimiter", this);
-		};
-		this.#getEnabled = () => {
-			return !!parseFunctionOrValue(this.options.enabled, this);
-		};
-		this.#getLimit = () => {
-			return parseFunctionOrValue(this.options.limit, this);
-		};
-		this.#getWindow = () => {
-			return parseFunctionOrValue(this.options.window, this);
-		};
-		this.maybeExecute = async (...args) => {
-			this.#setState({ maybeExecuteCount: this.store.state.maybeExecuteCount + 1 });
-			this.#cleanupOldExecutions();
-			if (this.#getExecutionTimesInWindow().length < this.#getLimit()) {
-				await this.#execute(...args);
-				return this.store.state.lastResult;
-			}
-			this.#setState({ rejectionCount: this.store.state.rejectionCount + 1 });
-			this.options.onReject?.(args, this);
-		};
-		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({
-				isExecuting: true,
-				executionTimes
-			});
-			try {
-				const currentAsyncRetryer = new 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,
-					lastResult: result
-				});
-				this.options.onSuccess?.(result, args, this);
-			} catch (error) {
-				this.#setState({ errorCount: this.store.state.errorCount + 1 });
-				this.options.onError?.(error, args, this);
-				if (this.options.throwOnError) throw error;
-			} finally {
-				this.asyncRetryers.delete(currentMaybeExecute);
-				this.#setState({
-					isExecuting: false,
-					settleCount: this.store.state.settleCount + 1
-				});
-				this.options.onSettled?.(args, this);
-			}
-			return this.store.state.lastResult;
-		};
-		this.#getExecutionTimesInWindow = () => {
-			if (this.options.windowType === "sliding") return this.store.state.executionTimes.filter((time) => time > Date.now() - this.#getWindow());
-			else {
-				if (this.store.state.executionTimes.length === 0) return [];
-				const windowStart = Math.min(...this.store.state.executionTimes);
-				const windowEnd = windowStart + this.#getWindow();
-				if (Date.now() > windowEnd) return [];
-				return this.store.state.executionTimes.filter((time) => time >= windowStart && time <= windowEnd);
-			}
-		};
-		this.#setCleanupTimeout = (executionTime) => {
-			if (this.options.windowType === "sliding" || this.#timeoutIds.size === 0) {
-				const timeUntilExpiration = executionTime - Date.now() + this.#getWindow() + 1;
-				const timeoutId = setTimeout(() => {
-					this.#cleanupOldExecutions();
-					this.#clearTimeout(timeoutId);
-				}, timeUntilExpiration);
-				this.#timeoutIds.add(timeoutId);
-			}
-		};
-		this.#clearTimeout = (timeoutId) => {
-			clearTimeout(timeoutId);
-			this.#timeoutIds.delete(timeoutId);
-		};
-		this.#clearTimeouts = () => {
-			this.#timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId));
-			this.#timeoutIds.clear();
-		};
-		this.#cleanupOldExecutions = () => {
-			this.#setState({ executionTimes: this.#getExecutionTimesInWindow() });
-		};
-		this.getRemainingInWindow = () => {
-			const relevantExecutionTimes = this.#getExecutionTimesInWindow();
-			return Math.max(0, this.#getLimit() - relevantExecutionTimes.length);
-		};
-		this.getMsUntilNextWindow = () => {
-			if (this.getRemainingInWindow() > 0) return 0;
-			return (this.store.state.executionTimes[0] ?? Infinity) + this.#getWindow() - Date.now();
-		};
-		this.getAbortSignal = (maybeExecuteCount) => {
-			const count = maybeExecuteCount ?? this.store.state.maybeExecuteCount;
-			return this.asyncRetryers.get(count)?.getAbortSignal() ?? null;
-		};
-		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 = initialOptions.key;
 		this.options = {
 			...defaultOptions,
@@ -257,25 +129,205 @@ var AsyncRateLimiter = class {
 			this.setOptions(event.payload.options);
 		});
 	}
-	#setState;
+	/**
+	* Updates the async rate limiter options
+	*/
+	setOptions = (newOptions) => {
+		this.options = {
+			...this.options,
+			...newOptions
+		};
+	};
+	#setState = (newState) => {
+		this.store.setState((state) => {
+			const combinedState = {
+				...state,
+				...newState
+			};
+			const isExceeded = combinedState.executionTimes.length >= this.#getLimit();
+			const status = !this.#getEnabled() ? "disabled" : combinedState.isExecuting ? "executing" : isExceeded ? "exceeded" : "idle";
+			return {
+				...combinedState,
+				isExceeded,
+				status
+			};
+		});
+		emitChange("AsyncRateLimiter", this);
+	};
 	/**
 	* Returns the current enabled state of the async rate limiter
 	*/
-	#getEnabled;
+	#getEnabled = () => {
+		return !!parseFunctionOrValue(this.options.enabled, this);
+	};
 	/**
 	* Returns the current limit of executions allowed within the time window
 	*/
-	#getLimit;
+	#getLimit = () => {
+		return parseFunctionOrValue(this.options.limit, this);
+	};
 	/**
 	* Returns the current time window in milliseconds
 	*/
-	#getWindow;
-	#execute;
-	#getExecutionTimesInWindow;
-	#setCleanupTimeout;
-	#clearTimeout;
-	#clearTimeouts;
-	#cleanupOldExecutions;
+	#getWindow = () => {
+		return parseFunctionOrValue(this.options.window, this);
+	};
+	/**
+	* Attempts to execute the rate-limited function if within the configured limits.
+	* Will reject execution if the number of calls in the current window exceeds the limit.
+	*
+	* 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 = async (...args) => {
+		this.#setState({ maybeExecuteCount: this.store.state.maybeExecuteCount + 1 });
+		this.#cleanupOldExecutions();
+		if (this.#getExecutionTimesInWindow().length < this.#getLimit()) {
+			await this.#execute(...args);
+			return this.store.state.lastResult;
+		}
+		this.#setState({ rejectionCount: this.store.state.rejectionCount + 1 });
+		this.options.onReject?.(args, 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({
+			isExecuting: true,
+			executionTimes
+		});
+		try {
+			const currentAsyncRetryer = new AsyncRetryer(this.fn, this.options.asyncRetryerOptions);
+			this.asyncRetryers.set(currentMaybeExecute, currentAsyncRetryer);
+			const result = await currentAsyncRetryer.execute(...args);
+			this.#setCleanupTimeout(now);
+			this.#setState({
+				successCount: this.store.state.successCount + 1,
+				lastResult: result
+			});
+			this.options.onSuccess?.(result, args, this);
+		} catch (error) {
+			this.#setState({ errorCount: this.store.state.errorCount + 1 });
+			this.options.onError?.(error, args, this);
+			if (this.options.throwOnError) throw error;
+		} finally {
+			this.asyncRetryers.delete(currentMaybeExecute);
+			this.#setState({
+				isExecuting: this.asyncRetryers.size > 0,
+				settleCount: this.store.state.settleCount + 1
+			});
+			this.options.onSettled?.(args, this);
+		}
+		return this.store.state.lastResult;
+	};
+	#getExecutionTimesInWindow = () => {
+		if (this.options.windowType === "sliding") return this.store.state.executionTimes.filter((time) => time > Date.now() - this.#getWindow());
+		else {
+			if (this.store.state.executionTimes.length === 0) return [];
+			const windowStart = Math.min(...this.store.state.executionTimes);
+			const windowEnd = windowStart + this.#getWindow();
+			if (Date.now() > windowEnd) return [];
+			return this.store.state.executionTimes.filter((time) => time >= windowStart && time <= windowEnd);
+		}
+	};
+	#setCleanupTimeout = (executionTime) => {
+		if (this.options.windowType === "sliding" || this.#timeoutIds.size === 0) {
+			const timeUntilExpiration = executionTime - Date.now() + this.#getWindow() + 1;
+			const timeoutId = setTimeout(() => {
+				this.#cleanupOldExecutions();
+				this.#clearTimeout(timeoutId);
+			}, timeUntilExpiration);
+			this.#timeoutIds.add(timeoutId);
+		}
+	};
+	#clearTimeout = (timeoutId) => {
+		clearTimeout(timeoutId);
+		this.#timeoutIds.delete(timeoutId);
+	};
+	#clearTimeouts = () => {
+		this.#timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId));
+		this.#timeoutIds.clear();
+	};
+	#cleanupOldExecutions = () => {
+		this.#setState({ executionTimes: this.#getExecutionTimesInWindow() });
+	};
+	/**
+	* Returns the number of remaining executions allowed in the current window
+	*/
+	getRemainingInWindow = () => {
+		const relevantExecutionTimes = this.#getExecutionTimesInWindow();
+		return Math.max(0, this.#getLimit() - relevantExecutionTimes.length);
+	};
+	/**
+	* Returns the number of milliseconds until the next execution will be possible
+	* For fixed windows, this is the time until the current window resets
+	* For sliding windows, this is the time until the oldest execution expires
+	*/
+	getMsUntilNextWindow = () => {
+		if (this.getRemainingInWindow() > 0) return 0;
+		return (this.store.state.executionTimes[0] ?? Infinity) + this.#getWindow() - Date.now();
+	};
+	/**
+	* 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;
+		return this.asyncRetryers.get(count)?.getAbortSignal() ?? null;
+	};
+	/**
+	* Aborts all ongoing executions with the internal abort controllers.
+	* Does NOT clear out the execution times or reset the rate limiter.
+	*/
+	abort = () => {
+		this.asyncRetryers.forEach((retryer) => retryer.abort());
+		this.asyncRetryers.clear();
+		this.#setState({ isExecuting: false });
+	};
+	/**
+	* Resets the rate limiter state
+	*/
+	reset = () => {
+		this.#setState(getDefaultAsyncRateLimiterState());
+		this.#clearTimeouts();
+		this.asyncRetryers.forEach((retryer) => retryer.reset());
+	};
 };
 /**
 * Creates an async rate-limited function that will execute the provided function up to a maximum number of times within a time window.
@@ -366,5 +418,4 @@ function asyncRateLimit(fn, initialOptions) {
 }
 
 //#endregion
-export { AsyncRateLimiter, asyncRateLimit, asyncRateLimiterOptions };
-//# sourceMappingURL=async-rate-limiter.js.map
+export { AsyncRateLimiter, asyncRateLimit, asyncRateLimiterOptions };

package/dist/async-retryer.d.ts

@@ -1,8 +1,7 @@
 import { AnyAsyncFunction } from "./types.js";
 import { Store } from "@tanstack/store";
-
 //#region src/async-retryer.d.ts
-interface AsyncRetryerState<TFn extends AnyAsyncFunction> {
+export interface AsyncRetryerState<TFn extends AnyAsyncFunction> {
   /**
    * The current retry attempt number (0 when not executing)
    */
@@ -36,7 +35,7 @@ interface AsyncRetryerState<TFn extends AnyAsyncFunction> {
    */
   totalExecutionTime: number;
 }
-interface AsyncRetryerOptions<TFn extends AnyAsyncFunction> {
+export interface AsyncRetryerOptions<TFn extends AnyAsyncFunction> {
   /**
    * The backoff strategy for retry delays:
    * - 'exponential': Wait time doubles with each attempt (1s, 2s, 4s, ...)
@@ -66,7 +65,10 @@ interface AsyncRetryerOptions<TFn extends AnyAsyncFunction> {
   jitter?: number;
   /**
    * Optional key to identify this async retryer instance.
-   * If provided, the async retryer will be identified by this key in the devtools and PacerProvider if applicable.
+   * Note: async retryers are not currently surfaced in the devtools, so this key
+   * is only a plain identifier. Retryer instances are often created per-execution
+   * (including internally by the other async utilities), so they intentionally do
+   * not register with the devtools event bus.
    */
   key?: string;
   /**
@@ -133,7 +135,7 @@ interface AsyncRetryerOptions<TFn extends AnyAsyncFunction> {
 /**
  * Utility function for sharing common `AsyncRetryerOptions` options between different `AsyncRetryer` instances.
  */
-declare function asyncRetryerOptions<TFn extends AnyAsyncFunction = AnyAsyncFunction, TOptions extends Partial<AsyncRetryerOptions<TFn>> = Partial<AsyncRetryerOptions<TFn>>>(options: TOptions): TOptions;
+export declare function asyncRetryerOptions<TFn extends AnyAsyncFunction = AnyAsyncFunction, TOptions extends Partial<AsyncRetryerOptions<TFn>> = Partial<AsyncRetryerOptions<TFn>>>(options: TOptions): TOptions;
 declare const defaultOptions: Omit<Required<AsyncRetryerOptions<any>>, 'initialState' | 'key' | 'onAbort' | 'onError' | 'onLastError' | 'onRetry' | 'onSettled' | 'onSuccess' | 'onExecutionTimeout' | 'onTotalExecutionTimeout'>;
 /**
  * Provides robust retry functionality for asynchronous functions, supporting configurable backoff strategies,
@@ -229,7 +231,7 @@ declare const defaultOptions: Omit<Required<AsyncRetryerOptions<any>>, 'initialS
  *
  * @template TFn The async function type to be retried.
  */
-declare class AsyncRetryer<TFn extends AnyAsyncFunction> {
+export declare class AsyncRetryer<TFn extends AnyAsyncFunction> {
   #private;
   fn: TFn;
   readonly store: Store<Readonly<AsyncRetryerState<TFn>>>;
@@ -313,7 +315,5 @@ declare class AsyncRetryer<TFn extends AnyAsyncFunction> {
  * const data2 = await fetchWithRetry('/api/data2')
  * ```
  */
-declare function asyncRetry<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions?: AsyncRetryerOptions<TFn>): (...args: Parameters<TFn>) => Promise<Awaited<ReturnType<TFn>> | undefined>;
-//#endregion
-export { AsyncRetryer, AsyncRetryerOptions, AsyncRetryerState, asyncRetry, asyncRetryerOptions };
-//# sourceMappingURL=async-retryer.d.ts.map
+export declare function asyncRetry<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions?: AsyncRetryerOptions<TFn>): (...args: Parameters<TFn>) => Promise<Awaited<ReturnType<TFn>> | undefined>;
+//#endregion