@tanstack/pacer 0.21.1 → 0.23.0

package/dist/async-debouncer.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-debouncer.ts
@@ -86,144 +86,15 @@ const defaultOptions = {
 * ```
 */
 var AsyncDebouncer = class {
-	#timeoutId;
-	#resolvePreviousPromise;
+	fn;
+	store = new Store(getDefaultAsyncDebouncerState());
+	key;
+	options;
+	asyncRetryers = /* @__PURE__ */ new Map();
+	#timeoutId = null;
+	#resolvePreviousPromise = null;
 	constructor(fn, initialOptions) {
 		this.fn = fn;
-		this.store = new Store(getDefaultAsyncDebouncerState());
-		this.asyncRetryers = /* @__PURE__ */ new Map();
-		this.#timeoutId = null;
-		this.#resolvePreviousPromise = null;
-		this.setOptions = (newOptions) => {
-			this.options = {
-				...this.options,
-				...newOptions
-			};
-			if (!this.#getEnabled()) this.cancel();
-		};
-		this.#setState = (newState) => {
-			this.store.setState((state) => {
-				const combinedState = {
-					...state,
-					...newState
-				};
-				const { isPending, isExecuting, settleCount } = combinedState;
-				return {
-					...combinedState,
-					status: !this.#getEnabled() ? "disabled" : isPending ? "pending" : isExecuting ? "executing" : settleCount > 0 ? "settled" : "idle"
-				};
-			});
-			emitChange("AsyncDebouncer", this);
-		};
-		this.#getEnabled = () => {
-			return !!parseFunctionOrValue(this.options.enabled, this);
-		};
-		this.#getWait = () => {
-			return parseFunctionOrValue(this.options.wait, this);
-		};
-		this.maybeExecute = async (...args) => {
-			if (!this.#getEnabled()) return void 0;
-			this.#cancelPendingExecution();
-			this.#setState({
-				lastArgs: args,
-				maybeExecuteCount: this.store.state.maybeExecuteCount + 1
-			});
-			if (this.options.leading && this.store.state.canLeadingExecute) {
-				this.#setState({ canLeadingExecute: false });
-				await this.#execute(...args);
-				return this.store.state.lastResult;
-			}
-			if (this.options.trailing && this.#getEnabled()) this.#setState({ isPending: true });
-			return new Promise((resolve, reject) => {
-				this.#resolvePreviousPromise = resolve;
-				this.#timeoutId = setTimeout(async () => {
-					if (this.options.trailing && this.store.state.lastArgs) try {
-						await this.#execute(...this.store.state.lastArgs);
-					} catch (error) {
-						reject(error);
-					}
-					this.#setState({ canLeadingExecute: true });
-					this.#resolvePreviousPromise = null;
-					resolve(this.store.state.lastResult);
-				}, this.#getWait());
-			});
-		};
-		this.#execute = async (...args) => {
-			if (!this.#getEnabled()) return void 0;
-			const currentMaybeExecuteCount = this.store.state.maybeExecuteCount + 1;
-			try {
-				this.#setState({ isExecuting: true });
-				const currentAsyncRetryer = new AsyncRetryer(this.fn, {
-					...this.options.asyncRetryerOptions,
-					key: `${this.key}-retryer-${currentMaybeExecuteCount}`
-				});
-				this.asyncRetryers.set(currentMaybeExecuteCount, currentAsyncRetryer);
-				const result = await currentAsyncRetryer.execute(...args);
-				this.#setState({
-					lastResult: result,
-					successCount: this.store.state.successCount + 1
-				});
-				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(currentMaybeExecuteCount);
-				this.#setState({
-					isExecuting: false,
-					isPending: false,
-					lastArgs: void 0,
-					settleCount: this.store.state.settleCount + 1
-				});
-				this.options.onSettled?.(args, this);
-			}
-			return this.store.state.lastResult;
-		};
-		this.flush = async () => {
-			if (this.store.state.isPending && this.store.state.lastArgs) {
-				const { lastArgs } = this.store.state;
-				this.#cancelPendingExecution();
-				return await this.#execute(...lastArgs);
-			}
-		};
-		this.#resolvePreviousPromiseInternal = () => {
-			if (this.#resolvePreviousPromise) {
-				this.#resolvePreviousPromise(this.store.state.lastResult);
-				this.#resolvePreviousPromise = null;
-			}
-		};
-		this.#clearTimeout = () => {
-			if (this.#timeoutId) {
-				clearTimeout(this.#timeoutId);
-				this.#timeoutId = null;
-			}
-		};
-		this.#cancelPendingExecution = () => {
-			this.#clearTimeout();
-			this.#resolvePreviousPromiseInternal();
-			this.#setState({
-				isPending: false,
-				lastArgs: void 0
-			});
-		};
-		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.cancel = () => {
-			this.#cancelPendingExecution();
-			this.#setState({ canLeadingExecute: true });
-		};
-		this.reset = () => {
-			this.#setState(getDefaultAsyncDebouncerState());
-			this.asyncRetryers.forEach((retryer) => retryer.reset());
-		};
 		this.key = initialOptions.key;
 		this.options = {
 			...defaultOptions,
@@ -237,22 +108,193 @@ var AsyncDebouncer = class {
 			this.setOptions(event.payload.options);
 		});
 	}
-	#setState;
+	/**
+	* Updates the async debouncer options
+	*/
+	setOptions = (newOptions) => {
+		this.options = {
+			...this.options,
+			...newOptions
+		};
+		if (!this.#getEnabled()) this.cancel();
+	};
+	#setState = (newState) => {
+		this.store.setState((state) => {
+			const combinedState = {
+				...state,
+				...newState
+			};
+			const { isPending, isExecuting, settleCount } = combinedState;
+			return {
+				...combinedState,
+				status: !this.#getEnabled() ? "disabled" : isPending ? "pending" : isExecuting ? "executing" : settleCount > 0 ? "settled" : "idle"
+			};
+		});
+		emitChange("AsyncDebouncer", this);
+	};
 	/**
 	* Returns the current debouncer enabled state
 	*/
-	#getEnabled;
+	#getEnabled = () => {
+		return !!parseFunctionOrValue(this.options.enabled, this);
+	};
 	/**
 	* Returns the current debouncer wait state
 	*/
-	#getWait;
-	#execute;
-	#resolvePreviousPromiseInternal;
-	#clearTimeout;
+	#getWait = () => {
+		return parseFunctionOrValue(this.options.wait, this);
+	};
+	/**
+	* Attempts to execute the debounced function.
+	* If a call is already in progress, it will be queued.
+	*
+	* Error Handling:
+	* - If the debounced 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 debounced function if no onError handler is configured
+	*/
+	maybeExecute = async (...args) => {
+		if (!this.#getEnabled()) return void 0;
+		this.#cancelPendingExecution();
+		this.#setState({
+			lastArgs: args,
+			maybeExecuteCount: this.store.state.maybeExecuteCount + 1
+		});
+		if (this.options.leading && this.store.state.canLeadingExecute) {
+			this.#setState({ canLeadingExecute: false });
+			await this.#execute(...args);
+			return this.store.state.lastResult;
+		}
+		if (this.options.trailing && this.#getEnabled()) this.#setState({ isPending: true });
+		return new Promise((resolve, reject) => {
+			this.#resolvePreviousPromise = resolve;
+			this.#timeoutId = setTimeout(async () => {
+				if (this.options.trailing && this.store.state.lastArgs) try {
+					await this.#execute(...this.store.state.lastArgs);
+				} catch (error) {
+					reject(error);
+				}
+				this.#setState({ canLeadingExecute: true });
+				this.#resolvePreviousPromise = null;
+				resolve(this.store.state.lastResult);
+			}, this.#getWait());
+		});
+	};
+	#execute = async (...args) => {
+		if (!this.#getEnabled()) return void 0;
+		const currentMaybeExecuteCount = this.store.state.maybeExecuteCount + 1;
+		try {
+			this.#setState({ isExecuting: true });
+			const currentAsyncRetryer = new AsyncRetryer(this.fn, this.options.asyncRetryerOptions);
+			this.asyncRetryers.set(currentMaybeExecuteCount, currentAsyncRetryer);
+			const result = await currentAsyncRetryer.execute(...args);
+			this.#setState({
+				lastResult: result,
+				successCount: this.store.state.successCount + 1
+			});
+			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(currentMaybeExecuteCount);
+			this.#setState({
+				isExecuting: false,
+				isPending: false,
+				lastArgs: void 0,
+				settleCount: this.store.state.settleCount + 1
+			});
+			this.options.onSettled?.(args, this);
+		}
+		return this.store.state.lastResult;
+	};
+	/**
+	* Processes the current pending execution immediately
+	*/
+	flush = async () => {
+		if (this.store.state.isPending && this.store.state.lastArgs) {
+			const { lastArgs } = this.store.state;
+			this.#cancelPendingExecution();
+			return await this.#execute(...lastArgs);
+		}
+	};
+	#resolvePreviousPromiseInternal = () => {
+		if (this.#resolvePreviousPromise) {
+			this.#resolvePreviousPromise(this.store.state.lastResult);
+			this.#resolvePreviousPromise = null;
+		}
+	};
+	#clearTimeout = () => {
+		if (this.#timeoutId) {
+			clearTimeout(this.#timeoutId);
+			this.#timeoutId = null;
+		}
+	};
 	/**
 	* Internal cancel without resetting the leading execute state
 	*/
-	#cancelPendingExecution;
+	#cancelPendingExecution = () => {
+		this.#clearTimeout();
+		this.#resolvePreviousPromiseInternal();
+		this.#setState({
+			isPending: false,
+			lastArgs: void 0
+		});
+	};
+	/**
+	* 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 debouncer = new AsyncDebouncer(
+	*   async (searchTerm: string) => {
+	*     const signal = debouncer.getAbortSignal()
+	*     if (signal) {
+	*       const response = await fetch(`/api/search?q=${searchTerm}`, { signal })
+	*       return response.json()
+	*     }
+	*   },
+	*   { wait: 300 }
+	* )
+	* ```
+	*/
+	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 cancel any pending execution that have not started yet.
+	*/
+	abort = () => {
+		this.asyncRetryers.forEach((retryer) => retryer.abort());
+		this.asyncRetryers.clear();
+		this.#setState({ isExecuting: false });
+	};
+	/**
+	* Cancels any pending execution that have not started yet.
+	* Does NOT abort any execution already in progress.
+	*/
+	cancel = () => {
+		this.#cancelPendingExecution();
+		this.#setState({ canLeadingExecute: true });
+	};
+	/**
+	* Resets the debouncer state to its default values
+	*/
+	reset = () => {
+		this.#setState(getDefaultAsyncDebouncerState());
+		this.asyncRetryers.forEach((retryer) => retryer.reset());
+	};
 };
 /**
 * Creates an async debounced function that delays execution until after a specified wait time.
@@ -323,5 +365,4 @@ function asyncDebounce(fn, initialOptions) {
 }
 
 //#endregion
-export { AsyncDebouncer, asyncDebounce, asyncDebouncerOptions };
-//# sourceMappingURL=async-debouncer.js.map
+export { AsyncDebouncer, asyncDebounce, asyncDebouncerOptions };

package/dist/async-queuer.d.ts

@@ -1,9 +1,8 @@
 import { AsyncRetryer, AsyncRetryerOptions } from "./async-retryer.js";
 import { QueuePosition } from "./queuer.js";
 import { Store } from "@tanstack/store";
-
 //#region src/async-queuer.d.ts
-interface AsyncQueuerState<TValue> {
+export interface AsyncQueuerState<TValue> {
   /**
    * Items currently being processed by the queuer
    */
