@tanstack/pacer 0.22.0 → 0.23.0

package/dist/rate-limiter.js

@@ -71,105 +71,13 @@ const defaultOptions = {
 * ```
 */
 var RateLimiter = class {
-	#timeoutIds;
+	fn;
+	store = new Store(getDefaultRateLimiterState());
+	key;
+	options;
+	#timeoutIds = /* @__PURE__ */ new Set();
 	constructor(fn, initialOptions) {
 		this.fn = fn;
-		this.store = new Store(getDefaultRateLimiterState());
-		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" : isExceeded ? "exceeded" : "idle";
-				return {
-					...combinedState,
-					isExceeded,
-					status
-				};
-			});
-			emitChange("RateLimiter", 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 = (...args) => {
-			this.#setState({ maybeExecuteCount: this.store.state.maybeExecuteCount + 1 });
-			this.#cleanupOldExecutions();
-			if (this.#getExecutionTimesInWindow().length < this.#getLimit()) {
-				this.#execute(...args);
-				return true;
-			}
-			this.#setState({ rejectionCount: this.store.state.rejectionCount + 1 });
-			this.options.onReject?.(this);
-			return false;
-		};
-		this.#execute = (...args) => {
-			if (!this.#getEnabled()) return;
-			const now = Date.now();
-			this.fn(...args);
-			this.store.state.executionTimes.push(now);
-			this.#setCleanupTimeout(now);
-			this.#setState({ executionCount: this.store.state.executionCount + 1 });
-			this.options.onExecute?.(args, this);
-		};
-		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.reset = () => {
-			this.#setState(getDefaultRateLimiterState());
-			this.#clearTimeouts();
-		};
 		this.key = initialOptions.key;
 		this.options = {
 			...defaultOptions,
@@ -183,25 +91,136 @@ var RateLimiter = class {
 			this.setOptions(event.payload.options);
 		});
 	}
-	#setState;
+	/**
+	* Updates the 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" : isExceeded ? "exceeded" : "idle";
+			return {
+				...combinedState,
+				isExceeded,
+				status
+			};
+		});
+		emitChange("RateLimiter", this);
+	};
 	/**
 	* Returns the current enabled state of the 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.
+	*
+	* @example
+	* ```ts
+	* const rateLimiter = new RateLimiter(fn, { limit: 5, window: 1000 });
+	*
+	* // First 5 calls will return true
+	* rateLimiter.maybeExecute('arg1', 'arg2'); // true
+	*
+	* // Additional calls within the window will return false
+	* rateLimiter.maybeExecute('arg1', 'arg2'); // false
+	* ```
+	*/
+	maybeExecute = (...args) => {
+		this.#setState({ maybeExecuteCount: this.store.state.maybeExecuteCount + 1 });
+		this.#cleanupOldExecutions();
+		if (this.#getExecutionTimesInWindow().length < this.#getLimit()) {
+			this.#execute(...args);
+			return true;
+		}
+		this.#setState({ rejectionCount: this.store.state.rejectionCount + 1 });
+		this.options.onReject?.(this);
+		return false;
+	};
+	#execute = (...args) => {
+		if (!this.#getEnabled()) return;
+		const now = Date.now();
+		this.fn(...args);
+		this.store.state.executionTimes.push(now);
+		this.#setCleanupTimeout(now);
+		this.#setState({ executionCount: this.store.state.executionCount + 1 });
+		this.options.onExecute?.(args, 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);
+		}
+	};
+	#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
+	*/
+	getMsUntilNextWindow = () => {
+		if (this.getRemainingInWindow() > 0) return 0;
+		return (this.store.state.executionTimes[0] ?? Infinity) + this.#getWindow() - Date.now();
+	};
+	/**
+	* Resets the rate limiter state
+	*/
+	reset = () => {
+		this.#setState(getDefaultRateLimiterState());
+		this.#clearTimeouts();
+	};
 };
 /**
 * Creates a rate-limited function that will execute the provided function up to a maximum number of times within a time window.
@@ -256,5 +275,4 @@ function rateLimit(fn, initialOptions) {
 }
 
 //#endregion
-export { RateLimiter, rateLimit, rateLimiterOptions };
-//# sourceMappingURL=rate-limiter.js.map
+export { RateLimiter, rateLimit, rateLimiterOptions };

package/dist/throttler.d.ts

@@ -1,7 +1,7 @@
 import { AnyFunction } from "./types.js";
 import { Store } from "@tanstack/store";
 //#region src/throttler.d.ts
-interface ThrottlerState<TFn extends AnyFunction> {
+export interface ThrottlerState<TFn extends AnyFunction> {
   /**
    * Number of function executions that have been completed
    */
@@ -34,7 +34,7 @@ interface ThrottlerState<TFn extends AnyFunction> {
 /**
  * Options for configuring a throttled function
  */
-interface ThrottlerOptions<TFn extends AnyFunction> {
+export interface ThrottlerOptions<TFn extends AnyFunction> {
   /**
    * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
    * Can be a boolean or a function that returns a boolean.
@@ -74,7 +74,7 @@ interface ThrottlerOptions<TFn extends AnyFunction> {
 /**
  * Utility function for sharing common `ThrottlerOptions` options between different `Throttler` instances.
  */
-declare function throttlerOptions<TFn extends AnyFunction = AnyFunction, TOptions extends Partial<ThrottlerOptions<TFn>> = Partial<ThrottlerOptions<TFn>>>(options: TOptions): TOptions;
+export declare function throttlerOptions<TFn extends AnyFunction = AnyFunction, TOptions extends Partial<ThrottlerOptions<TFn>> = Partial<ThrottlerOptions<TFn>>>(options: TOptions): TOptions;
 /**
  * A class that creates a throttled function.
  *
@@ -111,7 +111,7 @@ declare function throttlerOptions<TFn extends AnyFunction = AnyFunction, TOption
  * throttler.maybeExecute('123'); // Throttled
  * ```
  */
-declare class Throttler<TFn extends AnyFunction> {
+export declare class Throttler<TFn extends AnyFunction> {
   #private;
   fn: TFn;
   readonly store: Store<Readonly<ThrottlerState<TFn>>>;
@@ -200,7 +200,5 @@ declare class Throttler<TFn extends AnyFunction> {
  * });
  * ```
  */
-declare function throttle<TFn extends AnyFunction>(fn: TFn, initialOptions: ThrottlerOptions<TFn>): (...args: Parameters<TFn>) => void;
-//#endregion
-export { Throttler, ThrottlerOptions, ThrottlerState, throttle, throttlerOptions };
-//# sourceMappingURL=throttler.d.ts.map
+export declare function throttle<TFn extends AnyFunction>(fn: TFn, initialOptions: ThrottlerOptions<TFn>): (...args: Parameters<TFn>) => void;
+//#endregion

package/dist/throttler.js

@@ -63,92 +63,13 @@ const defaultOptions = {
 * ```
 */
 var Throttler = class {
+	fn;
+	store = new Store(getDefaultThrottlerState());
+	key;
+	options;
 	#timeoutId;
 	constructor(fn, initialOptions) {
 		this.fn = fn;
-		this.store = new Store(getDefaultThrottlerState());
-		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 } = combinedState;
-				return {
-					...combinedState,
-					status: !this.#getEnabled() ? "disabled" : isPending ? "pending" : "idle"
-				};
-			});
-			emitChange("Throttler", this);
-		};
-		this.#getEnabled = () => {
-			return !!parseFunctionOrValue(this.options.enabled, this);
-		};
-		this.#getWait = () => {
-			return parseFunctionOrValue(this.options.wait, this);
-		};
-		this.maybeExecute = (...args) => {
-			this.#setState({ maybeExecuteCount: this.store.state.maybeExecuteCount + 1 });
-			const now = Date.now();
-			const timeSinceLastExecution = now - this.store.state.lastExecutionTime;
-			const wait = this.#getWait();
-			if (this.options.leading && timeSinceLastExecution >= wait) this.#execute(...args);
-			else {
-				this.#setState({ lastArgs: args });
-				if (!this.#timeoutId && this.options.trailing) {
-					const timeoutDuration = wait - (this.store.state.lastExecutionTime ? now - this.store.state.lastExecutionTime : 0);
-					this.#setState({ isPending: true });
-					this.#timeoutId = setTimeout(() => {
-						const { lastArgs } = this.store.state;
-						if (lastArgs !== void 0) this.#execute(...lastArgs);
-					}, timeoutDuration);
-				}
-			}
-		};
-		this.#execute = (...args) => {
-			if (!this.#getEnabled()) return;
-			this.fn(...args);
-			const lastExecutionTime = Date.now();
-			const nextExecutionTime = lastExecutionTime + this.#getWait();
-			this.#clearTimeout();
-			this.#setState({
-				executionCount: this.store.state.executionCount + 1,
-				lastExecutionTime,
-				nextExecutionTime,
-				isPending: false,
-				lastArgs: void 0
-			});
-			this.options.onExecute?.(args, this);
-			setTimeout(() => {
-				if (!this.store.state.isPending) this.#setState({ nextExecutionTime: void 0 });
-			}, this.#getWait());
-		};
-		this.flush = () => {
-			if (this.store.state.isPending && this.store.state.lastArgs) this.#execute(...this.store.state.lastArgs);
-		};
-		this.#clearTimeout = () => {
-			if (this.#timeoutId) {
-				clearTimeout(this.#timeoutId);
-				this.#timeoutId = void 0;
-			}
-		};
-		this.cancel = () => {
-			this.#clearTimeout();
-			this.#setState({
-				lastArgs: void 0,
-				isPending: false
-			});
-		};
-		this.reset = () => {
-			this.#setState(getDefaultThrottlerState());
-		};
 		this.key = initialOptions.key;
 		this.options = {
 			...defaultOptions,
@@ -161,11 +82,128 @@ var Throttler = class {
 			this.setOptions(event.payload.options);
 		});
 	}
