@tanstack/pacer 0.21.1 → 0.23.0

package/README.md

@@ -1,5 +1,19 @@
 <div align="center">
-  <img src="./media/header_pacer.png" >
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/pacer.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/pacer.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/pacer.png"
+      alt="TanStack Pacer"
+      width="900"
+    />
+  </picture>
 </div>
 
 <br />
@@ -29,8 +43,9 @@
 </div>
 
 <div align="center">
-  
+
 ### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
+
 </div>
 
 # TanStack Pacer
@@ -88,10 +103,10 @@ A lightweight timing and scheduling library for debouncing, throttling, rate lim
 > [!NOTE]
 > You may know **TanStack Pacer** by our adapter names, too!
 >
-> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react/react-pacer)
-> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact/preact-pacer)
-> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid/solid-pacer)
-> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular/angular-pacer)
+> - [**React Pacer**](https://tanstack.com/pacer/latest/docs/framework/react)
+> - [**Preact Pacer**](https://tanstack.com/pacer/latest/docs/framework/preact)
+> - [**Solid Pacer**](https://tanstack.com/pacer/latest/docs/framework/solid)
+> - [**Angular Pacer**](https://tanstack.com/pacer/latest/docs/framework/angular)
 > - Svelte Pacer - needs a contributor!
 > - Vue Pacer - needs a contributor!
 

package/dist/async-batcher.d.ts

@@ -1,17 +1,16 @@
 import { OptionalKeys } from "./types.js";
 import { AsyncRetryer, AsyncRetryerOptions } from "./async-retryer.js";
 import { Store } from "@tanstack/store";
-
 //#region src/async-batcher.d.ts
-interface AsyncBatcherState<TValue> {
+export interface AsyncBatcherState<TValue> {
   /**
    * Number of batch executions that have resulted in errors
    */
   errorCount: number;
   /**
-   * Number of batch executions that have been executed
+   * Number of batch executions that have been started
    */
-  executeCount: number;
+  executionCount: number;
   /**
    * Array of items that failed during batch processing
    */
@@ -64,7 +63,7 @@ interface AsyncBatcherState<TValue> {
 /**
  * Options for configuring an AsyncBatcher instance
  */
-interface AsyncBatcherOptions<TValue> {
+export interface AsyncBatcherOptions<TValue> {
   /**
    * Options for configuring the underlying async retryer
    */
@@ -129,7 +128,7 @@ interface AsyncBatcherOptions<TValue> {
  * Utility function for sharing common `AsyncBatcherOptions` options between different `AsyncBatcher` instances.
  *
  */
-declare function asyncBatcherOptions<TValue = any, TOptions extends Partial<AsyncBatcherOptions<TValue>> = Partial<AsyncBatcherOptions<TValue>>>(options: TOptions): TOptions;
+export declare function asyncBatcherOptions<TValue = any, TOptions extends Partial<AsyncBatcherOptions<TValue>> = Partial<AsyncBatcherOptions<TValue>>>(options: TOptions): TOptions;
 type AsyncBatcherOptionsWithOptionalCallbacks<TValue> = OptionalKeys<Required<AsyncBatcherOptions<TValue>>, 'initialState' | 'onError' | 'onItemsChange' | 'onSettled' | 'onSuccess' | 'key'>;
 /**
  * A class that collects items and processes them in batches asynchronously.
@@ -198,7 +197,7 @@ type AsyncBatcherOptionsWithOptionalCallbacks<TValue> = OptionalKeys<Required<As
  * // batcher.execute() // manually trigger a batch
  * ```
  */
-declare class AsyncBatcher<TValue> {
+export declare class AsyncBatcher<TValue> {
   #private;
   fn: (items: Array<TValue>) => Promise<any>;
   readonly store: Store<Readonly<AsyncBatcherState<TValue>>>;
@@ -234,10 +233,10 @@ declare class AsyncBatcher<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 batcher = new AsyncBatcher(
@@ -256,7 +255,7 @@ declare class AsyncBatcher<TValue> {
    * )
    * ```
    */
-  getAbortSignal: (executeCount?: number) => AbortSignal | null;
+  getAbortSignal: (executionCount?: number) => AbortSignal | null;
   /**
    * Aborts all ongoing executions with the internal abort controllers.
    * Does NOT cancel any pending execution that have not started yet.
@@ -338,7 +337,5 @@ declare class AsyncBatcher<TValue> {
  * batchItems(3); // Triggers batch processing
  * ```
  */
-declare function asyncBatch<TValue>(fn: (items: Array<TValue>) => Promise<any>, options: AsyncBatcherOptions<TValue>): (item: TValue) => Promise<any>;
-//#endregion
-export { AsyncBatcher, AsyncBatcherOptions, AsyncBatcherState, asyncBatch, asyncBatcherOptions };
-//# sourceMappingURL=async-batcher.d.ts.map
+export declare function asyncBatch<TValue>(fn: (items: Array<TValue>) => Promise<any>, options: AsyncBatcherOptions<TValue>): (item: TValue) => Promise<any>;
+//#endregion

package/dist/async-batcher.js

@@ -1,13 +1,13 @@
 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-batcher.ts
 function getDefaultAsyncBatcherState() {
 	return {
 		errorCount: 0,
-		executeCount: 0,
+		executionCount: 0,
 		failedItems: [],
 		isEmpty: true,
 		isExecuting: false,
@@ -105,132 +105,14 @@ const defaultOptions = {
 * ```
 */
 var AsyncBatcher = class {
-	#timeoutId;
+	fn;
+	store = new Store(getDefaultAsyncBatcherState());
+	key;
+	options;
+	asyncRetryers = /* @__PURE__ */ new Map();
+	#timeoutId = null;
 	constructor(fn, initialOptions) {
 		this.fn = fn;
-		this.store = new Store(getDefaultAsyncBatcherState());
-		this.asyncRetryers = /* @__PURE__ */ new Map();
-		this.#timeoutId = null;
-		this.setOptions = (newOptions) => {
-			this.options = {
-				...this.options,
-				...newOptions
-			};
-		};
-		this.#setState = (newState) => {
-			this.store.setState((state) => {
-				const combinedState = {
-					...state,
-					...newState
-				};
-				const { isExecuting, isPending, items } = combinedState;
-				const size = items.length;
-				const isEmpty = size === 0;
-				return {
-					...combinedState,
-					isEmpty,
-					size,
-					status: isExecuting ? "executing" : isPending ? "pending" : isEmpty ? "idle" : "populated"
-				};
-			});
-			emitChange("AsyncBatcher", this);
-		};
-		this.#getWait = () => {
-			return parseFunctionOrValue(this.options.wait, this);
-		};
-		this.addItem = async (item) => {
-			this.#setState({
-				items: [...this.store.state.items, item],
-				isPending: this.options.wait !== Infinity
-			});
-			this.options.onItemsChange?.(this);
-			if (this.store.state.items.length >= this.options.maxSize || this.options.getShouldExecute(this.store.state.items, this)) return await this.#execute();
-			else if (this.options.wait !== Infinity) {
-				this.#clearTimeout();
-				this.#timeoutId = setTimeout(() => this.#execute(), this.#getWait());
-				await new Promise((resolve) => setTimeout(resolve, this.#getWait()));
-			}
-		};
-		this.#execute = async () => {
-			if (this.store.state.items.length === 0) return;
-			const currentExecuteCount = this.store.state.executeCount + 1;
-			const batch = this.peekAllItems();
-			this.clear();
-			this.options.onItemsChange?.(this);
-			this.#setState({
-				isExecuting: true,
-				executeCount: currentExecuteCount
-			});
-			try {
-				const currentAsyncRetryer = new AsyncRetryer(this.fn, this.options.asyncRetryerOptions);
-				this.asyncRetryers.set(currentExecuteCount, currentAsyncRetryer);
-				const result = await currentAsyncRetryer.execute(batch);
-				this.#setState({
-					totalItemsProcessed: this.store.state.totalItemsProcessed + batch.length,
-					lastResult: result,
-					successCount: this.store.state.successCount + 1
-				});
-				this.options.onSuccess?.(result, batch, this);
-				return result;
-			} catch (error) {
-				this.#setState({
-					errorCount: this.store.state.errorCount + 1,
-					failedItems: [...this.store.state.failedItems, ...batch],
-					totalItemsFailed: this.store.state.totalItemsFailed + batch.length
-				});
-				this.options.onError?.(error, batch, this);
-				if (this.options.throwOnError) throw error;
-				return;
-			} finally {
-				this.asyncRetryers.delete(currentExecuteCount);
-				this.#setState({
-					isExecuting: false,
-					settleCount: this.store.state.settleCount + 1
-				});
-				this.options.onSettled?.(batch, this);
-			}
-		};
-		this.flush = async () => {
-			this.#clearTimeout();
-			return await this.#execute();
-		};
-		this.peekAllItems = () => {
-			return [...this.store.state.items];
-		};
-		this.peekFailedItems = () => {
-			return [...this.store.state.failedItems];
-		};
-		this.#clearTimeout = () => {
-			if (this.#timeoutId) {
-				clearTimeout(this.#timeoutId);
-				this.#timeoutId = null;
-			}
-		};
-		this.clear = () => {
-			this.#setState({
-				items: [],
-				failedItems: [],
-				isPending: false
-			});
-		};
-		this.getAbortSignal = (executeCount) => {
-			const count = executeCount ?? this.store.state.executeCount;
-			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.#clearTimeout();
-			this.#setState({ isPending: false });
-		};
-		this.reset = () => {
-			this.#setState(getDefaultAsyncBatcherState());
-			this.options.onItemsChange?.(this);
-			this.asyncRetryers.forEach((retryer) => retryer.reset());
-		};
 		this.key = initialOptions.key;
 		this.options = {
 			...defaultOptions,
@@ -244,8 +126,57 @@ var AsyncBatcher = class {
 			this.setOptions(event.payload.options);
 		});
 	}
-	#setState;
-	#getWait;
+	/**
+	* Updates the async batcher options
+	*/
+	setOptions = (newOptions) => {
+		this.options = {
+			...this.options,
+			...newOptions
+		};
+	};
+	#setState = (newState) => {
+		this.store.setState((state) => {
+			const combinedState = {
+				...state,
+				...newState
+			};
+			const { isExecuting, isPending, items } = combinedState;
+			const size = items.length;
+			const isEmpty = size === 0;
+			return {
+				...combinedState,
+				isEmpty,
+				size,
+				status: isExecuting ? "executing" : isPending ? "pending" : isEmpty ? "idle" : "populated"
+			};
+		});
+		emitChange("AsyncBatcher", this);
+	};
+	#getWait = () => {
+		return parseFunctionOrValue(this.options.wait, this);
+	};
+	/**
+	* Adds an item to the async batcher
+	* If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed
+	*
+	* @returns The result from the batch function, or undefined if an error occurred and was handled by onError
+	*
+	* @throws The error from the batch function if no onError handler is configured or throwOnError is true
+	*/
+	addItem = async (item) => {
+		this.#setState({
+			items: [...this.store.state.items, item],
+			isPending: this.options.wait !== Infinity
+		});
+		this.options.onItemsChange?.(this);
+		if (this.store.state.items.length >= this.options.maxSize || this.options.getShouldExecute(this.store.state.items, this)) return await this.#execute();
+		else if (this.options.wait !== Infinity) {
+			this.#clearTimeout();
+			this.#timeoutId = setTimeout(() => this.#execute(), this.#getWait());
+			await new Promise((resolve) => setTimeout(resolve, this.#getWait()));
+		}
+	};
 	/**
 	* Processes the current batch of items asynchronously.
 	* This method will automatically be triggered if the batcher is running and any of these conditions are met:
@@ -258,8 +189,132 @@ var AsyncBatcher = class {
 	* @returns A promise that resolves with the result of the batch function, or undefined if an error occurred and was handled by onError
 	* @throws The error from the batch function if no onError handler is configured or throwOnError is true
 	*/
-	#execute;
-	#clearTimeout;
+	#execute = async () => {
+		if (this.store.state.items.length === 0) return;
+		const currentExecutionCount = this.store.state.executionCount + 1;
+		const batch = this.peekAllItems();
+		this.clear();
+		this.options.onItemsChange?.(this);
+		this.#setState({
+			isExecuting: true,
+			executionCount: currentExecutionCount
+		});
+		try {
+			const currentAsyncRetryer = new AsyncRetryer(this.fn, this.options.asyncRetryerOptions);
+			this.asyncRetryers.set(currentExecutionCount, currentAsyncRetryer);
+			const result = await currentAsyncRetryer.execute(batch);
+			this.#setState({
+				totalItemsProcessed: this.store.state.totalItemsProcessed + batch.length,
+				lastResult: result,
+				successCount: this.store.state.successCount + 1
+			});
+			this.options.onSuccess?.(result, batch, this);
+			return result;
+		} catch (error) {
+			this.#setState({
+				errorCount: this.store.state.errorCount + 1,
+				failedItems: [...this.store.state.failedItems, ...batch],
+				totalItemsFailed: this.store.state.totalItemsFailed + batch.length
+			});
+			this.options.onError?.(error, batch, this);
+			if (this.options.throwOnError) throw error;
+			return;
+		} finally {
+			this.asyncRetryers.delete(currentExecutionCount);
+			this.#setState({
+				isExecuting: false,
+				settleCount: this.store.state.settleCount + 1
+			});
+			this.options.onSettled?.(batch, this);
+		}
+	};
+	/**
+	* Processes the current batch of items immediately
+	*/
+	flush = async () => {
+		this.#clearTimeout();
+		return await this.#execute();
+	};
+	/**
+	* Returns a copy of all items in the async batcher
+	*/
+	peekAllItems = () => {
+		return [...this.store.state.items];
+	};
+	peekFailedItems = () => {
+		return [...this.store.state.failedItems];
+	};
+	#clearTimeout = () => {
+		if (this.#timeoutId) {
+			clearTimeout(this.#timeoutId);
+			this.#timeoutId = null;
+		}
+	};
+	/**
+	* Removes all items from the async batcher
+	*/
+	clear = () => {
+		this.#setState({
+			items: [],
+			failedItems: [],
+			isPending: false
+		});
+	};
+	/**
+	* Returns the AbortSignal for a specific 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 executionCount - Optional specific execution to get signal for
+	* @example
+	* ```typescript
+	* const batcher = new AsyncBatcher(
+	*   async (items: string[]) => {
+	*     const signal = batcher.getAbortSignal()
+	*     if (signal) {
+	*       const response = await fetch('/api/batch', {
+	*         method: 'POST',
+	*         body: JSON.stringify(items),
+	*         signal
+	*       })
+	*       return response.json()
+	*     }
+	*   },
+	*   { maxSize: 10, wait: 100 }
+	* )
+	* ```
+	*/
+	getAbortSignal = (executionCount) => {
+		const count = executionCount ?? this.store.state.executionCount;
+		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.
+	* Does NOT clear out the items.
+	*/
+	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.
+	* Does NOT clear out the items.
+	*/
+	cancel = () => {
+		this.#clearTimeout();
+		this.#setState({ isPending: false });
+	};
+	/**
+	* Resets the async batcher state to its default values
+	*/
+	reset = () => {
+		this.#setState(getDefaultAsyncBatcherState());
+		this.options.onItemsChange?.(this);
+		this.asyncRetryers.forEach((retryer) => retryer.reset());
+	};
 };
 /**
 * Creates an async batcher that processes items in batches.
@@ -330,5 +385,4 @@ function asyncBatch(fn, options) {
 }
 
 //#endregion
-export { AsyncBatcher, asyncBatch, asyncBatcherOptions };
-//# sourceMappingURL=async-batcher.js.map
+export { AsyncBatcher, asyncBatch, asyncBatcherOptions };

package/dist/async-debouncer.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-debouncer.d.ts
-interface AsyncDebouncerState<TFn extends AnyAsyncFunction> {
+export interface AsyncDebouncerState<TFn extends AnyAsyncFunction> {
   /**
    * Whether the debouncer can execute on the leading edge of the timeout
    */
@@ -27,7 +26,7 @@ interface AsyncDebouncerState<TFn extends AnyAsyncFunction> {
   /**
    * The result from the most recent successful function execution
    */
-  lastResult: ReturnType<TFn> | undefined;
+  lastResult: Awaited<ReturnType<TFn>> | undefined;
   /**
    * Number of times maybeExecute has been called (for reduction calculations)
    */
@@ -48,7 +47,7 @@ interface AsyncDebouncerState<TFn extends AnyAsyncFunction> {
 /**
  * Options for configuring an async debounced function
  */
-interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
+export interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
   /**
    * Options for configuring the underlying async retryer
    */
@@ -86,7 +85,7 @@ interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
   /**
    * Optional callback to call when the debounced function is executed
    */
-  onSuccess?: (result: ReturnType<TFn>, args: Parameters<TFn>, debouncer: AsyncDebouncer<TFn>) => void;
+  onSuccess?: (result: Awaited<ReturnType<TFn>>, args: Parameters<TFn>, debouncer: AsyncDebouncer<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.
@@ -108,7 +107,7 @@ interface AsyncDebouncerOptions<TFn extends AnyAsyncFunction> {
 /**
  * Utility function for sharing common `AsyncDebouncerOptions` options between different `AsyncDebouncer` instances.
  */
-declare function asyncDebouncerOptions<TFn extends AnyAsyncFunction = AnyAsyncFunction, TOptions extends Partial<AsyncDebouncerOptions<TFn>> = Partial<AsyncDebouncerOptions<TFn>>>(options: TOptions): TOptions;
+export declare function asyncDebouncerOptions<TFn extends AnyAsyncFunction = AnyAsyncFunction, TOptions extends Partial<AsyncDebouncerOptions<TFn>> = Partial<AsyncDebouncerOptions<TFn>>>(options: TOptions): TOptions;
 /**
  * A class that creates an async debounced function.
  *
@@ -163,7 +162,7 @@ declare function asyncDebouncerOptions<TFn extends AnyAsyncFunction = AnyAsyncFu
  * const results = await asyncDebouncer.maybeExecute(inputElement.value);
  * ```
  */
-declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
+export declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
   #private;
   fn: TFn;
   readonly store: Store<Readonly<AsyncDebouncerState<TFn>>>;
@@ -189,11 +188,11 @@ declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
    * @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: (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
+  maybeExecute: (...args: Parameters<TFn>) => Promise<Awaited<ReturnType<TFn>> | undefined>;
   /**
    * Processes the current pending execution immediately
    */
-  flush: () => Promise<ReturnType<TFn> | undefined>;
+  flush: () => Promise<Awaited<ReturnType<TFn>> | undefined>;
   /**
    * Returns the AbortSignal for a specific execution.
    * If no maybeExecuteCount is provided, returns the signal for the most recent execution.
@@ -294,7 +293,5 @@ declare class AsyncDebouncer<TFn extends AnyAsyncFunction> {
  * const result = await debounced("third");
  * ```
  */
-declare function asyncDebounce<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions: AsyncDebouncerOptions<TFn>): (...args: Parameters<TFn>) => Promise<ReturnType<TFn> | undefined>;
-//#endregion
-export { AsyncDebouncer, AsyncDebouncerOptions, AsyncDebouncerState, asyncDebounce, asyncDebouncerOptions };
-//# sourceMappingURL=async-debouncer.d.ts.map
+export declare function asyncDebounce<TFn extends AnyAsyncFunction>(fn: TFn, initialOptions: AsyncDebouncerOptions<TFn>): (...args: Parameters<TFn>) => Promise<Awaited<ReturnType<TFn>> | undefined>;
+//#endregion