@@ -19,7 +18,7 @@ interface AsyncQueuerState<TValue> {
   /**
    * Number of times execute has been called
    */
-  executeCount: number;
+  executionCount: number;
   /**
    * Number of items that have been removed from the queue due to expiration
    */
@@ -67,7 +66,7 @@ interface AsyncQueuerState<TValue> {
   /**
    * Number of task executions that have completed (either successfully or with errors)
    */
-  settledCount: number;
+  settleCount: number;
   /**
    * Number of items currently in the queue
    */
@@ -81,7 +80,7 @@ interface AsyncQueuerState<TValue> {
    */
   successCount: number;
 }
-interface AsyncQueuerOptions<TValue> {
+export interface AsyncQueuerOptions<TValue> {
   /**
    * Options for configuring the underlying async retryer
    */
@@ -181,7 +180,7 @@ interface AsyncQueuerOptions<TValue> {
 /**
  * Utility function for sharing common `AsyncQueuerOptions` options between different `AsyncQueuer` instances.
  */
-declare function asyncQueuerOptions<TValue = any, TOptions extends Partial<AsyncQueuerOptions<TValue>> = Partial<AsyncQueuerOptions<TValue>>>(options: TOptions): TOptions;
+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.
  *
@@ -246,7 +245,7 @@ declare function asyncQueuerOptions<TValue = any, TOptions extends Partial<Async
  * asyncQueuer.start();
  * ```
  */
-declare class AsyncQueuer<TValue> {
+export declare class AsyncQueuer<TValue> {
   #private;
   fn: (item: TValue) => Promise<any>;
   readonly store: Store<Readonly<AsyncQueuerState<TValue>>>;
@@ -261,6 +260,7 @@ declare class AsyncQueuer<TValue> {
   /**
    * Adds an item to the queue. If the queue is full, the item is rejected and onReject is called.
    * Items can be inserted based on priority or at the front/back depending on configuration.
+   * `undefined` cannot be queued (it is the internal "no item" sentinel) and is always rejected.
    *
    * @example
    * ```ts
@@ -340,10 +340,10 @@ declare class AsyncQueuer<TValue> {
   clear: () => void;
   /**
    * Returns the AbortSignal for a specific execution.
-   * If no executeCount is provided, returns the signal for the most recent execution.
+   * If no executionCount 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
+   * @param executionCount - Optional specific execution to get signal for
    * @example
    * ```typescript
    * const queuer = new AsyncQueuer(
@@ -358,7 +358,7 @@ declare class AsyncQueuer<TValue> {
    * )
    * ```
    */
-  getAbortSignal: (executeCount?: number) => AbortSignal | null;
+  getAbortSignal: (executionCount?: number) => AbortSignal | null;
   /**
    * Aborts all ongoing executions with the internal abort controllers.
    * Does NOT clear out the items.
@@ -434,7 +434,5 @@ declare class AsyncQueuer<TValue> {
  * enqueue('hello');
  * ```
  */
-declare function asyncQueue<TValue>(fn: (value: TValue) => Promise<any>, initialOptions: AsyncQueuerOptions<TValue>): (item: TValue, position?: QueuePosition, runOnItemsChange?: boolean) => boolean;
-//#endregion
-export { AsyncQueuer, AsyncQueuerOptions, AsyncQueuerState, asyncQueue, asyncQueuerOptions };
-//# sourceMappingURL=async-queuer.d.ts.map
+export declare function asyncQueue<TValue>(fn: (value: TValue) => Promise<any>, initialOptions: AsyncQueuerOptions<TValue>): (item: TValue, position?: QueuePosition, runOnItemsChange?: boolean) => boolean;
+//#endregion