-	#setState;
-	#getEnabled;
-	#getWait;
-	#execute;
-	#clearTimeout;
+	/**
+	* Updates the throttler 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 } = combinedState;
+			return {
+				...combinedState,
+				status: !this.#getEnabled() ? "disabled" : isPending ? "pending" : "idle"
+			};
+		});
+		emitChange("Throttler", this);
+	};
+	#getEnabled = () => {
+		return !!parseFunctionOrValue(this.options.enabled, this);
+	};
+	#getWait = () => {
+		return parseFunctionOrValue(this.options.wait, this);
+	};
+	/**
+	* 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 Throttler(fn, { wait: 1000 });
+	*
+	* // First call executes immediately
+	* throttled.maybeExecute('a', 'b');
+	*
+	* // Call during wait period - gets throttled
+	* throttled.maybeExecute('c', 'd');
+	* ```
+	*/
+	maybeExecute = (...args) => {
+		this.#setState({ maybeExecuteCount: this.store.state.maybeExecuteCount + 1 });
+		const now = Date.now();
+		const timeSinceLastExecution = now - this.store.state.lastExecutionTime;
+		const wait = this.#getWait();
+		if (this.options.leading && timeSinceLastExecution >= wait) this.#execute(...args);
+		else {
+			this.#setState({ lastArgs: args });
+			if (!this.#timeoutId && this.options.trailing) {
+				const timeoutDuration = wait - (this.store.state.lastExecutionTime ? now - this.store.state.lastExecutionTime : 0);
+				this.#setState({ isPending: true });
+				this.#timeoutId = setTimeout(() => {
+					const { lastArgs } = this.store.state;
+					if (lastArgs !== void 0) this.#execute(...lastArgs);
+				}, timeoutDuration);
+			}
+		}
+	};
+	#execute = (...args) => {
+		if (!this.#getEnabled()) return;
+		this.fn(...args);
+		const lastExecutionTime = Date.now();
+		const nextExecutionTime = lastExecutionTime + this.#getWait();
+		this.#clearTimeout();
+		this.#setState({
+			executionCount: this.store.state.executionCount + 1,
+			lastExecutionTime,
+			nextExecutionTime,
+			isPending: false,
+			lastArgs: void 0
+		});
+		this.options.onExecute?.(args, this);
+		setTimeout(() => {
+			if (!this.store.state.isPending) this.#setState({ nextExecutionTime: void 0 });
+		}, this.#getWait());
+	};
+	/**
+	* Processes the current pending execution immediately
+	*/
+	flush = () => {
+		if (this.store.state.isPending && this.store.state.lastArgs) this.#execute(...this.store.state.lastArgs);
+	};
+	#clearTimeout = () => {
+		if (this.#timeoutId) {
+			clearTimeout(this.#timeoutId);
+			this.#timeoutId = void 0;
+		}
+	};
+	/**
+	* Cancels any pending trailing execution and clears internal state.
+	*
+	* If a trailing execution is scheduled (due to throttling with trailing=true),
+	* this will prevent that execution from occurring. The internal timeout and
+	* stored arguments will be cleared.
+	*
+	* Has no effect if there is no pending execution.
+	*/
+	cancel = () => {
+		this.#clearTimeout();
+		this.#setState({
+			lastArgs: void 0,
+			isPending: false
+		});
+	};
+	/**
+	* Resets the throttler state to its default values
+	*/
+	reset = () => {
+		this.#setState(getDefaultThrottlerState());
+	};
 };
 /**
 * Creates a throttled function that limits how often the provided function can execute.
@@ -208,5 +246,4 @@ function throttle(fn, initialOptions) {
 }
 
 //#endregion
-export { Throttler, throttle, throttlerOptions };
-//# sourceMappingURL=throttler.js.map
+export { Throttler, throttle, throttlerOptions };

package/dist/types.d.ts

@@ -2,12 +2,10 @@
 /**
  * Represents a function that can be called with any arguments and returns any value.
  */
-type AnyFunction = (...args: Array<any>) => any;
+export type AnyFunction = (...args: Array<any>) => any;
 /**
  * Represents an asynchronous function that can be called with any arguments and returns a promise.
  */
-type AnyAsyncFunction = (...args: Array<any>) => Promise<any>;
-type OptionalKeys<T, TKey extends keyof T> = Omit<T, TKey> & Partial<Pick<T, TKey>>;
-//#endregion
-export { AnyAsyncFunction, AnyFunction, OptionalKeys };
-//# sourceMappingURL=types.d.ts.map
+export type AnyAsyncFunction = (...args: Array<any>) => Promise<any>;
+export type OptionalKeys<T, TKey extends keyof T> = Omit<T, TKey> & Partial<Pick<T, TKey>>;
+//#endregion

package/dist/utils.d.ts

@@ -1,7 +1,5 @@
 import { AnyFunction } from "./types.js";
 //#region src/utils.d.ts
-declare function isFunction<T extends AnyFunction>(value: any): value is T;
-declare function parseFunctionOrValue<T, TArgs extends Array<any>>(value: T | ((...args: TArgs) => T), ...args: TArgs): T;
-//#endregion
-export { isFunction, parseFunctionOrValue };
-//# sourceMappingURL=utils.d.ts.map
+export declare function isFunction<T extends AnyFunction>(value: any): value is T;
+export declare function parseFunctionOrValue<T, TArgs extends Array<any>>(value: T | ((...args: TArgs) => T), ...args: TArgs): T;
+//#endregion

package/dist/utils.js

@@ -7,5 +7,4 @@ function parseFunctionOrValue(value, ...args) {
 }
 
 //#endregion
-export { isFunction, parseFunctionOrValue };
-//# sourceMappingURL=utils.js.map
+export { isFunction, parseFunctionOrValue };